You can use the Available Number API to search for available numbers or activate an available number.
Numbers | Sinch (1.0.3)
The Numbers API enables you to search for, view, and activate numbers. It's considered a precursor to other APIs in the Sinch product family. The numbers API can be used in tandem with any of our APIs that perform messaging or calling. Once you have activated your numbers, you can then use the various other APIs, such as SMS or Voice, to assign and use those numbers.
Let's take a brief look at some of the formats used in the REST API.
JSON (application/json) is the content type of both requests and responses if not otherwise specified.
Requests with invalid JSON will be rejected.
Null values can be omitted in requests and will be omitted in responses. In some cases, explicitly setting null will overwrite a previously set value with null.
Only phone numbers in E.164 standard format are accepted by the API.
A summary of status codes can be found on the HTTP status codes page.
To successfully use callbacks with Numbers, add the following IP addresses to your allowlist:
- 54.76.19.159
- 54.78.194.39
- 54.155.83.128
New features might result in additional request and response parameters. New request parameters will either have a default value or be considered optional to retain backwards compatibility. It's highly recommended to ignore any unexpected parameters when reading JSON in API responses and in callback handlers.
Download OpenAPI description
Overview
Languages
Servers
Global API
https://numbers.api.sinch.com/
Path
Found on your Sinch Customer Dashboard. Settings > Projects.
Example: YOUR_projectId
Query
Only return regions for which numbers are provided with the given types: MOBILE, LOCAL or TOLL_FREE.
- MOBILE: Numbers that belong to a specific range.
- LOCAL: Numbers that are assigned to a specific geographic region.
- TOLL_FREE: Number that are free of charge for the calling party but billed for all arriving calls.
If you want to see all results, do not add the types query parameter.
| Items Enum Value | Description |
|---|---|
| MOBILE | Numbers that belong to a specific range. |
| LOCAL | Numbers that are assigned to a specific geographic region. |
| TOLL_FREE | Numbers that are free of charge for the calling party but billed for all arriving calls. |
- Global APIhttps://numbers.api.sinch.com/v1/projects/{projectId}/availableRegions
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://numbers.api.sinch.com/v1/projects/YOUR_projectId/availableRegions?types=MOBILE'A successful response, or an Error.
Response
application/json
{ "availableRegions": [ { … } ] }
Numbers Callbacks
You can set up callback URLs to receive event notifications when your numbers are updated.
When delivering events the order is not guaranteed (for example, a failed event scheduled for retry will not block other events that were queued).
The client's callback handler must implement the state machine that can decide what to do with unexpected events, for example, "old" events or invalid state transitions. In these cases the handler could use the API to GET the latest state for the resource.
The callback handler is expected to "ingest" the event and respond with 200 OK. The domain-specific business logic and processes should be executed outside of the callback request, as internal asynchronous jobs.
To use callbacks, add the following IP addresses to your allowlist:
- 54.76.19.159
- 54.78.194.39
- 54.155.83.128
OperationsWebhooks