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 authenticate using API keys, 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 to obtain and configure an API Security Key. Follow the steps below to get started.
For the authentication scheme, request example, environment separation, and security guidance that apply to the current API version, see Authentication for API v2026-04-16.
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
Send the key as the value of the
Api-Keyrequest header. Do not add aBearerprefix.Each API key is limited to 20 requests per second to ensure consistent performance across all users. If this limit is exceeded, the API will return an HTTP 429 Too Many Requests error.
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 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. 3. 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. 4. 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-04-16.
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#
https://api.didww.com/v3/
Sandbox environment#
https://sandbox-api.didww.com/v3/
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.