Numbers API
The MessageBird Numbers API gives you an overview of all available MessageBird phone numbers and allows you to purchase as well as manage all your phone numbers.
The Numbers API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.
Authorization
With each API call you'll need to set an access key to authenticate yourself. API keys can be created or retrieved through the MessageBird Dashboard.
To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.
Formats and Headers
All API responses are in JSON. You're required to send the Accept header with the value application/json with each request.
POST and PUT requests to the API must contain a JSON-formatted payload in the request body.
Errors
MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).
In the case of an error, the body of the response includes a JSON-formatted response that tells you exactly what is wrong.
Attributes
| Attribute | Type | Description |
|---|---|---|
| errors[].code | integer | An integer that represents the error type. |
| errors[].description | string | A human-readable description of the error. You can use this to let the user know what they can do about the error. |
| errors[].parameter | string | The parameter in your request related to the error if the error is parameter specific. |
Searching phone numbers available for purchase
Search for local, toll-free and mobile phone numbers that are available for you to purchase. You can search for phone numbers by country that match a pattern, are of a certain type or are in a specific region.
URL Parameters (required)
| Parameter | Type | Description |
|---|---|---|
| countryCode | string | An ISO 3166-1 alpha-2 formatted country code. Relates to the country calling code of the number. |
Query Parameters (optional)
| Parameter | Type | Description |
|---|---|---|
| number | string | One or multiple numbers to be that the listed phone numbers should contain. |
| features | array | The feature of a phone number. Possible values: sms, voice, mms. |
| type | string | The type of a phone number. Possible values: landline, mobile, premium_rate and toll_free. |
| limit | integer | Limit the results (default: 20, max.: 100). |
| search_pattern | string | Approach of searching the number. Possible values: start (result starts with the provided number fragment); anywhere (result has provided number fragment somewhere in it); end (result ends with the provided pattern). (default: '') |
| exclude_numbers_require_verification | boolean | Exclude numbers that require documentation. Possible values: (true, false). (default: false) |
| prices | boolean | Include numbers prices. Possible values: (true, false). (default: false) |
Definition
GET /v1/available-phone-numbers/{countryCode}
Example request
curl -X GET "https://numbers.messagebird.com/v1/available-phone-numbers/NL?features=sms&features=voice&type=mobile&number=319&search_pattern=start&limit=25" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"items": [{"number": "3197010260188","country": "NL","region": "","locality": "","features": ["sms","voice"],"type": "mobile","verificationRequired": true,"initialContractDuration": 2,"inboundCallsOnly": false,"monthlyPrice": 1,"currency": "EUR","conditions": ["Proof of in region address (max 3 months old)"]}],"limit": 20,"count": 1}
Purchasing a phone number
By combining the /v1/available-phone-numbers lookup with /v1/phone-numbers, you can purchase a phone number. Once you've found a phone number you'd like to purchase you simply POST the number to the /v1/phone-numbers.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| number | string | The phone number you want to purchase as presented in the response of /available-phone-numbers. |
| countryCode | string | Alpha-2 country code (example: NL) |
| billingIntervalMonths | integer | How often you will be charged for using the number. Valid values: 1, 3, 6, 9, 12 |
Definition
POST /v1/phone-numbers
Example request
curl -X POST "https://numbers.messagebird.com/v1/phone-numbers" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"number": "31971234567","countryCode": "NL","billingIntervalMonths": 1}'
Example response
{"number": "31971234567","country": "NL","region": "Haarlem","locality": "Haarlem","features": ["sms","voice"],"tags": [],"type": "landline_or_mobile","status": "active","createdAt": "2019-04-25T14:04:04Z","renewalAt": "2019-05-25T00:00:00Z"}
Fetching all purchased phone numbers
Retrieve a list of all your purchased phone numbers, filterable by a variety of criteria including phone number type, feature, tags or region.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Limit the amount of results per page. |
| offset | integer | Skip first n results. |
| features | array | Features for which search is done (example ?features=sms&features=voice). |
| tags | array | Tags for which search is done (example ?tags=mobile&tags=primary). |
| number | string | Fragment of number. |
| region | string | Fragment of region data. |
| locality | string | Fragment of locality data. |
| type | string | Number type (example: landline, mobile). |
Definition
GET /v1/phone-numbers
Example request
curl -X GET "https://numbers.messagebird.com/v1/phone-numbers?type=mobile&features=sms&features=voice" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"offset": 0,"limit": 20,"count": 1,"totalCount": 1,"items": [{"number": "31612345670","country": "NL","region": "Texel","locality": "Texel","features": ["sms","voice"],"tags": [],"type": "mobile","status": "active"}]}
Fetching a purchased phone number
Retrieve a specific phone number from your inventory of purchased numbers.
Definition
GET /v1/phone-numbers/{phoneNumber}
Example request
curl -X GET "https://numbers.messagebird.com/v1/phone-numbers/31612345670" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"number": "31612345670","country": "NL","region": "Texel","locality": "Texel","features": ["sms","voice"],"tags": [],"type": "mobile","status": "active"}
Updating a purchased phone number
Update certain attributes of your purchased phone numbers. Note: at the moment, we only support updating tags that can be used to group or label numbers.
Definition
PATCH /v1/phone-numbers/{phoneNumber}
Example request
curl -X PATCH "https://numbers.messagebird.com/v1/phone-numbers/31612345670" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"tags":["tag1"]}'
Example response
{"number": "31612345670","country": "NL","region": "Texel","locality": "Texel","features": ["sms","voice"],"tags": ["tag1"],"type": "mobile","status": "active"}
Searching available for back order products
Search for unified communication phone numbers that are available for you to back order.
URL Parameters (required)
| Parameter | Type | Description |
|---|---|---|
| countryCode | string | An ISO 3166-1 alpha-2 formatted country code. Relates to the country calling code of the number. |
Query Parameters (optional)
| Parameter | Type | Description |
|---|---|---|
| features | array | The feature of a phone number. Possible values: sms, voice, mms. |
| prefix | string | The prefix of a phone numbers. |
| type | string | The type of a phone number. Possible values: landline, mobile, premium_rate and toll_free. |
| limit | integer | Limit the results (default: 20, max.: 100). |
Definition
GET /v1/products
Example request
curl -X GET "https://numbers.messagebird.com/v1/products?features=voice&type=bv&country=GB" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"limit": 20,"count": 1,"items": [{"numberType": "bv","verificationRequired": true,"country": "GB","id": 1993,"currency": "EUR","price": 1}]}
Fetching back order product details
In order to place back order you need to specify desired prefix. Available prefixes could be found in prefixes field from GET v1/products/{productID} response.
URL Parameters (required)
| Parameter | Type | Description |
|---|---|---|
| productID | integer | Product ID returned from search products request |
Definition
GET /v1/products/{productID}
Example request
curl -X GET "https://numbers.messagebird.com/v1/products/1993" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"country": "GB","numberType": "bv","backOrderLeadTime": "5 - 10 Business days","reachableFromNationalFixed": true,"reachableFromNationalMobile": true,"reachableFromPayPhone": true,"verificationRequired": true,"initialContractDuration": "1 year","prefixes": [{"prefix": "44113","city": "Leeds","stateProv": "","prefixType": "Geographic"},{"prefix": "44114","city": "Sheffield","stateProv": "","prefixType": "Geographic"},{"prefix": "44115","city": "Nottingham","stateProv": "","prefixType": "Geographic"}],"remarks": ["Customer support is NOT allowed on a PRS number","The session pricing on your price list will reflect the number cost."],"conditions": ["Business use: VAT number","Service description required","Outbound calling not permitted","Business use : Name & Address","Entertainment Services","A native speaking helpdesk is mandatory","Customer support email","URL content-provider & URL content","Customer support national phone number"],"endUserData": ["End user name","End user address","VAT number","Content description","Customer care phone","Customer care e-mail"],"forbiddenContent": ["Adult content"]}
Place a back order
By combining the /v1/products and /v1/products/{productID} lookup with /v1/backorder, you can place a back order for multiple phone numbers. Once you've found a product that provides number you'd like to purchase you simply POST the product and prefix to the /v1/backorder.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| productID | integer | The product id of the number you want to purchase as presented in the response /v1/products |
| prefix | string | The prefix of the number you want to purchase as presented in the response of /v1/products/{productID}. |
| quantity | integer | Amount of number you want to purchase (maximum 100) |
Definition
POST /v1/backorders
Example request
curl -X POST "https://numbers.messagebird.com/v1/backorders" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"productID": 1993,"quantity": 3,"prefix": "31114"}'
Example response
{"id": "48f6057c21de42d4bbf73fb86caaf361"}
Fetching a placed back order
Retrieve a specific back order from your inventory. In order to start working on some backorders additional KYC information might be required. In that case backorder status will be blocked and within reason_codes you may find what is missing: MISSING_KYC shows that back order requires addition KYC documents. MISSING_EUD shows that back order requires addition KYC user information.
Definition
GET /v1/backorders/{backOrderID}
Example request
curl -X GET "https://numbers.messagebird.com/v1/backorders/48f6057c21de42d4bbf73fb86caaf361" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"id": "48f6057c21de42d4bbf73fb86caaf361","productID": 1993,"country": "GB","prefix": "44113","status": "blocked","reasonCodes": ["MISSING_KYC","MISSING_EUD"]}
Definition
GET /v1/backorders/{backOrderID}/documents
Example request
curl -X GET "https://numbers.messagebird.com/v1/backorders/48f6057c21de42d4bbf73fb86caaf361/documents" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"limit": 20,"count": 1,"items": [{"id": 62,"name": "Proof of in region address (max 3 months old)","description": "The number-user must provide proof that he has an address within the region of the prefix.","status": "missing"}]}
Definition
POST /v1/backorders/{backOrderID}/documents
Example request
curl -X POST "https://numbers.messagebird.com/v1/backorders/48f6057c21de42d4bbf73fb86caaf361/documents" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"id": 62,"name": "messagebird-kyc-upload-test.txt","mimeType": "text/plain","content": "RG9jdW1lbnQgdGhhdCBnb2luZyB0byBiZSB2ZXJpZmllZCBieSBhIHBlcnNvbi4="}'
Example response
HTTP/1.1 204 No Content
Definition
GET /v1/backorders/{backOrderID}/end-user-details
Example request
curl -X GET "https://numbers.messagebird.com/v1/backorders/48f6057c21de42d4bbf73fb86caaf361/end-user-details" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"items": [{"id": "CompanyName","label": "Company name"},{"id": "Street","label": "Street"},{"id": "StreetNumber","label": "Street number"},{"id": "ZipCode","label": "Zip code"},{"id": "City","label": "City"},{"id": "Country","label": "Country"}]}
Definition
POST /v1/backorders/{backOrderID}/end-user-details
Example request
curl -X POST "https://numbers.messagebird.com/v1/backorders/48f6057c21de42d4bbf73fb86caaf361/end-user-details" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"CompanyName": "Messagebird","Street": "Burgwal","StreetNumber": "35","ZipCode": "2011","City": "Amsterdam","Country": "Netherlands"}'
Example response
HTTP/1.1 204 No Content
Cancel a purchased phone number
Release this phone number from your account. You will no longer have access to this phone number and MessageBird will no longer receive calls or SMS/MMS messages on this number. You will stop being billed the monthly phone number fee and the phone number will eventually be recycled and potentially given to another customer, so use with care.
If you make a mistake, contact us. We may be able to give you the number back.
Number Pools
Number pools are set of pools that can be used in applications that require to use numbers dynamically. Currently, it can be only used with Voice API and SIP calls to randomise the caller ID.
Pool object
A pool is composed by the following attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | A random UUID used internally to uniquely identify a pool. |
| name | string | A unique name identifying a pool. A pool name can be of alphanumeric characters, - and _, from 3 to 100 characters. |
| service | string | The pool service. Possible values: randomcli. |
| configuration | object | The pool configuration object. |
| numbersCount | int | The amount of numbers in the pool. |
| createdAt | string | RFC3339 timestamp of when the pool has been created. |
| updatedAt | string | RFC3339 timestamp of when the pool has been updated. |
Pool service
The pool service defines the service you want to use the numbers pool with. Currently only randomcli is supported, in which case the outbound caller ID number is selected randomly from the pool.
Pool configuration
The pool configuration affects the way a number will be selected within a specific pool service.
Random CLI Configuration
| Attribute | Type | Description |
|---|---|---|
| byCountry | boolean | Select only numbers that belong to the same country of the destination. |
Create a number pool
You can create a number pool for some service with service-specific configurations.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | A number pool's name. The name should satisfy the [\w\-]{3,100} regular expression. |
| service | string | A service you want the pool to use for a call. Example: randomcli. |
| configuration | object | Service-specific configurations. |
Response
Returns a Pool object if the request was successful. If the request failed, an error object will be returned.
Definition
POST /v1/pools
Example request
curl -X POST "https://numbers.messagebird.com/v1/pools" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"poolName": "myPool","service": "randomcli","configuration": {"byCountry": false}}'
Example response
{"id": "726db88c-0fd6-44e8-8f0d-9ce2b2a5e16f","name": "myPool","service": "randomcli","createdAt": "2021-12-15T13:40:38.617645742Z","updatedAt": "2021-12-15T13:40:38.617645742Z","numbersCount": 0,"configuration": {"byCountry": false}}
Fetch a number pool
Fetch details of a single number pool.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | The name of the pool to fetch. |
Response
Returns a Pool object. If the request failed, an error object will be returned.
Definition
GET /v1/pools/{poolName}
Example request
curl -X GET "https://numbers.messagebird.com/v1/pools/myPool" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
Example response
{"id": "726db88c-0fd6-44e8-8f0d-9ce2b2a5e16f","name": "myPool","service": "randomcli","createdAt": "2021-12-15T13:40:38.617645742Z","updatedAt": "2021-12-15T13:40:38.617645742Z","numbersCount": 5,"configuration": {"byCountry": false}}
Edit a number pool
Edit a pool and its configuration. Be careful when renaming a pool because all requests for the old name will fail.
URL Parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | The name of the pool to edit. |
Payload parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | New name for the pool. (optional) |
| configuration | object | New service-based pool configuration. (optional) |
Response
If the request failed, an error object will be returned.
Definition
PUT /v1/pools/{poolName}
Example request
curl -X PUT "https://numbers.messagebird.com/v1/pools/myPool" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"poolName": "myRenamedPool","configuration": {"byCountry": true}}'
Example response
{"id": "726db88c-0fd6-44e8-8f0d-9ce2b2a5e16f","name": "myRenamedPool","service": "randomcli","createdAt": "2021-12-15T13:40:38.617645742Z","updatedAt": "2021-12-17T14:12:17.664352935Z","numbersCount": 5,"configuration": {"byCountry": true}}
List pools
List and filter number pools. Returns a list of number pools with their details if the request was successful. If the request failed, an error object will be returned.
Query Parameters (optional)
| Parameter | Type | Description |
|---|---|---|
| poolName | string | The name of the number pool. |
| service | string | The name of the service. |
| limit | integer | The maximum number of pools to show. The default is 20. |
| offset | integer | The amount of pools to skip. The default is 0. |
Definition
GET /v1/pools
Example request
curl -X GET "https://numbers.messagebird.com/v1/pools?name=myPool&service=randomcli&limit=1&offset=0" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json"
Example response
{"limit": 1,"offset": 0,"count": 1,"totalCount": 5,"items": [{"name": "myPool","service": "randomcli","createdAt": "2021-12-16T15:27:04.342Z","numbersCount": 10}]}
List pool numbers
List numbers that belong to a specific pool.
URL parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | A number pool's name. |
Query parameters (optional)
| Parameter | Type | Description |
|---|---|---|
| limit | integer | A maximum amount of numbers to show. The default limit is 20. |
| offset | integer | An amount of numbers to skip. The default offset is 0. |
| number | string | A string to be used for fetching numbers through partial match against this parameter. |
Response
If the request failed, an error object will be returned.
Definition
GET /v1/pools/{poolName}/numbers
Example request
curl -X GET "https://numbers.messagebird.com/v1/pools/myPool/numbers?limit=20&offset=0&number=316" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json"
Example response
{"limit": 20,"offset": 0,"count": 3,"totalCount": 3,"numbers": ["31612345678","31612345679","31612345670"],}
Add numbers to a pool
Add numbers to a pool.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | The name of the number pool. |
Payload parameters
| Parameter | Type | Description |
|---|---|---|
| numbers | array | An array of numbers to be attached to the pool. Each number must satisfy the ^\+?\d+$ regular expression. The total amount of numbers must not exceed 1000. |
Response
If the request failed, an error object will be returned. In case some of the numbers could not be added, a combined success and fail response will be returned.
Definition
POST /v1/pools/{poolName}/numbers
Example request
curl -X POST "https://numbers.messagebird.com/v1/pools/myPool/numbers" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json" \-d '{"numbers": ["31612345678","31612345679","31612345670"],}'
Example response
{"success": ["31612345678","31612345679"],"fail": [{"number": "31612345670","error": "number is not verified"}]}
Remove numbers from a pool
Remove all the specified numbers from a pool.
URL parameters
| Parameter | Type | Description |
|---|---|---|
| poolName | string | A number pool's name. |
Query parameters
| Parameter | Type | Description |
|---|---|---|
| numbers | string | A comma-separated list of numbers to be removed from the pool. Each number must satisfy the ^\+?\d+$ regular expression. The total amount of numbers must not exceed 1000. |
Response
If the request failed, an error object will be returned.
Definition
DELETE /v1/pools/{poolName}/numbers
Example request
curl -X DELETE "https://numbers.messagebird.com/v1/pools/myPool/numbers?numbers=31612345678,31612345679,31612345670" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-H "Content-Type: application/json"
Example response
HTTP/1.1 204 No Content
