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#

  1. Sign in to your DIDWW Account for production, or to your DIDWW Sandbox Account for sandbox.

  2. Navigate to the APIs section in the left-hand menu.

  3. Select the DIDWW API 3.

  4. Click on Create new API Key.

Create new API Key button.

Fig. 1. Create new API Key button.#

  1. 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).

  2. Click Create. A new key will be added to the API Keys table.

Creating a new API Key in the DIDWW User Panel.

Fig. 2. Creating a new API Key in the DIDWW User Panel.#

Note

  • Send the key as the value of the Api-Key request header. Do not add a Bearer prefix.

  • 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 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.

  1. 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.

  2. 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.

    • Continue to send the key in the Api-Key request header.

  3. Verify that each application works with the new key. Send a read-only request with the new key, then run your normal application checks.

    curl https://api.didww.com/v3/countries \
  --header "Api-Key: YOUR_NEW_API_KEY" \
  --header "Accept: application/vnd.api+json"

    For a sandbox key, use https://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.

  4. 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.

    Delete API key option in the Actions menu of the API Keys table.

    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 Unauthorized responses 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.

  1. Sign in to your DIDWW Account for production, or to your DIDWW Sandbox Account for sandbox.

  2. Navigate to the APIs section in the left-hand menu and select DIDWW API 3.

  3. In the Callback Secrets section, click Create new Callback Secret.

Create new Callback Secret button.

Fig. 4. Create new Callback Secret button.#

  1. 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.

  2. 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.

Creating a new Callback Secret in the DIDWW User Panel.

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-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#

PHP SDK

Access the official PHP SDK for integrating with the DIDWW API.

https://github.com/didww/didww-api-3-php-sdk
Java SDK

Access the official Java SDK for integrating with the DIDWW API.

https://github.com/didww/didww-api-3-java-sdk
Python SDK

Access the official Python SDK for integrating with the DIDWW API.

Install the didww package on PyPI.

https://github.com/didww/didww-api-3-python-sdk
TypeScript SDK

Access the official TypeScript SDK for integrating with the DIDWW API.

Install the @didww/sdk package on npm.

https://github.com/didww/didww-api-3-typescript-sdk
Go SDK

Access the official DIDWW API client SDK for the Go programming language.

https://github.com/didww/didww-api-3-go-sdk
.NET SDK

Access the official DIDWW API client SDK for the .NET platform.

https://github.com/didww/didww-api-3-dotnet-sdk
Ruby Client

Use the official Ruby client for interacting with the DIDWW API.

https://github.com/didww/didww-v3-ruby
Ruby on Rails Sample App

View a sample Rails app showing how to integrate with the DIDWW API.

https://github.com/didww/didww-v3-rails-sample
Postman Public Workspace

Explore DIDWW API endpoints in the Postman public workspace.

https://www.postman.com/didww-api/workspace/didww-api3-documentation

API Use Case Examples#

Buy a DID Number That Requires Verification

Learn how to purchase and verify a DID number when regulatory requirements apply.

Buy a DID Number That Requires Verification
Buy Numbers from a Specific DID Group

Learn how to select and purchase numbers from a specific DID group using API v3.

Buy Available DID Number(s)
Buy a Specific Number from DID Inventory

Learn how to select and purchase a specific number from available DID inventory using API v3.

Select, Reserve & Buy Available DID Number(s)
Register Emergency Calling Service

Learn how to register existing DIDs for emergency calling by using emergency requirements, validations, and verifications.

Register Emergency Calling Service
Update Emergency Calling Service

Learn how to replace the address of an existing emergency calling service by submitting a new emergency verification.

Update Emergency Calling Service