openapi: 3.0.1
info:
title: connect Address Management stock 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: stock
description: Query the available stock.
paths:
/stock/product/{product}/country/{country}/quantity/{quantity}:
parameters: []
get:
tags:
- stock
summary: Query our available stock for a given product in a country
description: "This method allows you to check if a given quantity of numbers are available in our stock for\n a given product in a country. In case we don’t have enough numbers in our stock, the method also\n gives you the quantity of numbers still available so that you know how many numbers you can order."
operationId: Check Available Stock
parameters:
- name: product
in: path
description: Filter stock by product
required: true
allowEmptyValue: false
schema:
type: string
description: Filter stock by product
readOnly: false
example: IBN
- name: country
in: path
description: Filter stock by country in ISO 3166-1 alpha-3 format.
required: true
allowEmptyValue: false
schema:
type: string
description: Filter stock by country in ISO 3166-1 alpha-3 format.
readOnly: false
example: BEL
- name: quantity
in: path
description: Quantity of numbers
required: true
allowEmptyValue: false
schema:
type: integer
description: Quantity of numbers
readOnly: false
example: '80'
- name: location
in: query
description: Check stock by location. (Not applicable for product GMN).
required: false
allowEmptyValue: false
schema:
type: string
description: Check stock by location. (Not applicable for product GMN).
readOnly: false
example: Brussels
- name: areaCode
in: query
description: Check stock by areaCode.
required: false
allowEmptyValue: false
schema:
type: string
description: Check stock by areaCode.
readOnly: false
example: '2'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/stock'
example: "{\n 'product': 'IBN',\n 'country': 'BEL',\n 'location': null,\n 'areaCode': '2',\n 'checkStock': true,\n 'quantity': 10\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}/services:
parameters: []
get:
tags:
- stock
summary: Retrieve the available and active services of a given number from the inventory.
description: The <i>/numbers/{number}/services</i> method allows you to retrieve the available and active services of a given number from your inventory. Services that are not available on the given number are not returned.
operationId: get number services
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: '443706070212'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/numberService'
example: null
example: null
'404':
description: Number not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example: null
number not found:
example: "[\n {\n 'code': 'E060'\n 'description': 'The number specified in request does not exist'\n 'timestamp': '2020'\n }\n]\n"
/stock/product/{product}/country/{country}/location/{location}/quantity/{quantity}:
parameters: []
get:
tags:
- stock
summary: Query our available stock for a Cloud Number in a given location.
description: 'This method allows you to check if a given quantity of Cloud Numbers are available in our stock for a given location.
In case we don''t have enough numbers in our stock, the method also gives you the quantity of numbers available in our stock so that you know how many numbers you can order.'
operationId: Check Available Stock By Location
parameters:
- name: product
in: path
description: Filter stock by product
required: true
allowEmptyValue: false
schema:
type: string
description: Filter stock by product
readOnly: false
example: IBN
- name: country
in: path
description: Filter stock by country in ISO 3166-1 alpha-3 format.
required: true
allowEmptyValue: false
schema:
type: string
description: Filter stock by country in ISO 3166-1 alpha-3 format.
readOnly: false
example: BEL
- name: location
in: path
description: Filter stock by location in country. 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.
required: true
allowEmptyValue: false
schema:
type: string
description: Filter stock by location in country. 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.
readOnly: false
example: Brussels
- name: quantity
in: path
description: Quantity of numbers you would like to order
required: true
allowEmptyValue: false
schema:
type: integer
description: Quantity of numbers you would like to order
readOnly: false
example: '25'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/stock'
example: "{\n 'product': 'IBN',\n 'country': 'BEL',\n 'location': 'Brussels',\n 'areaCode': null,\n 'checkStock': true,\n 'quantity': 25\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
/availablenumbers:
parameters: []
get:
tags:
- stock
summary: Retrieve available numbers for specific product, country and location.
description: The _/availablenumbers_ method allows you to preview a list of numbers that we have in our stock. You can then pick and order one or multiple numbers out of the list by calling the order method. The numbers cannot be reserved hence there is no guarantee that the numbers will still be available when you place the order.
operationId: get available numbers
parameters:
- name: product
in: query
description: Filter our stock by product. 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.
required: true
allowEmptyValue: false
schema:
type: string
description: Filter our stock by product. 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.
readOnly: false
example: IBN
- name: country
in: query
description: Filter our stock by country in ISO 3166-1 alpha-3 format
required: true
allowEmptyValue: false
schema:
type: string
description: Filter our stock by country in ISO 3166-1 alpha-3 format
readOnly: false
example: JPN
- name: location
in: query
description: Filter our stock by location. You can retrieve the list of locations by calling the method _/reference/locations_. (Not applicable for product GMN).
required: false
allowEmptyValue: false
schema:
type: string
description: Filter our stock by location. You can retrieve the list of locations by calling the method _/reference/locations_. (Not applicable for product GMN).
readOnly: false
example: Tokyo
- name: areaCode
in: query
description: Filter our stock by area code. You can retrieve the list of area codes by calling the method _/reference/locations_.
required: false
allowEmptyValue: false
schema:
type: string
description: Filter our stock by area code. You can retrieve the list of area codes by calling the method _/reference/locations_.
readOnly: false
example: '3'
- name: quantity
in: query
description: A value between 1 and 25. If the amount of numbers available is smaller than the requested quantity, only the available numbers are returned.
required: false
allowEmptyValue: false
schema:
type: string
description: A value between 1 and 25. If the amount of numbers available is smaller than the requested quantity, only the available numbers are returned.
readOnly: false
example: '25'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/availableNumber'
example: null
example: "[\n {\n 'number': '81370607021',\n 'product': 'IBN',\n 'country': 'JPN',\n 'location': 'Tokyo',\n 'areaCode': '3'\n },\n {\n 'number': '81370607022',\n 'product': 'IBN',\n 'country': 'JPN',\n 'location': 'Tokyo',\n 'areaCode': '3'\n },\n {\n 'number': '81370607301',\n 'product': 'IBN',\n 'country': 'JPN',\n 'location': 'Tokyo',\n 'areaCode': '3'\n },\n {\n 'number': '81370607302',\n 'product': 'IBN',\n 'country': 'JPN',\n 'location': 'Tokyo',\n 'areaCode': '3'\n },\n {\n 'number': '81370607303',\n 'product': 'IBN',\n 'country': 'JPN',\n 'location': 'Tokyo',\n 'areaCode': '3'\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
components:
schemas:
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
country:
type: string
description: Country code in ISO 3166-1 alpha-3 format.
example: JPN
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.
example: IBN
stock:
required:
- checkStock
- 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 and ITFS. IBN referring to Cloud Numbers and ITFS referring to International Freephone.
example: IBN
areaCode:
type: string
description: AreaCode will only be displayed if areaCode was specified in the request parameters.
example: '2'
quantity:
type: integer
description: The quantity of available numbers in stock which meet your request. 0 if there is currently no available stock.
example: 5
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: Brussels
checkStock:
type: boolean
description: Flag indicating if there are enough numbers in stock to meet your request.
example: true
example: null
numberService:
type: object
properties:
code:
type: string
description: Code of the service <ul> <li><b>IC</b>: Inbound Call</li> <li><b>NOC</b>: National Outbound Call</li> <li><b>IOC</b>: International Outbound Call</li> <li><b>ES</b>: Emergency Services</li> <li><b>DS</b>: Directory Services</li> <li><b>IM</b>: Inbound Messaging</li> <li><b>NOM</b>: National Outbound Messaging</li> <li><b>IOM</b>: International Outbound Messaging</li> </ul>
enum:
- IC
- NOC
- IOC
- ES
- DS
- IM
- NOM
- IOM
example: null
description:
type: string
description: Description of the service
example: null
active:
type: boolean
description: <b>true</b>: the service is active on your number <br/><b>false</b>: the service is available but not active on your number
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
availableNumber:
type: object
properties:
number:
type: string
description: Available numbers in stock.
example: '81345785554'
country:
$ref: '#/components/schemas/country'
product:
$ref: '#/components/schemas/product'
areaCode:
type: string
description: Area code of the number according to the national numbering plan.
example: '3'
location:
$ref: '#/components/schemas/location'
example: null