# 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](sandbox.html). --- ## 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](2026-04-16/authentication.html). ### How to Get Your API Key 1. Sign in to your [DIDWW Account](https://my.didww.com/#/users/sign_in) for production, or to your [DIDWW Sandbox Account](https://my-sandbox.didww.com/#/users/sign_in) 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.](../_images/create_new_api_key.png)](../_images/create_new_api_key.png) **Fig. 1.** Create new API Key button. 5. 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). 6. Click **Create**. A new key will be added to the **API Keys** table. [![Creating a new API Key in the DIDWW User Panel.](../_images/create_new_api_key2.png)](../_images/create_new_api_key2.png) **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](mailto:support%40didww.com) if API-key management is unavailable. See the [Sandbox authentication instructions](sandbox.html#api3-sandbox-authentication). ### 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](https://my.didww.com/#/users/sign_in) for production, or to your [DIDWW Sandbox Account](https://my-sandbox.didww.com/#/users/sign_in) 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.](../_images/create_new_callback_secret.png)](../_images/create_new_callback_secret.png) **Fig. 3.** Create new Callback Secret button. 4. 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. 5. 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.](../_images/create_new_callback_secret2.png)](../_images/create_new_callback_secret2.png) **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](2026-04-16/callbacks-details.html). --- ## 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. **Java SDK** Access the official Java SDK for integrating with the DIDWW API. **Python SDK** Access the official Python SDK for integrating with the DIDWW API. Install the [didww package on PyPI](https://pypi.org/project/didww/). **TypeScript SDK** Access the official TypeScript SDK for integrating with the DIDWW API. Install the [@didww/sdk package on npm](https://www.npmjs.com/package/@didww/sdk). **Go SDK** Access the official DIDWW API client SDK for the Go programming language. **.NET SDK** Access the official DIDWW API client SDK for the .NET platform. **Ruby Client** Use the official Ruby client for interacting with the DIDWW API. **Ruby on Rails Sample App** View a sample Rails app showing how to integrate with the DIDWW API. **Postman Public Workspace** Explore DIDWW API endpoints in the Postman public workspace. ## 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](examples/buy-dids-with-verification.html#user-panel-api-examples-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)](examples/buy-dids.html#user-panel-api-examples-random-dids) **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)](examples/buy-reserved-dids.html#user-panel-api-examples-available-dids) **Register Emergency Calling Service** Learn how to register existing DIDs for emergency calling by using emergency requirements, validations, and verifications. [Register Emergency Calling Service](examples/register-emergency-calling-service.html#api-examples-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](examples/update-emergency-calling-service.html#api-examples-update-emergency-calling-service) On this page