Select, Reserve & Buy Available DID Number(s)
This example shows the end-to-end process for purchasing a specific DID number from DID inventory by selecting it from the list of currently available numbers and reserving it before placing the order.
This flow is used when your account has access to GET /v3/available_dids and you
want to provide users with the option to browse and select a full DID number
from the list of available numbers. This is useful when a user wants to choose
a preferred number, such as a memorable, recognizable, or visually appealing
number, instead of ordering any available DID that matches only general
inventory criteria.
Unlike a regular DID purchase, where the order is created using only the
selected inventory criteria or sku.id, purchasing a specific DID number
requires an additional reservation step before the order is placed.
Because the selected DID number is a specific inventory item, you must first retrieve the list of available DID numbers and allow the user to select a number.
After the number is selected, you must create a DID reservation before placing the order. The reservation temporarily holds the selected number for your account so that another customer cannot purchase it while the order is being completed.
DID reservations expire after a limited time. Check the expire_at field in
the reservation response to determine when the reservation ends. If the selected
number is not purchased before the reservation expires, it is released back to inventory
and becomes available for other customers to purchase.
To buy a specific available number from DID inventory, follow these steps:
Important
The
GET /v3/available_didsfeature is not enabled by default. To enable it, contact sales@didww.com .Number selection availability may vary by country and city.
Step 1: Find the Country ID
Retrieve the unique ID for the target country using the /countries endpoint.
From the response, save the country.id for use in later steps when
retrieving cities and DID Groups.
For more information, see the /v3/countries endpoint documentation.
Use this approach when your application already knows the target country
(for example, from a stored customer selection or a predefined checkout flow).
Filter by ISO code to retrieve the matching country and its country.id.
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": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
"type": "countries",
"attributes": {
"name": "United States",
"prefix": "1",
"iso": "US"
}
}
],
"meta": {
"api_version": "2022-05-10"
}
}
Note
This example filters by country ISO code. Adjust filters as needed to match your use case.
Use this approach when building a country dropdown for end users.
This request returns countries that have DID Groups in coverage and DID numbers
available for purchase. You can sort the results by name and use each item’s
attributes.name for display and id as the selected country.id for
later steps.
filter[is_available] is a boolean filter:
When
true, returns countries with DID numbers available for purchase.When
false, returns countries that exist in coverage but currently have no DID numbers available for purchase.
http
GET /v3/countries?filter%5Bis_available%5D=true&sort=name 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%5Bis_available%5D=true&sort=name' -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": "24eb6e85-f628-4765-bbb2-420e48de76f2",
"type": "countries",
"attributes": {
"name": "Canada",
"prefix": "1",
"iso": "CA"
}
},
{
"id": "1f6fc2bd-f081-4202-9b1a-d9cb88d942b9",
"type": "countries",
"attributes": {
"name": "United States",
"prefix": "1",
"iso": "US"
}
}
],
"meta": {
"api_version": "2022-05-10"
}
}
Step 2: Find the City ID
Depending on your application flow, selecting a city may be optional or required.
If your application allows users to narrow DID availability by city (for
example, when displaying a coverage list for local numbers), you should retrieve
and store the corresponding city.id.
If your application does not differentiate availability by city (for example, when listing all cities within a country or purchasing non–city-specific DIDs), this step can be skipped.
Use the saved country.id to retrieve the city where the DID will be
purchased. From the response, save the city.id for use in later steps when
retrieving DID Groups that support number selection.
For more information, see the /v3/cities endpoint documentation.
http
GET /v3/cities?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&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=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&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": "f6672960-da2b-48a4-9f30-0065a8c54182",
"type": "cities",
"attributes": {
"name": "Los Angeles"
}
}
],
"meta": {
"total_records": 1,
"api_version": "2022-05-10"
}
}
Note
This example filters the response by a single city name. Adjust the request parameters as needed to match your use case.
Step 3: Retrieve DID Availability, Pricing, and Number Selection Status
Use the /did_groups endpoint, which is the primary source for
building DID number coverage and availability in your application.
It lets you present DID inventory for the selected location, including available DID Groups, pricing, included channel options, and whether a DID Group supports number selection.
When the DID Group returns available_dids_enabled = true, your application
can offer number selection for that DID Group and retrieve specific available
numbers in the next step..
From the GET /did_groups response, save the following values as needed:
did_group.id– Required to retrieve the list of available DID numbers in Step 4.stock_keeping_units.id– Used to display pricing options, allow the user to choose the preferred channel amount, and create the order.
For more information, see the /v3/did_groups endpoint documentation.
http
GET /v3/did_groups?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter%5Bcity.id%5D=f6672960-da2b-48a4-9f30-0065a8c54182&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=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter%5Bcity.id%5D=f6672960-da2b-48a4-9f30-0065a8c54182&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": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
"type": "did_groups",
"attributes": {
"prefix": "213",
"features": [
"voice_in"
],
"is_metered": false,
"area_name": "Los Angeles",
"allow_additional_channels": true
},
"meta": {
"available_dids_enabled": true,
"needs_registration": false,
"is_available": true,
"total_count": 2369
}
}
],
"meta": {
"total_records": 1,
"api_version": "2022-05-10"
}
}
Important
Only DID Groups with available_dids_enabled = true support retrieving
specific numbers using the /available_dids endpoint.
If the DID Group does not support this feature, use Buy a DID Number from DID Inventory.
If the DID requires verification before activation, follow Buy a DID Number that Requires Verification.
Step 4: Retrieve Available DIDs and Select a Number
Use the /available_dids endpoint to retrieve specific DID numbers that are currently available for purchase.
Call GET /v3/available_dids with include=did_group.stock_keeping_units to
retrieve available numbers together with their pricing options.
You may also filter by [filter]did_group.id to narrow the results to a specific DID
Group selected in Step 3.
From the GET /available_dids response, save the following values:
available_dids.id– Required to create a DID reservation for the selected number in Step 5.stock_keeping_units.id– Required later when creating the order for the reserved DID number.
For more information, see the /v3/available_dids endpoint documentation.
http
GET /v3/available_dids?include=did_group.stock_keeping_units&filter%5Bdid_group.id%5D=7fa8ba67-0622-4ac3-8ade-4aadf92566c5 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=7fa8ba67-0622-4ac3-8ade-4aadf92566c5' -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": "ea9884ee-887e-4c20-befb-286db7cf55da",
"type": "available_dids",
"attributes": {
"number": "12132933575"
},
"relationships": {
"did_group": {
"links": {
"self": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/relationships/did_group",
"related": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/did_group"
},
"data": {
"type": "did_groups",
"id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5"
}
},
"nanpa_prefix": {
"links": {
"self": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/relationships/nanpa_prefix",
"related": "https://api.didww.com/v3/available_dids/ea9884ee-887e-4c20-befb-286db7cf55da/nanpa_prefix"
}
}
}
}
],
"included": [
{
"id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5",
"type": "did_groups",
"attributes": {
"prefix": "213",
"features": [
"voice_in"
],
"is_metered": false,
"area_name": "Los Angeles",
"allow_additional_channels": true,
"service_restrictions": "\nTo enable SMS features on US numbers, please create an <a href=\"https://my.didww.com/#/sms_campaigns/new?activeStep=campaignDetails\" target=\"_blank\">SMS Campaign</a> after completing your order.\n"
},
"relationships": {
"country": {
"links": {
"self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/country",
"related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/country"
}
},
"city": {
"links": {
"self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/city",
"related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/city"
}
},
"did_group_type": {
"links": {
"self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/did_group_type",
"related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/did_group_type"
}
},
"region": {
"links": {
"self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/region",
"related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/region"
}
},
"stock_keeping_units": {
"links": {
"self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/stock_keeping_units",
"related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/stock_keeping_units"
},
"data": [
{
"type": "stock_keeping_units",
"id": "72f3a8a8-cd1e-41fc-8d4c-829e4fb8cdea"
},
{
"type": "stock_keeping_units",
"id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393"
}
]
},
"requirement": {
"links": {
"self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/requirement",
"related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/requirement"
}
}
},
"meta": {
"available_dids_enabled": true,
"needs_registration": false,
"is_available": true,
"total_count": 2371
}
},
{
"id": "72f3a8a8-cd1e-41fc-8d4c-829e4fb8cdea",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "0.0",
"monthly_price": "0.09",
"channels_included_count": 0
}
},
{
"id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393",
"type": "stock_keeping_units",
"attributes": {
"setup_price": "4.0",
"monthly_price": "4.0",
"channels_included_count": 2
}
}
],
"meta": {
"total_count": 2368,
"api_version": "2022-05-10"
}
}
Step 5: Create a DID Reservation
Reserve the selected number before creating the order. This temporarily locks the DID for your account and prevents other users from purchasing it while the order is being created.
Create the reservation using the available_dids.id value obtained in the
previous step.
The reservation remains active until the time shown in expire_at. If you
need to extend the reservation, resend the POST /v3/did_reservations
request for the same available DID before the reservation expires.
From the response, save the did_reservations.id and check expire_at to
see when the reservation expires.
For more information, see Create DID Reservation.
http
POST /v3/did_reservations HTTP/1.1
Host: api.didww.com
Api-Key: [API token]
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "did_reservations",
"attributes": {
"description": "Reserved for customer"
},
"relationships": {
"available_did": {
"data": {
"type": "available_dids",
"id": "4048d28a-6cab-46c9-98e9-d69d2466c131"
}
}
}
}
}
curl
curl -i -X POST https://api.didww.com/v3/did_reservations -H "Accept: application/vnd.api+json" -H "Api-Key: [API token]" -H "Content-Type: application/vnd.api+json" --data-raw '{"data": {"attributes": {"description": "Reserved for customer"}, "relationships": {"available_did": {"data": {"id": "4048d28a-6cab-46c9-98e9-d69d2466c131", "type": "available_dids"}}}, "type": "did_reservations"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6",
"type": "did_reservations",
"attributes": {
"expire_at": "2026-03-19T11:38:15.074Z",
"created_at": "2026-03-19T11:37:15.079Z",
"description": "Reserved for customer"
},
"relationships": {
"available_did": {
"data": {
"type": "available_dids",
"id": "4048d28a-6cab-46c9-98e9-d69d2466c131"
}
}
}
}
}
Step 6: Create the Order
Create the order using the selected stock_keeping_units.id and the saved
did_reservations.id.
This ensures the order is created for the exact reserved DID number selected in the previous steps.
For more information, see the /v3/orders endpoint documentation.
Note
A positive prepaid balance is required to successfully create the order.
For simplicity, detailed item attributes are not included in this response example.
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": false,
"items": [
{
"type": "did_order_items",
"attributes": {
"sku_id": "7a2d041e-0f08-4f61-a59b-f2eca3af23f9",
"did_reservation_id": "af7677ea-819c-4fc0-b0a6-588be5d434b2"
}
}
]
}
}
}
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": false, "items": [{"type": "did_order_items", "attributes": {"sku_id": "7a2d041e-0f08-4f61-a59b-f2eca3af23f9", "did_reservation_id": "af7677ea-819c-4fc0-b0a6-588be5d434b2"}}]}, "type": "orders"}}'
response
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "0f2dd6a8-7539-444a-b7c1-e89b3fe7d170",
"type": "orders",
"attributes": {
"amount": "8.0",
"status": "Pending",
"created_at": "2026-03-19T12:08:23.567Z",
"description": "DID",
"reference": "ZME-571778",
"items": [
{
"type": "did_order_items",
"attributes": {
"qty": 1,
"nrc": "4.0",
"mrc": "4.0",
"prorated_mrc": false,
"billed_from": null,
"billed_to": null,
"setup_price": "4.0",
"monthly_price": "4.0",
"did_group_id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5"
}
}
],
"callback_method": null,
"callback_url": null
}
},
"meta": {
"api_version": "2022-05-10"
}
}