openapi: 3.0.1
info:
title: connect Address Management inventory 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: inventory
description: Query the numbers you have bought over time.
paths:
/numbers:
parameters: []
get:
tags:
- inventory
summary: Retrieve the list of numbers in your inventory.
description: The _/numbers_ method allows you to retrieve the list of numbers in your inventory. You can retrieve the full list of your numbers in one call or filter out your request by providing the product, country, location, area code, status and number. As a response you will receive information linked to the number(s) that would help you manage them at your convenience.
operationId: get Inventory
parameters:
- name: product
in: query
description: Filter your inventory by product.
required: false
allowEmptyValue: false
schema:
type: string
description: Filter your inventory by product.
readOnly: false
example: IBN
- name: country
in: query
description: Filter your inventory by country in ISO 3166-1 alpha-3 format.
required: false
allowEmptyValue: false
schema:
type: string
description: Filter your inventory by country in ISO 3166-1 alpha-3 format.
readOnly: false
example: GBR
- name: location
in: query
description: Filter your inventory by location. (Not applicable for product GMN).
required: false
allowEmptyValue: false
schema:
type: string
description: Filter your inventory by location. (Not applicable for product GMN).
readOnly: false
example: National
- name: areaCode
in: query
description: Filter your inventory by areaCode.
required: false
allowEmptyValue: false
schema:
type: string
description: Filter your inventory by areaCode.
readOnly: false
example: '3'
- name: status
in: query
description: Filter your inventory by status. Valid status values are _Active_ and _Deactivated_. _Active_ referring to numbers provisioned and _Deactivated_ referring to numbers disconnected.
required: false
allowEmptyValue: false
schema:
type: string
description: Filter your inventory by status. Valid status values are _Active_ and _Deactivated_. _Active_ referring to numbers provisioned and _Deactivated_ referring to numbers disconnected.
readOnly: false
example: Active
- name: number
in: query
description: Filter your inventory by number. Exact match is applied.
required: false
allowEmptyValue: false
schema:
type: string
description: Filter your inventory by number. Exact match is applied.
readOnly: false
example: '445706070212'
- name: activeServiceCode
in: query
description: Filter your inventory by services. You can filter on multiple values. Possible values. <ul> <li>IC - Inbound Call</li> <li>NOC - National Outbound Call</li> <li>IOC - International Outbound Call</li> <li>ES - Emergency Services</li> <li>DS - Directory Services</li> <li>IM - Inbound Messaging</li> <li>NOM - National Outbound Messaging</li> <li>IOM - International Outbound Messaging</li> </ul>
required: false
allowEmptyValue: false
schema:
type: array
description: Filter your inventory by services. You can filter on multiple values. Possible values. <ul> <li>IC - Inbound Call</li> <li>NOC - National Outbound Call</li> <li>IOC - International Outbound Call</li> <li>ES - Emergency Services</li> <li>DS - Directory Services</li> <li>IM - Inbound Messaging</li> <li>NOM - National Outbound Messaging</li> <li>IOM - International Outbound Messaging</li> </ul>
readOnly: false
items:
type: string
enum:
- IC
- NOC
- IOC
- ES
- DS
- IM
- NOM
- IOM
example: null
example: null
- name: availableServiceCode
in: query
description: Filter your inventory by services. You can filter on multiple values. Possible values. <ul> <li>IC - Inbound Call</li> <li>NOC - National Outbound Call</li> <li>IOC - International Outbound Call</li> <li>ES - Emergency Services</li> <li>DS - Directory Services</li> <li>IM - Inbound Messaging</li> <li>NOM - National Outbound Messaging</li> <li>IOM - International Outbound Messaging</li> </ul>
required: false
allowEmptyValue: false
schema:
type: array
description: Filter your inventory by services. You can filter on multiple values. Possible values. <ul> <li>IC - Inbound Call</li> <li>NOC - National Outbound Call</li> <li>IOC - International Outbound Call</li> <li>ES - Emergency Services</li> <li>DS - Directory Services</li> <li>IM - Inbound Messaging</li> <li>NOM - National Outbound Messaging</li> <li>IOM - International Outbound Messaging</li> </ul>
readOnly: false
items:
type: string
enum:
- IC
- NOC
- IOC
- ES
- DS
- IM
- NOM
- IOM
example: null
example: null
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/customerNumber'
example: null
example: "[\n {\n 'number': '445706070212',\n 'product': 'IBN',\n 'country': 'GBR',\n 'location': 'National',\n 'areaCode': '3',\n 'accessArea': 'NA',\n 'profile': 'Profile A',\n 'status': 'Active',\n 'addressReference': '3f47bde5-d198-4a04-ba04-7274012ff34a',\n 'startDate': '2018-11-05',\n 'endDate': null\n },\n {\n 'number': '445706070215',\n 'product': 'IBN',\n 'country': 'GBR',\n 'location': 'National',\n 'areaCode': '3',\n 'accessArea': 'NA',\n 'profile': 'Profile A',\n 'status': 'Active',\n 'addressReference': '3f47bde5-d198-4a04-ba04-7274012ff34a',\n 'startDate': '2018-11-05',\n 'endDate': null\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
'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
/numbers/{number}:
parameters: []
get:
tags:
- inventory
summary: Retrieve the details of a given number from your inventory.
description: The _/numbers/{number}_ method allows you to retrieve the details of a given number from your inventory. As a response you will receive all information linked to the numbers that would help you manage them at your convenience (origin, status, address reference, pricing and routing details).
operationId: get Number Details
parameters:
- name: number
in: path
description: A given number from your inventory.
required: true
allowEmptyValue: false
schema:
type: string
description: A given number from your inventory.
readOnly: false
example: '445706070212'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/customerNumberWithDetails'
example: "{\n 'number': '443706070212',\n 'product': 'IBN',\n 'country': 'GBR',\n 'location': 'National',\n 'areaCode': '3',\n 'accessArea': 'NA',\n 'profile': 'Profile A',\n 'status': 'Active',\n 'addressReference': '3f47bde5-d198-4a04-ba04-7274012ff34a',\n 'startDate': '2018-11-05',\n 'endDate': null,\n 'endUserInfoValidation': {\n 'address': 'Need more information',\n 'addressDocuments': 'No validation required'\n },\n 'routing': [\n {\n 'accessType': 'fixMobPay',\n 'accessNetwork': null,\n 'crn': '234A443706070212',\n 'pop': 'ASIA'\n }\n ],\n 'nonUsageFees': {\n 'setUpFee': 10.00,\n 'MonthlyFee': 5.00,\n 'currency': 'EUR'\n },\n 'usageFees': [\n {\n 'accessType': 'FixMobPay',\n 'accessNetwork': null,\n 'tde': 'STD',\n 'callSetUpFee': 0.0010,\n 'perMinuteFee': 0.0015,\n 'currency': 'EUR'\n }\n ]\n}\n"
'400':
description: Bad request, An issue occurred while processing the input parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/numberSpecificError'
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: Number not found.
content:
application/json:
schema:
$ref: '#/components/schemas/numberSpecificError'
example: null
/numbers/addressReferences:
parameters: []
post:
tags:
- inventory
summary: Add or update address reference linked to number(s)
description: The method _/numbers/addressReferences_ allows you to add or change the address linked to one or multiple number(s). You can retrieve the current address linked to a number by calling the method _/numbers/{number}_. You can retrieve a list of your addresses by calling the method _/addresses_.
operationId: Update address reference
parameters: []
requestBody:
description: TBF
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/addressReferenceUpdateRequest'
example: null
example: null
required: false
responses:
'200':
description: Address references updated for given numbers.
'400':
description: Bad request, An issue occurred while processing the input parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/numberSpecificError'
example: null
components:
schemas:
customerNumber:
type: object
properties:
number:
type: string
description: The provisioned number.
example: '443706070215'
country:
type: string
description: Country code in ISO 3166-1 alpha-3 format.
example: GBR
product:
type: string
description: Valid product codes are 'IBN' and 'ITFS'. IBN referring to Cloud Number and ITFS referring to International Freephone Number.
example: IBN
areaCode:
type: string
description: Area code of the number according to the national numbering plan.
example: '3'
accessArea:
type: string
description: Used to differentiate the tariff of the number when relevant.
example: NA
addressReference:
type: string
description: Reference of the address you have linked to the numbers.
example: 3f47bde5-d198-4a04-ba04-7274012ff34a
endDate:
type: string
description: Date when the number has been disconnected. The format of the date is yyyy-mm-dd.
format: date
example: 'null'
profile:
type: string
description: Tariff differentiator within a country. It intervenes in the billing.
example: Profile A
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: National
startDate:
type: string
description: Date when the number has been provisioned. The format of the date is yyyy-mm-dd.
format: date
example: '2018-11-05'
virtualSimCardNumber:
type: string
description: Virtual Sim Card Number linked to Access Number. (For GMN only)
example: null
status:
type: string
description: This attribute indicates the status of the number. Active if the number is provisioned or Deactivated if the number has been disconnected.
example: Active
enum:
- Active
- Deactivated
example: null
nonUsageFees:
type: object
properties:
MonthlyFee:
type: string
description: Monthly recurring fee.
example: '0.2'
setUpFee:
type: string
description: Setup Fee
example: '0.4'
currency:
$ref: '#/components/schemas/currency'
description: Non usage fees define the setup and monthly recurring fees.
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
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
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
validationStatus:
type: string
enum:
- Need more information
- Under validation
- Validated
- No validation required
example: null
currency:
type: string
enum:
- EUR
- USD
- ZAR
example: null
addressReferenceUpdateRequest:
type: object
properties:
number:
type: string
description: The provisioned number for which you want to add/update the address.
example: '81345785554'
country:
type: string
description: Origin Country code in ISO 3166-1 alpha-3 format of the Access Number. The attribute is mandatory for update address reference of UIFN or MSC numbers.
example: BEL
addressReference:
type: string
description: The reference of an address that you want to link to the number. The address linked to this reference must have the status ‘Accepted’.
example: 37a50zzb-d568-4ddd-b11d-jejc7c2j3e30
example: null
customerNumberWithDetails:
type: object
allOf:
- $ref: '#/components/schemas/customerNumber'
- type: object
properties:
usageFees:
type: array
items:
$ref: '#/components/schemas/usageFees'
example: null
routing:
type: array
items:
$ref: '#/components/schemas/responseRouting'
example: null
endUserInfoValidation:
$ref: '#/components/schemas/endUserInfoValidation'
nonUsageFees:
$ref: '#/components/schemas/nonUsageFees'
example: null
example: null
usageFees:
type: object
properties:
accessType:
$ref: '#/components/schemas/accessType'
calendar:
type: string
description: Pricing Calendar Code.
example: SINT
tde:
type: string
description: Time division element that differentiates the price based on the day and time of the call. <ul> <li>`STD` - Standard</li> <li>`P` - Peak</li> <li>`OP` - Off Peak</li> <li>`OOP` - Off Off Peak</li> <li>`WED` - Weekend</li> </ul>
example: OP
enum:
- STD
- P
- OP
- OOP
- WED
callSetUpFee:
type: string
example: '0.001'
accessNetwork:
type: string
description: Parameter describing the network of the calling party. Different routes can be used per access network. If not specified the same routing will be applied to all access Networks.
example: SMART
currency:
$ref: '#/components/schemas/currency'
perMinuteFee:
type: string
example: '0.0015'
description: Usage fees define the call setup and per minute fees.
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
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