Numbers API beta

Notification icon

Programmable Numbers API is currently in Beta.

The MessageBird Programmable Numbers API provides a view into the MessageBird inventory of phone numbers available for purchase, the ability to purchase one or more chosen phone numbers, and manage all your purchased phone numbers.

API Endpoint

https://numbers.messagebird.com
All requests must be over SSL.

Object example

{
"errors": [
{
"code": 1001,
"message": "You are requesting with an invalid credential.",
"parameter": null
}
]
}

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

AttributeTypeDescription
errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameterstringThe 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)

ParameterTypeDescription
countryCodestring

Query Parameters (optional)

ParameterTypeDescription
numberstringOne or multiple numbers to be that the listed phone numbers should contain.
featuresarrayThe feature of a phone number. Possible values: smsvoicemms.
typestringThe type of a phone number. Possible values: landlinemobilepremium_rate.
limitintegerLimit the results (default: 20, max.: 100).
search_patternstringApproach 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: '')

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 gshuPaZoeEG6ovbc8M79w0QyM"

Example response

{
"items": [
{
"number": "3197010260188",
"country": "NL",
"region": "",
"locality": "",
"features": [
"sms",
"voice"
],
"type": "mobile"
}
],
"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

ParameterTypeDescription
numberstringThe phone number you want to purchase as presented in the response of /available-phone-numbers.
countryCodestringAlpha-2 country code (example: NL)
billingIntervalMonthsintegerHow 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 gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
--data '{"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

ParameterTypeDescription
limitintegerLimit the amount of results per page.
offsetintegerSkip first n results.
featuresarrayFeatures for which search is done (example ?features=sms&features=voice).
tagsarrayTags for which search is done (example ?tags=mobile&tags=primary).
numberstringFragment of number.
regionstringFragment of region data.
localitystringFragment of locality data.
typestringNumber 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 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 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 gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
--data '{"tags":["tag1"]}'

Example response

{
"number": "31612345670",
"country": "NL",
"region": "Texel",
"locality": "Texel",
"features": [
"sms",
"voice"
],
"tags": ["tag1"],
"type": "mobile",
"status": "active"
}

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.

Definition

DELETE /v1/phone-numbers/{phoneNumber}

Example request

$ curl -X "DELETE" "https://numbers.messagebird.com/v1/phone-numbers/31612345670" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json"

Example response

HTTP/1.1 200 OK
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings