{ "openapi": "3.0.1", "info": { "title": "mynumbers-address-management", "description": "This API makes it easy to manage your addresses by creating new addresses, add documents to your address, edit addresses and retrieve your addresses.\n\nDue to local regulation, addresses are required when purchasing Cloud Numbers in some countries (e.g. France, Switzerland, etc.). Depending on the country regulation, the Cloud Number may have to be linked to an address required in Region (same location/geographic zone), an address required in Country (same country) or a worldwide address (any country).\n\nThe ordering process for Cloud Numbers with address requirements is as follow:\n 1. You create an Address with _/addresses_ method\n 2. You can use the address to order numbers with the _/order_ method. Our API validates instantly the address and provisions the numbers in real time\n\n\nThere are some countries for which the numbers will not be provisioned in real time:\n -\tCountries for which the _real time provisioning_ flag is set to _No_. For more information on this flag you can refer to the Specifications API.\n -\tCountries with an address required in Region for which some manual validation is required (i.e. Hungary, Ireland, Netherlands, South Africa, Spain).\n\n\nIn addition, proof of address is also required in some countries hence the API allows documents to be added to the address.\n\nThe ordering process for Cloud Numbers with proof of address is as follow:\n 1. You create an Address with the _/addresses_ method\n 2. You add Documents to the Address with the _/addresses/{reference}/documents_ method\n 3. BICS validates the document(s). The validation status of the documents can be retrieved with the _/addresses/{reference}_ method\n 4. Once the document(s) is(are) verified and accepted by BICS, the address can be used to order Cloud Numbers with address requirements by calling the _/order_ methods\n\n\nFor more information about address requirements, you can read the Specifications API.\n

What are the errors that MyNumbers API can return ?

\n\n|\tCode\t|\tDescription\t|\tHttp response\t|\n|\t---\t|\t---\t|\t---\t|\n|\tE002\t|\tThe country does not exist in our system.\t|\t400\t|\n|\tE018\t|\tThe product is not yet handled via our API.\t|\t400\t|\n|\tE020\t|\tPlease fill out all the mandatory attributes.\t|\t400\t|\n|\tE030\t|\tThe service is temporarily unavailable. Please retry later or contact BICS.\t|\t500\t|\n|\tE031\t|\tThe media type in your header is invalid. Please use application/json.\t|\t400\t|\n|\tE033\t|\tThere is no address with this reference in our system. Please correct the reference.\t|\t400\t|\n|\tE034\t|\tPlease fill out the mandatory attribute {name of attribute}.\t|\t400\t|\n|\tE035\t|\tThe length of the attribute {attribute} is too long. The maximum length for this attribute is {size} characters.\t|\t400\t|\n|\tE036\t|\tAn address is required to order a number in the country. Please fill in the attribute addressReference.\t|\t400\t|\n|\tE037\t|\tAccording to Specifications. The following field(s) are required: VATNumber and/or Phone number.\t|\t400\t|\n|\tE040\t|\tThe alias is already used for another address. Please use unique alias for each address.\t|\t400\t|\n|\tE041\t|\tThere is no file in the request. Please add the file.\t|\t400\t|\n|\tE042\t|\tThe format of the file {documentName} is not valid. Allowed formats are [PDF, TIF, TIFF, JPG, JPEG, PNG, DOC, DOCX, XLS, XLSX].\t|\t400\t|\n|\tE043\t|\tThe size of the file is too large. The maximum size allowed is 10 MB.\t|\t400\t|\n|\tE046\t|\tThe length of the filename is too large. The maximum length for a filename is 240.\t|\t400\t|\n|\tE047\t|\tThe file name must contain only Latin symbols and 0-9_.\t|\t400\t|\n|\tE052\t|\tThis address can not be deleted because it is linked to some of your numbers, active order or porting request.\t|\t400\t|\n|\tE054\t|\tPlease fill out end user identity information. If the end user is a company, company name must be filled in. If the end user is a individual, the Firstname and the Lastname must be filled in.\t|\t400\t|\n|\tE055\t|\tThe format of the email is not valid. Please correct it.\t|\t400\t|\n|\tE061\t|\tEnum value is specified incorrectly.\t|\t400\t|\n|\tE081\t|\tRequest payload is invalid.\t|\t400\t|\n|\tE086\t|\tInvalid value for parameter {attribute}.\t|\t400\t|\n|\tE097\t|\tThis address can not be updated because it is already linked to some of your numbers, active order or porting request.\t|\t400\t|\n|\tE098\t|\tThe format of postal code in Netherlands consists of four digits followed by two uppercase letters. Please correct it.\t|\t400\t|\n|\tE101\t|\tThere is no document type with this code in our system.\t|\t400\t|\n|\tE105\t|\tThere is already a document with the given type associated to the address.\t|\t400\t|\n|\tE108\t|\tDocument type is not valid for this end subscriber type.\t|\t400\t|\n|\tE110\t|\tDocument cannot be deleted due to its current status.\t|\t400\t|\n|\tE111\t|\tEnd subscriber type cannot be changed after creation of an address.\t|\t400\t|\n|\tE112\t|\tSome documents that you have provided are under validation. They will be validated by BICS as soon as possible.\t|\t400\t|\n|\tE118\t|\tAddress cannot be deleted. Address is required for this country and product.\t|\t400\t|\n|\tE139\t|\tThe format of postal code in Spain consists of five digits. Please correct it.\t|\t400\t|\n|\tE143\t|\tInvalid postal code. Postal code must be 4 digits without spaces and not starting with 0.\t|\t400\t|\n|\tE145\t|\tThe format of Belgian Tax Id consists of 'BE' + 10 digits (no spaces, not dots). Please correct it.\t|\t400\t|\n", "version": "v1" }, "servers": [ { "url": "https://api.bics.com/mynumbers-address-management/v1" }, { "url": "https://sandbox.api.bics.com/mynumbers-address-management/v1" } ], "tags": [ { "name": "Document Management", "description": "" }, { "name": "Address Management", "description": "Manage your addresses" } ], "paths": { "/addresses/{reference}": { "summary": "/addresses/{reference}", "get": { "tags": [ "Address Management" ], "summary": "Retrieve the address by address reference", "description": "Retrieve a single address identified by its address reference. An address is composed of the address detail (Street Name, Street Number,...) and the reference.", "operationId": "Get Address By Reference", "parameters": [ { "name": "reference", "in": "path", "description": "reference of the address", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "reference of the address", "readOnly": false, "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" } } ], "responses": { "200": { "description": "successful operation", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressDetails" }, "example": "{\n 'alias': 'BICS France Office',\n 'street': 'Avenue Anatole',\n 'streetNumber': '5',\n 'box': 'A',\n 'residence': 'Eiffel',\n 'floor': '15',\n 'postalCode': '75007',\n 'city': 'Paris',\n 'state': 'Paris',\n 'country': 'FRA',\n 'reference': 'fb0044bd-da81-48a9-a64d-5f543e8b2d35',\n 'status': 'Submitted',\n 'comment': '',\n 'serviceUsage': 'Customer Support France',\n 'addressDocuments': [\n {\n 'documentReference': 'ac0334bc-da81-48a9-a64d-5f54474b2d35',\n 'fileName': 'proofOfAddress.pdf',\n 'size': 139769,\n 'status': 'Uploaded',\n 'created': '2018-09-07T10:10:59Z',\n 'comment': '',\n 'documentType': {\n 'code': 'POD4',\n 'description': 'Letter of Intent (LOI)'\n }\n }\n ],\n 'userIdentity': {\n 'endSubscriberType': 'Company',\n 'emailAddress' : 'mail@bics.com',\n 'companyName' : 'BICS',\n 'firstName' : null,\n 'lastName' : null,\n 'vatNumber' : 'BE0999999993',\n 'phoneNumber' : '3225551234'\n },\n 'allowedLocations': ['Paris', 'National'],\n 'allowedLocationsAreaCodes': [\n {\n 'location': 'Paris',\n 'areaCode': '187',\n 'nonGeographic': false\n },\n {\n 'location': 'National',\n 'areaCode': '9',\n 'nonGeographic': true\n }\n ]\n}\n" } }, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "put": { "tags": [ "Address Management" ], "summary": "Edit an address in your address book.", "description": "Edit an address in your address book. You must specify in the request all the attributes of the address even those you do not want to change. The end subscriber type cannot change after the creation of an address. If an address is linked to any active numbers, or any order, it can not be updated.", "operationId": "Update Address", "parameters": [ { "name": "reference", "in": "path", "description": "reference of the address", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "reference of the address", "readOnly": false, "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressRequest" }, "examples": {}, "example": null } } }, "responses": { "200": { "description": "successful operation", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressDetails" }, "example": "{\n 'alias': 'BICS France Office',\n 'street': 'Avenue Anatole',\n 'streetNumber': '5',\n 'box': 'A',\n 'residence': 'Eiffel',\n 'floor': '15',\n 'postalCode': '75007',\n 'city': 'Paris',\n 'state': 'Paris',\n 'country': 'FRA',\n 'reference': 'fb0044bd-da81-48a9-a64d-5f543e8b2d35',\n 'status': 'Submitted',\n 'comment': null,\n 'serviceUsage': 'Customer Support France,\n 'addressDocuments':\n [\n {\n 'documentReference': 'ac0334bc-da81-48a9-a64d-5f54474b2d35',\n 'fileName': 'proofOfAddress.pdf',\n 'size': 139769,\n 'status': 'Uploaded',\n 'created': '2018-09-07T10:10:59Z',\n 'comment': '',\n 'documentType'\n {\n 'code': 'POD4',\n 'description': 'Letter of Intent (LOI)'\n }\n }\n ],\n 'userIdentity': {\n 'endSubscriberType': 'Company',\n 'emailAddress': 'mail@bics.com',\n 'companyName': 'BICS France Office',\n 'firstName': '',\n 'lastName': '',\n 'vatNumber': 'BE0999999993',\n 'phoneNumber': '3225551234'\n },\n 'allowedLocations': ['Paris', 'National'],\n 'allowedLocationsAreaCodes': [\n {\n 'location': 'Paris',\n 'areaCode': '187',\n 'nonGeographic': false\n },\n {\n 'location': 'National',\n 'areaCode': '9',\n 'nonGeographic': true\n }\n ]\n}\n" } }, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "delete": { "tags": [ "Address Management" ], "summary": "Delete an address from your address book.", "description": "Delete an address identified by its reference. This service deletes the address from your address book as well as all documents linked to this address. It is not possible to delete an address as long as you have active Cloud Numbers linked to this address.", "operationId": "Delete Address", "parameters": [ { "name": "reference", "in": "path", "description": "Reference of the address", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "Reference of the address", "readOnly": false, "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" } } ], "responses": { "200": { "description": "successful operation", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressDeletionResponse" }, "example": "{\n 'reference': 'fb0044bd-da81-48a9-a64d-5f543e8b2d35',\n 'status': 'Deleted'\n}\n" } }, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "parameters": [] }, "/addresses/{reference}/documents/{documentReference}": { "summary": "/addresses/{reference}/documents/{documentReference}", "delete": { "tags": [ "Document Management" ], "summary": "Delete Document By Reference", "description": "Delete a proof document linked to one of your addresses. You can only delete existing documents when the status of the document is 'Submitted', 'Rejected' or 'Declined'.\n\nThe Address reference and document reference must be specified in the url.", "operationId": "Delete Document By Reference", "parameters": [ { "name": "reference", "in": "path", "description": "Identifier of the address", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "Identifier of the address", "readOnly": false, "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" } }, { "name": "documentReference", "in": "path", "description": "Identifier of the document", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "Identifier of the document", "readOnly": false, "example": "24bebc37-505f-4b46-9021-6d31b839cd7c" } } ], "responses": { "200": { "description": "successful operation", "headers": {}, "content": {}, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "404": { "description": "resource is not found", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "parameters": [] }, "/addresses/{reference}/documentTypeCode/{code}": { "summary": "/addresses/{reference}/documentTypeCode/{code}", "delete": { "tags": [ "Address Management" ], "summary": "Delete Document", "description": "

***DEPRECATED


This method is deprecated. Please use new Delete By Reference method.
Delete a proof document linked to one of your addresses. You can only delete existing documents when the status of the document is 'Submitted', 'Rejected' or 'Declined'.\n\nThe Address reference and document type code must be specified in the url.", "operationId": "Delete Document", "parameters": [ { "name": "reference", "in": "path", "description": "address reference", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "address reference", "readOnly": false, "example": "4a5f613a-1d02-4b66-9914-974f96901f1b" } }, { "name": "code", "in": "path", "description": "Code of type of uploaded document.\n\nSee API _/reference/documenttypes_ for all possible values.", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "Code of type of uploaded document.\n\nSee API _/reference/documenttypes_ for all possible values.", "readOnly": false, "example": "POD4" } } ], "responses": { "200": { "description": "Successful operation.", "headers": {}, "content": {}, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } }, "deprecated": true }, "parameters": [] }, "/addresses/{reference}/documents": { "summary": "/addresses/{reference}/documents", "post": { "tags": [ "Address Management" ], "summary": "Add a proof document", "description": "Add a proof document and link it to one of your addresses. After the creation of an address, you can call this service for each document you want to link to this address. Multiple documents can be added to the same address. The allowed formats of a document are pdf, doc, docx, png, jpg and tiff. The Address reference must be specified in the url, the content type of the request must be form-data and the document need to be added as an attachment in the request. In the response of this service for the uploaded document system will return unique documentReference which will be identifier for the document that need to be used in other calls.", "operationId": "Add Document", "parameters": [ { "name": "reference", "in": "path", "description": "reference of the address", "required": true, "allowEmptyValue": false, "style": "simple", "explode": false, "schema": { "type": "string", "description": "reference of the address", "readOnly": false, "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Multipart form data file", "format": "binary", "readOnly": false, "example": null }, "documentTypeCode": { "type": "string", "description": "Code of type of uploaded document. See API _/reference/documenttypes_ for all possible values.", "readOnly": false, "example": "POD4" } }, "example": null }, "examples": {}, "example": null } } }, "responses": { "200": { "description": "successful operation", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressDocumentResponse" }, "example": "{\n 'status': 'Uploaded',\n 'reference': 'fb0044bd-da81-48a9-a64d-5f543e8b2d35',\n 'documentName': 'LOI.pdf',\n 'comment': '',\n 'documentReference': 'ac0334bc-da81-48a9-a64d-5f54474b2d35',\n 'documentType':\n {\n 'code': 'POD4',\n 'description': 'Letter of Intent (LOI)'\n }\n}\n" } }, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "example": "{\n 'code': 'E033',\n 'description': 'There is no address with this reference in our system. Please correct the reference.',\n 'timestamp': '2019-07-11T15:16:49.53+02:00'\n}\n" } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "parameters": [] }, "/addresses": { "summary": "/addresses", "get": { "tags": [ "Address Management" ], "summary": "Retrieve the list of your addresses.", "description": "Retrieve the list of your addresses. Each address is composed of the address detail (Street Name, Street Number, etc.) and the reference of the address.\n\nIf you want to get the list of your addresses for a specific country, you can use the input parameter country.", "operationId": "Get Addresses", "parameters": [ { "name": "country", "in": "query", "description": "Country code in ISO 3166-1 alpha-3 format.", "required": false, "allowEmptyValue": false, "style": "form", "explode": true, "schema": { "type": "string", "description": "Country code in ISO 3166-1 alpha-3 format.", "readOnly": false, "example": "FRA" } } ], "responses": { "200": { "description": "successful operation", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/address" }, "example": null }, "example": "[\n {\n 'alias': 'BICS France Office',\n 'street': 'Avenue Anatole',\n 'streetNumber': '5',\n 'box': 'A',\n 'residence': 'Eiffel',\n 'floor': '15',\n 'postalCode': '75007',\n 'city': 'Paris',\n 'state': 'Paris',\n 'country': 'FRA',\n 'reference': 'fb0044bd-da81-48a9-a64d-5f543e8b2d35',\n 'status': 'Accepted',\n 'comment': '',\n 'serviceUsage': 'Customer Support France',\n 'userIdentity': {\n 'endSubscriberType': 'Company',\n 'emailAddress' : 'info@bics.com',\n 'companyName' : 'BICS',\n 'firstName' : ' ',\n 'lastName' : ' ',\n 'vatNumber' : 'BE0999999993',\n 'phoneNumber' : '3225551234'\n }\n },\n {\n 'alias': 'ITAT Belgium Office',\n 'street': 'Paradeplein',\n 'streetNumber': '1',\n 'box': '',\n 'residence': '',\n 'floor': '',\n 'postalCode': '2030',\n 'city': 'Antwerpen',\n 'state': 'Antwerpen',\n 'country': 'BEL',\n 'reference': 'fa454bd-da81-48a9-a64d-5f543e8b2d320',\n 'status': 'Submitted',\n 'comment': '',\n 'serviceUsage': 'Customer Support France',\n 'userIdentity': {\n 'endSubscriberType': 'Company',\n 'emailAddress' : '',\n 'companyName' : 'ITAT Belgium Office',\n 'firstName' : ' ',\n 'lastName' : ' ',\n 'vatNumber' : 'BE0999999991',\n 'phoneNumber' : '3225551234'\n }\n },\n {\n 'alias': 'BICS US Office',\n 'street': 'Mission Street 19th Floor',\n 'streetNumber': '535',\n 'box': '',\n 'residence': '',\n 'floor': '19',\n 'postalCode': 'CA-94105',\n 'city': 'San Francisco',\n 'state': 'San Francisco',\n 'country': 'USA',\n 'reference': 'e5234bd-da81-48a9-a64d-5f543e8b2e865',\n 'status': 'More information required',\n 'comment': 'Please add a the proof of address.',\n 'serviceUsage': 'Customer Support France',\n 'userIdentity': {\n 'endSubscriberType': 'Company',\n 'emailAddress' : ' ',\n 'companyName' : 'BICS US Office',\n 'firstName' : ' ',\n 'lastName' : ' ',\n 'vatNumber' : 'BE0999999999',\n 'phoneNumber' : '3225551234'\n }\n }\n]\n" } }, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "post": { "tags": [ "Address Management" ], "summary": "Add an address in your address book", "description": "Create a new address in your address book with the aim of ordering Cloud Numbers in countries where address is required. BICS is obliged to collect the address of the end user for these countries.", "operationId": "Create Address", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressRequest" }, "examples": {}, "example": null } } }, "responses": { "200": { "description": "successful operation", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/addressDetails" }, "example": "{\n 'alias': 'BICS France Office',\n 'street': 'Avenue Anatole',\n 'streetNumber': '5',\n 'box': 'A',\n 'residence': 'Eiffel',\n 'floor': '15',\n 'postalCode': '75007',\n 'city': 'Paris',\n 'state': 'Paris',\n 'country': 'FRA',\n 'reference': 'fb0044bd-da81-48a9-a64d-5f543e8b2d35',\n 'status': 'Submitted',\n 'comment': '',\n 'serviceUsage': 'Customer Support France',\n 'addressDocuments': [],\n 'userIdentity': {\n 'endSubscriberType': 'Company',\n 'emailAddress' : 'mail@bics.com',\n 'companyName' : 'BICS',\n 'firstName' : '',\n 'lastName' : '',\n 'vatNumber' : 'BE0999999993',\n 'phoneNumber' : '3225551234'\n },\n 'allowedLocations': [],\n 'allowedLocationsAreaCodes': []\n}\n" } }, "links": {} }, "400": { "description": "Bad request, An issue occurred while processing the input parameters.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "401": { "description": "the API Key was not mentioned or is invalid (see authentication)", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} }, "403": { "description": "this service cannot be used according to your API Key", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" }, "examples": {}, "example": null } }, "links": {} } } }, "parameters": [] } }, "components": { "schemas": { "addressRequest": { "required": [ "alias", "city", "country", "postalCode", "street", "streetNumber" ], "type": "object", "properties": { "country": { "type": "string", "description": "Country code in ISO 3166-1 alpha-3 format.", "example": "FRA" }, "serviceUsage": { "type": "string", "description": "Free text to describe usage of numbers.", "example": null }, "city": { "type": "string", "description": "City.", "example": "Paris" }, "streetNumber": { "type": "string", "description": "House number.", "example": "5" }, "postalCode": { "type": "string", "description": "Postal Code.", "example": "75007" }, "box": { "type": "string", "description": "Postal box.", "example": "B" }, "language": { "type": "string", "description": "Language code, case insensitive.", "example": "en" }, "userIdentity": { "$ref": "#/components/schemas/userIdentityDetail" }, "street": { "type": "string", "description": "Street name.", "example": "Rue Anatole" }, "alias": { "type": "string", "description": "Alias of the Address. It helps you to identify the address of the end user.", "example": "BICS France office" }, "state": { "type": "string", "description": "State.", "example": "Paris" }, "floor": { "type": "string", "description": "Floor number.", "example": "15" }, "residence": { "type": "string", "description": "Residence name.", "example": "Eiffel" } }, "example": null }, "addressDocumentResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "Reference of the Address. This attribute is used to order Cloud numbers in a country where the address of the end-user is required.", "example": "3ff35db2-1301-43b1-89f8-4df00faa8a50" }, "documentType": { "$ref": "#/components/schemas/documentType" }, "comment": { "type": "string", "description": "Reason why your document was Rejected or Declined", "example": "Not readable. Please provide new document" }, "documentReference": { "type": "string", "description": "Saved document reference", "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" }, "documentName": { "type": "string", "description": "Name of the document", "example": "someName.ext" }, "status": { "$ref": "#/components/schemas/addressDocumentStatus" } }, "example": null }, "addressStatusResponse": { "type": "object", "properties": { "reference": { "type": "string", "description": "Reference of the Address. This attribute is used to order Cloud numbers in a country where the address of the end-user is required.", "example": "3ff35db2-1301-43b1-89f8-4df00faa8a50" }, "comment": { "type": "string", "description": "Give additional information in case the address is rejected.", "example": "This address does not exist." }, "status": { "type": "string", "description": "Validation status of the address.\n\n", "example": "Submitted" } }, "example": null }, "address": { "required": [ "reference", "status" ], "type": "object", "properties": { "country": { "type": "string", "description": "Country code in ISO 3166-1 alpha-3 format.", "example": "FRA" }, "serviceUsage": { "type": "string", "description": "Service usage", "example": null }, "city": { "type": "string", "description": "City.", "example": "Paris" }, "streetNumber": { "type": "string", "description": "House number.", "example": "2" }, "postalCode": { "type": "string", "description": "Optional parameter. Postal Code.", "example": "1060" }, "box": { "type": "string", "description": "Optional parameter. Postal box.", "example": "B" }, "language": { "type": "string", "description": "Language code, case insensitive.", "example": "en" }, "userIdentity": { "$ref": "#/components/schemas/userIdentityDetail" }, "reference": { "type": "string", "description": "Reference of the Address. This attribute is used to order Cloud numbers in a country where the address of the end user is required.", "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" }, "street": { "type": "string", "description": "Street name.", "example": "Rue Lebeau" }, "alias": { "type": "string", "description": "Alias of the Address. It helps you to identify the address of the end user. Alias must be unique.", "example": "BICS France office" }, "comment": { "type": "string", "description": "Give additional information in case more information is required to validate the address or in case the address is rejected.\n", "example": "This address does not exist. Please correct it." }, "state": { "type": "string", "description": "Optional parameter. State.", "example": "California" }, "floor": { "type": "string", "description": "Optional parameter. Floor number.", "example": "5" }, "residence": { "type": "string", "description": "Optional parameter. Residence name.", "example": "Argenteuil" }, "status": { "type": "string", "description": "Validation status of the address.\n \n", "example": "Submitted" } }, "example": null }, "addressDeletionStatus": { "type": "string", "description": "Address deletion result status", "enum": [ "Deleted" ], "example": null }, "documentType": { "type": "object", "properties": { "code": { "type": "string", "description": "document type code", "example": "POD1" }, "description": { "type": "string", "description": "document type description", "example": "Letter of Intent" } }, "description": "Type of document", "example": null }, "locationAreaCode": { "type": "object", "properties": { "areaCode": { "type": "string", "description": "Area code of the number according to the national numbering plan.", "example": "2" }, "location": { "type": "string", "description": "A Location indicates in most cases the city the number belongs to. It is sometimes used to specify if it is a national or a mobile number.", "example": "Brussels" }, "nonGeographic": { "type": "boolean", "description": "Indicates if the location is non geographic (e.g. National).", "example": true } }, "example": null }, "addressDetails": { "required": [ "reference", "status" ], "type": "object", "properties": { "country": { "type": "string", "description": "Country code in ISO 3166-1 alpha-3 format.", "example": "BEL" }, "serviceUsage": { "type": "string", "description": "Free text to describe usage of numbers.", "example": null }, "city": { "type": "string", "description": "City.", "example": "Brussels" }, "streetNumber": { "type": "string", "description": "House number.", "example": "2" }, "postalCode": { "type": "string", "description": "Postal Code.", "example": "1060" }, "box": { "type": "string", "description": "Postal box.", "example": "B" }, "language": { "type": "string", "description": "Language code, case insensitive.", "example": "en" }, "userIdentity": { "$ref": "#/components/schemas/userIdentityDetail" }, "allowedLocationsAreaCodes": { "type": "array", "description": "List of locations and area codes. It mentions all the locations and area codes that can be ordered with this address.", "items": { "$ref": "#/components/schemas/locationAreaCode" }, "example": null }, "reference": { "type": "string", "description": "Reference of the Address. This attribute is used to order Cloud numbers in a country where the address of the end user is required.", "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" }, "addressDocuments": { "type": "array", "description": "List of documents submitted for this address.", "example": "null", "items": { "$ref": "#/components/schemas/addressDocumentMetadata" } }, "street": { "type": "string", "description": "Street name.", "example": "Rue Lebeau" }, "alias": { "type": "string", "description": "Alias of the Address. It helps you to identify the address of the end user. Alias must be unique.", "example": "BICS Belgium office" }, "comment": { "type": "string", "description": "Additional information about validation status of the address. It helps you to correct the address to be accepted.\n", "example": "This address does not exist. Please correct it." }, "state": { "type": "string", "description": "State.", "example": "California" }, "floor": { "type": "string", "description": "Floor number.", "example": "5" }, "residence": { "type": "string", "description": "Residence name.", "example": "Argenteuil" }, "allowedLocations": { "type": "array", "description": "List of all locations that can be ordered with this address.", "example": "[\"NA\",\"National\"]", "items": { "type": "string", "example": null } }, "status": { "type": "string", "description": "Validation status of the address.\n \n", "example": "Submitted" } }, "example": null }, "addressDocumentStatus": { "type": "string", "description": "Validation status:\n \n", "enum": [ "Uploaded", "Rejected", "Submitted", "Under Validation", "Validated", "Expired", "Declined" ], "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 }, "addressDocumentMetadata": { "type": "object", "properties": { "fileName": { "type": "string", "example": "fileName" }, "size": { "type": "integer", "format": "int64", "example": null }, "documentType": { "$ref": "#/components/schemas/documentType" }, "created": { "type": "string", "description": "Timestamp of error in UTC format.", "format": "date-time", "example": null }, "comment": { "type": "string", "description": "Reason why your document was Rejected or Declined", "example": "Not readable. Please provide new document" }, "documentReference": { "type": "string", "description": "Saved document reference", "example": "fb0044bd-da81-48a9-a64d-5f543e8b2d35" }, "status": { "$ref": "#/components/schemas/addressDocumentStatus" } }, "example": null }, "addressDeletionResponse": { "type": "object", "properties": { "reference": { "type": "string", "example": "d9224465-cce9-4df1-b2b8-4f39cce00959" }, "status": { "$ref": "#/components/schemas/addressDeletionStatus" } }, "example": null }, "addressStatus": { "type": "string", "description": "Validation status of an Address.", "enum": [ "Submitted" ], "example": null }, "userIdentityDetail": { "required": [ "emailAddress" ], "type": "object", "properties": { "firstName": { "type": "string", "description": "First Name of the end subscriber", "example": "Kernel" }, "lastName": { "type": "string", "description": "Last Name of the end subscriber", "example": "Braun" }, "emailAddress": { "type": "string", "description": "Email address of owner of address", "example": "email@bics.com" }, "phoneNumber": { "type": "string", "description": "Phonenumber of owner of address", "example": "325648855" }, "companyName": { "type": "string", "description": "Name of the company which is the owner of address", "example": "BICS" }, "endSubscriberType": { "type": "string", "description": "Possible values are :\n \n", "example": null }, "vatNumber": { "type": "string", "description": "Unique identification number used for tax (e.g. VAT, GST, TIN)", "example": "BE0999999999" } }, "description": "User identity of the end subscriber", "example": null } }, "responses": {}, "parameters": {}, "examples": {}, "requestBodies": {}, "headers": {}, "links": {}, "callbacks": {} } }