# 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 `expires_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: - [Step 1: Find the Country ID](#user-panel-api-examples-available-dids-step1) - [Step 2: Find the City ID](#user-panel-api-examples-available-dids-step2) - [Step 3: Retrieve DID Availability, Pricing, and Number Selection Status](#user-panel-api-examples-available-dids-step3) - [Step 4: Retrieve Available DIDs and Select a Number](#user-panel-api-examples-available-dids-step4) - [Step 5: Create a DID Reservation](#user-panel-api-examples-available-dids-step5) - [Step 6: Create the Order](#user-panel-api-examples-available-dids-step6) Important - The `GET /v3/available_dids` feature is not enabled by default. To enable it, contact [sales@didww.com](mailto:sales%40didww.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](../2026-04-16/coverage-resources/countries/get-countries.html#countries-v34-get-countries) endpoint documentation. *Find a country by ISO code* 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`. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] Note This example filters by country ISO code. Adjust filters as needed to match your use case. *List countries available for purchase* 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. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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](../2026-04-16/coverage-resources/city/get-cities.html#cities-v34-get-cities) endpoint documentation. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] 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](#user-panel-api-examples-available-dids-step4).. 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](#user-panel-api-examples-available-dids-step4). - `stock_keeping_units.id` - Used to display pricing options, allow the user to choose the preferred channel amount, and [create the order](#user-panel-api-examples-available-dids-step6). For more information, see the [/v3/did\_groups](../2026-04-16/coverage-resources/did-group/get-did-groups.html#did-groups-v34-get-did-groups) endpoint documentation. [[DIDWW-API-EXAMPLE-START]] 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": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] 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](buy-dids.html#user-panel-api-examples-did-group). - If the DID requires **verification** before activation, follow [Buy a DID Number that Requires Verification](buy-dids-with-verification.html#user-panel-api-examples-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](#user-panel-api-examples-available-dids-step3). 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](#user-panel-api-examples-available-dids-step5). - `stock_keeping_units.id` - Required later when creating the order for the reserved DID number. For more information, see the [/v3/available\_dids](../2026-04-16/coverage-resources/available-did/get-available-dids.html#available-dids-v34-get-available-dids) endpoint documentation. [[DIDWW-API-EXAMPLE-START]] 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 SMS Campaign 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" } ] }, "address_requirement": { "links": { "self": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/relationships/address_requirement", "related": "https://api.didww.com/v3/did_groups/7fa8ba67-0622-4ac3-8ade-4aadf92566c5/address_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": { "channels_included_count": 0 } }, { "id": "0c6a151e-15e9-495e-b0b4-a5af4c8be393", "type": "stock_keeping_units", "attributes": { "channels_included_count": 2 } } ], "meta": { "total_count": 2368, "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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 `expires_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 `expires_at` to see when the reservation expires. For more information, see [Create DID Reservation](../2026-04-16/coverage-resources/did-reservation/create-did-reservation.html). [[DIDWW-API-EXAMPLE-START]] 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": { "expires_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" } } } } } ``` [[DIDWW-API-EXAMPLE-END]] --- ## 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](../2026-04-16/inventory-resources/order/create-order.html#orders-v34-create-order) 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. [[DIDWW-API-EXAMPLE-START]] 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, "did_group_id": "7fa8ba67-0622-4ac3-8ade-4aadf92566c5" } } ], "callback_method": null, "callback_url": null } }, "meta": { "api_version": "2026-04-16" } } ``` [[DIDWW-API-EXAMPLE-END]] On this page