Colt Voice APIs Guide - Colt Technology Services
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Colt Voice APIs Guide
Colt Voice APIs Guide
Number Hosting APIs Implementation Guide
Copyright ©
No part of this document may be reproduced or adapted in any form, including photocopying or storing it by electronic
means, except as is necessary for the purpose of the recipient's dealings with Colt, without the written permission of
Colt. Any copies made of any part of this document shall include the notice:
© 2021 Colt Technology Services. The Colt name and logos are trademarks. All rights reserved.
No information contained in this document shall be disclosed to any third party without the written permission of Colt.
Colt Voice API Guide v1.4 1 / 68Document History
Soft copies of this document are maintained under change control, but hard copies are not. This may
not be a printout of the latest version.
Revision history
Revision Date Description
1.0 March 28, 2020 Document creation:
• Merge of ‘API guide 2.0’ and ‘Colt Number Hosting Solution Guide v3.0’.
1.1.0 July 9, 2020 Document updates:
• New DSU fields in SE & ES for activation, new port-in & update operations
• Address fields updates in SE & ES for activation, new port-in & update
operations
• Support of partial address update for ported-in numbers for Premium offer
• WSDL URL correction
1.2 September 2, Document updates:
2020
• End point URL correction in section 2.3
• Update of country code from ‘UK’ to ‘GB’
• Updated porting status from Expired to Delayed in section 6.1.3
1.3 October 10, 2020 Document updates:
• Added new API validGeographicAddress API in section 2.4
• Updated section 3.4 and 3.5 for BE
• Updated section 4.4 for BE,ES and SE
• Updated section 5.1 for ES, SE and BE
• Updated section 7.6 for BE
1.4 January 23, 2021 Document updates:
• Rebranding
• Updated description for ‘Customer Type’ field in section 3.4.1
• Added example for validateGeographicAddress REST JSON API in section
5.1
• Updated ‘Operator List’ in section 6.2.1
• Updated country details for Single/Multiline in section 6.2.1
• Updated ‘Notes’ details in sections 6.2.2, 6.3.4 and 6.3.5
• Updated ‘allowed file type’ for LOA and invoice in section 6.2.2 and 6.3.7
• Updated description for ‘Port not initiated’ status in section 7.8.1
• Added Appendix A for Operator List
Colt Voice API Guide v1.4 2 / 68Contents
1 Introduction ......................................................................................................................................... 5
1.1 Guide Objective & Structure ........................................................................................................ 5
1.2 Product Documentation ............................................................................................................... 5
1.3 Number Coverage & Offering ...................................................................................................... 5
1.4 Number Allocation Rules ............................................................................................................. 5
1.4.1 Germany: 100+ Range Allocation ............................................................................................ 5
1.4.2 Portugal: Tri-Party Agreement ................................................................................................. 6
1.5 Fair use policy & Security ............................................................................................................ 6
2 Colt Voice B2B APIs ........................................................................................................................... 7
2.1 Standard ..................................................................................................................................... 7
2.2 Authentication mechanism .......................................................................................................... 7
2.3 Access & End-Point URLs ........................................................................................................... 7
2.4 List of APIs.................................................................................................................................. 7
2.5 Order ID [transactionID]..............................................................................................................10
2.6 Order Status [transactionStatus] .................................................................................................10
2.7 Customer Reference [customeRef] .............................................................................................11
2.8 Premium Offer............................................................................................................................11
2.9 Bulk API [bulkNhTransactions] ...................................................................................................12
2.10 Sub Reselling [subResellerID] ....................................................................................................12
2.11 Portugal: Colt CVP [additionalCustRef2] ....................................................................................12
2.12 Error & Rejection Codes .............................................................................................................12
3 API Request Structure .......................................................................................................................13
3.1 Fields Value, Validation, Type & Country Application ..................................................................13
3.2 serviceHeader & resellerProfile ..................................................................................................13
3.3 Number Format ..........................................................................................................................14
3.4 End-customer Details .................................................................................................................15
3.4.1 customerType = Business ......................................................................................................15
3.4.2 customerType = Residential ...................................................................................................16
3.5 Emergency Address (endCustomerAddress) ..............................................................................16
4 Number Life Cycle .............................................................................................................................18
4.1 Number Status [cliStatus] ...........................................................................................................18
4.2 Colt Number Life Cycle...............................................................................................................19
4.3 Ported-In Number Life Cycle ......................................................................................................19
4.4 Number Action & Transition ........................................................................................................19
5 Search & Acquire Number .................................................................................................................22
5.1 Get Local Area Code (LAC) by Address [validateGeoNumber API] .............................................22
5.2 Get Free Geo Number by Local Area [numberEnquiry API] ........................................................25
5.3 Get Free Location Independent Number [numberEnquiry API] ....................................................27
5.4 Get Free 0330 & 0333 Number in the UK [numberEnquiry API] ..................................................28
5.5 Acquire Number [numberReservation & numberActivation APIs].................................................29
6 Port-In .................................................................................................................................................32
6.1 Port-In Life Cycle........................................................................................................................32
6.1.1 Order Status [transactionStatus].............................................................................................32
Colt Voice API Guide v1.4 3 / 686.1.2 Port-In in the Netherlands ......................................................................................................34
6.1.3 Port-In in the Other Countries .................................................................................................34
6.1.4 Transaction Action & Transition ..............................................................................................34
6.2 New Port-In [portIn API]..............................................................................................................36
6.2.1 Request (1/3): Order Information ............................................................................................36
6.2.2 Request (2/3): Attachment......................................................................................................37
6.2.3 Request (3/3): Email Notification Contact Details [switchMaintainer] .......................................38
6.2.4 Output/Response ...................................................................................................................38
6.3 Port-In Updates ..........................................................................................................................39
6.3.1 Port-In Date Change in all countries except NL & IT [updatePortIn API] ..................................40
6.3.2 Cancellation in all countries except NL [cancelPortIn API] ......................................................41
6.3.3 Cancellation in NL [transactionDataUpdate API] .....................................................................42
6.3.4 Schedule Port in NL [transactionDataUpdate API] ..................................................................43
6.3.5 Activate Port in NL [transactionDataUpdate API] ....................................................................45
6.3.6 Send Notes In All Countries Except NL [transactionDataUpdate API] .....................................46
6.3.7 Update when transactionStatus = ‘Customer feedback awaited’ In All Countries Except NL
[transactionDataUpdate API] ................................................................................................................47
6.4 On the Porting Date....................................................................................................................49
6.5 Porting Documentation & More! ..................................................................................................49
7 Number Inventory & Update ..............................................................................................................49
7.1 Get List of Numbers by Status [numberEnquiry API] ...................................................................49
7.2 Get Number Status [numberEnquiry API] ...................................................................................52
7.3 Get Number History [getTelephoneNumberHistory API] ..............................................................52
7.4 Get Number Detail [getNumberDetail API] ..................................................................................54
7.5 Update Emergency Address [updateEndCustomerAddress API] .................................................55
7.6 Phonebook Publication [updateEndCustomerAddress API].........................................................56
7.7 Phonebook Publication [updateDirectoryServices API] ...............................................................57
7.8 Port-Out .....................................................................................................................................58
7.8.1 Order Status [transactionStatus].............................................................................................58
7.8.2 Port-Out in Denmark, France, Italy, Ireland, Portugal, Spain, Sweden & United Kingdom (no
customer action required).....................................................................................................................59
7.8.3 Port-Out in Austria, Belgium, Germany (w/o WBCI), Netherlands and Switzerland (customer
action required) [transactionDataUpdate API] .......................................................................................60
8 Return Number...................................................................................................................................62
8.1 Return Number to Colt [cancelReservation & numberDeactivation APIs].....................................62
8.2 Reactivate Quarantined Number [numberReactivation & portInReactivation APIs] ......................63
9 Order Management ............................................................................................................................65
9.1 Get Order Details [getTransactionDetails API] ............................................................................65
9.2 Get List of Orders [getTransactionList API] .................................................................................65
9.3 API Call Back .............................................................................................................................67
Colt Voice API Guide v1.4 4 / 681 Introduction
1.1 Guide Objective & Structure
This guide aims to support you for complete Number Life Cycle Management via Colt Voice APIs.
After short introduction and general principles being explained, this guide will follow the below structure:
1.2 Product Documentation
This guide shall be read together with the following documentation:
Document Description
Business rules & features availability
Service Matrix error codes (system, porting, address validation, …)
Fields validation with applicable API & countries
API Baseline samples &
API request & response structures & samples.
structures
Colt Voice APIs Samples request & response examples for each API & most common scenarios.
Geo Coverage Local Area supported by Colt.
1.3 Number Coverage & Offering
Please check Service Matrix & Geo coverage files for number type offered by Colt & geographic coverage.
1.4 Number Allocation Rules
1.4.1 Germany: 100+ Range Allocation
German Regulator Bundesnetzagentur (BNetzA) defines the maximum range sizes for new subscribers in the
document ‘Struktur und Ausgestaltung des Nummernbereichs für Ortsnetzrufnummern‘.
A German and an English version are available on the homepage of BNetzA:
1. Bestimmung der Anzahl zuzuteilender Rufnummern bei durchwahlfähigen VoIP-Anschlüssen
2. http://www.bundesnetzagentur.de/cln_1431/DE/Sachgebiete/Telekommunikation/Unternehmen_Insti
tutionen/Nummerierung/Rufnummern/ONRufnr/Ortsnetze_Basepage.html?nn=268384
Colt Voice API Guide v1.4 5 / 68(Struktur und Ausgestaltung des Nummernbereichs für Ortsnetzrufnummern)
3. https://www.bundesnetzagentur.de/EN/Areas/Telecommunications/Companies/NumberManagement
/GeographicNumbers/LocalNumbers_Basepage.html?nn=404520
(Structure and configuration of the number range for geographic numbers)
For block greater than 100, allocation must be approved by BNetzA before assigning numbers to the end-
customer.
Process is as per the following:
• Customer sends the request form to BNetzA
• Official timeline for BNetzA to answer is 3 weeks, but less than 1 week in practice.
• Customer sends the approval to Colt
• Customer can assign the numbers.
It’s customer responsibilities to engage with BNetzA and share the confirmation with Colt.
Request form is available below in German/English. It can be filled out in both languages, the other language
will be populated automatically.
1.4.2 Portugal: Tri-Party Agreement
All orders must include Tri-Party Agreement, available upon request to Colt.
Tri-Party Agreement shall be sent to Colt Porting Desk Portugal via email, with the corresponding transaction
ID before the end-customer assignment. Order without Tri-Party Agreement will be rejected or reverted.
1.5 Fair use policy & Security
Any misuse of number, whatever nature, might lead to service suspension or number claimed back.
Idle session timeout for API is 10min. Server rejects any request that includes a cookie identifying an expired
or invalid session, even if the request includes valid user credentials.
Colt Voice API Guide v1.4 6 / 682 Colt Voice B2B APIs
2.1 Standard
Colt APIs are based on XML standard. All interfaces are synchronous SSL based security connection.
API Call Back is made using REST JSON.
2.2 Authentication mechanism
Authentication Mechanism is based on User and Password. Both will be provided by Colt during API
access creation and will cover all your Service Profiles.
2.3 Access & End-Point URLs
Colt APIs can be enable in the below environments:
• Production: live environment. Network, billing & emergency services are enable.
• Sandbox: none-production environment made for testing, with production version of APIs. Network,
billing & emergency services are not enable.
• Beta: none-production environment made for testing of new features before release, with upcoming
version of APIs. Only available before new releases. Network, billing & emergency services are not
enable.
Colt Production APIs are accessible via the below interfaces:
Interface Production
WSDL URL
https://wbmdmzis02.colt.net/ws/ColtNumberHosting.common.webSvcProvider:numberHosting?WSDL
SOAP End point URL
https://wbmdmzis02.colt.net/ws/ColtNumberHosting.common.webSvcProvider:numberHosting/ColtNumberH
osting_common_webSvcProvider_numberHosting_Port
HTTPS https://wbmdmzis02.colt.net/invoke/ColtNumberHosting.common.http/ + API name
HTTPS examples
• https://wbmdmzis02.colt.net/invoke/ColtNumberHosting.common.http/numberEnquiry
• https://wbmdmzis02.colt.net/invoke/ColtNumberHosting.common.http/numberActivation
2.4 List of APIs
Colt APIs are listed and described in the below table:
Colt Voice API Guide v1.4 7 / 68Chargeable
API transactionType Description (orderID
created)
Allows you to get:
numberEnquiry N/A • List of free numbers No
• Number inventory details (list of
number, number status).
Allows you to get:
• Available LAC for an address.
• {Address + Number} combination
validateGeoNumber N/A confirmation (if countries where No
numbering plan defines location that
can be used with numbers).
• Decommissioned for Germany
Allows you to get:
• Same as validateGeoNumber
validateGeoNumberv2 N/A • Complete address validation & No
verification
• Applicable for ES and SE
Developed as a REST JSON API,
• Validate end-customer addresses
upfront in Informatica Address Doctor
• Fetch Geo & non Geo (e.g. Nomadic)
area codes for a successfully
validated address
o Return an Address ID / key
for a successfully validated
address, which can then be
used:- o To fetch address
details
validGeographicAddress N/A No
o during number association
(activation, new port-in,
update APIs), instead of
providing the address again
• To retrieve all your validated
addresses
• Mitigate & reduce the volume of
business failures due to incorrect
addresses
• Submit orders cleanly
• Be regulatory compliant
Colt Voice API Guide v1.4 8 / 68Chargeable
API transactionType Description (orderID
created)
Allows you to add number in stock without end-
Number customer assignment nor network
numberReservation Yes
Reservation configuration. Number will be reserved for 90
calendar days, and then shift back to free pool.
Number
Allows you to return back to Colt reserved
cancelReservation Reservation No
number.
Cancellation
Number Allows you to assign number to an end-
numberActivation Yes
Activation customer and activate on Colt network.
Update End Allows you to update activated number details,
updateEndCustomerAddress No
Customer Detail e.g. emergency address.
Update Directory Allows you to update number publication
updateDirectoryServices No
Services details.
Allows you to create new port-in order.
portIn New Port In Please note: Out of hours porting is Yes
chargeable.
Update Port In Allows you to update port-in order (date
updatePortIn No
Date change)
cancelPortIn Cancel Port In Allows you to cancel port-in order. No
Port Transaction Allows you to update a port-in order (cancel,
transactionDataUpdate No
Update notes, scheduling, activate…).
Number Allows you to return activated number back to
numberDeactivation No
Deactivation Colt.
Number
numberReactivation Allows you to reactivate Colt number. Yes
Reactivation
Reactivate Port
portInReactivation Allows you to reactivate ported-in number. Yes
In
Allows you to perform numberActivation, portIn
bulkNhTransactions N/A As per the API.
& updateEndCustomerAddress bulk request.
Colt Voice API Guide v1.4 9 / 68Chargeable
API transactionType Description (orderID
created)
Allows you to get list of orders matching your
getTransactionList N/A No
search criteria.
getTransactionDetails N/A Allows you to get details for a specific order. No
Allows you to get list of orders for a specific
getTelephoneNumberHistory N/A No
number.
Allows you to get details for a specific active
getNumberDetail N/A No
number.
• transactionType can be used as search criteria in getTransactionList API.
2.5 Order ID [transactionID]
After order creation, an unique ID [transactionID] will be returned to you.
transactionID follows the below pattern and format:
Value
Pattern 32 character long (128 bit)
Format “[A-Za-z0-9\-]{1,36}“
Maximum length 36, including ‘-’ characters
Example 8700206f-c3b3-4c10-8cc2-2490f41eedc0
• portIn & portOut orders: Colt will return a first transactionID, also named ‘Parent Transaction ID’. Please
always track this ID to get the latest updates of your order.
2.6 Order Status [transactionStatus]
Your transaction will have a status [transactionStatus], that will vary over the time and the scenarios.
Non porting related orders have a 2 steps update: ‘In progress’, from order creation until completion, and
then the final status.
Please find below transactionStatus and description:
Colt Voice API Guide v1.4 10 / 68transactionStat
Description Next action
us
In progress Your order is in progress, usually the first step. No action required.
Completed Your order has been completed. No action required.
Failed with This error, also known as business error, occurs when you Please have a look to error message,
error have submitted incorrect information. correct and resubmit the request.
This error, also known as technical error, occurs when No action required from you, Colt will
Failed
unexpected error occurred during process. correct and resubmit the request.
Porting related orders have multiple update, at each key order milestone. Please refer to porting sections
for more information.
2.7 Customer Reference [customeRef]
customerRef field allows you map your internal reference (e.g. order or service ID, …) with number at Colt.
Field is optional and available in the below API(s):
• numberReservation,
• numberActivation
• portIn
• updateEndCustomerAddress
2.8 Premium Offer
Premium offer allows you to get:
• Preactivated numbers
• Ability to update end-customer at sub-range level and to manage the aging/quarantine period.
Below picture summarizes the number life cycle for Premium offer:
Colt Voice API Guide v1.4 11 / 68• Access to Premium offer is subject to Colt validation.
• Only available in Belgium, Denmark, France, Ireland, Netherlands, Portugal, Spain, Sweden,
United Kingdom (9).
2.9 Bulk API [bulkNhTransactions]
The bulkNhTransactions API allows you to place bulk request for:
• numberActivation,
• portIn,
• updateEndCustomerAddress.
Please refer to Service Matrix for additional information about bulk capabilities.
2.10 Sub Reselling [subResellerID]
In some countries, it is allowed to provide number purchased from Colt using your indirect sales channel, but
it’s mandatory to report the 3rd party to Colt (sub reseller OCN), using subResellerID field.
Field is optional and available in the below API(s):
• numberActivation
• portIn
• updateEndCustomerAddress
• subResellerID is not available in FR, IT, PT (3), meaning you must own the relationship with the end-
customer.
2.11 Portugal: Colt CVP [additionalCustRef2]
Colt will return you the ‘Colt CVP’ in additionalCustRef2 field of getTransactionDetails API response.
2.12 Error & Rejection Codes
Please refer to the Service Matrix for:
• System Error Codes
• Port-In Rejection & Exception Codes
• LAC validation / validateGeoNumber API Error Codes
Colt Voice API Guide v1.4 12 / 683 API Request Structure
API structure can be summarized as per the below:
• Header (serviceHeader & resellerProfile)
• Telephone Number
• End-Customer Detail
• Emergency Address
• Port-In Detail
• Phonebook Publication
All sections are not applicable in all API calls.
Next chapters will provide you comprehensive description of each section and later on, where to be used.
3.1 Fields Value, Validation, Type & Country Application
This guide will provide you most the information you need to understand Colt APIs. Nevertheless, fields value
& validation might vary per API and/or country. You will find list of fields in the Service Matrix, with:
• Value
• Length
• Description/Example
• Type per API (Mandatory, Conditional Mandatory, Optional or Not Applicable)
• Country application (Yes, No)
Service Matrix follows the same structure as the guide.
3.2 serviceHeader & resellerProfile
Below parameter(s) from [serviceHeader] & [resellerProfile] shall be sent to Colt for all requests:
Parameter Type Description
Mandatory
senderSystem Value = Xml
(Default)
Format: yyyy-MM-dd’T‘hh:mm:ss.SSS‘Z’
creationTime Optional
Ex: 2020-03-24T12:07:00.000Z
Your Service Profile. Upper case alphanumeric
serviceProfile Mandatory only.
Ex (FR): A29
Colt Voice API Guide v1.4 13 / 68Parameter Type Description
Mandatory
productID Value = Geographic Number Hosting
(Default)
Country Code. Upper case alphanumeric only.
Country Mandatory
Ex: GB for United Kingdom, FR for France, …
Please find below country codes supported in Colt APIs:
Country Country Code
Austria AT
Belgium BE
Denmark DK
France FR
Germany DE
Ireland IE
Italy IT
Netherlands NL
Portugal PT
Spain ES
Sweden SE
Switzerland CH
United Kingdom GB
3.3 Number Format
Colt APIs support below number formats:
• Split national format, combination of {areaCode, areaCodeExtn, rangeStart & rangeEnd} in the
APIs.
• E164 international format, combination of {startFullNumber & endFullNumber} in the APIs
Both formats can be used in the request, Colt recommends the use of e164 format.
Example: French national number range 03.82.50.xx.x0 – x9
• Split format: areaCode = 3, areaCodeExtn = 8250, rangeStart = xxx0 & rangeEnd = xxx9
• E164 format: startFullNumber = +3338250xxx0 & endFullNumber = +3338250xxx9
Split format to E164 format mapping
Colt Voice API Guide v1.4 14 / 68Austria (+43), Germany (+49), Ireland (+353), Netherlands (+31), Sweden (+46), Switzerland (+41), United Kingdom
(+44):
• startFullNumber = CC + areaCode (without leading 0) + areaCodeExtn + rangeStart
• endFullNumber = CC + areaCode (without leading 0) + areaCodeExtn + rangeEnd
Belgium (+32), Denmark (+45), France (+33), Italy (+39), Portugal (+351), Spain (+34)
• startFullNumber = CC + areaCode + areaCodeExtn + rangeStart
• endFullNumber = CC + areaCode + areaCodeExtn + rangeEnd
Germany (+49)
• startFullNumber = ‘+49’ + areaCode + rangeStart
• endFullNumber = ‘+49’ + areaCode + rangeEnd
• In Italy, e164 format for geo number includes leading zero as well.
• getTelephoneNumberHistory API only supports e164 international format as input (cli field).
• Only split format is supported in numberEnquiry API response.
• Only e164 format is supported in getNumberDetail API response.
• Order Detail response will have the same format as the request.
• {rangeStart & rangeEnd} or {startFullNumber & endtFullNumber} are mandatory, even for single
number.
3.4 End-customer Details
Colt supports the below customerType:
• Business end-customer in all countries
• Residential end-customer in BE, DE, IE, NL, SE (5).
3.4.1 customerType = Business
Please find below fields you need to send to Colt and description:
Parameter Type Country Description
Value = Business
customerType Mandatory BE, DE, IE, NL, SE (5) Note: for other countries, the value
is not expected.
endCustomerName Mandatory All (13) End-customer’s name.
Value =
endCustomerLanguage Mandatory BE (1)
• FR (for French)
• NL (for Dutch)
Colt Voice API Guide v1.4 15 / 68Parameter Type Country Description
• DE (for German)
registeredName Optional BE (1) End-customer’s registered name.
customerVATnumber Mandatory PT (1) Note: in PT = end-customer’s NIF.
customerVATnumber Optional BE (1) End customer VAT number
cifNIF Mandatory ES (1) Your end-customer’s NIF number.
newPortIn API Only
subscriberID Mandatory DK, SE (2) End-customer’s organisation
number.
newPortIn API Only
companyRegistrationNumber Mandatory FR (1)
End-customer’s SIRET number.
3.4.2 customerType = Residential
Please find below fields you need to send to Colt and description:
Parameter Type Country Description
customerType Mandatory BE, DE, IE, NL, SE (5) Value = Residential.
firstName Mandatory DE, IE, NL, SE (4) End-customer’s first name.
firstName Optional BE (1) End-customer’s first name.
lastName Mandatory BE, DE, IE, NL, SE (5) End-customer’s last name.
endCustomerDateOfBirth Mandatory DE (1) Format: dd-mm-yyyy.
Value =
• FR (for French)
endCustomerLanguage Mandatory BE (1)
• NL (for Dutch)
• DE (for German)
3.5 Emergency Address (endCustomerAddress)
Please find below fields you need to send to Colt as part of the address, and associated description:
Colt Voice API Guide v1.4 16 / 68Parameter AT BE DK FR DE IE IT NL PT ES SE CH GB
premisesNumber CM N/A CM CM CM CM M CM CM M M M CM
buildingName CM N/A CM CM CM CM N/A CM CM N/A N/A N/A CM
premisesNumberLetter N/A N/A N/A N/A N/A N/A N/A O N/A N/A N/A N/A N/A
streetName M M M M M M M M M M M M M
streetType N/A N/A N/A N/A N/A N/A N/A N/A N/A M N/A N/A N/A
province N/A N/A N/A N/A N/A N/A N/A N/A N/A M N/A N/A N/A
municipalityName N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A M N/A
cityTown M M M M M M M M M M M M M
postalZipCode M M M M M M M M M M M M M
addressExtension N/A O N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A N/A
With: M = Mandatory, CM = Conditional Mandatory, O = Optional & N/A = Not Applicable.
Colt Voice API Guide v1.4 17 / 684 Number Life Cycle
4.1 Number Status [cliStatus]
Please find below list of cliStatus supported by Colt APIs, with associated country availability & description.
cliStatus Country Description
Free All (13) Colt free number you can search and acquire
Colt Number in your stock.
Reserved All (13) Network is not configured & no end-customer assigned.
Reservation period = 90 days.
Intermediate status for Colt number during activation process.
Allocated All (13)
No action possible.
Colt number in your stock.
Activated All (13) Network is configured & end-customer assigned (variance
applicable for Premium offer).
Following a deactivation, Colt number stays in your stock during
quarantine period as Quarantined.
Quarantined All (13)
Network is not configured & no end-customer assigned.
Quarantine period varies per country.
After port-in order has been confirmed (transactionStatus = Firm
order commitment), ported-In number will appear in your stock
PortIn_Allocated All except DE (12) as PortedIn_Allocated.
Network is not configured & no end-customer assigned.
No action possible.
Ported-In number in your stock.
PortIn_Activated All (13)
Network is configured & end-customer assigned.
Following a deactivation, Ported-In number stays in your stock
during quarantine period as PortIn_Quarantined.
PortIn_Quarantined FR, NL, PT, CH (4)
Network is not configured & no end-customer assigned.
Quarantine period varies per country.
You will find in the next sections possible actions depending on the number status.
Colt Voice API Guide v1.4 18 / 684.2 Colt Number Life Cycle The below diagram provides a view of number status [cliStatus] transition based on API action: 4.3 Ported-In Number Life Cycle The below diagram provides a view of number status [cliStatus] transition based on API action: 4.4 Number Action & Transition The below table provides status transition depending on user action and country: Colt Voice API Guide v1.4 19 / 68
Number Current Next
Country User API
Source cliStatus cliStatus
Colt All (13) Customer numberReservation Free Reserved
Colt All except IT (12) Customer numberActivation Free Activated
Colt All (13) Customer numberActivation Reserved Activated
Colt All (13) Customer cancelReservation Reserved Free
(reservation period
Colt All (13) Colt System Reserved Free
expiration)
AT, DE, FR, IE, IT,
Colt Customer updateDirectoryServices Activated Activated
PT, CH, GB (8)
AT, DE, FR, IE, IT, PortIn_Activat
Ported-In Customer updateDirectoryServices PortIn_Activated
PT, CH, GB (8) ed
Colt BE, DK, FR, IE,
updateEndCustomerAddress
(Premium NL, PT, ES, SE, Customer Activated Activated
- ADD
Only) GB (9)
Activated
Colt & updateEndCustomerAddress Activated
All (13) Customer PortIn_Activat
Ported-In - MODIFY PortIn_Activated
ed
Colt BE, DK, FR, IE,
updateEndCustomerAddress
(Premium NL, PT, ES, SE, Customer Activated Activated
- REMOVE
Only) GB (9)
Colt All (13) Customer numberDeactivation Activated Quarantined
PortIn_Quaran
Ported-In FR, NL, PT, CH (4) Customer numberDeactivation PortIn_Activated
tined
AT, BE, DE, DK,
Ported-In IE, IT, ES, SE, GB Customer numberDeactivation PortIn_Activated Returned
(9)
Colt All (13) Customer numberReactivation Quarantined Activated
Colt All (13) Colt System (quarantine expiration) Quarantined Activated
PortIn_Quaranti PortIn_Activat
Ported-In FR, NL, PT, CH (4) Customer portInReactivation
ned ed
PortIn_Quaranti
Ported-In FR, NL, PT, CH (4) Colt System (quarantine expiration) Returned
ned
Colt All (13) Colt portOut Activated PortOut
Ported-In All (13) Colt portOut PortIn_Activated Returned
Colt Voice API Guide v1.4 20 / 68Number Current Next
Country User API
Source cliStatus cliStatus
Ported-In All (13) Colt portOut PortIn_Activated Transferred
Colt Voice API Guide v1.4 21 / 685 Search & Acquire Number
5.1 Get Local Area Code (LAC) by Address [validateGeoNumber API]
Description
In most countries, National Numbering Plan defines location where geographic number can be used.
It can be seen as a mapping address and first digits of the number (i.e. the LAC), and known at Colt as LAC
Validation.
LAC Validation
validateGeoNumber validateGeoNumberv2 validGeographicAddress (during Activation,
Country
Availability Availability Availability new Port-In &
Update calls)
Austria No No Yes No
Belgium Yes No Yes Yes
Denmark No No Yes No
France Yes No Yes Yes
Germany No No Yes Yes
Ireland Yes No Yes Yes
Italy Yes No Yes Yes
Netherlands Yes No Yes Yes
Portugal Yes No Yes Yes
Spain Yes Yes Yes Yes
Sweden Yes Yes Yes Yes
Switzerland No No Yes No
United Kingdom Yes No Yes No
The validateGeoNumber returns:
• Available LAC for a given address (if only the address is sent).
• Address & number mapping confirmation (if both address and number are sent).
validateGeoNumber is very useful and important to:
• Enable an Address Based Search for free geo number capability by calling next numberEnquiry API,
with the Local Area associated to the address as input.
Colt Voice API Guide v1.4 22 / 68• Ensure your next action (activation, new port-in, update) will be a success at LAC validation stage.
validateGeoNumberv2 allows you to get:
• Same as validateGeoNumber
• Complete address validation & verification
• Applicable for ES and SE
validGeographicAddress developed as a REST JSON API,
• Validate end-customer addresses upfront in Informatica Address Doctor
• Fetch Geo & non Geo (e.g. Nomadic) area codes for a successfully validated address
• Return an Address ID / key for a successfully validated address, which can then be used:-
• To fetch address details during number association (activation, new port-in, update APIs), instead of
providing the address again
• To retrieve all your validated addresses
• Mitigate & reduce the volume of business failures due to incorrect addresses
• Submit orders cleanly
• Be regulatory compliant
Input parameter(s)
Parameters vary depending on the country. Please find below a summary:
validateGeoNumber validateGeoNumberv2 validateGeographicAddress
Country
Address Parameter(s) Address Parameter(s) Parameter(s)
Austria N/A N/A Complete address
Belgium postalZipCode N/A Complete address
Denmark N/A N/A Complete address
France cityTown, postalZipCode N/A Complete address
Germany N/A N/A Complete address
Ireland cityTown N/A Complete address
Italy cityTown N/A Complete address
Netherlands cityTown N/A Complete address
Portugal cityTown N/A Complete address
Spain cityTown, postalZipCode Complete address Complete address
Colt Voice API Guide v1.4 23 / 68validateGeoNumber validateGeoNumberv2 validateGeographicAddress
Country
Address Parameter(s) Address Parameter(s) Parameter(s)
Sweden cityTown Complete address Complete address
Switzerland N/A N/A Complete address
United
postalZipCode N/A Complete address
Kingdom
• Please check Service Matrix for complete scenarios description and error handling.
• In AT, LAC validation is not implemented at Colt but required to be followed.
• For DE, validateGeoNumber API is decommissioned. validGeographicAddress to be used for address
validation
Example for validateGeographicAddress REST JSON API:
Request Response
validateGeographicAddress {"validGeographicAddress": [{
{ "addressID": "1-828ZN5",
"validGeographicAddress":{ "validationDate": "11/03/2020 03:58:41",
"geographicAddress":{ "validationStatus": "Valid",
"alias":"", "geographicAddress": {
"streetName":"Hauptstraße", "alias": "",
"streetNumber":"", "streetName": "Hauptstr.",
"streetType":"", "streetNumber": "",
"extension":"", "streetType": "",
"premisesNo":"40", "extension": "",
"premisesLetter":"", "premisesNo": "40",
"premisesName":"", "premisesLetter": "",
"stairCase":"", "premisesName": "",
"doorNo":"", "stairCase": "",
"department":"", "doorNo": "",
"floor":"", "department": "",
"floorSuite":"", "floor": "",
"flatNumber":"", "floorSuite": "",
"poBoxNumber":"", "flatNumber": "",
"cifNIF":"", "poBoxNumber": "",
Colt Voice API Guide v1.4 24 / 68Request Response
"province":"", "province": "Nordrhein-Westfalen",
"municipality":"", "municipality": "",
"city":"Vorhelm", "city": "Ahlen",
"postalCode":"59228", "postalCode": "59227",
"district":"", "district": "",
"state":"", "state": "",
"country":"DE" "country": "DE",
} "provinceCode": "",
} "municipalityCode": "",
} "areaDetails": [{"areaCode": "2528"}],
"nomadicLAC": [
{"nomadicLAC": "3221"},
{"nomadicLAC": "3222"}
]
}
}]}
5.2 Get Free Geo Number by Local Area [numberEnquiry API]
Description
The number Enquiry API returns list of free numbers for a given Local Area.
Input parameter(s)
In all countries except Germany (DE), you need to send the below parameters as input:
Parameter Type Value
cliStatus Mandatory Value = ‘Free’
Your search criteria.
geoblockDetails/areaCode Mandatory Ex (GB): 0208 for London, ex (FR): 1 for Area
17018.
Mandatory (FR
geoblockDetails/areaCodeExtn Your search criteria.
Only)
Colt Voice API Guide v1.4 25 / 68Parameter Type Value
Ex (FR): 7018 for Area 17018.
Your search criteria. Values are:
geoblockDetails/blockSize Mandatory • In all countries except AT: 1, 10, 100.
• In AT: 1.
Your search criteria. Values are from 1 to 9.
geoblockDetails/quantity Optional
Default value (if not passed) = 1.
numberType Mandatory Value = ‘Geo’
numberCategory Mandatory Value = ‘IPGEO’
In Germany (DE) & for single number, you need to send the below parameters as input:
Parameter Type Value
cliStatus Mandatory Value = ‘Free’
Your search criteria.
geoSingleNumbersDetails/areaCode Mandatory
Ex (DE): 69 for Frankfurt.
numberType Mandatory Value = ‘Geo’
numberCategory Mandatory Value = ‘IPGEO Single’
In Germany (DE) & for range , you need to send the below parameters as input:
Parameter Type Value
cliStatus Mandatory Value = ‘Free’
Your search criteria.
geoblockDetails/areaCode Mandatory
Ex (DE): 69 for Frankfurt.
Your search criteria. Please refer to Service
geoblockDetails/blockSize Mandatory
Matrix.
numberType Mandatory Value = ‘Geo’
numberCategory Mandatory Value = ‘IPGEO Range’
Colt Voice API Guide v1.4 26 / 68Output/Response
List of number matching your request will be returned. In the scenario where Colt would not have enough
capacity to meet your request, the closest quantity will be returned.
Please find below port of response for 2 single number search in London:
0208
080
9645
9645
Free
0208
080
9664
9664
Free
• Please refer to Colt Geo coverage file to get list of Local Area
• In FR, the Local Area is 5 digits long, without leading 0. In Colt API, Local Area is combination of
areaCode as first digit (value = 1,2,3,4,5) & areaCodeExtn as remaining 4 digits.
5.3 Get Free Location Independent Number [numberEnquiry API]
Description
The number Enquiry API returns list of free Location Independent Numbers.
Input parameter(s)
You need to send the below parameters as input:
Parameter Type Value
cliStatus Mandatory Value = ‘Free’
Colt Voice API Guide v1.4 27 / 68Parameter Type Value
Your search criteria. Values are the same as Geo
nonGeoblockDetails/blockSize Mandatory
search.
Your search criteria. Your search criteria. Values
nonGeoblockDetails/quantity Optional are the same as Geo search.
N/A in DE.
numberType Mandatory Value = ‘Non Geo’
numberCategory Mandatory Value = ‘VOIP’
Output/Response
List of number matching your request will be returned. In the scenario where Colt would not have enough
capacity to meet your request, the closest quantity will be returned.
• Location Independent is not available in BE, FR, DK, PT (4).
5.4 Get Free 0330 & 0333 Number in the UK [numberEnquiry API]
Description
The number Enquiry API returns list of free UK ‘03’ numbers. 2 categories are available:
• ‘UK WIDE (Any Users)’
• ‘UK WIDE (Public Services & Not for Profit)’
Input parameter(s)
Parameter Type Value
cliStatus Mandatory Value = ‘Free’
nonGeoblockDetails/blockSize Mandatory Values: 1, 10, 100.
Your search criteria. Values are from 1 to 9.
nonGeoblockDetails/quantity Optional
Default value (if not passed) = 1.
Colt Voice API Guide v1.4 28 / 68Parameter Type Value
numberType Mandatory Value = ‘Non Geo’
Value =
numberCategory Mandatory • ‘UK WIDE (Any Users)’
• ‘UK WIDE (Public Services & Not for
Profit)’
Output/Response
List of number matching your request will be returned. In the scenario where Colt would not have enough
capacity to meet your request, the closest quantity will be returned.
• Search by AreaCode is not available.
5.5 Acquire Number [numberReservation & numberActivation APIs]
Description
Once you have identified number you would like to purchase, you can acquire it by calling below API(s):
API Description
Only if cliStatus = ‘Free’
• Number will be available in your inventory for 90 days. After that period, number will
go back to free status.
numberReservation
• Number will not be assigned to an end-user yet, meaning end-user information such
as name, address, … are not required.
• Network is not configured and number cannot be reached.
Only if cliStatus = ‘Free’ or ‘Reserved’
• Number will be assigned to an end-user, meaning end-user information such as
numberActivation
name, address, … are mandatory.
• Network will be configured and number will be ready to be used.
Input parameter(s)
Below are parameters you need to send to Colt:
Parameter Country numberReservation numberActivation Description
[endCustomerDetails] All (13) N/A Mandatory Please refer to section 3.4
Colt Voice API Guide v1.4 29 / 68Parameter Country numberReservation numberActivation Description
(Optional for
Premium)
Mandatory
[endCustomerAddress] All (13) N/A (Optional for Please refer to section 3.5
Premium)
startFullNumber All (13) Mandatory Mandatory Please refer to section 3.3
endFullNumber All (13) Mandatory Mandatory Please refer to section 3.3
custReference All (13) Optional Optional Please refer to section 2.7
FR, IT, PT
SubResellerID N/A Optional Please refer to section 2.10
(3)
[directoryServicesDetails] All (13) N/A Optional Please refer to sections 7.6 & 7.7
userName All (13) Mandatory Mandatory User name placing the request.
cliStatus update
Please find below cliStatus update & next possible action(s):
Next Possible
API Called Country Previous cliStatus New Status
Action(s)
numberReservation All (13) Free Reserved Activate, Return
numberActivation All (13) Reserved Activated Update, Return
numberActivation All except IT (12) Free Activated Update, Return
Output/Response
A transactionID will be generated and returned back to you.
The transactionStatus will be ‘In progress’, until process completion.
• Only full range can be reserved or activated.
• Direct activation (Free to Activated) is not available in IT.
• LAC Validation might be applicable in some country as part of the process. Please refer to section 5.1.
Colt Voice API Guide v1.4 30 / 68Colt Voice API Guide v1.4 31 / 68
6 Port-In
6.1 Port-In Life Cycle
High level process, from submission to completion, can be summarized as per the below image:
6.1.1 Order Status [transactionStatus]
port-In transaction might have additional status [transactionStatus] than the ones described in the section
2.5.
Please find below list of the ones applicable to port-in orders:
transactionSta
Country Description
tus
Order validation is pending at Colt end. Status is applicable:
Validation In All except − As first status after order submission.
Progress NL (12)
− After customer has provided additional, i.e. after ‘Customer feedback
awaited’
Submitted to
All (13) The order has been sent to releasing operator for port negotiation.
operator
Order has been confirmed by the losing operator with:
− The First Possible Date (FPD) in the Netherlands (usually within the next
48 hours).
• FPD is the soonest date numbers can be ported-in. It can be any
Firm order day within the next 120 calendar days.
All (13)
commitment
• Please note that an overall FPD will be returned for order with
multiple ranges and different FPD.
• You can schedule the port (optional).
− Agreed port date & window in the other countries.
Colt Voice API Guide v1.4 32 / 68transactionSta
Country Description
tus
Once the FPD is reached, order status will change automatically to ‘Ready for
Porting Initiation’. You can initiate or schedule the Port within the next 90
Ready for calendar days.
porting NL (1)
Please note that order will automatically expire 90 calendar days after FPD if
Initiation
port has not been initiated. Email notification will be sent 10 days before
expiration, every day until expiration.
Porting All except
Port has been initiated by Colt.
initiated NL (12)
Port has been completed.
Completed All (13)
No further action possible.
Customer
All except Additional information are required by Colt and/or the releasing operator.
feedback
NL (12) Please note order will expire after 72 hours if no update provided by customer.
awaited
All except
Delayed Port has been delayed. Colt will provide the reason.
NL (12)
Order automatically expires after:
• 90 calendar days after the FPD if initiation has not been performed in
the Netherlands.
Expired All (13)
• 72 hours for order in ‘Customer Feedback Awaited’ status (i.e. if you
have not provided updates to the order) in the other countries.
No further action will be possible.
Cancelled All (13) Order has been cancelled. No further action will be possible.
Order has been rejected by Colt. Rejection code and reason will be shared.
Rejected All (13)
No further action will be possible.
All except The port has been rolled back to the releasing operator.
Porting failed
NL (12) No further action will be possible.
Colt Voice API Guide v1.4 33 / 686.1.2 Port-In in the Netherlands
The below diagram provides a view of transaction status [transactionStatus] transition based on API action:
Please note that Port-In process is fully automated with direct connection to National Porting Database (COIN).
Colt Porting Desk only manages complex and Out of Hours orders.
6.1.3 Port-In in the Other Countries
The below diagram provides a view of transaction status [transactionStatus] transition based on API action:
• Applicable in Austria, Belgium, Denmark, France, Germany, Ireland, Italy, Portugal, Spain,
Sweden, Switzerland & United Kingdom (12).
6.1.4 Transaction Action & Transition
The below table provides status transition depending on user action and country:
Current Target
Country User Action
transactionStatus transactionStatus
All except NL (12) Colt System (automated check = OK) (N/A, submission) Validation in progress
All (13) Colt System Automated check NOK (N/A, submission) Rejected
NL (1) Colt System Automated check OK (N/A, submission) Submitted to operator
Validation in
All except NL (12) Colt Submit to Operator Submitted to operator
progress
Colt Voice API Guide v1.4 34 / 68Current Target
Country User Action
transactionStatus transactionStatus
Validation in
All except NL (12) Colt Reject Rejected
progress
Validation in
All except NL (12) Colt Request Customer Feedback Customer feedback awaited
progress
Submitted to
All (13) Colt Confirm Order Firm order commitment
operator
Submitted to
All (13) Colt Reject Rejected
operator
Submitted to
All except NL (12) Colt Request Customer Feedback Customer feedback awaited
operator
Customer
All except NL (12) Customer Modify Port Validation in progress
feedback awaited
Customer
All except NL (12) Colt System No update after 3 working days Expired
feedback awaited
Firm order
NL (1) Colt System N/A Ready for porting initiation
commitment
Firm order
All except NL (12) Colt Notify Customer about delay Delayed
commitment
Firm order
All except NL (12) Colt Activate Port-In Porting initiated
commitment
Ready for porting
NL (1) Customer Activate Port-In Porting initiated
initiation
Ready for porting
NL (1) Colt System No update after 90 calendar days Expired
initiation
All except NL (12) Colt Test successful Porting initiated Completed
All except NL (12) Colt Notify Customer about delay Porting initiated Delayed
All except NL (12) Colt Activate Port-In Delayed Porting initiated
All except NL (12) Colt Initiate Roll Back Delayed Porting failed
Colt Voice API Guide v1.4 35 / 686.2 New Port-In [portIn API]
The portIn API allows you to request a new port-in request to Colt.
Request can be summarized as per the below:
1) Port-In order information
a. End-customer information (name, address…).
b. List of numbers to be ported-in.
c. Porting information (porting form, wish date & time, ….).
d. Phonebook publication details (optional).
2) Attachment
3) Email notification contact details.
Below sections will give you view of information you need to send to Colt.
• Attachment is mandatory for all port-In requests
6.2.1 Request (1/3): Order Information
Input parameter(s)
Please find below information you need to send to Colt:
Parameter Type Country Description
[endCustomerDetails] Mandatory All (13) Please refer to section 3.4
[endCustomerAddress] Mandatory All (13) Please refer to section 3.5
[newCustomerAddress] Optional All (13) Please refer to section 3.5
startFullNumber Mandatory All (13) Please refer to section 3.3
endFullNumber Mandatory All (13) Please refer to section 3.3
customerRef Optional All (13) Please refer to section 2.73.3
All except FR,
subResellerID Optional Please refer to section 2.10
IT, PT (10)
All expect NL
currentOperator Mandatory Please refer to porting matrix
(12)
Colt Voice API Guide v1.4 36 / 68You can also read
