API Keys
Please visit the “API” section in the DIDWW User Panel to receive your API Security Key and to access full API documentation (Fig. 1).
Fig. 1. API settings and documentation
Basic configuration:
Callbacks - allow to receive events related to your Orders, Exports, and Address Verifications via HTTP request.
Access IP’s - IP addresses from which access to the API will be allowed. Supported formats: IPv4, IPv6, /mask.
To receive your API key, click on “Send API security key to email”.
Note
DIDWW API allows 20 requests per second for a single API KEY to ensure that the API remains responsive to all users.
To use the DIDWW API in either the sandbox or production environment, you must register and receive an API key which will be used by your application.
To receive your production API key:
Sign into your DIDWW Account and access the “API access settings” on the API page. If you do not have an account with DIDWW, please register for free.
Click on “Send API security key to email” and you will receive your private key at your registered email address.
You must include this key following the Api-Key prefix in your API requests as shown in the example below:
http
GET /v3/countries HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Api-Key: 4D41E00J6KMXABS
curl
curl -i -X GET https://api.didww.com/v3/countries -H "Api-Key: 4D41E00J6KMXABS" -H "Content-Type: application/vnd.api+json"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
To receive your sandbox API key:
Please contact DIDWW Technical Support Team.
You must include this key following the Api-Key prefix in your API requests as shown in the example below:
http
GET /v3/countries HTTP/1.1
Host: sandbox-api.didww.com
Content-Type: application/vnd.api+json
Api-Key: 4D41E00J6KMXABS
curl
curl -i -X GET https://sandbox-api.didww.com/v3/countries -H "Api-Key: 4D41E00J6KMXABS" -H "Content-Type: application/vnd.api+json"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Environments and Endpoints
DIDWW maintains both a sandbox and a production environment for the API.
The sandbox allows you to develop your application outside the production environment and therefore does not affect critical data. Operating your application in the sandbox is essentially the same as operating in the production environment, and all aspects of the API may be tested. However, no actual transactions take place that modify the DIDWW number inventory or cause charges to be incurred. This environment is important for testing the functionality and logic of your application before deploying to production or releasing to customers.
The endpoints are as follows:
Sandbox environment:
https://sandbox-api.didww.com/v3/
Production environment:
https://api.didww.com/v3/
Rate Limits
Requests to any https://api.didww.com/v3/ endpoint are rate limited to ensure that the API remains responsive to all users. Rate limits are 20 requests per second and are applied to API-KEY instead of IP. After exceeding the limit, 429 HTTP status code will be returned.
{
"errors": [
{
"status": "429",
"detail": "Too Many Requests"
}
]
}
API Versioning
The API 3 versioning controls the API behavior. The newer API versions may behave differently and contain additional resources and parameters. The used API version is defined by the date when the first API3 Request has been sent. Once API 3 is upgraded in a backwards-incompatible way, we release a new dated version to avoid breaking your current infrastructure. API version will not change automatically and customer is responsible for upgrading it via DIDWW User Panel.
You can see your current API 3 version in response meta.api_version.
Currently used API 3 version can be reviewed on the API page.
Upgrading API 3 Version
The newer version can be used by sending an X-DIDWW-API-Version header in your request.
The invalid value of X-DIDWW-API-Version header will be ignored.
The meta.api_version value will be affected by X-DIDWW-API-Version header.
It will switch API 3 version per request basis and does not affect other requests.
http
GET /v3/voice_in_trunk_groups HTTP/1.1
Host: api.didww.com
Content-Type: application/vnd.api+json
Api-Key: [API Token]
X-DIDWW-API-Version: 2022-05-10
curl
curl -i -X GET https://api.didww.com/v3/voice_in_trunk_groups -H "Api-Key: [API Token]" -H "Content-Type: application/vnd.api+json" -H "X-Didww-Api-Version: 2022-05-10"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "12345678-abcd-4321-efgh-9876543210ab",
"type": "voice_in_trunk_groups",
"attributes": {
"created_at": "2023-09-01T08:06:37.162Z",
"name": "TG test",
"capacity_limit": null
},
"relationships": {
"voice_in_trunks": {}
},
"meta": {
"trunks_count": 2
}
}
],
"meta": {
"total_records": 1,
"api_version": "2022-05-10"
}
}
You can change your API 3 version on the API page.
Before changing your API 3 version check API 3 Changelog.
Note
If your currently used version is newer then the X-DIDWW-API-Version value sent, API will ignore the X-DIDWW-API-Version header.
API 3 version downgrade is not available.
PHP SDK
Access the official PHP SDK for interacting with the DIDWW API.
Ruby Client
Explore the Ruby client library for integrating with the DIDWW API.
See a live example of the DIDWW API in action with a Ruby on Rails sample app.
Postman Public Workspace
Access the Postman public workspace for exploring the DIDWW API endpoints.