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:
Find the country ID.
Find the city ID.
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"
}
]
}
}
}
}