Use Case Examples
The DIDWW API provides a robust and flexible interface for managing your telecommunication services. This section includes practical, step-by-step examples of common workflows for ordering DID numbers. Each use case demonstrates how to use the API effectively based on different selection criteria, such as geographic location, prefix, or specific number availability.
Learn how to buy a random number from a specific DID group using API v3.
Learn how to order a DID number by filtering with a specific NPA/NXX prefix using API v3.
Learn how to select and purchase a specific number from available DID inventory using API v3.
Example 1: Buy a Random Number from a Specific DID Group
To buy a random number, follow these steps:
Get the country and city IDs.
Retrieve the appropriate DID Group and SKU IDs.
Place the order using the selected SKU IDs.
Step 1: Find the Country ID
Start by retrieving the unique ID for the country. Use the /countries endpoint and filter by name, prefix or a two-letter ISO code. For full details, see the /v3/countries endpoint documentation.
http
GET /v3/countries?filter%5Biso%5D=GB HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/countries?filter%5Biso%5D=GB' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "c8647639-fc9c-47b2-acec-7c9e14465c25",
"type": "countries",
"attributes": {
"name": "United Kingdom",
"iso": "GB"
}
}
]
}
From this response, save the country.id.
Step 2: Find the City ID
Use the country.id from Step 1 to get the city ID where you want to buy the number. See the /v3/cities endpoint documentation for more details.
http
GET /v3/cities?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bname%5D=London HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/cities?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bname%5D=London' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "e696dec7-9c65-4e99-aab7-55a1f98154f0",
"type": "cities",
"attributes": {
"name": "London"
}
}
]
}
From this response, save the city.id.
Step 3: Find the DID Group and SKU ID
With the city.id, query the /did_groups endpoint and include stock_keeping_units to find available DIDs and their pricing. See the /v3/did_groups endpoint documentation for more information.
http
GET /v3/did_groups?include=stock_keeping_units&filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0 HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/did_groups?include=stock_keeping_units&filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "fc271bcc-1f9c-4c19-8174-28b7c55a208a",
"type": "did_groups",
"attributes": {
"area_name": "London"
},
"relationships": {
"stock_keeping_units": {
"data": [
{ "type": "stock_keeping_units", "id": "d7b28c79-b505-4995-9b78-d73b016b277d" },
{ "type": "stock_keeping_units", "id": "74d2af35-0cab-4ad8-aca7-5800baa1daa3" }
]
}
}
}
],
"included": [
{
"id": "d7b28c79-b505-4995-9b78-d73b016b277d",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "1.2",
"channels_included_count": 0
}
},
{
"id": "74d2af35-0cab-4ad8-aca7-5800baa1daa3",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "10.0",
"channels_included_count": 2
}
}
]
}
From the response, select the sku.id from the included section based on your needs.
Important
Choose the SKU ID based on the number of included channels:
For 0 included channels, use the SKU ID with “channels_included_count”: 0.
For 2 included channels, use the SKU ID with “channels_included_count”: 2.
To learn more about channels, see Capacity.
Step 4: Create the Order
Use the selected sku.id to create the order. In this example, we’ll purchase a number with 2 included channels. Refer to the /v3/orders endpoint documentation for details.
http
POST /v3/orders HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "orders",
"attributes": {
"allow_back_ordering": true,
"items": [
{
"type": "did_order_items",
"attributes": {
"sku_id": "74d2af35-0cab-4ad8-aca7-5800baa1daa3",
"qty": 1
}
}
]
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"allow_back_ordering": true, "items": [{"type": "did_order_items", "attributes": {"sku_id": "74d2af35-0cab-4ad8-aca7-5800baa1daa3", "qty": 1}}]}, "type": "orders"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "df0f0bc2-5607-4370-8c05-add19974cfbb",
"type": "orders",
"attributes": {
"amount": "12.1",
"status": "Completed",
"created_at": "2025-07-07T11:44:51.542Z",
"description": "1 x United Kingdom - Local - London",
"reference": "XFX-924453"
},
"relationships": {
"order_items": {
"data": [
{
"type": "order_items",
"id": "2de14280-92a1-464a-8108-1e43d735af2a"
}
]
}
}
}
}
Example 2: Buy a DID Number Using an NPA/NXX Prefix
This process allows you to purchase a random DID number from a specific NPA/NXX (area code and prefix) within the North American Numbering Plan (NANP).
To buy a random DID number based on a specific NPA/NXX (area code and prefix), follow these steps:
Retrieve the country and region IDs (e.g., United States and New York).
Get the NANPA prefix ID using the NPA/NXX value (e.g., 212461).
Find a matching DID Group and select a suitable SKU ID.
Place the order using the selected SKU ID.
The SKU (stock keeping unit) determines pricing and capacity options—such as whether the DID includes 0 or 2 inbound channels.
Attention
Run each API request individually using live data in a real environment to ensure accurate results.
Step 1: Find the Country ID
Start by retrieving the unique ID for the country. Use the /countries endpoint and filter by name, prefix, or two-letter ISO code. For full details, see the /v3/countries endpoint documentation.
http
GET /v3/countries?filter%5Biso%5D=US HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/countries?filter%5Biso%5D=US' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
"type": "countries",
"attributes": {
"name": "United States",
"iso": "US"
}
}
]
}
From this response, save the country.id.
Step 2: Find the Region ID
Use the country.id to retrieve the region where you want to buy the number. For more information, see the /v3/regions endpoint documentation.
http
GET /v3/regions?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=New+York HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/regions?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=New+York' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "7ad33fd7-f808-4d09-abeb-ec91b7ca5a62",
"type": "regions",
"attributes": {
"name": "New York"
}
}
]
}
From this response, save the region.id.
Step 3: Find the NANPA Prefix ID
Next, query the /nanpa_prefixes endpoint using the country.id, region.id, and desired NPA/NXX (e.g., 212-461) filters. See the /v3/nanpa_prefixes endpoint documentation for more details.
http
GET /v3/nanpa_prefixes?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bregion.id%5D=7ad33fd7-f808-4d09-abeb-ec91b7ca5a62&filter%5Bnpanxx%5D=212461 HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/nanpa_prefixes?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bregion.id%5D=7ad33fd7-f808-4d09-abeb-ec91b7ca5a62&filter%5Bnpanxx%5D=212461' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "999a8e93-6e3e-4c7b-b3b3-1e5b10a26e77",
"type": "nanpa_prefixes",
"attributes": {
"npa": "212",
"nxx": "461"
}
}
]
}
From this response, save the nanpa_prefix.id.
Step 4: Find the DID Group and SKU ID
Use the nanpa_prefix.id to find an associated DID Group and available SKUs by querying the /did_groups endpoint with include=stock_keeping_units.
For additional information, refer to the /v3/did_groups endpoint documentation.
http
GET /v3/did_groups?include=stock_keeping_units&filter%5Bnanpa_prefix.id%5D=cf8f6445-85b7-4126-8ac0-f6663e0dabc6 HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/did_groups?include=stock_keeping_units&filter%5Bnanpa_prefix.id%5D=cf8f6445-85b7-4126-8ac0-f6663e0dabc6' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "ac9de84c-4681-4042-b3a4-3a19c7d08724",
"type": "did_groups",
"attributes": {
"area_name": "New York"
},
"relationships": {
"stock_keeping_units": {
"data": [
{ "type": "stock_keeping_units", "id": "33d24d87-5bc7-457a-8278-d2cae0a10f3d" },
{ "type": "stock_keeping_units", "id": "94e9bb5b-b2b0-4c59-b152-37756c676f6b" }
]
}
}
}
],
"included": [
{
"id": "33d24d87-5bc7-457a-8278-d2cae0a10f3d",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "99.0",
"monthly_price": "20.0",
"channels_included_count": 0
}
},
{
"id": "94e9bb5b-b2b0-4c59-b152-37756c676f6b",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "99.0",
"monthly_price": "20.0",
"channels_included_count": 2
}
}
]
}
From the response, select the sku.id` from the ``included section that meets your requirements.
Important
Choose the SKU ID based on the number of included channels:
For 0 included channels, use the SKU ID with “channels_included_count”: 0.
For 2 included channels, use the SKU ID with “channels_included_count”: 2.
To learn more about channels, see Flexible Capacity Documentation.
Step 5: Create the Order
Use the selected sku.id to create the order.
In this example, we’ll purchase a number with 2 included channels.
For details on order creation, refer to the /v3/orders endpoint documentation.
http
POST /v3/orders HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "orders",
"attributes": {
"allow_back_ordering": true,
"items": [
{
"type": "did_order_items",
"attributes": {
"sku_id": "94e9bb5b-b2b0-4c59-b152-37756c676f6b",
"qty": 1
}
}
]
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"allow_back_ordering": true, "items": [{"type": "did_order_items", "attributes": {"sku_id": "94e9bb5b-b2b0-4c59-b152-37756c676f6b", "qty": 1}}]}, "type": "orders"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "019a7164-814c-4a8a-9c3b-5a1e7845c123",
"type": "orders",
"attributes": {
"amount": "119.0",
"status": "Completed",
"created_at": "2025-07-08T12:00:00.000Z",
"description": "1 x United States - Local - New York",
"reference": "ABC-123456"
},
"relationships": {
"order_items": {
"data": [
{
"type": "order_items",
"id": "456b8e88-3d1f-4f7b-9b3c-9a1b3d5c7e9f"
}
]
}
}
}
}
Example 3: Buy an Available Number from DID Inventory
This process lets you purchase a specific, known phone number from the available DID inventory. Use this flow to find a number in your desired location and place an order for it.
Note
This feature requires the number selection tool. Contact customer.care@didww.com or sales@didww.com to enable it.
Results are returned in a random order and are not sorted.
Previous requests are not cached. A new request may return the same results as a prior request, depending on the filters used.
To buy an available number from DID Inventory, follow these steps:
Get the country and city IDs.
Find a DID Group with available numbers.
Retrieve an available DID and choose a suitable SKU.
Place the order using the selected SKU ID.
Step 1: Find the Country ID
Retrieve the unique ID for the target country (e.g., United States) using the /countries endpoint.
See the /v3/countries endpoint documentation.
http
GET /v3/countries?filter%5Biso%5D=US HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/countries?filter%5Biso%5D=US' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "3b11ad09-dc7e-451a-9d32-ae9c1604aaa8",
"type": "countries",
"attributes": {
"name": "United States",
"iso": "US"
}
}
]
}
From this response, save the country.id.
Step 2: Find the City ID
Use the country.id to query the /cities endpoint for your target city (e.g., Los Angeles). See the /v3/cities documentation to learn more.
http
GET /v3/cities?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Los+Angeles HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/cities?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bname%5D=Los+Angeles' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "ef8d6406-afbf-44b5-ab2c-53bebdd2f192",
"type": "cities",
"attributes": {
"name": "Los Angeles"
}
}
]
}
From this response, save the city.id.
Step 3: Find an available DID Group
Query the /did_groups endpoint with country.id, city.id, and available_dids_enabled=true to find a group that supports number selection. Some regions or groups may not support this feature. See the /v3/did_groups documentation to learn more.
http
GET /v3/did_groups?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bcity.id%5D=ef8d6406-afbf-44b5-ab2c-53bebdd2f192&filter%5Bavailable_dids_enabled%5D=true HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/did_groups?filter%5Bcountry.id%5D=3b11ad09-dc7e-451a-9d32-ae9c1604aaa8&filter%5Bcity.id%5D=ef8d6406-afbf-44b5-ab2c-53bebdd2f192&filter%5Bavailable_dids_enabled%5D=true' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "35d88800-2f02-4a15-96c0-151c4fc1b241",
"type": "did_groups",
"attributes": {
"area_name": "Los Angeles"
},
"meta": {
"available_dids_enabled": true
}
}
]
}
From this response, save the did_group.id.
Step 4: Find an Available DID and SKU
Use the did_group.id to call /available_dids (with include=did_group.stock_keeping_units) to retrieve available numbers and their SKUs.
See the /v3/available_dids endpoint documentation.
http
GET /v3/available_dids?include=did_group.stock_keeping_units&filter%5Bdid_group.id%5D=35d88800-2f02-4a15-96c0-151c4fc1b241 HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Accept: application/vnd.api+json
curl
curl -i -X GET 'https://api.didww.com/v3/available_dids?include=did_group.stock_keeping_units&filter%5Bdid_group.id%5D=35d88800-2f02-4a15-96c0-151c4fc1b241' -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]"
response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6",
"type": "available_dids",
"attributes": {
"number": "12131234xxx"
}
}
],
"included": [
{
"id": "a2e4cd60-435c-4838-8a26-b213e5ee9055",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "1.2",
"channels_included_count": 0
}
},
{
"id": "fec4945f-d914-4916-8931-259e940c9029",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "10.0",
"channels_included_count": 2
}
}
}
]
}
Select the appropriate sku.id based on pricing and channel count.
Important
Choose the SKU ID based on included channels:
0 channels – select the SKU with “channels_included_count”: 0
2 channels – select the SKU with “channels_included_count”: 2
For more on channel options, see Flexible Capacity.
Step 5: Create the Order
Use the selected sku.id to create an order for the available DID number.
Refer to the /v3/orders endpoint documentation for full details.
http
POST /v3/orders HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "orders",
"attributes": {
"allow_back_ordering": true,
"items": [
{
"type": "did_order_items",
"attributes": {
"sku_id": "fec4945f-d914-4916-8931-259e940c9029",
"qty": 1
}
}
]
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/orders -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"allow_back_ordering": true, "items": [{"type": "did_order_items", "attributes": {"sku_id": "fec4945f-d914-4916-8931-259e940c9029", "qty": 1}}]}, "type": "orders"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "f0e9d8c7-b6a5-f4e3-d2c1-b0a9f8e7d6c5",
"type": "orders",
"attributes": {
"amount": "10.0",
"status": "Completed",
"created_at": "2025-07-09T10:00:00.000Z",
"description": "1 x 12131234xxx",
"reference": "GHI-789012"
},
"relationships": {
"order_items": {
"data": [
{
"type": "order_items",
"id": "cba98765-4321-fedc-ba98-76543210cba9"
}
]
}
}
}
}