Customer Registration Number (VAT) validation API

API to validate the VAT / tax ID of an end-customer against the information held by the EU Commission

Read more about Customer Registration Number (VAT) validation API

API Details:

Status	LIVE
Version	v1
Maturity status	Production
Endpoint (Production)	https://apis.colt.net/common-services/v1/check-vat-number
Endpoint (Sandbox)	https://sandbox.apis.colt.net/common-services/v1/check-vat-number

commonServices_v1.0.0_22Nov2024_1.yaml (10.64 KB)

Title

In May 2024 we have introduced an external check on the CIF/NIF/VAT ID in Portugal and Spain against the European Commission’s VAT Information Exchange System (VIES). – see: https://europa.eu/youreurope/business/taxation/vat/check-vat-number-vies/index_en.htm. The reason is to improve the accuracy and validity of orders for new numbers and ports as explained below:

The VAT ID/CIF is included in the CVP generated by Colt for an end-customer and is highly confidential. The CVP was introduced by the PT Regulator, Anacom, to give greater security to end-customers. End-customers must include their CVP in a future port order to prove their request is genuine.
As requested by the ES Regulator, CNMC, the VAT ID/CIF/NIF must be uploaded into the emergency database in Spain and be an exact match to the registered end-customer name.

In Numbers on Demand portal you will see the extra validation step on the CIF/NIF/VAT ID in Portugal & Spain when activating a number, porting-in a number and updating an end-customer address, including bulk orders. In both Portugal and Spain if your end-customer has only recently registered for VAT and their details are not yet in VIES, then you can enter their VAT ID by selecting “NIF//CIF/VAT ID not registered” and your order will proceed as normal.

New REST API will be available for VAT validation based on VIES API (check-vat-number) and make available to the customer.

NIF/VAT is mandatory parameter for PT.
NIF/CIF/VAT and customer name is mandatory parameter for ES.

Please click here for the OAS Specification for VAT validation APIs

Please note: the Vies API doesn't not support the check of freelancers' DNI IDs as part of the VAT ID checker. Please select the VAT ID not registered option to bypass the check.

field “companyNumberRegistered” in /v1/order/{orderId} API.

Vies API will validate VAT/NIF for PT.
Vies API will validate VAT/CIF/NIF + customer name for ES.

“companyNumberRegistered” as an optional parameter in below APIs with accepted values as ‘Yes’ and ‘No’:

/v1/activation/order
/v1/updateCustomer/order
/v1/portIn/order

Our full list of terms and conditions, alongside our acceptable use policy is available below.

Read our terms and conditions

Mandatory fields:

Country, endCustomerName and companyRegistrationNumber (Spain)

country and companyRegistrationNumber (Portugal)

Spain:

Request	Response
{ "country": "ES", "companyRegistrationNumber": "A81626905", "endCustomerName": "Colt Technology Services SA" }	{ "country": "ES", "companyRegistrationNumber": "A81626905", "requestDate": "2025-03-10T11:17:48.372Z", "valid": true, "endCustomerName": "Colt Technology Services SA", "endCustomerNameMatch": true }

Request

Response

{

"country": "ES",

"companyRegistrationNumber": "A81626905",

"endCustomerName": "Colt Technology Services SA"

}

{

"country": "ES",

"companyRegistrationNumber": "A81626905",

"requestDate": "2025-03-10T11:17:48.372Z",

"valid": true,

"endCustomerName": "Colt Technology Services SA",

"endCustomerNameMatch": true

}

Request	Response
{ "country": "ES", "companyRegistrationNumber": "12345", "endCustomerName": "Colt" }	{ "country": "ES", "companyRegistrationNumber": "12345", "requestDate": "2025-03-10T11:18:35.346Z", "valid": false, "endCustomerNameMatch": false }

Request

Response

{

"country": "ES",

"companyRegistrationNumber": "12345",

"endCustomerName": "Colt"

}

{

"country": "ES",

"companyRegistrationNumber": "12345",

"requestDate": "2025-03-10T11:18:35.346Z",

"valid": false,

"endCustomerNameMatch": false

}

Portugal:

Request	Response
{ "country": "PT", "companyRegistrationNumber": "PT505289385" }	{ "country": "PT", "companyRegistrationNumber": "505289385", "requestDate": "2025-03-10T11:19:08.103Z", "valid": true, "endCustomerName": "COLT TECHNOLOGY SERVICES, UNIPESSOAL LDA", "endCustomerNameMatch": false }

Request

Response

{

"country": "PT",

"companyRegistrationNumber": "PT505289385"

}

{

"country": "PT",

"companyRegistrationNumber": "505289385",

"requestDate": "2025-03-10T11:19:08.103Z",

"valid": true,

"endCustomerName": "COLT TECHNOLOGY SERVICES, UNIPESSOAL LDA",

"endCustomerNameMatch": false

}

Request	Response
{ "country": "PT", "companyRegistrationNumber": "1234" }	{ "country": "PT", "companyRegistrationNumber": "1234", "requestDate": "2025-03-10T11:19:33.997Z", "valid": false, "endCustomerName": "---", "endCustomerNameMatch": false }

Request

Response

{

"country": "PT",

"companyRegistrationNumber": "1234"

}

{

"country": "PT",

"companyRegistrationNumber": "1234",

"requestDate": "2025-03-10T11:19:33.997Z",

"valid": false,

"endCustomerName": "---",

"endCustomerNameMatch": false

}

Voice Billing APIs

APIs to enable you to download daily or consolidated unrated call records (CDRs) for your end-customer billing, or rated monthly CDRs and non-usage charges such as number activation or port-in charges for your cost reconciliation.

Read more about Voice Billing APIs

Voice Billing API Details

Status	LIVE
Version	v1
Maturity status	Production
Endpoint (Production)	https://apis.colt.net/usageManagement/resourceName
Endpoint (Sandbox)	https://sandbox.apis.colt.net/usageManagement/resourceName

Resource Names:

Operation	Resource Name
Unrated CDR	/unratedCallDetailRecord
Generate consolidated unrated CDR	/generateConsolidatedUnratedCallDetailRecord
Consolidated unrated CDR	/consolidatedUnratedCallDetailRecord
Rated CDR	/ratedCallDetailRecord
Non usage report	/nonUsageReport

Call Detail Records API_v1.0.0_06Feb2025.yaml (45.4 KB)

Colt Voice REST Billing API Guide 1.0.docx (517.2 KB)

Title

Voice Billing APIs

Next Gen REST CDR APIs will enable you to download the following:

Daily unrated and/or consolidated unrated CDRs for the products listed below
1. Geographic Number Hosting
2. IN for Resellers (e.g. Freephone, Shared Cost, IN Geo etc.)
3. Voice Line
4. Voice Line (v) (also known as IPVoiceLine)
5. SIP Trunking
6. CIC for Resellers
7. CIC Opc Reseller

monthly rated CDRs for any Colt voice product
non-usage files (.r.cat) containing e.g. Number Hosting order charges, such as new number activation
The existing rules will not change e.g. regarding the availability of the CDRs & non-usage files (e.g. unrated CDRs will continue to be available for the past 90 days only).
The existing CDR download functionality available in Cocom Web Manager and via FTP will continue to be available.

Our full list of terms and conditions, alongside our acceptable use policy is available below.

Read our terms and conditions

Country Code	Country Name
AT	Austria
BE	Belgium
DE	Germany
ES	Spain
FR	France
GB	Great Britain
IE	Ireland
IT	Italy
NL	Netherlands
SE	Sweden
DK	Denmark
PT	Portugal
CH	Switzerland
LU*	Luxembourg
CZ*	Czech Republic
SK*	Slovakia
RO*	Romania
PL*	Poland
FI*	Finland
NO*	Norway
JP*	Japan

*Unrated CDRs for these countries are available for the SIP Trunking service only.

Below is the TMF compliant error payload:

{

"code": "ERR01",

"reason": "string",

"message": "string"

}

Get Unrated CDRs

Twice a day, every day of the week, Colt will deposit a file of Call Detail Records (CDR) on the server.

The exception is for the Global SIP countries such as Luxembourg, the Czech Republic, Slovakia & Romania, where the unrated CDRs are delivered daily.

This will contain all of the CDRs collected by the Colt network since the last file, typically each 12 hours. The CDR files are provided in a pre-defined, fixed length format.

Post Consolidated Unrated CDRs

This feature enables you to place a request for a consolidated CDR file through APIs.

Up to 90 days of CDRs can be requested, e.g. a consolidated file of a week’s worth of CDRs and these files will be delivered to both Colt Online & APIs.

Get Consolidated unrated CDR

Within 2 hours the consolidated CDR file will be available for download via APIs which you used in your request.

The consolidated CDR file will be available to download for 5 days, after that the file will be removed and you will need to submit a new request (if you have not downloaded it).

All Consolidated CDR files delivered have a filename in the following format:-

<profile><orderID>.cdr.zip.

Where:

<profile> is up to 5 alphanumeric and is the applicable profile for the product
<orderID> is the combination of date and unique number returned after requesting for consolidated CDR
.cdr is the extension
.zip is where the file is zipped

Example: AM220120110182.cdr.zip

The CDR file contains only CDR records in a fixed length format. A CDR file is made available twice per day – once in the morning and once in the afternoon. The files are delivered at approximately 9AM and 5PM CET.

The 9 AM CET file contains calls from 4PM CET the previous day until 8AM CET on the current day
The 5 PM CET file contains calls from 8AM CET to 4PM CET on the current day

Please note that CDR files are delivered to your directory 7 days a week and will vary in size depending on the level of traffic that your customers generate.

Please note the exception is for the Global SIP countries such as Luxembourg, the Czech Republic, Slovakia & Romania, where the unrated CDRs are delivered daily at approximately 9 AM CET.

CDR File Format

Character Coding

ASCII

File Mark-up Coding

No structured Mark-Up used
Fixed length records
Fixed length fields, space filled

Compression/Decompression Algorithms

CDR files are delivered in Zip format (Unix Gzip, MS Windows Zip). However, Colt recognizes that this can be difficult for certain companies to receive and the CDR files can be delivered in plain text if required. Please notify the Colt Customer Services if you need the CDR files to be delivered as plain text (Uncompressed) files.

File Name

All unrated CDR files delivered to Colt Online and APIs have a filename in the following format:-

<countrycode>_<profile>_<productidentifier>_<sequence no>_<date>.cdr.gz

Where:

<countrycode> in ISO 2 character format
<profile> is up to 5 alphanumerics and is the applicable profile for the product
<productidentifier> is the product identifier (1-2 alphanumerics) – see table below
<sequence no> is a rolling four digit sequence per <profile>_<product> combination
<date> is YYYYMMDDHHmmss
.cdr is the extension
.gz is where the file is zipped

Product Identifier	Product name
00	Voice Line
10	SIP Trunking
11	IP Voice Line (Voice Line (v))
12	IN for Resellers
15	Geographic Number Hosting
19	CIC for Resellers
20	CIC Opc Reseller

Example: DE_ABC_01_0001_20101208090122.cdr.gz

A standard format for unrated CDRs applies to our reseller and wholesale product portfolio. This standard CDR format is harmonised across all Colt countries and applies to existing and new products going forward in Colt Online.

Please note: There is an ASCII Control Character (Line Feed, HEX 0A) after the last field 19 “End of record”. This Control character generates a new line for the next CDR and shows that the actual CDR ends. Normally you can ignore this control character except you use a HEX-Editor to process your CDRs.

Please Note: The first CDR file will appear in Colt Online after the first call has been made.

Ref	Name	Bytes/ Length	Position	Alpha/ Numeric	Format & Description
1	Origin	20	1	N	Originating CLI with leading 0. Filler spaces must be added to fill in the spaces designated for a field. In the case of IN, the last 4 digits are replaced with ‘x’. In the case of Czech Republic (CZ), Poland (PL), Romania (RO) ,Slovakia (SK), Luxembourg (LUX), Finland (FI) ,Norway (NO), Japan (JP) for SIP Trunking, the Originating CLI starts with the country code In the case of Global IN for Resellers ordered through the UK, the caller’s number will be in the international format, starting with 00 + the country code + the number (omitting the leading zero) e.g. caller calling from a mobile in Romania: 004074582xxxx
2	Destination (Terminating)	20	21	N	Destination 0 = Domestic and National, Destination 00 = International In the case of Czech Republic (CZ), Poland (PL), Romania (RO) ,Slovakia (SK), Luxembourg (LUX), Finland (FI) ,Norway (NO), Japan (JP) for SIP Trunking, the destination starts with the country code
3	Product Type	2	41	N	‘01’=Indirect Service ‘00’ = Direct Service '04' = Direct Service ’06‘=NH Geo Premium ‘07’=NH Geo Wholesale '08'=NH Geo Retail '09'=NH Geo Incoming '10'=NH IN Incoming '79' = SIP Trunking ‘80’ = IP Voice Line (Voice Line (v)) CIC for Reseller is SIP trunk reseller, so cdr format will have product code as ‘79’
4	Date	8	43	N	YYYYMMDD
5	Time	8	51	N	HHMMSSss . Time duration is broken up into tenths of a second. Fractions of a second will be ignored.
6	Duration	8	59	N	Duration of the call to the nearest 1/10^th of a second SSSSSSSs
7	Continuation	1	67	N	‘0’, ‘1’, ‘2’, ‘3’ or ‘5’ – normally a 0. To be used only if calls are greater than 6 hours
8	Switch ID	25	68	N	Unique switch identifier
9	Trunk incoming	25	93	N	Internal use only
10	Trunk outgoing	25	118	N	Internal use only
11	Account Code	20	143	A	Not in use
12	Pulses in	6	163	N	Not in use
13	Pulses generated	6	169	N	Not in use
14	Pulses sent	6	175	A	In use for all IN, Voice & VoIP services in UK & France: Charge Band defined by Regulator(Ofcom UK/Arcep FR) for calls to non-geographic numbers. If no Charge Band is available, the value is 000000 or blank.
15	Service Indicator	4	181	N	0000 for standard calls, 0001 for ISDN calls
16	Charged (C-Num)	20	185	N	Trunk ID shown here for IP Voice Line (Voice Line (v)) and for SIP Trunking In use for IN services – the number to which the IN service number is translated. In the case of Global IN for Resellers ordered through the UK, this number will be in the international format, starting with 00 + the country code + the number (omitting the leading zero)
17	Dialled (D-Num)	20	205	N	In use for IN services (IN service number) In the case of Global IN for Resellers ordered through the UK, the IN service number will be in the international format, starting with 00 + the country code + the number (omitting the leading zero) e.g. Romania freephone number: 0040800890123
18	Carrier	3	225	A	The Reseller profile of up to 3 alphanumerics
19	End of Record	1	228	A	Value of zero is shown
20	Line Feed	1	229	ASCII Control Character	Line Feed (ASCII Control Character not visible in plain text editors

Sample unrated CDRs for Voice Line:-

06971041234 0368751234002011093007235400000007301 00063 OF3XBN33687512340 0000010000010000 0368751234 SV0

06971041234 038203731234002011093007225600000013201 00063 OF3XBN33855523484 0000010000010000 038203731234 SV0

06971041234 066311234002011093007250000000001101 00063 OF3EZLA663121234 0000010000010000 066311234 SV0

Sample unrated CDRs for Voice Line (FR):-

0982406525 0841118663002015082009134390000074070 03300 1088 1062 000000000000 A0050010 0033899108018PBW0 PBW2S

0494270512 0494107021002015082011415520000000540 03302 1503 1503 000000000000 A0050010 0033826106714PAC0 PAC2S

Sample unrated CDRs for SIP Trunking:-

038422001234 081010251234792011060314221108000000000 ZHA CXVIE013038422001234 0000 ABC0

038422001234 0517661234792011060314222708000022440 ZHA CXVIE013038422001234 0000 ABC0

0732388824321 0732771234792011060314261409000013790 ZHA CXVIE0130732388824321 0000 ABC0

0158031234 00351913231234792011060314323700000000210 ZHA CXMAD0130158031234 0000 ABC0

Sample unrated CDRs for SIP Trunking (CZ, FI, JP, LU, NO, RO & SK):-

352206099 442033535570792015091610405600 170 0000 ALB0

420296180311 442033535475792015100911120200 550 0000 AAX0

40312200237 40753086507792015070215113800 1480 0000 BKD0

421232335698 390321393652792015092110045300 90 0000 BKE0

Sample unrated CDRs for IN for Resellers (Freephone & shared cost):-

0129356xxxx 08003581234002011101923483510000008300 01001 3059 0129356xxxx 0000000000000000000000 01618361234 08003581234ADC0

0773777xxxx 08003581234002011101923455270000068380 01001 2702 0773777xxxx 0000000000000000000000 01618361234 08003581234ADC0

0755747xxxx 08003581234002011101923580620000008090 01001 2042 0755747xxxx 0000000000000000000000 01618361234 08003581234ADC0

Sample unrated CDRs for Wholesale SIP:-

0307870098 0230333517082012110610363380000005050 MIA SNCB0103 CXMIT0130307870098 0000 AJC0

0230333517 0307870098092012110610401400000002570 MIA CXMIT013 SNCB01010230333517 0000 AJC0

Sample unrated CDRs for IN Number Hosting:-

0230329xxx 800909395002012102610530410000000730 00225 10270230329xxx 0000000000000000000010 3483954697 39800909395AJB0

Sample unrated CDR for Global IN for reseller (CA, CZ, FI, HK, JP, NO, RO & US):-

004074582xxxx 0040800890020002018032308352100000000240 00000 004074582xxxx 0000 00 0040800890020DMP0

004074582xxxx 0040800890020002018032308394500000000240 00000 004074582xxxx 0000 00 0040800890020DMP0

Every month Colt will deposit a file of rated Call Detail Records (CDR) on the server which provide further details of the total call usage displayed on your Cotl invoice for our Voice, VoIP & IN products.

This will contain all of the CDRs collected by the Colt network since the last monthly file.

Response Schema

string($binary)

Every month Colt will deposit a file of non-usage charges on the server which provide further details of the total transactional charges displayed on your Colt invoice primarily for our Number Hosting service such as number reservation & activation & port-in activation charges.

This will contain all of the non-usage charges collected by the Colt network since the last monthly file.

Response Schema

string($binary)

Voice Address Management

A comprehensive set of APIs which enable you to validate an end-customer's address against the recognised national database e.g. Post Office, find a valid Local Area Code (LAC) for a given address and retrieve an address based on an address ID. You can test these API in a sandbox with a “try it out” feature or in production.

Read more about Voice Address Management

API Details

Status	LIVE
Version	v1
Maturity status	Production
Endpoint (Production)	https://apis.colt.net/addressManagement/resourceName
Endpoint (Sandbox)	https://sandbox.apis.colt.net/addressManagement/resourceName

Resource Name

Operation	Resource Name
Validate Address	/v1/validateAddress
FeGettch Local Area Code (LAC)	/v1/LACByLocation
Get Address (using addressID)	/v1/address/{addressID}

addressManagement_v1.0.0_12Mar2024_2.yaml (30.32 KB)

The Address Management APIs can be used to validate address, get Local Area Code (LAC) and retrieve addresses. These API will help you to reduce the order failures, thereby providing improved customer experience. The APIs identifies address components and validates them.

You can use these APIs for all 20 countries (please refer to ‘Country Code’ tab for country list).

The APIs provides field level validation checks, including suggestions if address is partially correct. It also attempts to infer missing or incorrect address components.

It also standardizes the address which can be used for placing activation/port-in/address update orders and also returns/stores the latitude/longitude coordinates (only for Germany) for the provided address.

Please note: In Germany we have a very strict dependency between LAC and address. Also the emergency call routing is based on the address. LAC and emergency Routing code must be identified via the coordinates of the address. Colt will get the coordinates internally via address doctor ADv4 and will allow to fetch the valid Local Area Code.

validateAddress REST API- returns geo coordinates (latitude/longitude) along with validated address in response. These coordinates can be used to fetch the validLAC using the fetchLACbyLocation API.
fetchLACbyLocation REST API- Address is optional Germany but Geo Coordinates (will be returned in validateAddress API response) are required in the request to get the validLAC in response.
If address is valid and LAC or coordinates are not returned in response, please reach out to us with the valid address details.

Our full list of terms and conditions, alongside our acceptable use policy is available below.

Read our terms and conditions

Please find below country codes supported in Colt APIs:

Country	Country Code
Zone A
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
Zone B
Luxembourg	LU
Slovakia	SK
Finland	FI
Norway	NO
Czech Republic	CZ
Romania	RO
Poland	PL

POST/validateAddress API validates the address using country specific parameters.

Parameters vary depending on the country. Please find a summary below:

Country	validateAddress Parameter(S) country wise
Austria, Denmark, , Germany, Netherlands, Sweden, UK, Zone B countries	houseNumber, streetName, city, postalCode, country
France	houseNumber, streetName, streetType, city, postalCode, poBoxNumber, country
Belgium	houseNumber, addressExtension, streetName, subLocality, city, postalCode, country
Italy	houseNumber, streetName, streetType, subLocality, province, city, postalCode, country
Portugal	houseNumber, streetName, city, postalCode, sublocality, country
Spain	houseNumber, streetName, streetType, province, city, postalCode, country
Switzerland	houseNumber, streetName, city, postalCode, country
Ireland	houseNumber, streetName, sublocality, city, postalCode, county, country

GET/LACByLocation API to get Local Area Code (LAC) for a given location.

Below parameters are required to fetch the LAC along with country code.

Country	Complete address	Coordinates (latitude/longitude)	postalCode	city	province	houseNumber
GB	-	-	Yes	-	-	-
Spain	-	-	Yes	Yes	-	-
Belgium	-	-	Yes	-	-	-
Netherlands	-	-	Yes	-	-	Yes
Ireland	-	-	-	Yes	-	-
Italy	-	-	-	Yes	Yes	-
Portugal	-	-	Yes	Yes	-	-
Sweden	-	-	Yes	-	-	-
Germany	Yes (Optional)	Yes	-	-	-
Austria, France, Denmark, Switzerland		Enter any parameter, all LACs will be returned

‘additionalInfo’ will return comments from Colt if you’re trying to find a LAC which is valid but available for Wholesale SIP (Number Hosting).

GET/address/{addressID API to get address for a given addressId.

Request	Response
https://apis.colt.net/addressManagement/v1/address/1-C5QUF3?country=DE	{ "houseNumber": "18", "streetName": "GERVINUSSTRAßE", "subLocality": "WESTEND-NORD", "city": "FRANKFURT AM MAIN", "province": "HESSEN", "postalCode": "60322", "country": "DE", "addressID": "1-C5QUF3", "latitude": "50.12206", "longitude": "8.67208" }

Request

Response

https://apis.colt.net/addressManagement/v1/address/1-C5QUF3?country=DE

{

"houseNumber": "18",

"streetName": "GERVINUSSTRAßE",

"subLocality": "WESTEND-NORD",

"city": "FRANKFURT AM MAIN",

"province": "HESSEN",

"postalCode": "60322",

"country": "DE",

"addressID": "1-C5QUF3",

"latitude": "50.12206",

"longitude": "8.67208"

}

Wholesale SIP Number Management

A comprehensive set of APIs which underpin Colt’s Wholesale SIP service. These APIs enable you to activate new phone numbers and port-in existing phone numbers to Colt in a sandbox environment with a “try it out” feature or in the production environment.

Read more about Wholesale SIP Number Management

API Details:

Status	LIVE
Version	v1
Maturity status	Production
Endpoint (Production)	https://apis.colt.net/numberManagement/resourceName
Endpoint (Sandbox)	https://sandbox.apis.colt.net/numberManagement/resourceName

Below are the list of Wholesale SIP APIs (with resource names)

Operation	API resource name	Method	Description
Search free number(s)	/v1/freeNumber	GET	Allows you to get list of free numbers
Search number(s) from the inventory	/v1/Number	GET	Allows you to search your number from your number inventory with multiple search criteria (by status, customer reference, orderID, CLI details). You can also fetch the number details (end customer name, status, address, customer Registration Number) by providing numberRangeStart and numberRangeEnd parameters
Reserve number(s)	/v1/reservation/order	POST	Allows you to add or reserve number in stock without endcustomer assignment nor network configuration. Number will be reserved for 90 calendar days.
Return number(s)	/v1/return/order	POST	Allows you to return the number to Colt by cancelling the reservation of reserved numbers and deactivating Activated/Port-in Activated numbers.
Activate number(s)	/v1/activation/order	POST	Allows you to assign number to an end-customer and activate on Colt network.
Update end customer details and directory service details	/v1/updateCustomer/order	POST	Allows you to update activated number details, e.g. emergency address and Directory services(for few countries only) etc.
Port number(s)	/v1/portIn/order	POST	Allows you to create new port-in order. Please note: Out of hours porting is chargeable.
Update porting order	/v1/portUpdate/order	POST	Allows you to updatea porting order (change date, cancel, modify, send notes, accept/reject port out order, schedule port, activate port)
Portability checker	t/v1/checkPortability	POST	API to allow you to confirm whether a number/range can be ported-in
Reactivate number(s)	/v1/reactivation/order	POST	Allows you to reactivate colt owned or ported in numbers. Number will be reassigned to the same end-user, Network will be reconfigured, and number will be ready to be used again.
Bulk activation	/v1/bulkActivationOrder	POST	Allows you to send bulk request for activation API.
Bulk portIn	/v1/bulkPortInOrder	POST	Allows you to send bulk request for portIn API.
Bulk end customer/ DS details	/v1/bulkUpdateCustomerDetailsOrder	POST	Allows you to send bulk request for address/DS update API.
Fetch list of orders	/v1/order	GET	Allows you to get list of orders matching your search criteria.
Fetch order details	/v1/order/{orderId}	GET	Allows you to get details for a specific order.
CLI Order History	/v1/CLIOrderHistory	GET	Allows you to get list of orders for a specific number.
Fetch free number count	/v1freeNumberCount	GET	RESTRICTED USE ONLY allows you to get the count of free numbers for given LAC
Lock free numbers	/v1/lockFreeNumbers	POST	RESTRICTED USE ONLY allows you to get the list of free numbers in locked state for 10 mins for a given LAC
Request for free numbers backfill	/v1/freeNumberBackfill/order	POST	RESTRICTED USE ONLY Allows you to request for free number backfill for a specific location
Cancel backfill request	/v1/cancelFreeNumberBackfill/order	POST	RESTRICTED USE ONLY Allows you to cancel a free number backfill request which has been submitted and which is not yet fulfilled.

Please note: If you use the "Try it out" feature in the production environment, then charges will apply as per your Wholesale SIP ratecard. For more information on pricing, please contact your Account Manager.

numberManagement_v1.0.0_05Feb2025_R18_0.yaml (235.19 KB)

Free number search.docx (78.53 KB)

Reserve numbers_0.docx (80.6 KB)

Activate numbers.docx (202.5 KB)

Update address and directory service details_0.docx (209.79 KB)

Check Portability.docx (60.02 KB)

Port In Numbers.docx (278.79 KB)

Return Number.docx (50.64 KB)

Reactivate Number.docx (50.22 KB)

Get inventory details.docx (238.31 KB)

Order Management.docx (119.37 KB)

Lock and Backfill Numbers.docx (235.87 KB)

Title

Introducing Wholesale SIP Trunking APIs

Wholesale SIP (Number Hosting) is Colt Wholesale SIP trunking with on Demand Number Management supporting high volume transactions (reservation, activation, porting) via our Numbers on Demand (NOD) portal and our APIs. We have pan-European coverage in 20 countries, with full regulatory compliance and a uniform experience for Carrier Grade SIP Trunks.

Wholesale SIP addresses Service Providers with their own VoIP platform who want to build, integrate and sell their own VoIP & Cloud solutions under their own brand to their business end-customers. We are the digital infrastructure provider, underpinning Hyperscalers' & OTTs' growth in the Cloud Voice market.

We are a one stop shop, enabling you to order new geographic & nomadic numbers, as well as Port-In numbers over API and in our NOD portal for your end-customers. This gives you an opportunity to simplify your business processes, build E2E automation, and deliver a high quality end-customer experience.

Colt Wholesale SIP APIs are based on REST JSON. Our Next Gen REST APIs:

Conform to the Industry standard REST-JSON APIs
Align with TMF conventions
Support OAuth2.0 and JWT based authentication and authorization
Support open API specifications (earlier swagger)
Support flexible version management
Optimized fields and offer a standard format for numbers, date-time, etc.

List of Wholesale SIP (Number Hosting) Countries

Please find below country supported in Colt APIs:

Country	Country Code
Zone A
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
Zone B
Luxembourg	LU
Slovakia	SK
Finland	FI
Norway	NO
Czech Republic	CZ
Romania	RO
Poland	PL

Our full list of terms and conditions, alongside our acceptable use policy is available below.

Read our terms and conditions

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:

Bestimmung der Anzahl zuzuteilender Rufnummern bei durchwahlfähigen VoIP-Anschlüssen
http://www.bundesnetzagentur.de/cln_1431/DE/Sachgebiete/Telekommunikation/Unternehmen_Institutionen/Nummerierung/Rufnummern/ONRufnr/Ortsnetze_Basepage.html?nn=268384

(Struktur und Ausgestaltung des Nummernbereichs für Ortsnetzrufnummern)

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 a block greater than 100, the 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 the customer’s responsibility 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.

Austria

There is a private numbering plan in Austria. When you assign a single main number to an end-customer, the end-customer can configure or add digits/extensions (0-9 or 00-99 or 000-999 or 0000-9999) to the main number in their PBX, as per their needs. You do not need to inform Colt of the range of extensions/digits when (de/re) activating a number, submitting a port-in order or sending an address update – these transactions require the main number only. The end-customer’s emergency address is entered and stored at the main number level, and not at the extension level.

France: Hosted customer numbers

There are 2 important Regulatory changes impacting the use of phone numbers in France, which came into effect on 1st January 2023:-

1. The resale of geographic and location independent numbers for outbound voice services is forbidden

2. France no longer has 400+ local area codes. 01-05 numbers are available for use throughout mainland France

ARCEP, the Regulator in France, published further information on these changes here: https://www.arcep.fr/uploads/tx_gsavis/22-1583.pdf

If you are reselling Colt numbers to your end-customers under your own brand, then you need to take action to register with ARCEP and obtain your own numbers, which Colt can then host on your behalf. You can contact your Colt Account Manager to complete the order form to host your number blocks with Colt. For further information, please refer to these links to the Customer Q&A in English and in French.

Hosting your numbers

When we confirm your own numbers are available to use, you will be able to reserve and (pre)activate your own numbers, update addresses etc. As a result of the Regulatory changes above you will only need to search for numbers on the basis of the LAC: 01-05 and the LAC extension or search by city will no longer be available - should you need the historical reference, please refer to the Number Coverage file. Your own numbers will be available in ranges of 1, 10, 100 as requested in your order form. If you run out of single numbers, then our system will automatically take a range of 10 Free numbers and split this into 10 Free single numbers and similar logic applies if you run out of ranges of 10 etc. You can also view or query for your Free numbers in France and this enables you to monitor your own inventory and apply to ARCEP for new number blocks in good time – the E2E lead-time is 2-3 months depending on ARCEP, Orange & OLO availability during busy periods.

If you have obtained your own routing/porting prefix in France then you can select this when you port-in a number.

We will return deactivated numbers from your number blocks to your “free” pool of numbers at the end of the quarantine & frozen period. We will return numbers which were ported-out and which have been cancelled / deactivated by the end-customer into your “free” pool of numbers at the end of the quarantine & frozen period, using our established processes & system integration with APNF.

The responsibility to supply compliance reports or to comply with regulatory audits is yours. Colt will provide a clear view of your number inventory - the number status & end-customer data via our APIs & Numbers on Demand which you can use to meet these requests together with your own data.

Tri-partite agreement with Colt numbers

If you do not have your own numbers from ARCEP yet, then from 21^st January 2023 you are responsible for submitting a tri-partite agreement with every order for new Colt number activations. The tri-partite agreement template can be found in English here and in French here. You are responsible for filling in your own company details, the numbers being ordered, entering the accurate address details of your end-customer and obtaining the end-customer’s signature.

France: Introduction of RIO codes for the wider business market

There are some changes to the use of RIO codes in France, which came into effect from 1st December 2023, pursuant to Arcep’s decision no 2022-2148.

A RIO code is a unique identifier associated to a telephone number, which is created when a consumer or small business request a new telephone number in France and its purpose is to facilitate the portability process. If they wish to move / port numbers to a new operator, then the new operator will request the RIO code provided by the current operator for each single telephone number from the consumer / small business in order to validate that the port order is legitimate and to implement the porting order. These RIO codes are not yet mandatory in the wider business market but this will gradually change.

The changes are:

Colt, as a technical operator, must define a unique RIO code for every:
1. Colt geographic or location independent number
2. Geographic or location independent number ported-in to Colt
3. Geographic or location independent number hosted by Colt on your behalf – this includes both new and ported-in numbers where you have mandated Colt as your OPTA (i.e. where we technically manage the porting of your numbers on your behalf)
Colt must make these RIO codes available to you via a secure portal, which is our Numbers on Demand portal and over API and these will be available in our May 2024 release. Up until the May 2024 release, if you require the RIO code for e.g. a consumer / small business port, then please get in touch with [email protected].

It is not foreseen that RIO codes will be required for number portability in the wider business market until 2025, due to the complexity of inter-operator process & system integration work and pursuant to Arcep’s decision.

In a wider context, if you currently support consumers, we would like to remind you that consumer-specific obligations apply pursuant to the regulations, including the provision of an IVR service through which you provide the RIO code associated to a specific number.

As an operator providing voice services in France, you are responsible for portability to your end-customers and other operators, even where Colt is technically managing portability for you as your OPTA. Obligations regarding how the RIO codes should be shared with your subscribers apply, as well as other obligations related to portability (i.e. additional information to be provided to your subscribers, contractual provisions, etc.). Obligations may vary depending on the customer type (business, small business, consumer) and the kind of service you provide (OTT, single-number or multi-number offers, etc.).

For further information please see this decision from ARCEP: https://information.colt.net/hubfs/22-2148_FR_Published%20document_22Mar2023%20en-GB.pdf

The RIO code will be present against each CLI in the Numbers on Demand portal when viewing the ‘Number Details’ and will be returned in the B2B API response (SOAP/HTTPs: getNumberDetails and REST: GET/CLIDetails) as well.

Portugal & Spain: Introduction of CIF/NIF/VAT ID check

The VAT ID/CIF is included in the CVP generated by Colt for an end-customer and is highly confidential. The CVP was introduced by the PT Regulator, Anacom, to give greater security to end-customers. End-customers must include their CVP in a future port order to prove their request is genuine.
As requested by the ES Regulator, CNMC, the VAT ID/CIF/NIF must be uploaded into the emergency database in Spain and be an exact match to the registered end-customer name.

Spain: Number Type offerings

Number Type offerings	‘Geo’	‘Geo-nomadic’	‘Nomadic’
Description	LAC can be used only for the applicable city / town	LAC can be used within the province for any city / town	LAC can be used across entire country of Spain
Local Area Codes (LACs)	LACs starting with 8- Please refer to Number Coverage file present in www.colt.net/cocom	LACs starting with 8- Please refer to Number Coverage file present in www.colt.net/cocom	512/516
Free Number Search	Yes	Yes	Yes
LAC Validation	Yes	Yes	No
Port-in/ Port-Out	Yes	No	No
Quarantine Period	30 calender days	30 calender days	30 calender days
numberType (used for ‘Free’ number search	Geo	Geo	Non Geo

Colt Number Life Cycle

The below diagram provides a view of number status [cliStatus] transition based on API action:

Ported-In Number Life Cycle

The below diagram provides a view of number status [cliStatus] transition based on API action:

Number Format

Colt REST APIs support these number formats:

E164 international format, combination of {startFullNumber & endFullNumber} in the APIs

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

Austria (+43), Belgium (+32), Czech Republic (+420), Denmark (+45), Finland (+358), France (+33), Germany (+49), Ireland (+353), Italy Nomadic (+39), Luxembourg(+352),Netherlands (+31), Norway (+47), Poland (+48), Portugal (+351), Romania (+40), Slovakia (+421), Spain (+34), Sweden (+46), Switzerland (+41), United Kingdom (+44) :

startFullNumber = CC + areaCode (without leading 0) + areaCodeExtn + rangeStart
endFullNumber = CC + areaCode (without leading 0) + areaCodeExtn + rangeEnd

Italy Geo (+39):

startFullNumber = CC + areaCode (with leading 0) + areaCodeExtn + rangeStart
endFullNumber = CC + areaCode (with leading 0) + areaCodeExtn + rangeEnd

Germany (+49)

startFullNumber = CC + areaCode + rangeStart
endFullNumber = CC + areaCode + rangeEnd

Number Status

Please find the list of resourceStatus supported by Colt APIs, with associated country availability & description.

resourceStatus	Country	Description
Free	All	Colt free number you can search and acquire, or customer owned numbers (FR only)
Reserved	All	Colt Number in your stock, and/or customer owned numbers (FR only) Network is not configured & no end-customer assigned. Reservation period = 90 days.
Allocated	All	Intermediate status for Colt number or customer owned numbers (FR only) during activation process. No action possible.
Activated	All	Colt number in your stock, and/ or customer owned numbers (FR only) Network is configured & end-customer assigned (variance applicable for Premium offer).
Quarantined	All	Following a deactivation, Colt number and/or customer owned numbers (FR only) stays in your stock during quarantine period as Quarantined. Network is not configured & no end-customer assigned. Quarantine period varies per country. For zone B country: when Colt perform hard cease, the numbers will move to this status
PortIn_Allocated	All except DE	After port-in order has been confirmed (transactionStatus = Firm order commitment), ported-In number will appear in your stock as PortedIn_Allocated. Network is not configured & no end-customer assigned. No action possible.
PortIn_Activated	All	Ported-In number in your stock. Network is configured & end-customer assigned.
PortIn_Quarantined	FR, NL, PT, CH, SE, ES, IT	Following a deactivation, Ported-In number stays in your stock during quarantine period as PortIn_Quarantined. Network is not configured & no end-customer assigned. Quarantine period varies per country. Port-In Reactivation can be requested
PortIn_Reallocated	FR, NL, PT, CH, SE, ES, IT	When Port-In reactivation is requested, the numbers goes into intermediate status. Network configuration and end customer re-assignment is in progress. No action possible.
Port Out In Progress	All except DE	When a port-out request is raised for Colt-owned numbers which will be ported out from Colt’s network to new operator. No action possible.
Transfer In Progress	All except DE	When a port-out request is raised for Ported-In numbers which will be ported out from Colt’s network and is scheduled to be transferred to new operator. No action possible.
Return In Progress	All except DE	When a port-out request is raised for Ported-In numbers which will be ported out from Colt’s network and is scheduled to be returned to the original range holder. No action possible.
PortOut	All	When Colt-owned numbers are ported out from Colt’s network
Transferred	All except DE	When a ported-in number is ported out of Colt’s network and is transferred to new operator
Returned	All except DE	When a ported-in number is ported out of Colt’s network and is returned to original range holder

Number Action & Transition

The below table provides status transition depending on user action and country:

Number Source	Country	User	REST API (resource name)	Current cli status	Next cli status
Colt	All	Customer	/v1/reservation/order	Free	Reserved
Colt	All except IT	Customer	/v1/activation/order	Free	Activated
Colt	All	Customer	/v1/activation/order	Reserved	Activated
Colt	All	Customer	/v1/return/order	Reserved	Free
Colt	All except Zone B countries	Colt System	(reservation period expiration)	Reserved	Free
Colt (Premium Only)	All except DE	Customer	Address Update- (ADD) REST API /v1/updateCustomer/order	Activated	Activated
Colt & Ported-In	All	Customer	Address Update- (MODIFY) REST API /v1/updateCustomer/order	Activated PortIn_Activated	Activated PortIn_Activated
Colt	All	Customer	/v1/return/order	Activated	Quarantined
Ported-In	FR, NL, PT, CH, ES	Customer	/v1/return/order	PortIn_Activated	PortIn_Quarantined
Ported-In	AT, BE, CH, DK, IE, IT, SE, GB	Customer	/v1/return/order	PortIn_Activated	Returned
Colt	All	Customer	/v1/reactivation/order	Quarantined	Activated
Colt	All except Zone B countries	Colt System	(quarantine expiration)	Quarantined	Activated
Ported-In	FR, NL, PT, ES, SE, CH	Customer	/v1/reactivation/order	PortIn_Quarantined	PortIn_Activated
Ported-In	FR, NL, PT, CH, ES	Colt System	(quarantine expiration)	PortIn_Quarantined	Returned
Colt	All (20)	Colt	portOut (Internal only)	Activated	PortOut
Ported-In	All (20)	Colt	portOut (Internal only)	PortIn_Activated	Returned
Ported-In	All (20)	Colt	portOut (Internal only)	PortIn_Activated	Transferred

Order ID

After order creation, a unique ID [orderID] will be returned to you.

orderID follows the below pattern and format:

	Description
Pattern	32 character long (128 bit)
Format	“[A-Za-z0-9\-]{1,36}“
Maximum length	36, including ‘-’ characters
Example	8700206f-c3b3-4c10-8cc2-2490f41eedc0

Order Status

Your order will have a status [orderStatus], 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 orderStatus and description:

orderStatus	Description	Next action
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 error	This error, also known as a business error Occurs when you have submitted incorrect information.	Please review the error message, correct and resubmit the request.

Please note: If a failure occurs whilst updating the Emergency Database for the order types below, a message: “Your order is technically completed and pending for emergency database update" will be shared as a new Order Description. Order types are:-

Activation
Deactivation
Address Update
Reactivation
Port-In
Port-Out

Email notifications will be triggered for Port-In and Port-Out orders with the same message. Post the successful completion of an order which reflects the successful update of the Emergency Database, the order description will be updated to: “Request has been processed successfully.”

Applicable for all countries except DE, DK and Zone B.

Porting related orders have multiple updates, at each key order milestone.

For port updates, Colt API will return a new orderID, named ‘Child Order ID’.
Please track child orderID to get status of the update (mainly for cancellation & date change) and please continue to track parent ID to get order status.

Please refer to porting sections for more information.

Please find below list of the ones applicable to Port-In orders:

orderStatus	Country	Description
Validation In Progress	All except NL	Order validation is pending at Colt end. Status is applicable: As first status after order submission. After customer has provided additional, i.e., after ‘Customer feedback awaited’
Submitted to operator	All	The order has been sent to releasing operator for port negotiation.
Firm order commitment	All	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 day within the next 120 calendar days. 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.
Ready for porting Initiation	NL	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 calendar days. Please note that order will automatically expire 90 calendar days after FPD if port has not been initiated. Email notification will be sent 10 days before expiration, every day until expiration.
Porting initiated	All except NL	Port has been initiated by Colt.
Completed	All	Port has been completed. No further action possible.
Customer feedback awaited	All except NL	Additional information is required by Colt and/or the releasing operator. Please note order will expire after 72 hours if no update provided by customer.
Delayed	All except NL	Port has been delayed before the initiation of porting. Colt will provide the reason.
Porting Completion Delayed	All except NL	Port has been delayed after the initiation of porting. Colt will provide the reason.
Expired	All except NL	Order automatically expires after: 90 calendar days after the FPD if initiation has not been performed in the Netherlands. 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	Order has been cancelled. No further action will be possible.
Rejected	All	Order has been rejected by Colt. Rejection code and reason will be shared. No further action will be possible.
Porting failed	All except NL	The port has been rolled back to the releasing operator. No further action will be possible.

For more details on Porting, please click here.

Port-In in the Netherlands

The below diagram provides a view of order status 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.

Port-In in the Other Countries

The below diagram provides a view of order status transition based on API action:

When a port-out request will be received by Colt from another provider, Colt will create a portOut order and notification will be sent to you. In some countries, you will be asked to confirm or reject the request.

Port Out Order Status

port-out order might have additional status [orderStatus] than the ones described in the section 2.5.

Please find below list of the ones applicable to port-out orders:

orderStatus	Country	Description
Confirmed	All except AT, BE, DE, CH, NL	In countries where your confirmation is not required, this will be the order status, mainly until port-out completion. Number status will be ‘Port out In progress/ Transfer In progress / Return In progress’.
Customer feedback awaited	BE, CH	In countries where your confirmation is required, this will be the first order status. You will be asked to accept or reject the request. Colt will automatically accept the request on your behalf after 2 working days. Daily reminders will be sent to you to accept the port out request once the order is created in “Customer feedback awaited” status. Number status will be ‘Port out In progress/ Transfer In progress / Return In progress’.
Customer feedback awaited	AT, DE	In countries where your confirmation is required, this will be the first order status. You will be asked to accept or reject the request. Colt will automatically accept the request on your behalf after 5 working days Daily reminders will be sent to you to accept the port out request once the order is created in “Customer feedback awaited” status. Number status will be ‘Port out In progress/ Transfer In progress / Return In progress’.
Customer feedback awaited	NL	In NL, where your confirmation is required, this will be the first order status. You will be asked to accept or reject the request. You will have 2 working days to: Accept the request and provide the First Possible Date (FPD) for the Port-Out, Decline the request with the relevant blocking code. Same as port-in, FPD is the soonest numbers can be ported-out and should be any day within the next 120 calendar days. Please note that Colt will automatically accept the request and set the FPD to the next business day on your behalf after 48 hours. Number status will be ‘Port out In progress/ Transfer In progress / Return In progress’.
Rejected	AT, BE, DE, CH, NL	Applicable in countries where your confirmation is required. If you reject the request, this will be the final status. Please always share the rejection reason. No further action.
Confirmed	AT, BE, CH	Applicable in countries where your confirmation is required. If you accept the request, this will be the next status, until order completion or update. Number status will remain in ‘Port out In progress/ Transfer In progress / Return In progress’.
Firm Order Commitment	NL	In NL, after you have accepted the request, the order will be in this status until the First Possible Date (FPD) is reached – or order cancelled.
Ready for porting initiation	NL	In NL, when the First Possible Date (FPD) is reached, the status will be changed automatically, and the gaining operator will be able to initiate the port during the next 90 calendar days. Without action during this period, order will expire.
Expired	NL	Gaining operator did not request the port. No further action.
Port initiated	NL	When the gaining operator has requested the port.
Port Out initiated	All except NL	When the port-out is initiated from Colt or the Gaining Operator
Cancelled	All	Order has been cancelled. No further action.
Completed	All	Port completed. Number is not live on your service anymore. Rollback can be requested for all countries (except NL) by reaching out to Colt’s local porting desk. If the Rollback request is accepted by Colt, then the port-out order will move to ‘confirmed’ status and number status will be ‘Port out In progress/ Transfer In progress / Return In progress’.

Please note: All DE port out orders raised by a registered DE reseller will move to ‘Customer Feedback Awaited’ status and will require confirmation/rejection from the registered DE reseller. If no response received, an order will automatically move to Confirmed status after 5 working days

You can update port-in/out orders using portUpdate/order API.

Port-In Date Change in all countries except NL & IT

Below image provides you high level flow:

A child orderID will be generated, with orderStatus = Validation In Progress.
Parent orderID will remain in the same status until update completion.

Following process completion, child & parent orderStatus will be updated as per the below:

Action	Child orderStatus Update	Parent orderStatus Update
Request accepted by Colt	Accepted	Submitted to operator
Request rejected by Colt	Rejected	No status change

Request can only be performed when orderStatus = ‘Validation in progress’, ‘Firm order commitment’ & ‘Customer feedback awaited’.
Please note that when orderStatus = ‘Firm order commitment’, a date change can only be requested at the latest 2 working days before the agreed port date in all Zone A countries (except FR), 3 working days in Finland, 4 working days in France & other Zone B countries.

Modify Port in all countries except NL

The API allows you to modify your port when the order moves to the ‘Customer feedback awaited’ status. This includes, modify porting date/window, current operator details, CLI list, main billing number, add new attachments and notes.

A child orderID will be generated, with orderStatus = In Progress.
Parent orderID will remain in the same status until update completion. Post completion of child order, parent order will move to Validation in progress status.

Cancellation in all countries except NL

The API allows you to request cancellation of your order. Cancellation has to be approved by Colt Porting Desk.

Below image provides you high level flow:

A child orderID will be generated, with orderStatus = Validation In Progress.
Parent orderID will remain in the same status until update completion.

Following process completion, child & parent orderStatus will be updated as per the below:

Action	Child orderStatus Update	Parent orderStatus Update
Request accepted by Colt	Accepted	Cancelled
Request rejected by Colt	Rejected	No status change

Request can only be performed when orderStatus = ‘Validation in progress’, ‘Submitted to operator’, ‘Firm order commitment’ & ‘Customer feedback awaited’.
Please note that when orderStatus = ‘Firm order commitment’, cancellation can only be requested at the latest 4 working days before the agreed port date in Norway, Czech Republic, Poland, Romania and Slovakia, 3 working days before the agreed port date in Luxembourg, Finland and 2 working days before the agreed port date in the Zone A countries.

You can cancel the reservation of reserved numbers or deactivate any activated/port-in activated numbers using the return/order API.

API	Description
/return/order	Only if cliStatus = Reserved Number will be removed from your inventory and go back to free status.
Only if cliStatus = Activated or PortIn_Activated. Number will either enter the quarantine period or be returned to the range holder. Network configuration will be removed, and number will not be reachable.

API

Description

/return/order

Only if cliStatus = Reserved

Number will be removed from your inventory and go back to free status.

Only if cliStatus = Activated or PortIn_Activated.

Number will either enter the quarantine period or be returned to the range holder.

Network configuration will be removed, and number will not be reachable.

Deactivation journey of NL 088 numbers/ranges.

088 deactivation is immediate upon submission without the 2 month (quarantine) period
Deactivation lead time in regulatory database is 3 working days (day of submission not counted).
Completion will be confirmed/notified to you as soon as numbers are removed from Colt network and on the receipt of the Ack from PTXS upon submission of the deactivation request
No re-instate or re-activation is possible once deactivation is submitted
Numbers will be updated as ‘Returned’

ADD & MODIFY using address update APIs (NL)

Below are for the Netherlands only:-

End Customer Details and the Directory Services entry are Mandatory for Activation, Portin and Address update (ADD) scenarios.
- As the Emergency address is optional, then the end customer details will be populated in the emergency database (if the emergency address is not provided)
- If the Emergency address is provided, then no LAC validation will be done on the emergency address and it will be populated in the emergency database
- LAC validation applies to the End Customer address only

Emergency Address is optional in Address update (action=ADD).
- If the Emergency address is provided, then no LAC validation will be done on the emergency address and it will be populated in the emergency database

In an Address Update(Modify) request the customer can include any or ALL of these as conditional mandatory:
- Directory Services entry, and/or
- the End Customer Address and/or
- the Emergency Address.
- If the Emergency address is provided, then it will be populated in the emergency database. Any new or updated Emergency address will be validated before it is accepted. LAC validation does not apply to emergency address.
- LAC validation applies to the End Customer address only

ADD operation is only applicable to Premium customers and MODIFY is applicable for both Standard and Premium customers.

Phonebook Publication

In Belgium, Ireland, Italy, Portugal, Sweden, Netherlands, Spain, Austria and UK, Colt APIs allows you to provide and update Directory Service as well.

In the Netherlands, you can use the activation, Port-In and address update functionality to provide new or additional Address and Directory Services information at an order and/or at a CLI level.

Please refer to below table while submitting the request for these countries.

API	End customer Details & address + Directory Services update (BE, ES, SE)	End customer Details & address + Directory Services update (NL)	Emergency Address (NL)	End customer Details & address (IE, IT, PT, UK, CH)	Directory Services update (IE, IT, PT, UK, CH)
/activation/order (Pre-activation)	Not applicable	Not applicable	Not applicable	Not applicable	Not applicable
/activation/order	Mandatory	Mandatory	Not applicable	Mandatory	Optional
/updateCustomer/order (ADD)	Mandatory	Mandatory	Optional	Mandatory	Optional
/updateCustomer/order (MODIFY)	Mandatory	any or ALL of these as conditional mandatory: Directory Services entry, and/or the End Customer Address and/or Emergency Address		any or ALL of these as conditional mandatory: Directory Services entry, and/or the End Customer Address	any or ALL of these as conditional mandatory: Directory Services entry, and/or the End Customer Address

Below is the TMF compliant error payload:

{

"code": "ERR01",

"reason": "string",

"message": "string"

}

Error Codes

Below are the error codes which comes as the part of API response

HTTP response Code	code	reason	message	Details
400 Bad request	001	OAS validation failed	{APIGW error message} e.g: Mandatory field missing, pattern not matching, The request is missing APIGWTrackingId.	Colt will return a HTTP-400 error when the request is malformed or invalid. See the message of the error for tips before trying again.
400 Bad request	002	Validation not met	The mandatory parameter/node <> is missing. Allowed length of <field name> in <country name> is <max allowed length> only. Allowed pattern of <field name> in <country name> is <>. <>field only accepts numbers in E164 format. Maximum allowed ranges/CLI is <> (1 for all customers and 20 for Microsoft) Please refer to field wise validation message in next table.
401 Unauthorized	001	Authentication error	The authorization parameter is missing.	Colt will return a HTTP-401 error when the specified user’s authorization parameter is either invalid or missing or expired. Ensure the provided credentials are valid.
	002	Authentication error	Invalid token.
	003	Authentication error	Token expired.
	004	Authentication error	The ClientID/Application ID + country is not valid.
403 Forbidden	001	Resource forbidden	The client application is not authorized to call this resource.	Colt will return a HTTP-403 error when the user does not have access to the API.
404 Not found	001	Resource not found	The requested URI or the requested resource does not exist	Colt will returns a HTTP-404 error when the path is not found. Ensure the request path provided is correct.
405 Method not supported	001	Method not allowed	The requested method is not allowed for this resource.	Colt will return a HTTP-405 error when the HTTP method used in the request is invalid. Check the allowed HTTP methods for this endpoint
415 Unsupported Media Type	001	Unsupported media type	The format of the posted body is not supported by the endpoint.	Colt will returns a HTTP-415 error when the content-type of the request is incorrect. Ensure the request header contains Content-Type: ‘application/x-www-form-urlencoded’ and try again.
429 Too many requests	001	Rate limit exceeded	The application has made too many calls and has exceeded the rate limit for this service	Colt will returns a HTTP-429 error when the rate limit has been reached.
500 Internal server error	001	Internal server error	The server encountered an unexpected error and is unable to process the request at this time	Colt will return a HTTP-500 Error when an unknown error occurs. If you receive a HTTP-500 error from the Colt API
503 Service unavailable	001	service unavailable	The service is temporarily unavailable	Backend unavailable. Colt will return a HTTP-503 error if the service is unavailable for some reason, such as when there are no servers available to serve the request or if the system is at capacity.
504 Gateway timeout	001	Gateway timeout	Gateway timeout	System timed out talking to downstream system

Please click here to access Wholesale SIP documents like the Service Matrix, Numbers on Demand user guide and release notes.

Please click on 'API Documents' on the left to find the OAS specification and sample API requests and responses.

Voice Authentication API- OAuth 2.0

API to generate an access token to authenticate Voice API requests (APIs: Wholesale SIP number management, Voice Address Management, Voice Billing and Customer registration number/VAT valdiation).

Read more about Voice Authentication API- OAuth 2.0

API Details

Status	LIVE
Version	v1
Maturity status	Production
Endpoint (Production)	https://apis.colt.net/authentication/v1/oauth/token
Endpoint (Sandbox)	https://sandbox.apis.colt.net/authentication/v1/oauth/token

Error returned in the response

Http response	code	reason	message	details (for reference only)
400 Bad request	001	Validation not met	The request is missing authorization parameter.	The request is missing authorization parameter
	002	Validation not met	The request is missing grant_type.	The request is missing grant_type
	003	Validation not met	The request is missing content_type header	The request is missing content_type header
	004	Validation not met	The request is missing x-tracking-id.	The request is missing x-tracking-id
	005	Validation not met	Invalid input parameter	The request contains unsupported parameters Multiple credentials More than one mechanism for authenticating
	006	Validation not met	The authorization grant type is not supported by authorization server	The authorization grant type is not supported by authorization server
401 Unauthorized	001	Authentication error	The authorization parameter is missing.	Client authentication failed due to no client authentication included in the request.
401 Unauthorized	002	Authentication error	The authorization parameter is not valid.	Client authentication failed due to unsupported authentication method other than Basic.
415 Unsupported Media Type	001	Validation not met	The format of the posted body is not supported by the endpoint.	The format of the posted body is not supported by the endpoint.
500 Internal server error	001	Internal error	An unknown internal error occurred	Generic failure message used if no more precise code can be provided.
500 Internal server error	002	internal error	O Auth server failed.	The server failed to generate access token
503 Service unavailable	001	service unavailable	The service is temporarily unavailable	Backend unavailable.

authorization_v1.0.0_28Nov2024 (1)_0.yaml (11.29 KB)

OAuth 2.0 is the industry-standard protocol for authorization. This API returns an JSON web token (JWT) which is required to authorize API calls for a given app.

You can request up to 5 CLIENT_ID + CLIENT_Secret per company account.

API features

access tokens generated by this API are valid for a limited period (30 mins) which is returned in the API response.

If the token expires, this API will need to be called again.

Connectivity and Price API

Use Connectivity and Price APIs to check the availability of connectivity services and get real-time quotes.

Operations

How to get access to this API?

If you are a Colt customer then please contact your Account Executive.

How to use this API

Click below to download the API user guide.

Download User Guide

Not a customer yet?

Contact our Sales Team

WSDL File

ColtB2bFramework_common_webSvcProvider_b2bFramework_v5_Port_0.xml (89.36 KB)

Read more about Connectivity and Price API

SDN API

On demand platform supports custom build API, the "SDN API". They allow customers to order and configure data connectivity services and bypass the traditional service delivery process. They provide on demand ethernet, ipaccess and cloud connectivity solution. The API supports bandwidth flexing, boosting the existing bandwidth, port diversity. The connection can also be ceased using the API. We now support connectivity to offnet locations as well.

Read more about SDN API

How to get access to this API?

If you are a Colt customer then please contact your Account Executive.

What is the onboarding process?

Your Account Executive will request the logins for the sandbox account. AE will share the details with you.

The sandbox environment has production like features and you are free to test any use case using the APIs. Our devops team will support you during this period.

Once you are ready with API development and want to move to production , the Account executive has to raise separate registration request that creates Colt online logins and On demand platform credentials.

How to get support for this API?

You can use the support option available in On-demand portal for post-production support.

Not a customer yet?

Contact our Sales Team

How to Try the API?

To try the API and different operations please use On demand API Documentation

Colt On Demand Solutions

Colt On Demand Service is the solution for your business sites to cloud computing, disaster recovery, business continuity planning, content delivery, applications and host of other remotely-based IT services.

OnDemand platform provide below main product offerings.

Ethernet on Demand - On Demand connectivity to private enterprise locations Extends On Demand offering to 25,000+ enterprise buildings across Europe and APAC Supports data centre to Enterprise and Enterprise to Enterprise connectivity Supports on-net and near-net locations. On Demand connectivity between data centres.800+ Data Centres with shared equipment areas in Europe, APAC and the US 200+ data centres that support real time delivery
Cloud On Demand - connectivity into the cloud. Connectivity from data centre & Enterprise buildings into the public cloud Both API enabled hosted connectivity and dedicated port connectivity to the cloud Available for Microsoft Azure, ExpressRoute, Amazon Web Services Direct Connect, Google Cloud Partner Interconnect, IBM Direct Link and Oracle FastConnect
IP Access on Demand - On Demand internet connectivity. Connectivity from data entre & Enterprise buildings into the public internet Customers benefit from Colt’s carrier grade internet access service with additional On Demand features such as flexible commercials and real time upgrades Initially only available in Europe, up to 1Gbps
Cross-connects. In Datacentres / Carrier Hotels, Colt delivers the ports to a shared location CEA / MMR. It is the customer responsibility to order a cross-connect from the CEA/MMR to their own equipment. This can be ordered directly by the customer with the data centre provider or via Colt at selected locations. Only available for optical ports.

Product Structure

Colt On Demand is based on components which can be used to build end to end services. These components are re-usable and distinct, with attributes specific to each component such as bandwidth and contract term. The components available are:

Ethernet ports
Ethernet connections
Cloud ports
Cloud connections
IP Access connections
Cross connect

The Use-cases section describes how to achieve these functionalities using different APIs.By combining 2 or more of the above components any network topology can be created, from a simple point to point ethernet link or internet access at one location to complex mesh network topologies. For some examples on how to provision the most common network service topologies please refer to the ‘End to end use cases’ section.

API Security

All the Colt SDN APIs are protected by SSL/TLS encryption, so when you call them you should ensure your client code is using this mechanism. The APIs need secured token which has to be provided with every request to access them.

Generic Response Code

The following table shows how and when response codes must be used within the API.

Success

	Code	Use This When
1	200 - OK	GET- data retrieved successfully.
2	201 -Created	PUT – Data inserted successfully. PATCH- Data amended successfully POST- Data inserted successfully DELETE- Data deleted successfully
3	204 No Content	Empty Content

Errors

	Code	Indicates
1	400 Bad Request	Invalid client request
2	401 Unauthorized	Client credentials not verified
3	403 Forbidden	The client does not have access to the content
4	404 Data Not Found	The server cannot find the requested resource.

Versioning

We use the following rules when versioning:

Most of the existing APIs use version as an optional parameter.
When updating an existing endpoint, we add a new endpoint with a /v2/... (or /v3, etc) prefix. We do this under the following circumstances:
When a new mandatory attribute is added or an existing optional attribute is made mandatory. When an existing attribute is removed (optional or mandatory).
The original endpoint and schema object remain unchanged. We will support up to 3 versions of an endpoint and we will supply 6 months’ notice to all registered users before we retire an endpoint version.

Use-cases

This section describes the APIs and the endpoints that are used in different process steps as mentioned in the introduction section.

End points

Use new API v2/port/services to create,modify,delete and retrieve Ethernet port

Ethernet ports

Under the On Demand model, ports are a separate component - unlike the traditional data networking model where ports are an integral part of a circuit connection. All On Demand ports are capable of supporting multiple service types, using VLAN segregation. Example use cases include:

Multicloud – multiple cloud connections terminating on the same physical On Demand port at the customer site
NNI for Ethernet Virtual Private Line – multiple Ethernet connections aggregated on the same physical port for service provider handoff
Enterprise multi service – internet access, data centre connections and multiple cloud connections to support typical enterprise WAN services.
Colt supports a full range of physical 1Gbps, 10Gbps & 100Gbps port specifications. Please note diversity and resilience options for Ethernet Ports are not available via the On Demand platform.
This section describes the APIs used to retrieve list and associated data, create, modify and delete an Ethernet port.

Add an Ethernet Port

To add an Ethernet port use following sets of APIs.
Step1. To search for a building from customer address book Use GET api/locations/ or to search from global database use GET /api/global_directory/address which uses city, country, building name, street name, post code or google place identifier (this is retrieved from google maps for more information refer https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder) as optional query parameter. Count is set to 100 to retrieve first 100 records

Step2. Existing site:
Once you identified the building where a port has to be installed next search for the site. Use GET api/building/{building_id}/site to retrieve the site details along with capacity available at the site. This results in retrieving Logical port speed , port interface and connector.

Step3. Retrieve price for selected product using GET api/prices?service_type={service_type}&building_id={building identifier}&product_id= {product_id} where service_type is ETHERNETPORTand building identifier or location identifier is retrieved from Step1 and product_id from Step2

Step4. Existing capacity
Finally use POST /api/v2/port/services with payload


{
  "price_id": ,
  "site_id": "",
  "port_name": ""
}

where price_id is retrieved from above Step3, location_id from /global_directory and port_name is given name of the new port. The API returns the request and service identifier.

New capacity
If the capacity is not available, first create a temporary site in the given building by using POST /api/locations using the payload


{
 "building_id": "",
 "site_floor": "",
 "site_room_name": ""
}

Use GET api/products?service_type=ETHERNETPORT&location_id={location_id} to retrieve the products that are available at that building where the location_id is the the temporary site id

Next retrieve price for selected product using GET api/prices?service_type={service_type}&building_id={building identifier}&product_id= {product_id} where service_type is ETHERNETPORT and building identifier or location identifier is temporary site created earlier

Next create the port using the same endpoint /api/v2/port/services used in existing capacity with payload given below

{
  "site_access_price_id": ,
  "name": "",
  "price_id": ,
  "site_access_details": {
    "access_out_of_hours": true,
    "notice_required_days": "0",
    "site_contact": {
      "email": "",
      "name": "",
      "phone": ""
    },
    "technical_contact": {
      "email": "",
      "name": "",
      "phone": ""
    },
    "technical_contact_company": "string",
    "user_contact": {
      "email": "",
      "name": "",
      "phone": ""
    }
  },
  "site_id": ""
}

where site_access_price_id can be retrived using GET /api/prices?service_type=SITEPORT&location_id={location_id}, price_id is the price associated with the ethernet port and site_access_details are details assoicated with the site.

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename an Ethernet port

Use PATCH /api/v2/port/services/{port_id} to Rename the port. Provide new port_name as payload

Delete an Ethernet Port

Use DELETE /api/v2/port/services/{port_id} to Delete the port.

List Ethernet ports

Use GET /api/v2/port/services to retrieve all the ports

Retrieve a single Ethernet Port information

Use GET /api/v2/port/services/{port_id} to retrieve data of an individual port. Products, prices, address details are the key set of information retrieved from the API.

Download Letter of Authority

Use POST /api/v2/port/services/{port_id}/loa endpoint and provide issued_to as payload to get the LOA

Use GET /api/v2/port/requests/

Retrieve service_id using GET /api/v2/port/services/{port_id} endpoint Next use /api/v2/connection/services and check if the service_id is associated with component_connections as from_port_id or to_port_id

Use Get /api/cross_connect and search for associated_port_id in the response object as the given port

Cloud Ports

Colt has enabled automated service orchestration with multiple cloud service providers (CSP) such as MS Azure and AWS for real-time connectivity to the cloud using existing Colt-CSP interconnects. Customers can connect from all On Demand enabled locations (including all data centres and enterprise locations) to the public cloud by reserving a Cloud port against the desired cloud provider and creating a Cloud connection to it from any existing Ethernet port. Although the process to create a cloud port is slightly different for each cloud provider, the overall On Demand cloud service model is always the same with two cloud-specific service components: a cloud port and a cloud connection to it from a standard port. Cloud connections terminate on standard ports which can be in either data centres or enterprise locations. Cloud port – to – cloud port connections are not currently supported. Customers who wish to flex the bandwidth on their cloud circuit connections are advised to over-size the cloud port to enable bandwidth to be flexed up to this limit. Below section describes the different APIs use operate on cloud ports.

MS Azure ExpressRoute

Add cloud port

To order an Azure port follow below steps-
Step 1. Go to Azure portal and create an ExpressRoute service selecting ‘Colt’ as the provider. Get a service key (UUID)
Step 2. GET api/prices?service_type=CLOUDPORT&service= AZURE_EXPRESS to retrieve all the prices for cloud provider
Step 3. Call POST api/ports with below payload

{
  "port_name": "Azure port",
  "price_id": <price_id>,
  "cloud_provider": "AZURE_EXPRESS",
  "azure_service_key": "< azure_service_key >"
}

Where port_name is given name, Price_id is retrieved from first call ,azure_service_key provided by cloud provider in Step 1.

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ports/{port_id} to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports data and search for cloud_provider= "AZURE_EXPRESS” in the results

Retrieve a single Cloud Port information

Use GET /api/ports/{port_id}

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= "AZURE_EXPRESS” in the results

AWS DirectConnect Dedicated Cloud Port

Dedicated cloud ports can support multiple EVPL services with different VLANs.

Add Cloud Port

To order an AWS direct connect Dedicated port follow below steps
Step 1. Log into AWS console. Select Correct region and direct connect PoP. Download Letter of Authority.
Step 2. Use GET api/cloudsites to retrieve AWS regions, interconnects data which has site_type information
Step 3. Next use GET api/prices?service_type=CLOUDPORT&service= AWS_DEDICATED&site_type={site_type} to retrieve all the prices for cloud provider
Step 4. Call POST api/ports with below payload

{
  "port_name": "< port_name >",
  "price_id": "<price_id>",
  "cloud_provider": "AWS_DEDICATED",
  "aws_region": "<aws_region>",
  "building_id": "<building_id>",
  "loa": loa.pdf
}

where port_name is given port name price_id is retrieved basis site_type and service from the prices api aws_region is region created by AWS basis the data centre in a geography e.g. Europe central1 retrieved from the /cloudsites endpoint , building_id is retrieved from the /cloudsites endpoint and loa is Letter of authority retrieved from Step 1. Note this port is not created on demand and takes time

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ports/{port_id} to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports and search for cloud_provider= " AWS_DEDICATED” in the results

Retrieve Cloud Port information

Use GET /api/ports/{port_id}

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= " AWS_DEDICATED” in the results

AWS DirectConnect Hosted Cloud Port

Hosted cloud ports can only have 1 connection at a time and no VLAN config can be done on the cloud port end.

Add Cloud Port

Step 1.
Log into AWS console. Select Correct region and direct connect PoP. Generate the AWS Account number.
Step 2.
Use GET api/cloudsites to retrieve AWS regions, interconnects data which has site_type , region and building_id information Step 3.
Next use GET /api/prices?service_type=CLOUDPORT&service=AWS_HOSTED&region={region_id}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth Step 4.
Call POSTapi/ports with below payload

{
  "port_name": "< port_name >",
  "price_id": "<price_id>",
  "cloud_provider": "AWS_HOSTED",
  "aws_account_no": "<aws_account_no>",
  "building_id": "<building_id>",
  "aws_region": ",<aws_region>"
}

where port_name is given port name price_id is retrieved from the prices api aws_account_no is provided by AWS in Step 1. aws_region Regions created by AWS basis the data centre in a geography e.g. Europe central 1 building_id is retrieved from the api/cloudsites endpoint.
Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ports/{port_id}to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports and search for cloud_provider= " AWS_HOSTED” in the result

Retrieve a single Cloud Port information

Use GET api/ports/{port_id} where port_id is the identifier for the port

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= " AWS_HOSTED” in the result

Google Cloud Partner Interconnect

Add Cloud Port

To order Google cloud partner interconnect port follow same steps
Step 1. Login to Google Cloud Platform portal. Choose colt as provider. Generate pairing key. Use following steps to create Google cloud port. If the pairing key is partially activated after creating a port using the API, key has to be activated again by login to google platform
Step 2. Use GET api/cloudsites to retrieve Google regions, interconnects data which has site_type , region and building_id information
Step 3. Next use GET /api/prices?service_type=CLOUDPORT&service=GOOGLE_CLOUD&region={region}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth
Step 4. Call POST api/google/service/port with below payload

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " GOOGLE_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>",
  "building_id": ",building_id>",
  
}

where port_name is given port name price_id is retrieved from the prices api csp_key is of format uuid/region/zone provided by Google to the customer in Step 1. cloud_region Regions created by Google basis the data centre in a geography e.g. Asia pacific southeast 1 building_id is building identifier and both retrieved from the /cloudsites endpoint
Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/google/service/port/{port_id} to rename Google port

Delete Cloud Port

DELETE /api/google/service/port/{port_id} to delete the port

List Cloud Ports

Use GET /api/google/service/port

Retrieve a single Cloud Port information

Use GET api/google/service/port/{port_id}

Use GET api/google/request/port to retrieve Google port requests data. Retrieve the service Id using the session id and that can be used to retrieve the related requests

IBM Cloud DirectConnect

Add Cloud Port

To order IBM cloud port follow following steps
Step 1. Login to IBM portal.Select location then “Colt" as provider.Select the port bandwidth ( 50Mbps and 5Gbps).Select the rounting and the get the key. Enter the BGP routing details.Once the FastConnect service has been created, customers will be assigned a Service Key – this will be required to create a cloud port.
Step 2. Use GET /api/prices?service_type=CLOUDPORT&service=IBM_CLOUD to retrieve price for the given Region, Location and Bandwidth
Step 3. Call POST api/ibm/service/port with below payload

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " IBM_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>"
}

where port_name is given port name price_id is retrieved from the prices api csp_key is provided by IBM to the customer in Step 1. cloud_region is not needed for IBM cloud
Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ibm/service/port/{port_id} to rename IBM port

Delete Cloud Port

DELETE /api/ibm/service/port/{port_id} to delete the port

List Cloud ports

Use GET /api/ibm/service/port to retrieve list of IBM Ports and related information

Retrieve a single Cloud Port information

Use GET api/ibm/service/port/{port_id}

Use GET api/ibm/request/port to retrieve IBM port requests data

Oracle Cloud FastConnect

Add Cloud Port

To order Oracle cloud port follow following steps
Step 1. Login to Oracle cloud portal.Select “Oracle Provider” and then “Colt DCA”.Select a “Private/Public” domain.Enter the FastConnect port bandwidth (1G-10G) Enter the BGP routing details.Once the FastConnect service has been created, customers will be assigned a Service Key – this will be required to create a cloud port.
Step 2. Use GET /api/prices?service_type=CLOUDPORT&service=ORACLE_CLOUD&region={region}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth
Step 3. Call POST api/oracle/service/port with below payload

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " ORACLE_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>"
  "building_id": "<building_id>"
}

where port_name is given port name price_id is retrieved from the prices api csp_key is provided by Oracle as described in Step 1. cloud_region is the region chosen when the port was created
Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/oracle/service/port/{port_id} to rename oracle port

Delete Cloud Port

DELETE /api/oracle/service/port/{port_id} to delete the port

List Cloud ports

Use GET /api/oracle/service/port to retrieve all Oracle ports

Retrieve single port data

Use GET /api/oracle/service/port/{port_id}

Use GET api/oracle/request/port to retrieve all the request

Equinix Fabric Interconnect

Add Cloud Port

To order an Equinix cloud port follow following steps
Step 1. Login to Equinix interface. Create Fabric interconnect service choosing Colt as a provider. Generate a service key.Use the SDN API.
Step 2. Use GET api/cloudsites to retrieve Equinix regions, interconnects data which has site_type , region and building_id information
Step 3. Next use GET /api/prices?service_type=CLOUDPORT&service=EQUINIX_CLOUD&region={region}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth
Step 4. Call POST /api/v2/equinix/services with below payload

{
  "price_id": <price_id>,
  "cloud_provider": "EQUINIX_CLOUD",
  "name": "<port_name>",
  "csp_key": "<csp_key>",
  "building_id": "<building_id>",
  "cloud_region": "<cloud_region>"
}

where price_id is retrieved from the prices api port_name is Port name given by customer csp_key is key provided by cloud provider to customer building_id is retrieved from cloudsites api cloud_region e.g. am for Amsterdam retrieved from cloudsites api

Rename Cloud Port

Use PATCH /api/v2/equinix/services/{id} to Rename the port with pay load {"new_name":"Equinixcloudport 11"} Where port id is port identification number and new_name is updated name

Delete Cloud Port

Use DELETE /api/v2/equinix/services/{id} to Delete the port

List Cloud ports

Use GET /api/v2/equinix/services to retrieve all ports data

Retrieve single port data

Use GET /api/v2/equinix/services/{id} to retrieve single port details

Use GET /v2/equinix/request/{id} get request data for particular port identifier
Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Connectivity

Use new API v2/connection/services to create,modify,delete and retrieve Ethernet connection

Ethernet connections

Connections are circuits that are routed between two On Demand ports. On Demand ports can be dynamically configured to support either Ethernet Private Line (“point to point”) based on transparent handover or Ethernet Virtual Private Line “(hub and spoke”) services based on a VLAN handover.

EPL and EVPL are not treated as different service types in the On Demand platform, although the services are configured differently.

On Demand connections support bandwidths between 10Mbps and 20Gbps. Higher bandwidths are available on request. The supported bandwidth of an On Demand circuit connection is based on the bandwidth of the ports at the A and B end points. This applies to both fixed term and flexible contracts.

For point to point (EPL) services where the A end and B end port speeds are equal, the circuit connection bandwidth is based on bandwidth ranges that are related to the speed of both ports.

The bandwidths that are supported for EPL configurations are 1 to 10 Gbps port range for all locations and 40 to 100Gbps port range for Key Data centre

For EVPL services the maximum circuit connection bandwidth is determined by the lower “unused” bandwidth on each port. For example, the supported bandwidth range for a circuit connection routed between a 10Gbps NNI and a 1Gbps B end port is 10Mbps-1Gbps (i.e. the range associated with the lower speed port).

Topology

	Service type	VLAN config
1	Point to Point(EPL)	P-P
2	Hub and Spoke(EVPL)	X-P
3	EVPL(mesh) filtering at spoke	X-F
4	Ethernet line	F-F

Connections have three VLAN modes, which apply to each end of the circuit connection:

Mode	Application	Description
Open port (P)	1 circuit connection per port	Port based handover, all VLANs are passed transparently
Add VLAN(X)	Multiple circuit connections per port (Colt adds VLAN tag)	VLAN based handover, 1 VLAN per Connection. VLAN added on egress, towards customer (in translation mode). VLAN can be S-VLAN (88a8) or C-VLAN (8100)
Filter VLAN(F)	Multiple circuit connections per port (Colt filters VLAN tags)	VLAN filtered on ingress to Colt network (against a single VLAN number).

The supported combinations are shown in the below table (A end and B ends can be used interchangeably).

A-end	open port	Add VLAN	Add VLAN	Add VLAN	Filter VLAN
B-end	open port	Open port	Add VLAN	Filter VLAN	Filter VLAN
Description	Standard Ethernet Private Line (EPL)configuration	Ethernet Virtual Private Line (EVPL)configuration port	Ethernet Virtual Private Line (EVPL),hub presenstation at both ends	Ethernet Virtual Private Line (EVPL),with VLAN filetering at spoke site	As per scenario 3 above, except VLAN IDs are preserved(same at each end)
Equivalent Colt service	Ethernet Line(EPL)	Ethernet Hub and Spoke	N/A	MEF Access EVPL	Ethernet Line

This section describes the APIs that are used to create, manage and cease Ethernet connections.

Create an Ethernet Connection

An Ethernet connection can be ordered only between two Ethernet ports . This section describes steps needed to create an Ethernet connections with bare minimum attributes. Specific case is discussed in Use cases section.
Step 1. Use GET /api/v2/port/services to find out the ports .
Step 2. Next retrieve the prices and products for connecting 2 ports using GET api/prices?service_type=ETHERNETCIRCUIT&from_port_id={from_port_id}&to_port_id={to_port_id} where the from and to port ids are retrieved from the earlier API call.
Step 3. To make a connection request, use POST /api/v2/connection/services the payload consists of

{
"from_port_id": "<from_port_id>",
"from_vlans": {
    "vlan_mapping": "<vlan_mapping>",
    "vlan_type": "<vlan_type>",
    "vlan_id": vlan_id
},
"name": "<connection_name>",
"price": {
    "price_id": <price_id>
},
"to_port_id": "<to_port_id>",
"to_vlans": {
    "vlan_mapping": "<vlan_mapping>",
    "vlan_type": "<vlan_type>",
    "vlan_id": vlan_id
}

Where connection_name is the name given to the connection, from_vlans and to_vlans has vlan_mapping e.g., “X” or “P” or “F”,vlan_type e.g. “S” or “C” (VLAN can be S-VLAN (88a8) or C-VLAN (8100) and vlanid ranging from 1 to 4094

Rename Ethernet Connection

Use PUT /api/v2/connection/services/{connection_id} to update the name of Ethernet connection with payload as name which is updated connection name

Delete Ethernet Connection

Use DELETE api/v2/connection/services/{connection_id} to delete an Ethernet

List Ethernet connections

Use GET api/v2/connection/services endpoint

Retrieve single Ethernet Connection Information

Use GET api/v2/connection/{connection_id}

Use GET /api/v2/connection/requests

Modify Bandwidth

Customer have an option to modify bandwidth OnDemand. The charges are based on the number of changes done. E.g. if 10MB service is advanced to 1GB for 20 minutes we charge for 1 hour.If the changes are made twice in a month.
Use PUT /api/v2/connection/services/{connection_id} to update the bandwidth by providing price_id which can be retrieved using GET /api/prices?service_type=ETHERNETCIRCUIT&connection_id={connection_id} and setting the appropriate coterminus_option

Modify VLAN configuration

Use PUT /api/v2/connection/services/{connection_id} to update the VLAN parameters connection with payload with updated VLAN parameters

Modify Contractual Commitment

Step1.
Use GET /api/prices?version=1&service_type=ETHERNETCIRCUIT&connection_id={connection_id}&version={updated_version_id}

Step 2.
Use PUT api/connection/services/{connection_id} with payload

{    
  "price_id": <price_id>,
  "coterminus_option": <coterminus_option>
}

Schedule Bandwidth Changes

This is only available for services with no commitment.
Retrieve prices using /api/prices?service_type=ETHERNETCIRCUIT&connection_id={connection_id} Use POST /api/schedule with payload

{
  "price_id": <price_id>,
  "connection_id": " <connection_id>",
  "event_frequency": "< event_frequency>",
  "event_date": "<event_date>"
}

Where event_frequency could be ONE_OFF, WEEKLY, MONTHLY etc

Create Cloud Connection

There is an ethernet port which is already created at “A end “ and at the B end a cloud port is used and a connection is ordered between them.

Below APIs are used in different steps to achieve a cloud connection
Step 1. Use GET /api/ports?available=true this provides ports those are already created For Google port use GET /api/google/service/port?available=true For IBM use GET /api/ibm/service/port?available=true For Oracle use GET /api/oracle/service/port?available=true For Equinix use GET /api/v2/equinix/service
Step 2. Use GET /prices?service_type=CLOUDCIRCUIT&from_port_id={from_port_id}&to_port_id={to_port_id}&to_port_id_2={to_port_id_2} where from_port_id (Ethernet port id) and to_port_id (Cloud port id) and to_port_id_2 is a secondary port data is retrieved from the /api/ports endpoint to_port_id_2 which is he secondary port id has to be provided only for Azure connection
Step 3. Use POST /api/connections with payload as below data elements

{
  "price_id": <price_id>,
  "connection_name": "<connection_name>",
  "component_connections": [
    {
      "from_port_id": "<from_port_id>",
      "to_port_id": "<to_port_id>",
      "cloud_provider_from_port": "<cloud_provider_from_port>",
      "cloud_provider_to_port": cloud_provider_to_port,
      "a_end_vlan_mapping": "<a_end_vlan_mapping>",
      "b_end_vlan_mapping": "<b_end_vlan_mapping>",
      "a_end_vlan_type": "<a_end_vlan_type>",
      "b_end_vlan_type": "<b_end_vlan_type>",
      "a_end_vlan_ids": [],
      "b_end_vlan_ids": []
    }
  ]
}

For Azure use cloud_provider_from_port= AZURE_EXPRESS For Google use cloud_provider_from_port= GOOGLE_CLOUD For IBM use cloud_provider_from_port= IBM_CLOUD For Oracle use cloud_provider_from_port= ORACLE_CLOUD

For Equinix cloud cloud_provider_from_port is EQUINIX_CLOUD. For AWS Dedicated cloud_provider_from_port is AWS_DEDICATED For AWS HOSTED cloud_provider_from_port is AWS_HOSTED

Rename Cloud Connection

Use PUT /api/connections/{connection_id} to update the name of connection with payload as name which is updated connection name

Delete Cloud Connection

Use DELETE api/connections/{connection_id} to delete Cloud Connection

List Cloud connections

Use GET api/connections endpoint with attribute is_cloud_connection=true in the response

Retrieve single cloud Connection Information

Use GET api/connections/{connection_id}

Use GET /api/requests and in the result search for requests which has resource as “CONNECTION” and id is the connection id and is_cloud=true

Modify Bandwidth

Use PUT /api/connections/{connection_id} to update the bandwidth by providing price_id which can be retrieved using GET /api/prices?service_type=CLOUDCIRCUIT&connection_id=

Modify VLAN configuration

Use PUT /api/connections/{connection_id} to update the VLAN parameters connection with payload with updated VLAN parameters

Modify Contractual Commitment

Step1. Use GET /api/prices?version=1&service_type=CLOUDCIRCUIT&connection_id={connection_id}&version={updated_version_id}
Step 2. Use PUT api/connections/{connection_id} with payload

{
  "price_id": <price_id>,
  "coterminus_option": < coterminus_option>,
  "is_cloud_connection": < is_cloud_connection >
}

where is_cloud_connection = true

Schedule Bandwidth Changes

This is only available for services with no commitment.
Retrieve prices using /api/prices?service_type=CLOUDCIRCUIT&connection_id={connection_id} and use POST Use POST /api/schedule with payload

{
  "price_id": "<price_id>",
  "connection_id": " <connection_id>",
  "event_frequency": "< event_frequency>",
  "event_date": "<event_date>"
}

event_frequency could be ONE_OFF, WEEKLY, MONTHLY etc

Create IP Access Connections

IP Access provides a dedicated permanent access to the public Internet. Colt IP Access allows customers to connect business sites of all sizes to the Internet easily, efficiently and securely with guaranteed IP bandwidth. It is a wires-only service with PA IPv4 /29 addresses only and customers need to provide a router.

Add an IP Access Connection

IP Access on Demand - On Demand internet connectivity is the commercial offering supported by following set of API. The A end is Ethernet port and B end is internet connectivity.
Step 1. Use GET /api/v2/port/services to find the Ethernet ports that are already created

Step 2. Retrieve IP Access products and prices that could be available for the port using /api/prices?service_type={service_type}&from_port_id={from_port_id} where service_type= IPACCESS_CIRCUIT and from_port_id is retrieved from earlier API call

Step 3. Call POST /api/ipaccess/request with payload

{
  "action": "CREATE",
  "price_id": <price_id>,
  "connection_name": "<connection_name>",
  "from_port_id": "<from_port_id>",
  "port_vlan_mapping": "< port_vlan_mapping >",
  "port_vlan_type": "< port_vlan_type >",
  "port_vlan_ids": [
    {
      "from_id_range": < from_id_range>,
      "to_id_range": < to_id_range >
    }
  ]
}

where price_id retrieved from prices api, connection_name is name given to connection, from_port_id is ethernet port id, port_vlan_mapping e.g. “X”, port_vlan_type e.g. ”C”, from_id_range and to_id_range number of VLAN port ids

Rename IP Access connection

Use PUT /api/ipaccess/service/{connection_id} and payload as connection_name which is updated name for the connection.

Delete IP Access Connection

Use POST /api/ipaccess/request with payload{"action":"DELETE","connection_id":""}

List IP Access Connections

Use GET /api/ipaccess/service to retrieve IP Access connections where available is mandatory query parameter

Use GET /api/ipaccess/request

Modify Bandwidth

Step 1. Retrieve price using GET /api/prices?service_type={service_type}&connection_id={connection_id} where service_type = IPACCESS_CIRCUIT
Step 2. Call /api/ipaccess/request with payload

{
  "action":"<action> ",
  "price_id":<price_id>,
  "coterminus_option":< coterminus_option>,
  "connection_id":"<connection_id>"
} where action = UPDATE

Modify VLAN Configuration

Call POST [api/ipaccess/request] (#post-/ipaccess/request) with payload

{
  "action": "<action>",
  "connection_id": "<connection_identifier>",
  "port_vlan_mapping": "< coterminus_option >",
  "port_vlan_type": "< port_vlan_type >",
  "port_vlan_ids": [
    {
      "from_id_range": "<VLAN_ID>",
      "to_id_range": "<VLAN_ID>"
    }
  ]
}

where action= UPDATE , port_vlan_mapping = X, port_vlan_type= C and VLAN_ID= numerical VLAN id

Modify Contractual Commitment

Step 1. call GET /api/prices?version=1&service_type=IPACCESS_CIRCUIT&connection_id={connection_id}&version={updated_version_id}
Step 2. call POST api/ipaccess/request/ with payload

{
  "action": "<action>",
  "price_id": <price_id>,
  "coterminus_option": <coterminus_option>,
  "connection_id": "<connection_id>"
}

Retrieve IP Access Connection Information

Use GET api/ipaccess/request/{request_id}

Use GET api/ipaccess/request/ retrieve the service_id from the session and find out the related requests

Cross-connects

Customers can request a fibre cross connect in a data centre via the On Demand platform, which will result in Colt placing a request on the data centre operator for a cross connect between the specified On Demand port and the demarcation point in the customer rack.

Please note that only fibre cross connects are supported - copper cross connects are not supported.

Where a cross connect is requested, customers are required to enter the demarcation details and are also required to upload a letter of authority to grant Colt permission to place a cross connect order to the customer rack. The demarcation details and LOA (pdf file format) are mandatory. Cross-connects require a physical installation and therefore are a manual operation that does not complete in ‘real-time’. The standard lead times apply for Cross-connect orders. This section describe the APIs used to create, display, delete and retrieve associated requests data for a given cross connect

Add Cross-connect

Cross connects can only be added on already added Ports. Following steps are needed to request a cross connect
Step 1. Create an ethernet port at a location where cross connects has to be ordered refer steps in Add an Ethernet Port
Step 2. Retrieve charges for a cross connect at a building Use /api/prices?service_type=CROSSCONNECT&building_id={building_id}
Step 3. Use POST api/cross_connect with payload as

{
  "port_request_id": "< port_request_id>",
  "port_id": "<port_id>",
  "customer_pp_port": "< customer_pp_port >",
  "customer_pp_floor": "< customer_pp_floor>",
  "customer_pp_room": "< customer_pp_room>",
  "customer_pp_cabinet": "< customer_pp_cabinet>",
  "customer_pp_rack": "< customer_pp_rack>",
  "customer_pp_device": "< customer_pp_device >",
  "customer_pp_slot": "< customer_pp_slot>",
  "customer_pp_connector": "< customer_pp_connector >",
  "loa": "<loa>",
  "price_id": "<price_id>",
  "connector": "<connector>"
}

PP is presentation panel, port_request_id is the request id of the port created in Step 1. port_id is the service_id of the port created in Step 1, price_id is retrieved from Step 2, loa is letter of authority, connector is connector used in Ethernet port

Delete cross connect

Use DELETE api/cross_connect/{id} to delete a cross connect where id is cross_connect identifier

List Cross-connects

Use GET api/cross_connect to retrieve list of cross connect and related data connections data

Retrieve Cross-connect Information

Use GET api/cross_connect/{id} to retrieve data for single cross connection where id is cross_connect identifier

Use GET /api/requests and search for requests which has resource as “CROSSCONNECT” and id is the port id

Retrieve Billing Data

Use GET charges to retrieve all the charges associated with Ports, Connections and Boosted bandwidths for Cloud, Ethernet and IP Access connections for a given customer

Use GET api/charges to retrieve all the charges associated with Ports, Connections for a given customer. The response contains information about recurring, one off , penalty charges associated with connection, port or IP Access connection.

Provide Bandwidth Boost

Bandwidth Boost feature enables temporary bandwidth upgrades on connections with a commitment term, allowing them to change the bandwidth back to the original committed bandwidth when they choose. Therefore, a customer could buy a 100M service on a 36-month contract, and at any time during that period decide to boost the service above 100M as much as required, paying a premium, to eventually downgrade back to the original 100M bandwidth and rate. The feature is available for Ethernet, Cloud and IP Access connections.

Retrieve Bandwidth boost options for connection type

Use GET /api/prices?service_type={service_type}&from_port_id={from_port_id}&to_port_id={to_port_id} where service_type=Ethernet or cloud or ipaccess connection. The rental_boost_charge and bandwidth_mb in the response gives price and bandwidth value.

Apply Bandwidth boost to existing connection

Step 1. Retrieve bandwidth boost options and associated prices using GET /api/prices?service_type={service_type}&connection_id={connection _id} where service_type is ETHERNETCIRCUIT or CLOUDCIRCUIT or IPACCESS_CIRCUIT and connection_id is connection identifier for the connection. The bandwidth_boost_prices array returns required values.

Step 2. Use PUT /api/connections/{connection_id} with request payload attribute boost_bandwidth_mbps as query param

List available Bandwidth Boost and prices for a connection

Use GET /api/connections search for rental_boost_charge and bandwidth_mb which represent the bandwidth and its corresponding charges at a given date.

Find Boosted bandwidth for connection

Use Get /api/connections check for base_bandwidth and bandwidth values and if they are different use the bandwidth value as boosted value

Find Boosted bandwidth requests

Use GET /api/requests and look for record where resource=CONNECTION and action=BOOST. If this value is present then the bandwidth value will be the boosted bandwidth and the base_bandwidth attribute will be unboosted bandwidth, old_bandwidth will show the value prior to this request.

Charges associated with bandwidth boost

Use GET /api/charges. boost_charges array will have amount, date on whihc boost was applied and type=BOOST values.

Retrieve Trouble tickets data

Use GET tickets to retrieve all the trouble tickets raised by system or service desk and provide view of status on each one of them to your customer.

Retrieve tickets data

Use GET api/tickets to retrieve all the tickets information

Manage multiple customers accounts

If you have multiple customer accounts associated to your login, you have a possibility to use any one of them at a time. You can then manage the services associated with that customer account.
To see which accounts are associated with your login use GET /api/v3/user.
To set a particular customer account as a preffered customer use PATCH /api/v2/user
To view terms and condition details for associated customer account use GET /api/v2/legal_requirements and provide 2 letter language code as request parameter as preferred_language e.g. "DE"
To accept terms and condition for an associated customer account use PATCH /api/v2/legal_requirements and provide the input payload as

{
"id": 49652,
"accepted": true
}

End-to-end use-cases

This section covers the end-to-end use cases that are developed using building blocks like Ethernet and cloud ports. These also cover usage of fetures like location retrieval, product attributes to determine the prices for connectivity.

Create Point to Point connection

Create a-end ethernet port
Create b-end ethernet port
Create ethernet connection with P-P VLAN mapping.

Step 1. Add two Ethernet port
Step 2. Make Ethernet connection with payload

{
  
"from_port_id": "<from_port_id>",
"from_vlans": {
  "vlan_mapping": "P",
  "vlan_type": "",
  "vlan_id": null
},
"name": "P2Pconnection",
"price": {
  "price_id": <price_id>
},
"to_port_id": "<to_port_id>",
"to_vlans": {
  "vlan_mapping": "P",
  "vlan_type": "",
  "vlan_id": null
}

}

Where vlan_mapping are “P” for both from and to port Refer P2P section of the Ethernet connection

Create Hub and Spoke connection

Create b-end ethernet port
Create ethernet connection with X-P or X-X (x on hub end)or F-F mapping

Step1 and Step 2 is adding two ethernet ports
Step 3. Make an Ethernet Connection where change in payload values from_vlans - vlan_mapping is “X” and to_vlans - vlan_mapping is “P” or both as “X” or “F” at both.Refer Ethernet Virtual Private Line section of Ethernet connection

Order bundle for Ethernet (New*)

Currently the On Demand platform allows users to place Port and Connection requests. However for a Connection request both end ports need to be already live and active. This means that if customers want to place an order for a connection which requires new capacity to be built, they need to wait weeks/months until both ports are delivered before they can place the Connection request. This feature therefore will allow customers to place all required requests for a connection at the same time in one action, with each request triggering automatically once all the pre-requisites are completed.

This means that customers in one single action can submit:

A port create request for the a-end by using POST /api/v2/port/services operation
A port create request for the b-end again using POST /api/v2/port/services operation and
Submit a connection request between the a-end and b-end ports using POST /v2/connection/services operation while the ports are still getting created to achieve this.

Create a Cloud Connection

This is made of 3 steps:

Create a cloud port
Create an ethernet port (optional if already available)
Create a cloud connection Refer Cloud connections

Create an IP Access Connection

This is made of 2 steps:

Create an ethernet port
Create an IP access connection. Refer IP Access section

Cross connect

Add ethernet port
Add cross connect

Address qualification

Step 1. Search for buildings from customer address book use GET /api/locations just to confirm that the building is not already added to the address book
Step 2. Search building/location where Port has to be ordered in the global directory use GET /api/global_directory/address
Step 3. Search for Sites available in the building using GET /api/building/{building_id}/site
Step 4. Add the building to address book using POST /api/locations with payload

{
  "building_id": "<building_id",
  "location_name": "<location_name>",
  "country": "<country_name>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

Where the site_floor and site_room_name has to be provided if the site is newly added else will be already available in the building details and will be available as a response of step 3.
Exception scenario
If the address is not available in Colt database then the result of Step 2 will be an empty array Use GET /api/geolocation-reachable?lat={latitude}&long={longitude}&place_id={place_d}

If the Address is reachable API responds with

{
  "nearnet_price_id":<nearnet_price_id>,
  "reachable": true,
  "installation_currency": "<currency>",
  "installation_charge": <charge>
}

If not then Colt connection is not supported at the location. Add the building to Address book Use POST /api/locations with payload

{  
"location_name": "<location_name>",
  "city": "<city>",
  "country": "<country>”,
  "latitude": <latitude>,
  "longitude": <longitude>,
  "address": ",address>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Add new site to building

Step1. Search for a site availability at a given building use GET api/building//site this should result in empty site data array
Step 2. To add a new site use POST /api/locations

{
  "building_id": "< building_id >",
  "location_name": "< location_name >",
  "country": "<country_name>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

where site_floor is the new floor number and site_room_name is new site name where port has to be installed. This API returns "id":"”, “novitas_site_type":" “ which are used in further process of price retrieval

The referenced media source is missing and needs to be re-embedded.

Find Prices for ordering a Port or making a connection

To Find prices for installing an Ethernet Port and a connection between 2 port following steps are used
Step 1. Get the building details where A end port has to be installed using /api/global_directory/address?place_id=ChIJH8vQ7fmLGGAR_Vx9A5i46pc&count=100 discussed in step 1. Of Add Ethernet Connection section. This API will return null if connected building is not available.
Step 2. Retrieve prices and products available for Ethernet port at the given building using GET /api/prices?service_type=ETHERNETPORT&site_type={site_type} where site_type is retrieved from step 1. which is novitas_site_type
Step 3. Choose B End as Ethernet port similar to Step 2 and retrieve the prices
Step 4. Retrieve prices for making an Ethernet connection between these two ports using GET /api/prices?service_type=ETHERNETCIRCUIT&from_site_type={from_site_type}&to_site_type={from_site_type} where from_site_type and to_site_type are retrieved from the Step 1
To find Price to make IP Access Connection following steps are used
Step 1. Get the Ethernet port installations product and charges for the chosen building
Step 2. Retrieve product and prices for IP Access connection using
GET /api/prices?service_type=IPACCESSCIRCUIT&site_type={site_type}
To find Prices for cloud connection
Step 1. Retrieve all the information about the cloud providers using GET /api/cloudsites
Step 2. Retrieve Product and prices for port installation using GET /prices?service_type=CLOUDPORT&site_type=DCA-MSA-JP-TKY where site_type is retrieved from step 1
Step 3. Retrieve prices for making cloud connection at the given port api/prices?service_type=CLOUDCIRCUIT&from_site_type={from_site_type}&to_site_type={to_site_type}&to_site_type_1={to_site_type _1}&service=AZURE_EXPRESS where from_site_type is cloud END retrieved in step 1 and to_site_type is the A END Ethernet port of the network

Note for other cloud providers service attribute changes according to provider and to_site_type_1 attribute is not needed.

Terminology

CEA - Common Equipment Area
Coterminus option: When changing a connection in some chargeable way, this option defines whether the new contract should run only until the end date of the current contract (true), or whether you want to “reset” the contract period to start from the date of the change”.
Cross Connect: A cross-connect is a physical, hardwired cable that provides a direct connection between two different termination locations within a data centre. the letter of authority is NOT provided by the datacentre owner, it has to be provided by the owner of the equipment you are connecting to, i.e. Colt if the customer orders the cross-connect and the customer if Colt orders it.
Global directory: Information of buildings where Colt’s connectivity is available
LOA: Letter of authority provided to install connection
MMR: Meet me room
novitas_site_type: Is a Colt term to represent a site e.g. KDC-PL-WOW created by combining the building category (KDC, DCNET, LANLINK, DCA-MSA, DCA-AWSH, etc), PL 2 letter country code and WOW 3 letter metropolitan area code.
Order id: This is generated by Siebel for siteport and cross-connect requests
PORT_TYPE: DCNPORT/LANPORT/DCAPORT - DCNPORTs are located in data centres. LANPORTs are located on customer premise. DCAPORTs are cloud ports.
Product: Colt products e.g. Twisted pair electrical 1Gbps ethernet port
Request ID- Request identifier is created for every state chnage of connection e.g. create,modify,delete.
Service ID- A unique reference to a service the customer has paid for/requested from the time it is created until the time it is terminated. Applies to all Ports & Connections.
Service Type: Connectivity prices are derived basis Service types e.g. ETHERNETPORT'' , CROSSCONNECT or ''ETHERNETCIRCUIT
Shared area: This is a place where along with other providers Colt connectivity can be provided
Site: Location in the building where ports can be installed.
SITEPORT: This is a request type which only installs the capacity – this will also create a PORT request to reserve the capacity once it has been delivered.
VLAN type: S-VLAN (88a8) or C-VLAN (8100)

Colt On Demand Solutions

OnDemand platform provide below main product offerings.

Ethernet on Demand - On Demand connectivity to private enterprise locations Extends On Demand offering to 25,000+ enterprise buildings across Europe and APAC Supports data centre to Enterprise and Enterprise to Enterprise connectivity Supports on-net and near-net locations. On Demand connectivity between data centres.800+ Data Centres with shared equipment areas in Europe, APAC and the US 200+ data centres that support real time delivery
Cloud On Demand - connectivity into the cloud. Connectivity from data centre & Enterprise buildings into the public cloud Both API enabled hosted connectivity and dedicated port connectivity to the cloud Available for Microsoft Azure, ExpressRoute, Amazon Web Services Direct Connect, Google Cloud Partner Interconnect, IBM Direct Link and Oracle FastConnect
IP Access on Demand - On Demand internet connectivity. Connectivity from data entre & Enterprise buildings into the public internet Customers benefit from Colt’s carrier grade internet access service with additional On Demand features such as flexible commercials and real time upgrades Initially only available in Europe, up to 1Gbps
Cross-connects. In Datacentres / Carrier Hotels, Colt delivers the ports to a shared location CEA / MMR. It is the customer responsibility to order a cross-connect from the CEA/MMR to their own equipment. This can be ordered directly by the customer with the data centre provider or via Colt at selected locations. Only available for optical ports.

Product Structure

Ethernet ports
Ethernet connections
Cloud ports
Cloud connections
IP Access connections
Cross connect

API Security

Generic Response Code

The following table shows how and when response codes must be used within the API.

Success

	Code	Use This When
1	200 - OK	GET- data retrieved successfully.
2	201 -Created	PUT – Data inserted successfully. PATCH- Data amended successfully POST- Data inserted successfully DELETE- Data deleted successfully
3	204 No Content	Empty Content

Errors

	Code	Indicates
1	400 Bad Request	Invalid client request
2	401 Unauthorized	Client credentials not verified
3	403 Forbidden	The client does not have access to the content
4	404 Data Not Found	The server cannot find the requested resource.

Versioning

We use the following rules when versioning:

Most of the existing APIs use version as an optional parameter.
When updating an existing endpoint, we add a new endpoint with a /v2/... (or /v3, etc) prefix. We do this under the following circumstances:
When a new mandatory attribute is added or an existing optional attribute is made mandatory. When an existing attribute is removed (optional or mandatory).
The original endpoint and schema object remain unchanged. We will support up to 3 versions of an endpoint and we will supply 6 months’ notice to all registered users before we retire an endpoint version.

Use-cases

This section describes the APIs and the endpoints that are used in different process steps as mentioned in the introduction section.

End points

Use new API v2/port/services to create,modify,delete and retrieve Ethernet port

Ethernet ports

Multicloud – multiple cloud connections terminating on the same physical On Demand port at the customer site
NNI for Ethernet Virtual Private Line – multiple Ethernet connections aggregated on the same physical port for service provider handoff
Enterprise multi service – internet access, data centre connections and multiple cloud connections to support typical enterprise WAN services.
Colt supports a full range of physical 1Gbps, 10Gbps & 100Gbps port specifications. Please note diversity and resilience options for Ethernet Ports are not available via the On Demand platform.
This section describes the APIs used to retrieve list and associated data, create, modify and delete an Ethernet port.

Add an Ethernet Port

Step4. Existing capacity
Finally use POST /api/v2/port/services with payload


{
  "price_id": ,
  "site_id": "",
  "port_name": ""
}

where price_id is retrieved from above Step3, location_id from /global_directory and port_name is given name of the new port. The API returns the request and service identifier.

New capacity
If the capacity is not available, first create a temporary site in the given building by using POST /api/locations using the payload


{
 "building_id": "",
 "site_floor": "",
 "site_room_name": ""
}

Use GET api/products?service_type=ETHERNETPORT&location_id={location_id} to retrieve the products that are available at that building where the location_id is the the temporary site id

Next create the port using the same endpoint /api/v2/port/services used in existing capacity with payload given below

{
  "site_access_price_id": ,
  "name": "",
  "price_id": ,
  "site_access_details": {
    "access_out_of_hours": true,
    "notice_required_days": "0",
    "site_contact": {
      "email": "",
      "name": "",
      "phone": ""
    },
    "technical_contact": {
      "email": "",
      "name": "",
      "phone": ""
    },
    "technical_contact_company": "string",
    "user_contact": {
      "email": "",
      "name": "",
      "phone": ""
    }
  },
  "site_id": ""
}

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename an Ethernet port

Use PATCH /api/v2/port/services/{port_id} to Rename the port. Provide new port_name as payload

Delete an Ethernet Port

Use DELETE /api/v2/port/services/{port_id} to Delete the port.

List Ethernet ports

Use GET /api/v2/port/services to retrieve all the ports

Retrieve a single Ethernet Port information

Use GET /api/v2/port/services/{port_id} to retrieve data of an individual port. Products, prices, address details are the key set of information retrieved from the API.

Download Letter of Authority

Use POST /api/v2/port/services/{port_id}/loa endpoint and provide issued_to as payload to get the LOA

Use GET /api/v2/port/requests/

Use Get /api/cross_connect and search for associated_port_id in the response object as the given port

Cloud Ports

MS Azure ExpressRoute

Add cloud port

{
  "port_name": "Azure port",
  "price_id": <price_id>,
  "cloud_provider": "AZURE_EXPRESS",
  "azure_service_key": "< azure_service_key >"
}

Where port_name is given name, Price_id is retrieved from first call ,azure_service_key provided by cloud provider in Step 1.

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ports/{port_id} to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports data and search for cloud_provider= "AZURE_EXPRESS” in the results

Retrieve a single Cloud Port information

Use GET /api/ports/{port_id}

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= "AZURE_EXPRESS” in the results

AWS DirectConnect Dedicated Cloud Port

Dedicated cloud ports can support multiple EVPL services with different VLANs.

Add Cloud Port

{
  "port_name": "< port_name >",
  "price_id": "<price_id>",
  "cloud_provider": "AWS_DEDICATED",
  "aws_region": "<aws_region>",
  "building_id": "<building_id>",
  "loa": loa.pdf
}

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ports/{port_id} to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports and search for cloud_provider= " AWS_DEDICATED” in the results

Retrieve Cloud Port information

Use GET /api/ports/{port_id}

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= " AWS_DEDICATED” in the results

AWS DirectConnect Hosted Cloud Port

Hosted cloud ports can only have 1 connection at a time and no VLAN config can be done on the cloud port end.

Add Cloud Port

{
  "port_name": "< port_name >",
  "price_id": "<price_id>",
  "cloud_provider": "AWS_HOSTED",
  "aws_account_no": "<aws_account_no>",
  "building_id": "<building_id>",
  "aws_region": ",<aws_region>"
}

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ports/{port_id}to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports and search for cloud_provider= " AWS_HOSTED” in the result

Retrieve a single Cloud Port information

Use GET api/ports/{port_id} where port_id is the identifier for the port

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= " AWS_HOSTED” in the result

Google Cloud Partner Interconnect

Add Cloud Port

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " GOOGLE_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>",
  "building_id": ",building_id>",
  
}

Rename Cloud Port

Use PUT /api/google/service/port/{port_id} to rename Google port

Delete Cloud Port

DELETE /api/google/service/port/{port_id} to delete the port

List Cloud Ports

Use GET /api/google/service/port

Retrieve a single Cloud Port information

Use GET api/google/service/port/{port_id}

Use GET api/google/request/port to retrieve Google port requests data. Retrieve the service Id using the session id and that can be used to retrieve the related requests

IBM Cloud DirectConnect

Add Cloud Port

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " IBM_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>"
}

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/ibm/service/port/{port_id} to rename IBM port

Delete Cloud Port

DELETE /api/ibm/service/port/{port_id} to delete the port

List Cloud ports

Use GET /api/ibm/service/port to retrieve list of IBM Ports and related information

Retrieve a single Cloud Port information

Use GET api/ibm/service/port/{port_id}

Use GET api/ibm/request/port to retrieve IBM port requests data

Oracle Cloud FastConnect

Add Cloud Port

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " ORACLE_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>"
  "building_id": "<building_id>"
}

The referenced media source is missing and needs to be re-embedded.

Rename Cloud Port

Use PUT /api/oracle/service/port/{port_id} to rename oracle port

Delete Cloud Port

DELETE /api/oracle/service/port/{port_id} to delete the port

List Cloud ports

Use GET /api/oracle/service/port to retrieve all Oracle ports

Retrieve single port data

Use GET /api/oracle/service/port/{port_id}

Use GET api/oracle/request/port to retrieve all the request

Equinix Fabric Interconnect

Add Cloud Port

{
  "price_id": <price_id>,
  "cloud_provider": "EQUINIX_CLOUD",
  "name": "<port_name>",
  "csp_key": "<csp_key>",
  "building_id": "<building_id>",
  "cloud_region": "<cloud_region>"
}

Rename Cloud Port

Use PATCH /api/v2/equinix/services/{id} to Rename the port with pay load {"new_name":"Equinixcloudport 11"} Where port id is port identification number and new_name is updated name

Delete Cloud Port

Use DELETE /api/v2/equinix/services/{id} to Delete the port

List Cloud ports

Use GET /api/v2/equinix/services to retrieve all ports data

Retrieve single port data

Use GET /api/v2/equinix/services/{id} to retrieve single port details

Use GET /v2/equinix/request/{id} get request data for particular port identifier
Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Connectivity

Use new API v2/connection/services to create,modify,delete and retrieve Ethernet connection

Ethernet connections

EPL and EVPL are not treated as different service types in the On Demand platform, although the services are configured differently.

For point to point (EPL) services where the A end and B end port speeds are equal, the circuit connection bandwidth is based on bandwidth ranges that are related to the speed of both ports.

The bandwidths that are supported for EPL configurations are 1 to 10 Gbps port range for all locations and 40 to 100Gbps port range for Key Data centre

Topology

	Service type	VLAN config
1	Point to Point(EPL)	P-P
2	Hub and Spoke(EVPL)	X-P
3	EVPL(mesh) filtering at spoke	X-F
4	Ethernet line	F-F

Connections have three VLAN modes, which apply to each end of the circuit connection:

Mode	Application	Description
Open port (P)	1 circuit connection per port	Port based handover, all VLANs are passed transparently
Add VLAN(X)	Multiple circuit connections per port (Colt adds VLAN tag)	VLAN based handover, 1 VLAN per Connection. VLAN added on egress, towards customer (in translation mode). VLAN can be S-VLAN (88a8) or C-VLAN (8100)
Filter VLAN(F)	Multiple circuit connections per port (Colt filters VLAN tags)	VLAN filtered on ingress to Colt network (against a single VLAN number).

The supported combinations are shown in the below table (A end and B ends can be used interchangeably).

A-end	open port	Add VLAN	Add VLAN	Add VLAN	Filter VLAN
B-end	open port	Open port	Add VLAN	Filter VLAN	Filter VLAN
Description	Standard Ethernet Private Line (EPL)configuration	Ethernet Virtual Private Line (EVPL)configuration port	Ethernet Virtual Private Line (EVPL),hub presenstation at both ends	Ethernet Virtual Private Line (EVPL),with VLAN filetering at spoke site	As per scenario 3 above, except VLAN IDs are preserved(same at each end)
Equivalent Colt service	Ethernet Line(EPL)	Ethernet Hub and Spoke	N/A	MEF Access EVPL	Ethernet Line

This section describes the APIs that are used to create, manage and cease Ethernet connections.

Create an Ethernet Connection

{
"from_port_id": "<from_port_id>",
"from_vlans": {
    "vlan_mapping": "<vlan_mapping>",
    "vlan_type": "<vlan_type>",
    "vlan_id": vlan_id
},
"name": "<connection_name>",
"price": {
    "price_id": <price_id>
},
"to_port_id": "<to_port_id>",
"to_vlans": {
    "vlan_mapping": "<vlan_mapping>",
    "vlan_type": "<vlan_type>",
    "vlan_id": vlan_id
}

Rename Ethernet Connection

Use PUT /api/v2/connection/services/{connection_id} to update the name of Ethernet connection with payload as name which is updated connection name

Delete Ethernet Connection

Use DELETE api/v2/connection/services/{connection_id} to delete an Ethernet

List Ethernet connections

Use GET api/v2/connection/services endpoint

Retrieve single Ethernet Connection Information

Use GET api/v2/connection/{connection_id}

Use GET /api/v2/connection/requests

Modify Bandwidth

Modify VLAN configuration

Use PUT /api/v2/connection/services/{connection_id} to update the VLAN parameters connection with payload with updated VLAN parameters

Modify Contractual Commitment

Step1.
Use GET /api/prices?version=1&service_type=ETHERNETCIRCUIT&connection_id={connection_id}&version={updated_version_id}

Step 2.
Use PUT api/connection/services/{connection_id} with payload

{    
  "price_id": <price_id>,
  "coterminus_option": <coterminus_option>
}

Schedule Bandwidth Changes

This is only available for services with no commitment.
Retrieve prices using /api/prices?service_type=ETHERNETCIRCUIT&connection_id={connection_id} Use POST /api/schedule with payload

{
  "price_id": <price_id>,
  "connection_id": " <connection_id>",
  "event_frequency": "< event_frequency>",
  "event_date": "<event_date>"
}

Where event_frequency could be ONE_OFF, WEEKLY, MONTHLY etc

Create Cloud Connection

There is an ethernet port which is already created at “A end “ and at the B end a cloud port is used and a connection is ordered between them.

{
  "price_id": <price_id>,
  "connection_name": "<connection_name>",
  "component_connections": [
    {
      "from_port_id": "<from_port_id>",
      "to_port_id": "<to_port_id>",
      "cloud_provider_from_port": "<cloud_provider_from_port>",
      "cloud_provider_to_port": cloud_provider_to_port,
      "a_end_vlan_mapping": "<a_end_vlan_mapping>",
      "b_end_vlan_mapping": "<b_end_vlan_mapping>",
      "a_end_vlan_type": "<a_end_vlan_type>",
      "b_end_vlan_type": "<b_end_vlan_type>",
      "a_end_vlan_ids": [],
      "b_end_vlan_ids": []
    }
  ]
}

For Equinix cloud cloud_provider_from_port is EQUINIX_CLOUD. For AWS Dedicated cloud_provider_from_port is AWS_DEDICATED For AWS HOSTED cloud_provider_from_port is AWS_HOSTED

Rename Cloud Connection

Use PUT /api/connections/{connection_id} to update the name of connection with payload as name which is updated connection name

Delete Cloud Connection

Use DELETE api/connections/{connection_id} to delete Cloud Connection

List Cloud connections

Use GET api/connections endpoint with attribute is_cloud_connection=true in the response

Retrieve single cloud Connection Information

Use GET api/connections/{connection_id}

Use GET /api/requests and in the result search for requests which has resource as “CONNECTION” and id is the connection id and is_cloud=true

Modify Bandwidth

Use PUT /api/connections/{connection_id} to update the bandwidth by providing price_id which can be retrieved using GET /api/prices?service_type=CLOUDCIRCUIT&connection_id=

Modify VLAN configuration

Use PUT /api/connections/{connection_id} to update the VLAN parameters connection with payload with updated VLAN parameters

Modify Contractual Commitment

Step1. Use GET /api/prices?version=1&service_type=CLOUDCIRCUIT&connection_id={connection_id}&version={updated_version_id}
Step 2. Use PUT api/connections/{connection_id} with payload

{
  "price_id": <price_id>,
  "coterminus_option": < coterminus_option>,
  "is_cloud_connection": < is_cloud_connection >
}

where is_cloud_connection = true

Schedule Bandwidth Changes

This is only available for services with no commitment.
Retrieve prices using /api/prices?service_type=CLOUDCIRCUIT&connection_id={connection_id} and use POST Use POST /api/schedule with payload

{
  "price_id": "<price_id>",
  "connection_id": " <connection_id>",
  "event_frequency": "< event_frequency>",
  "event_date": "<event_date>"
}

event_frequency could be ONE_OFF, WEEKLY, MONTHLY etc

Create IP Access Connections

Add an IP Access Connection

Step 3. Call POST /api/ipaccess/request with payload

{
  "action": "CREATE",
  "price_id": <price_id>,
  "connection_name": "<connection_name>",
  "from_port_id": "<from_port_id>",
  "port_vlan_mapping": "< port_vlan_mapping >",
  "port_vlan_type": "< port_vlan_type >",
  "port_vlan_ids": [
    {
      "from_id_range": < from_id_range>,
      "to_id_range": < to_id_range >
    }
  ]
}

Rename IP Access connection

Use PUT /api/ipaccess/service/{connection_id} and payload as connection_name which is updated name for the connection.

Delete IP Access Connection

Use POST /api/ipaccess/request with payload{"action":"DELETE","connection_id":""}

List IP Access Connections

Use GET /api/ipaccess/service to retrieve IP Access connections where available is mandatory query parameter

Use GET /api/ipaccess/request

Modify Bandwidth

Step 1. Retrieve price using GET /api/prices?service_type={service_type}&connection_id={connection_id} where service_type = IPACCESS_CIRCUIT
Step 2. Call /api/ipaccess/request with payload

{
  "action":"<action> ",
  "price_id":<price_id>,
  "coterminus_option":< coterminus_option>,
  "connection_id":"<connection_id>"
} where action = UPDATE

Modify VLAN Configuration

Call POST [api/ipaccess/request] (#post-/ipaccess/request) with payload

{
  "action": "<action>",
  "connection_id": "<connection_identifier>",
  "port_vlan_mapping": "< coterminus_option >",
  "port_vlan_type": "< port_vlan_type >",
  "port_vlan_ids": [
    {
      "from_id_range": "<VLAN_ID>",
      "to_id_range": "<VLAN_ID>"
    }
  ]
}

where action= UPDATE , port_vlan_mapping = X, port_vlan_type= C and VLAN_ID= numerical VLAN id

Modify Contractual Commitment

Step 1. call GET /api/prices?version=1&service_type=IPACCESS_CIRCUIT&connection_id={connection_id}&version={updated_version_id}
Step 2. call POST api/ipaccess/request/ with payload

{
  "action": "<action>",
  "price_id": <price_id>,
  "coterminus_option": <coterminus_option>,
  "connection_id": "<connection_id>"
}

Retrieve IP Access Connection Information

Use GET api/ipaccess/request/{request_id}

Use GET api/ipaccess/request/ retrieve the service_id from the session and find out the related requests

Cross-connects

Please note that only fibre cross connects are supported - copper cross connects are not supported.

Add Cross-connect

{
  "port_request_id": "< port_request_id>",
  "port_id": "<port_id>",
  "customer_pp_port": "< customer_pp_port >",
  "customer_pp_floor": "< customer_pp_floor>",
  "customer_pp_room": "< customer_pp_room>",
  "customer_pp_cabinet": "< customer_pp_cabinet>",
  "customer_pp_rack": "< customer_pp_rack>",
  "customer_pp_device": "< customer_pp_device >",
  "customer_pp_slot": "< customer_pp_slot>",
  "customer_pp_connector": "< customer_pp_connector >",
  "loa": "<loa>",
  "price_id": "<price_id>",
  "connector": "<connector>"
}

Delete cross connect

Use DELETE api/cross_connect/{id} to delete a cross connect where id is cross_connect identifier

List Cross-connects

Use GET api/cross_connect to retrieve list of cross connect and related data connections data

Retrieve Cross-connect Information

Use GET api/cross_connect/{id} to retrieve data for single cross connection where id is cross_connect identifier

Use GET /api/requests and search for requests which has resource as “CROSSCONNECT” and id is the port id

Retrieve Billing Data

Use GET charges to retrieve all the charges associated with Ports, Connections and Boosted bandwidths for Cloud, Ethernet and IP Access connections for a given customer

Provide Bandwidth Boost

Retrieve Bandwidth boost options for connection type

Apply Bandwidth boost to existing connection

Step 2. Use PUT /api/connections/{connection_id} with request payload attribute boost_bandwidth_mbps as query param

List available Bandwidth Boost and prices for a connection

Use GET /api/connections search for rental_boost_charge and bandwidth_mb which represent the bandwidth and its corresponding charges at a given date.

Find Boosted bandwidth for connection

Use Get /api/connections check for base_bandwidth and bandwidth values and if they are different use the bandwidth value as boosted value

Find Boosted bandwidth requests

Charges associated with bandwidth boost

Use GET /api/charges. boost_charges array will have amount, date on whihc boost was applied and type=BOOST values.

Retrieve Trouble tickets data

Use GET tickets to retrieve all the trouble tickets raised by system or service desk and provide view of status on each one of them to your customer.

Retrieve tickets data

Use GET api/tickets to retrieve all the tickets information

Manage multiple customers accounts

{
"id": 49652,
"accepted": true
}

End-to-end use-cases

Create Point to Point connection

Create a-end ethernet port
Create b-end ethernet port
Create ethernet connection with P-P VLAN mapping.

Step 1. Add two Ethernet port
Step 2. Make Ethernet connection with payload

{
  
"from_port_id": "<from_port_id>",
"from_vlans": {
  "vlan_mapping": "P",
  "vlan_type": "",
  "vlan_id": null
},
"name": "P2Pconnection",
"price": {
  "price_id": <price_id>
},
"to_port_id": "<to_port_id>",
"to_vlans": {
  "vlan_mapping": "P",
  "vlan_type": "",
  "vlan_id": null
}

}

Where vlan_mapping are “P” for both from and to port Refer P2P section of the Ethernet connection

Create Hub and Spoke connection

Create b-end ethernet port
Create ethernet connection with X-P or X-X (x on hub end)or F-F mapping

Order bundle for Ethernet (New*)

This means that customers in one single action can submit:

A port create request for the a-end by using POST /api/v2/port/services operation
A port create request for the b-end again using POST /api/v2/port/services operation and
Submit a connection request between the a-end and b-end ports using POST /v2/connection/services operation while the ports are still getting created to achieve this.

Create a Cloud Connection

This is made of 3 steps:

Create a cloud port
Create an ethernet port (optional if already available)
Create a cloud connection Refer Cloud connections

Create an IP Access Connection

This is made of 2 steps:

Create an ethernet port
Create an IP access connection. Refer IP Access section

Cross connect

Add ethernet port
Add cross connect

Address qualification

{
  "building_id": "<building_id",
  "location_name": "<location_name>",
  "country": "<country_name>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

If the Address is reachable API responds with

{
  "nearnet_price_id":<nearnet_price_id>,
  "reachable": true,
  "installation_currency": "<currency>",
  "installation_charge": <charge>
}

If not then Colt connection is not supported at the location. Add the building to Address book Use POST /api/locations with payload

{  
"location_name": "<location_name>",
  "city": "<city>",
  "country": "<country>”,
  "latitude": <latitude>,
  "longitude": <longitude>,
  "address": ",address>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

Refer a flowchart below for the process steps.

The referenced media source is missing and needs to be re-embedded.

Add new site to building

Step1. Search for a site availability at a given building use GET api/building//site this should result in empty site data array
Step 2. To add a new site use POST /api/locations

{
  "building_id": "< building_id >",
  "location_name": "< location_name >",
  "country": "<country_name>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

The referenced media source is missing and needs to be re-embedded.

Find Prices for ordering a Port or making a connection

Note for other cloud providers service attribute changes according to provider and to_site_type_1 attribute is not needed.

Terminology

CEA - Common Equipment Area
Coterminus option: When changing a connection in some chargeable way, this option defines whether the new contract should run only until the end date of the current contract (true), or whether you want to “reset” the contract period to start from the date of the change”.
Cross Connect: A cross-connect is a physical, hardwired cable that provides a direct connection between two different termination locations within a data centre. the letter of authority is NOT provided by the datacentre owner, it has to be provided by the owner of the equipment you are connecting to, i.e. Colt if the customer orders the cross-connect and the customer if Colt orders it.
Global directory: Information of buildings where Colt’s connectivity is available
LOA: Letter of authority provided to install connection
MMR: Meet me room
novitas_site_type: Is a Colt term to represent a site e.g. KDC-PL-WOW created by combining the building category (KDC, DCNET, LANLINK, DCA-MSA, DCA-AWSH, etc), PL 2 letter country code and WOW 3 letter metropolitan area code.
Order id: This is generated by Siebel for siteport and cross-connect requests
PORT_TYPE: DCNPORT/LANPORT/DCAPORT - DCNPORTs are located in data centres. LANPORTs are located on customer premise. DCAPORTs are cloud ports.
Product: Colt products e.g. Twisted pair electrical 1Gbps ethernet port
Request ID- Request identifier is created for every state chnage of connection e.g. create,modify,delete.
Service ID- A unique reference to a service the customer has paid for/requested from the time it is created until the time it is terminated. Applies to all Ports & Connections.
Service Type: Connectivity prices are derived basis Service types e.g. ETHERNETPORT'' , CROSSCONNECT or ''ETHERNETCIRCUIT
Shared area: This is a place where along with other providers Colt connectivity can be provided
Site: Location in the building where ports can be installed.
SITEPORT: This is a request type which only installs the capacity – this will also create a PORT request to reserve the capacity once it has been delivered.
VLAN type: S-VLAN (88a8) or C-VLAN (8100)

Introducing SDN APIs

The Colt On-demand platform offers a suite of flexible connectivity solutions, including on-demand Ethernet connectivity between enterprise locations and data centers, direct cloud connectivity to major public cloud providers, on-demand internet access, and cross-connects within data centers. Customers can utilize Colt's APIs to quickly provision and scale these network services as needed, benefiting from features like real-time provisioning and flexible billing options without long-term commitments.

Ethernet port
Ethernet connection
Cloud Port
IPAccess connection
Cross connect

How to get access to this API?

If you are a Colt customer then please contact your Account Executive.

What is the onboarding process?

Your Account Executive will request the logins for the sandbox account. AE will share the details with you.

The sandbox environment has production like features and you are free to test any use case using the APIs. Our devops team will support you during this period.

How to get support for this API?

You can use the support option available in On-demand portal for post-production support.

Not a customer yet?

Contact our Sales Team

How to Try the API?

To try the API and different operations please use On demand API Documentation

checkPriceExists

Read more about checkPriceExists

checkPrice

Read more about checkPrice

checkConnectivity

Read more about checkConnectivity

Subscribe to

Voice Billing API Details

Response Schema

Please find below list of the ones applicable to Port-In orders:

port-out order might have additional status [orderStatus] than the ones described in the section 2.5.

Error Codes

How to get access to this API?

How to use this API

Not a customer yet?

How to get access to this API?

What is the onboarding process?

How to get support for this API?

Not a customer yet?

How to Try the API?

Colt On Demand Solutions

Product Structure

API Security

Generic Response Code

Success

Errors

Versioning

Use-cases

End points

Use new API v2/port/services to create,modify,delete and retrieve Ethernet port

Ethernet ports

Add an Ethernet Port

Rename an Ethernet port

Delete an Ethernet Port

List Ethernet ports

Retrieve a single Ethernet Port information

Download Letter of Authority

Find related requests

Find related connections

Find related cross connection

Cloud Ports

MS Azure ExpressRoute

Add cloud port

Rename Cloud Port

Delete Cloud Port

List Cloud Ports

Retrieve a single Cloud Port information

Find related requests

AWS DirectConnect Dedicated Cloud Port

Add Cloud Port

Rename Cloud Port

Delete Cloud Port

List Cloud Ports

Retrieve Cloud Port information

Find related requests

AWS DirectConnect Hosted Cloud Port

Add Cloud Port

Rename Cloud Port

Delete Cloud Port

List Cloud Ports

Retrieve a single Cloud Port information

Find related requests

Google Cloud Partner Interconnect

Add Cloud Port

Rename Cloud Port

Delete Cloud Port

List Cloud Ports

Retrieve a single Cloud Port information

Find related requests

IBM Cloud DirectConnect

Add Cloud Port

Rename Cloud Port

Delete Cloud Port

List Cloud ports

Retrieve a single Cloud Port information

Find related requests

Oracle Cloud FastConnect

Add Cloud Port

Rename Cloud Port

Delete Cloud Port

List Cloud ports

Retrieve single port data

Find related requests

Equinix Fabric Interconnect

Add Cloud Port

Rename Cloud Port

Delete Cloud Port