openapi: 3.0.1
info:
title: connect Address Management order API
description: "The Cloud Connect Service is a comprehensive multi-cloud one-stop-shop solution that provides a unique combination of layer 2 transport, which is provided by BICS, and dedicated connectivity (hosted connection) directly to the Cloud Service Provider (CSP) infrastructure. This service bypasses the public internet, ensuring reliable, secure, and fast connectivity.\n\nWithin each Cloud Connect Service, the Ethernet Virtual Private Line (EVPL) is provisioned on BICS network defined by MEF 6.2. The EVPL is a secure, point-to-point Ethernet service that provides a high-performance, low-latency connection between your on-premises infrastructure and the CSP infrastructure. \n\nThank you for considering BICS Cloud Connect Service and using our API. If you have any questions or concerns, please contact BICS customer support."
version: v1
servers:
- url: https://api.bics.com/connect/v1
tags:
- name: order
description: Purchase a number from the stock.
paths:
/order/bulk:
parameters: []
post:
tags:
- order
summary: Order easily single or multiple number(s) that we have in our stock.
description: 'Order easily single or multiple number(s) that we have in our stock. The method _/order_ provisions the number on the fly. In other words, the number can be used immediately after the API call.
You just have to fill out in your request the product and the country. Location, area code, quantity of numbers and routing details can be provided to better fit your needs. The content type of the request must be _application/json_.
You can also provide as an input one or multiple specific number(s) that we have in stock. The list of available numbers can be retrieved by calling the method _/availablenumbers_.
For some countries, you also need to specify the reference of the address of the end subscriber. For more information about address requirements, please read the Specifications API section and section Address Management API.
In case there are not enough numbers in stock, you also have the opportunity to split order in two orders: A regular order composed of the numbers that are available in stock and a back order for the remaining numbers that our operational team will fulfill as soon as possible. You can mention the order options in your request to specify the type of orders that API can create for you.'
operationId: Order Numbers In Bulk
parameters: []
requestBody:
description: Criteria's to order and provision routings of bulk numbers.
content:
application/json:
schema:
$ref: '#/components/schemas/bulkOrder'
example: null
required: true
responses:
'200':
description: The provisioned number
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/bulkOrderResponse'
example: null
example: null
'400':
description: Bad request, An issue occurred while processing the input parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/numberSpecificError'
example: null
'404':
description: No available numbers in stock anymore.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
/order/{orderId}:
parameters: []
get:
tags:
- order
summary: Get order by order id
description: The _/order/{orderId}_ method allows you to retrieve the details of a given order. As a response you will receive all information linked to the order that would help you manage it at your convenience.
operationId: Get Order Details
parameters:
- name: orderId
in: path
description: A given order identifier
required: true
allowEmptyValue: false
schema:
type: string
description: A given order identifier
readOnly: false
example: '34535'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/bulkOrderResponse'
example: null
'400':
description: Bad request, An issue occurred while processing the input parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
'401':
description: the API Key was not mentioned or is invalid (see authentication)
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
'403':
description: this service cannot be used according to your API Key
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
'404':
description: Order does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
/order:
parameters: []
post:
tags:
- order
summary: Order a single available number
description: 'Order easily single number that we have in our stock. The method _/order_ provisions the number on the fly. In other words, the number can be used immediately after the API call.
You just have to fill out in your request the product and the country. Location, area code, and routing details can be provided to better fit your needs.
The content type of the request must be application/json. For some countries, you also need to specify the reference of the address of the end subscriber. For more information about address requirements, please read the Specifications API section and section Address Management API.
In case there are not enough numbers in stock, you also have an opportunity to create an order that our operational team will fulfill as soon as possible. You can mention the order options in your request to specify the type of orders that API can create for you.'
operationId: Order Single Number
parameters: []
requestBody:
description: Criteria's to order and provision routing of one number.
content:
application/json:
schema:
$ref: '#/components/schemas/order'
example: null
required: true
responses:
'200':
description: The provisioned number
content:
application/json:
schema:
$ref: '#/components/schemas/orderResponse'
example: "{\n 'number': '81345785554',\n 'product': 'IBN',\n 'country': 'JPN',\n 'accessArea': 'NA',\n 'location': 'Tokyo',\n 'areaCode': '3',\n 'orderId': '34521',\n 'addressReference': '1247b1ca-ffec-4576-be45-c837cdbff546'\n 'routing': [\n {\n 'accessType': 'fixMobPay',\n 'accessNetwork': null,\n 'crnType': 'prefix',\n 'crnValue': '234A',\n 'crn': '234A81345785554',\n 'pop': 'ASIA'\n }\n ]\n}\n"
'400':
description: Bad request, An issue occurred while processing the input parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
'404':
description: No available numbers in stock anymore.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
/order/{orderReference}/orderItem/{orderItemReference}:
parameters: []
patch:
tags:
- order
summary: Edit order by change address reference
description: The _/order/{orderReference}/orderItem/{orderItemReference}_ method allows you to change the address reference linked to an order item. It must be used in case the address that you initially provided is not valid and you want to provide another one to fulfil the order.
operationId: Edit Order
parameters:
- name: orderReference
in: path
description: A given order reference
required: true
allowEmptyValue: false
schema:
type: string
description: A given order reference
readOnly: false
example: '34535'
- name: orderItemReference
in: path
description: A given order item reference
required: true
allowEmptyValue: false
schema:
type: string
description: A given order item reference
readOnly: false
example: '45953'
requestBody:
description: Customer's address reference
content:
application/json:
schema:
$ref: '#/components/schemas/orderItemPatchRequest'
example: null
required: true
responses:
'400':
description: Bad request, An issue occurred while processing the input parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
'204':
description: Address Reference updated for given order item.
components:
schemas:
order:
type: object
allOf:
- required:
- country
- product
type: object
properties:
country:
type: string
description: Country code in ISO 3166-1 alpha-3 format.
example: BEL
product:
type: string
description: Valid product codes are 'IBN', 'ITFS' and 'GMN'. IBN referring to Cloud Numbers, ITFS referring to International Freephone and GMN referring to Global Mobile Number.
example: IBN
areaCode:
type: string
description: Optional parameter that indicates the area code of the number according to the national numbering plan. This attribute is not mandatory.
example: '2'
orderOptions:
$ref: '#/components/schemas/orderOptions'
accessArea:
type: string
description: Optional parameter allowing to select an exact price definition. See pricelist method for more info.
example: NA
addressReference:
type: string
description: Optional parameter allowing to specify the reference of the address you want to link to the Cloud Number. It must be used to order numbers in countries where address of the end subscriber is required.
example: 37a50zzb-d568-4ddd-b11d-jejc7c2j3e30
profile:
type: string
description: Optional parameter allowing to select an exact price definition. See pricelist method for more info.
example: Profile A
location:
type: string
description: Optional parameter that indicates in most cases the city that is attached to the number according to the national numbering plan. Sometimes, it is used to indicate whether it is a national or a mobile number. This attribute is not mandatory and can be filled in for Cloud Number (IBN) only.
example: Brussels
myReference:
type: string
description: Optional parameter that allows you to specify your own order reference.
example: AB4569
example: null
- $ref: '#/components/schemas/customerRoutingContainer'
example: null
crnType:
type: string
description: "The translation rule for the customer routing number that you want to apply to the number.\n<ul>\n <li>`prefix` - To prefix the access number with the specified crnValue.</li>\n <li>`suffix` - To suffix the access number with the specified crnValue.</li>\n <li>`freetext` - To define your own customer routing number.</li>\n <li>`copy` - To use the access number as your customer routing number.</li>\n <li>`NA` - To bar incoming calls for this routing.</li>\n</ul>\n"
example: prefix
enum:
- prefix
- suffix
- freetext
- copy
- NA
validationStatus:
type: string
enum:
- Need more information
- Under validation
- Validated
- No validation required
example: null
orderRequestItem:
type: object
allOf:
- type: object
properties:
number:
type: string
description: The number that you want to order. This attribute needs to be specified if you buy specific numbers.
example: '81345785554'
addressReference:
type: string
description: Optional parameter that allows you to specify the reference of the address you want to link to the number. It must be used to order number in countries where the end-user address is required.
example: 37a50zzb-d568-4ddd-b11d-jejc7c2j3e30
description: If you want to buy one or multiple specific numbers, you can provide the numbers in the appropriate format. For each number you can provide the address reference and the routing information.
example: null
- $ref: '#/components/schemas/customerRoutingContainer'
example: null
responseRoutingWithDetails:
type: object
allOf:
- type: object
properties:
crnValue:
type: string
description: 'The value to be used by the translation rule of the crnType. Only applicable to crnTypes prefix, suffix and freetext.
'
example: 259AB
crnType:
$ref: '#/components/schemas/crnType'
example: null
- $ref: '#/components/schemas/responseRouting'
example: null
customerRoutingContainer:
type: object
properties:
routing:
type: array
description: The routing configuration you want to apply for this number.
items:
$ref: '#/components/schemas/customerRouting'
example: null
example: null
responseRouting:
type: object
properties:
accessType:
type: string
description: "Access type of the calling party. You can apply a different routing per access type. The possible values are\n<ul>\n <li> fix: Fix line</li>\n <li> mob: Mobile line</li>\n <li> pay: Payphone line</li>\n <li> fixMob: Fix and Mobile lines</li>\n <li> fixPay: Fix and Payphone lines</li>\n <li> mobPay: Mobile and Payphone lines</li>\n <li> fixMobPay: Fix, Mobile and Payphone lines</li>\n</ul>\n"
example: fixMobPay
pop:
type: string
description: Point of Presence (PoP) refers to your access point to which the traffic is routed.
example: ASIA
accessNetwork:
type: string
description: Parameter describing the network of the calling party. Different routes can be used per access network.
example: BICS
crn:
type: string
description: Customer Routing Number.
example: 259AB81345785554
example: null
orderItemPatchRequest:
type: object
properties:
addressReference:
type: string
description: Address reference id.
example: 365c51a4-07b8-4b04-bb6c-cbf1a1cc2205
example: null
orderStatus:
type: string
description: "Status of the order. For real-time number provisioning, the order status starts as <b>Provisioning</b> and updates to <b>Delivered</b> once completed in backend systems.\n<ul>\n <li>Created: Order is created. BICS will fulfil it as soon as possible.</li>\n <li>End user information under validation: BICS validates provided end user information.</li>\n <li>On hold, need more information: Some information is missing such as proof of document. Attribute Comment gives additional information.</li>\n <li>Being processed: Order is being processed. Numbers will be provisioned soon.</li>\n <li>Provisioning: Numbers are currently being set up and are not yet available for use. Once provisioning is complete, the status will be updated to <b>Delivered</b>.</li>\n <li>Delivered: Order is delivered, and numbers are provisioned.</li>\n <li>Cancelled by you: Order cancelled by you.</li>\n <li>Cancelled by BICS: Order cancelled by BICS.</li>\n</ul>\n"
enum:
- Created
- End user information under validation
- On hold, more information required
- Being processed
- Provisioning
- Delivered
- Cancelled by you
- Cancelled by BICS
example: null
orderResponse:
type: object
properties:
number:
type: string
description: The provisioned access number
example: '81345785554'
country:
type: string
description: Country code in ISO 3166-1 alpha-3 format.
example: JPN
routing:
type: array
description: The routing configuration applied.
items:
$ref: '#/components/schemas/responseRoutingWithDetails'
example: null
product:
type: string
description: Valid product codes are 'IBN' and 'ITFS'. IBN referring to Cloud Numbers and ITFS referring to International Freephone.
example: IBN
areaCode:
type: string
description: Optional parameter that indicates the area code of the number according to the national numbering plan. This attribute is not mandatory.
example: '3'
accessArea:
type: string
description: The tariff differentiator the access number belongs to.
example: NA
addressReference:
type: string
description: Identifier of the address of the end subscriber. It must be used to order numbers in countries where address of the end subscriber is required.
example: 37a50zzb-d568-4ddd-b11d-jejc7c2j3e30
orderId:
type: string
description: SHOUL BE ADAPTED - Reference of your order. This will refer to your order on the MyNumbers portal.
example: '34521'
location:
type: string
description: A Location indicates in most cases the city the number belongs to. It is also used to specify if it is a national or a mobile number.
example: Tokyo
status:
$ref: '#/components/schemas/orderStatus'
example: null
accessType:
type: string
description: "Access type of the calling party. You can apply a different routing per access type. The possible values are\n<ul>\n <li> fix: Fix line</li>\n <li> mob: Mobile line</li>\n <li> pay: Payphone line</li>\n <li> fixMob: Fix and Mobile lines</li>\n <li> fixPay: Fix and Payphone lines</li>\n <li> mobPay: Mobile and Payphone lines</li>\n <li> fixMobPay: Fix, Mobile and Payphone lines</li>\n</ul>\n"
enum:
- fix
- mob
- pay
- fixMob
- fixPay
- mobPay
- fixMobPay
example: null
bulkOrderResponse:
type: object
properties:
country:
type: string
description: Country code in ISO 3166-1 alpha-3 format.
example: JPN
product:
type: string
description: Valid product codes are 'IBN' and 'ITFS'. IBN referring to Cloud Numbers and ITFS referring to International Freephone.
example: IBN
orderId:
type: string
description: Identifier of your order.
example: '34521'
profile:
type: string
description: Tariff differentiator within a country. It intervenes in the billing.
example: Profile A
orderItems:
type: array
description: An order is composed of an array of items. There is an order item per number provisioned.
items:
$ref: '#/components/schemas/orderItem'
example: null
areaCode:
type: string
description: Area code of the number according to the national numbering plan.
example: '3'
createdDate:
type: string
description: Created date of the order.
format: date-time
example: '2019-12-17T01:00:00+01:00'
accessArea:
type: string
description: Used to differentiate the tariff of the number when relevant.
example: NA
modifiedDate:
type: string
description: Modified date of the order.
format: date-time
example: '2019-12-18T03:20:00+01:00'
comment:
type: string
description: Additional information on the status of the order. It helps you to understand what you need to provide to fulfil your order.
example: Please provide the company registration
location:
type: string
description: Location indicates in most cases the city that is attached to the number according to the national numbering plan. Sometimes, it is used to indicate whether it is a national or a mobile number.
example: Tokyo
myReference:
type: string
description: Your internal order reference.
example: AB4569
status:
$ref: '#/components/schemas/orderStatus'
example: null
orderItem:
type: object
properties:
number:
type: string
description: The provisioned number.
example: '81345785554'
routing:
type: array
description: Routing configuration applied.
items:
$ref: '#/components/schemas/responseRoutingWithDetails'
example: null
areaCode:
type: string
description: Area code of the number according to the national numbering plan.
example: '3'
addressReference:
type: string
description: Reference of the address you have linked to the number.
example: 37a50zzb-d568-4ddd-b11d-jejc7c2j3e30
orderItemId:
type: string
description: Reference of the order item.
example: '63451'
location:
type: string
description: Location indicates in most cases the city that is attached to the number according to the national numbering plan. Sometimes, it is used to indicate whether it is a national or a mobile number.
example: Tokyo
endUserInfoValidation:
$ref: '#/components/schemas/endUserInfoValidation'
example: null
endUserInfoValidation:
type: object
properties:
addressDocuments:
$ref: '#/components/schemas/validationStatus'
address:
$ref: '#/components/schemas/validationStatus'
description: 'Set of attributes indicates the validation status of the end user information. Attribute address gives the
status of the address of the end user and attribute addressDocuments gives the status of the documents provided
against the country specifications.
'
example: null
bulkOrder:
type: object
allOf:
- type: object
properties:
country:
type: string
description: Country code in ISO 3166-1 alpha-3 format. This attribute does not need to be specified if you buy specific numbers, otherwise it is mandatory.
example: BEL
orderRequestItems:
type: array
description: If you want to buy one or multiple specific numbers, you can provide the numbers in the appropriate format. For each number you can provide the address reference and the routing information.
items:
$ref: '#/components/schemas/orderRequestItem'
example: null
product:
type: string
description: Valid product codes are IBN, ITFS and GMN. IBN referring to Cloud Number, ITFS referring to International Freephone Number and GMN referring to Global Mobile Number. This attribute does not need to be specified if you buy specific numbers, otherwise it is mandatory.
example: IBN
areaCode:
type: string
description: Optional parameter that indicates the area code of the number according to the national numbering plan. This attribute is not mandatory.
example: '2'
quantity:
type: integer
description: Quantity of numbers you want to buy. If not specified only 1 number will be ordered.
example: 1
orderOptions:
$ref: '#/components/schemas/orderOptions'
addressReference:
type: string
description: Optional parameter that allows you to specify the reference of the address you want to link to the numbers. It must be used to order numbers in countries where the end-user address is required.
example: 37a50zzb-d568-4ddd-b11d-jejc7c2j3e30
location:
type: string
description: Optional parameter that indicates in most cases the city that is attached to the number according to the national numbering plan. Sometimes, it is used to indicate whether it is a national or a mobile number. This attribute is not mandatory and can be filled in for Cloud Number (IBN) only.
example: brussels
myReference:
type: string
description: Optional parameter that allows you to specify your own order reference.
example: AB4569
example: null
- $ref: '#/components/schemas/customerRoutingContainer'
example: null
error:
type: object
properties:
code:
type: string
description: Error code, the complete description can be found in API documentation
example: EXXX
description:
type: string
description: Description of the error, the complete description can be found in API documentation
example: Description of the error that occurred.
timestamp:
type: string
description: timestamp of error in UTC format
format: date-time
example: null
example: null
orderOptions:
type: object
properties:
backOrderAllowed:
type: boolean
description: Optional parameter that indicates if MyNumbers API is allowed to create an order that will be fulfilled by our operational team. It occurs when there are no numbers available in our stock. By default, this attribute is set to False.
example: true
consecutiveNumbers:
type: boolean
description: Optional parameter to indicate if consecutive numbers should be ordered. By default, this attribute is set to False.
example: true
firstNumberEndsWith:
type: string
description: Optional parameter to specify the ending digits of the first consecutive number. Only digits are allowed, and it must be a maximum of 4 digits.
example: '1234'
regularOrderAllowed:
type: boolean
description: Optional parameter that indicates if MyNumbers API is allowed to create an order that will be fulfilled by our operational team. It occurs when manual end user information is required. By default, this attribute is set to False.
example: true
description: Optional parameters that allow you to specify the type of orders you want to get.
example: null
numberSpecificError:
type: object
allOf:
- $ref: '#/components/schemas/error'
- type: object
properties:
number:
type: string
example: Number to which error corresponds to.
country:
type: string
example: Number and Origin Country code in ISO 3166-1 alpha-3 to which error corresponds to.
example: null
example: null
customerRouting:
required:
- crnType
type: object
properties:
accessType:
$ref: '#/components/schemas/accessType'
pop:
type: string
description: Point of Presence (PoP) refers to your access point to which the traffic is routed.
example: America
accessNetwork:
type: string
description: The network of the calling party. Routing detail can differ per access network of the calling party.
example: SMART
crnValue:
type: string
description: 'The value to be used by the translation rule of the crnType. Only applicable to crnTypes prefix, suffix and freetext.
'
example: 259AB
crnType:
$ref: '#/components/schemas/crnType'
description: This parameter allows you to specify routing information for the numbers you buy. You can differentiate calls based on access type/access network by defining a different customer routing number per access type/access network. For more info about the combination access type/access network, please consult the method Get Pricelist. If you want to define the same routing configuration for every combination access type/access network, you can omit the routing attributes Access Type and Access Network, and only specify crnType and crnValue. If you order multiple numbers at once (by providing the quantity parameter) the same routing will be applied to all numbers ordered.
example: null