Introduction

The DIDWW API provides a simple yet powerful interface that allows you to fully integrate your own applications with DIDWW services. An extensive set of actions may be performed using this API, such as ordering and configuring phone numbers, setting capacity, creating SIP trunks and retrieving CDRs and other operational data. As such, this interface is the ideal tool for building alternative dashboards, developing mobile applications and automating front and back-end applications.

The DIDWW API is a fully compliant implementation of the JSON API specification, which defines how an application should request that resources be fetched or modified, and how a server should respond to those requests. This REST (Representational State Transfer) interface provides an easy-to-use set of HTTP endpoints that let you access our services using GET, PUT, POST, PATCH and DELETE methods.

Note

This document assumes that you are familiar with web programming concepts, web data formats, and the JSON API specification. Additional Information about JSON is available on their official website.

API Keys

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 at https://my.didww.com 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 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 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 https://my.didww.com/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.

You can change your API 3 version on https://my.didww.com/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.