Getting Started#
The DIDWW API v3 provides a powerful interface for programmatically managing phone number inventory, ordering, and service configurations. This guide explains how to create API keys and authenticate requests, work in different environments, manage API versioning, and use SDKs and tools for integration.
For the complete test-environment workflow, including account registration, authentication, a safe first request, and known limitations, see the DIDWW API Sandbox guide.
API Authentication and Keys#
To interact with the DIDWW API, you need an API key created in the DIDWW User Panel. Follow the steps below to get started.
How the key is used depends on the API version:
Version 2026-11-19: the API key is used only to mint short-lived access tokens with
POST /tokenon the DIDWW token service. API requests send the access token in theAuthorization: Bearerheader; an API key sent in theApi-Keyheader is refused. See Authentication for API v2026-11-19.Versions up to 2026-04-16: API requests send the API key in the
Api-Keyheader. See Authentication for API v2026-04-16.
Accounts without a configured default version, including new accounts, use version 2026-11-19, so their API keys work only with POST /token and the export file download. For version selection, see API Versioning and Deprecation Policy.
These pages describe the authentication scheme, request examples, environment separation, and security guidance of each version.
How to Get Your API Key#
Sign in to your DIDWW Account for production, or to your DIDWW Sandbox Account for sandbox.
Navigate to the APIs section in the left-hand menu.
Select the DIDWW API 3.
Click on Create new API Key.
Fig. 1. Create new API Key button.#
In the Create API Key form:
Friendly name: Enter a descriptive name for the key (e.g., Production Key, Integration Test).
Access IP’s: Optionally restrict access by specifying allowed IP addresses (e.g., 192.0.2.0/24).
Click Create. A new key will be added to the API Keys table.
Fig. 2. Creating a new API Key in the DIDWW User Panel.#
Note
In version 2026-11-19, send the key in the
Api-Keyheader ofPOST /tokenrequests (it is also accepted by the export file download), and send the minted access token asAuthorization: Bearer <access token>with API requests.In versions up to 2026-04-16, send the key as the value of the
Api-Keyrequest header. Do not add aBearerprefix.In version 2026-11-19, the requests an account sends to
api.didww.com(sandbox-api.didww.comin the sandbox) with access tokens share one budget of 20 requests per second, whichever API key minted the tokens. When the budget is spent, the API returns HTTP 429 Too Many Requests with aRetry-Afterheader that gives the number of seconds to wait.In versions up to 2026-04-16, each API key is limited to 20 requests per second. If this limit is exceeded, the API returns HTTP 429 Too Many Requests.
Create your sandbox API key in the Sandbox User Panel under APIs → DIDWW API 3. Contact DIDWW Customer Support if API-key management is unavailable. See the Sandbox authentication instructions.
How to Rotate Your API Key#
Rotate an API key if it is exposed, or on a regular schedule. Rotating replaces the key with a new one. Create and configure the replacement key first, and delete the old key only after every application uses the new one. This keeps your integration working during the change.
Important
If an API key is exposed or you suspect it is compromised, delete it immediately and create a replacement. Do not keep a compromised key active while you switch your applications to the new key. Requests from applications that still use the deleted key fail until the replacement is deployed, so plan for that downtime.
Create a replacement API key. Follow How to Get Your API Key in the same environment as the key you are replacing: the Production User Panel for a production key, or the Sandbox User Panel for a sandbox key.
Use a descriptive Friendly name that identifies the replacement, for example
Billing service 2026-10.Add the same Access IP’s restrictions as the old key, unless the source addresses of your application have changed.
Keep the old key until you complete step 4.
Configure the new key in every application that uses the old key. Include all deployed instances, background workers, scheduled jobs, and integration tools.
Store the new key in your secret manager or secure configuration.
Reload or redeploy the application if it reads the key only at startup.
In version 2026-11-19, mint access tokens with the new key on the token service. In versions up to 2026-04-16, send the new key in the
Api-Keyrequest header.
Verify that each application works with the new key. Check the new key with a read-only request, then run your normal application checks.
In version 2026-11-19, mint an access token with the new key, then send a read-only request with that token:
1curl --request POST \ 2 --url https://auth.didww.com/token \ 3 --header "Api-Key: YOUR_NEW_API_KEY" \ 4 --header "Content-Type: application/json" \ 5 --data '{"aud": "api.didww.com", "scope": "read", "api_version": "2026-11-19"}' 6 7curl https://api.didww.com/v3/countries \ 8 --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 9 --header "Accept: application/vnd.api+json"
Replace
YOUR_ACCESS_TOKENwith theaccess_tokenvalue of the token response. See Authentication for API v2026-11-19.In versions up to 2026-04-16, send the new key in the
Api-Keyheader:1curl https://api.didww.com/v3/countries \ 2 --header "Api-Key: YOUR_NEW_API_KEY" \ 3 --header "Accept: application/vnd.api+json"
For a sandbox key, use
https://auth-sandbox.didww.com/tokenandhttps://sandbox-api.didww.com/v3/countries.Before you continue, confirm that no application still uses the old key. The Last Used column of the API Keys table shows when each key was last used. You can also open the old key with Actions > Configure API key to see its Last used time. When the old key shows no new use, every application has switched. Requests that still use a deleted key fail with
401 Unauthorized.Delete the old API key. In the API Keys table under APIs → DIDWW API 3, click Actions next to the key you replaced and select Delete API key. In the Delete API Security Key window, click Delete to confirm. Integrations that still use the deleted key can no longer authenticate. In version 2026-11-19, access tokens minted with the deleted key are refused by
api.didww.comfrom that moment, even before they expire.
Fig. 3. Deleting the old API key in the DIDWW User Panel.#
Remove every remaining copy of the old key from secret managers, configuration files, and CI/CD settings.
Monitor your applications for
401 Unauthorizedresponses after the deletion.
Recommended rotation frequency
Use a risk-based schedule. Rotate long-lived API keys at least every 90 days, or more often if your security policy requires it.
Delete and replace an exposed or suspected compromised key immediately, regardless of its age.
Delete API keys that are no longer used.
The 90-day interval is a recommended practice, not a DIDWW key expiry rule or a compliance requirement.
Rotating an API key does not affect callbacks. DIDWW signs callbacks with your callback secret, which you replace separately. See How to Set Up a Callback Secret.
How to Set Up a Callback Secret#
Callbacks are HTTP requests DIDWW sends to your server when an asynchronous API operation changes state. DIDWW signs every callback with the enabled callback secret of your account, and sends callbacks only while a callback secret is enabled.
Sign in to your DIDWW Account for production, or to your DIDWW Sandbox Account for sandbox.
Navigate to the APIs section in the left-hand menu and select DIDWW API 3.
In the Callback Secrets section, click Create new Callback Secret.
Fig. 4. Create new Callback Secret button.#
In the Create Callback Secret form:
Friendly name: Enter a descriptive name for the secret (e.g., Production Callbacks).
Enabled: Turn on to sign callbacks with this secret. Only one callback secret can be enabled at a time: enabling a secret disables the previously enabled one.
Click Create. The secret is generated by DIDWW and added to the Callback Secrets table, where you can reveal and copy it to configure your callback receiver.
Fig. 5. Creating a new Callback Secret in the DIDWW User Panel.#
Note
To replace a callback secret without a gap in delivery, create a new secret with Enabled turned off, configure your receiver to accept it, enable it, and then delete the old one.
Deleting the enabled callback secret stops callbacks until another secret is enabled.
For callback events, payloads, and signature validation, see the Callback Details page of your API version, for example Callback Details for API v2026-11-19.
API Environments#
DIDWW provides two separate environments for API integration:
Production environment: Used for live operations involving actual number inventory and billing.
Sandbox environment: Used for development and testing purposes, simulating production behavior without affecting real data or incurring charges.
The sandbox environment mirrors the functionality of the production environment, making it ideal for validating API requests, application logic, and workflow integration before going live. No actual number provisioning or billing operations occur in the sandbox.
Production environment#
API base URL:
https://api.didww.com/v3/
Token service (API version 2026-11-19):
https://auth.didww.com/token
Sandbox environment#
API base URL:
https://sandbox-api.didww.com/v3/
Token service (API version 2026-11-19):
https://auth-sandbox.didww.com/token
API keys and access tokens are valid only in the environment where they were created.
SDKs and Tools#
Access the official PHP SDK for integrating with the DIDWW API.
Access the official Java SDK for integrating with the DIDWW API.
Access the official Python SDK for integrating with the DIDWW API.
Install the didww package on PyPI.
Access the official TypeScript SDK for integrating with the DIDWW API.
Install the @didww/sdk package on npm.
Access the official DIDWW API client SDK for the Go programming language.
Access the official DIDWW API client SDK for the .NET platform.
Use the official Ruby client for interacting with the DIDWW API.
View a sample Rails app showing how to integrate with the DIDWW API.
Explore DIDWW API endpoints in the Postman public workspace.
API Use Case Examples#
Learn how to purchase and verify a DID number when regulatory requirements apply.
Learn how to select and purchase numbers from a specific DID group using API v3.
Learn how to select and purchase a specific number from available DID inventory using API v3.
Learn how to register existing DIDs for emergency calling by using emergency requirements, validations, and verifications.
Learn how to replace the address of an existing emergency calling service by submitting a new emergency verification.