Buy Available DID Number(s)

This example shows the end-to-end process for purchasing a DID number from DID inventory.

This flow allows the platform to assign an available DID number from the inventory that matches the selected criteria.

To buy a DID number from DID inventory, follow these steps:

• Step 1: Find the Country

• Step 2: Show Inventory Filters for the Selected Country

• Step 3: Retrieve DID Availability, Pricing, and Coverage

• Step 4: Create the Order

Note

The UUIDs shown in the examples below are for illustration purposes only.

Always execute requests in your own environment and use the UUIDs returned in API responses.

---

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, regions, NANPA prefixes, and DID Groups.

For more information, see the /v3/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.

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.

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.

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: Show Inventory Filters for the Selected Country

After the user selects a country and your application saves the country.id, the next step is to help the user narrow the available DID inventory.

At this stage, your site should display the filters that are supported for the selected country. The available filters depend on the numbering rules and inventory structure for that country.

Available filtering options for this flow include:

• DID Group Types filters DID inventory by number category, such as Local, Mobile, National, or Toll-free.

• Cities filters DID inventory by city within the selected country.

• Regions filters DID inventory by region within the United States, Canada, and the United Kingdom.

• NANPA Prefixes (NPA/NXX) filters Local DID inventory in the United States and Canada by area code and central office code.

Note

Use the filtering method that matches the selected country and your search experience.

Building the Filtering Experience Example

Guide the user through the filtering flow:

1. The user selects a country from the country list.

2. Your application saves the selected country.id.

3. Your site displays the inventory filters available for that country.

4. The user chooses a filter option and selects a value.

5. Your application saves the returned resource ID, such as city.id, or nanpa_prefix.id.

6. Use the saved ID in the next step to retrieve DID Inventory using GET /v3/did_groups.

For example:

• If the user selects United States or Canada, your site can also allow the user to select a region and then choose NPA/NXX prefix.

• To display NPA/NXX options for the United States, the customer should first select a state. After that, your application can retrieve and display the list of available NANPA prefixes for that state.

Note

Do not show all possible filters unconditionally. Instead, show or enable only the filters that are relevant to the selected country and to the search flow supported by your application.

Filtering Examples

Search by City

Use this filter when your application allows the user to narrow DID availability by city.

Before you can filter DID inventory by city in the next step, you must first retrieve the corresponding city.id using the /cities endpoint.

To narrow the results, use the saved country.id together with the city name entered or selected by the user.

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=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/cities?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&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": "368bf92f-c36e-473f-96fc-d53ed1b4028b",
            "type": "cities",
            "attributes": {
                "name": "New York"
            }
        }
    ]
}

Search by NANPA Prefix (NPA/NXX)

Use this filter when your application allows the user to narrow DID inventory by NPA/NXX.

This filtering option is available only for United States and Canada, because these countries use the North American Numbering Plan (NANP).

Before you can filter DID inventory by NANPA prefix in the next step, you must first retrieve the corresponding nanpa_prefix.id. To do this, first retrieve the selected state or province using the /regions endpoint, and save the returned region.id.

Then use the saved country.id together with region.id to retrieve available NANPA prefixes by using the /nanpa_prefixes endpoint.

From the response, save the returned nanpa_prefix.id. You will use this value in the next step to filter DID Groups by NANPA prefix.

The flow is:

1. Save the selected country.id.

2. Retrieve the selected state or province and save region.id.

3. Retrieve NANPA prefixes using country.id and region.id.

4. Save the selected nanpa_prefix.id for the next step.

1. Retrieve the State or Province

First, use the saved country.id to retrieve the state or province selected by the user.

For more information, see the /v3/regions endpoint documentation.

http

GET /v3/regions?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&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=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&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": "ab7e83bc-814b-4cfa-a14c-d2df3de2a545",
            "type": "regions",
            "attributes": {
                "name": "New York",
                "iso": "US-NY"
            }
        }
    ],
    "meta": {
        "api_version": "2022-05-10"
    }
}

2. Retrieve NPA/NXX Values for the Selected Region

Next, use the saved country.id and region.id to retrieve the available NANPA prefixes for that state or province.

Your application can then display the returned npa and nxx values in a dropdown or searchable list so the user can select the required code.

Save the selected nanpa_prefix.id for use in the next step when retrieving DID Inventory using GET /did_groups.

For more information, see the /v3/nanpa_prefixes endpoint documentation.

http

GET /v3/nanpa_prefixes?filter%5Bcountry.id%5D=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter%5Bregion.id%5D=ab7e83bc-814b-4cfa-a14c-d2df3de2a545 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=1f6fc2bd-f081-4202-9b1a-d9cb88d942b9&filter%5Bregion.id%5D=ab7e83bc-814b-4cfa-a14c-d2df3de2a545' -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": "48b91ed5-13db-4920-a4cb-d0260d692053",
            "type": "nanpa_prefixes",
            "attributes": {
                "npa": "212",
                "nxx": "111"
            }
        }
    ],
    "meta": {
        "api_version": "2022-05-10"
    }
}

---

Step 3: Retrieve DID Availability, Pricing, and Number Selection Availability

Use the /did_groups endpoint to retrieve the DID number inventory groups that match the selected inventory criteria.

This endpoint is the primary source for building DID number coverage and availability in your application. It allows you to present users with:

• available DID number types, such as Local, Mobile, National, and Toll-free

• supported prefixes and geographic areas

• available features, such as voice and SMS

• pricing options and included channel configurations

• whether registration is required before activation

Include stock_keeping_units in the request to retrieve SKU pricing and included channel configurations for each DID Group.

From the GET /did_groups response, save the stock_keeping_units.id that will be used to create the order in the next step.

For more information, see the /v3/did_groups endpoint documentation.

Filter by City

Use this approach when the inventory was located using city.id in Step 2.

Then apply filter[city.id] to retrieve DID Groups available in the selected city.

http

GET /v3/did_groups?include=stock_keeping_units&filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b 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=368bf92f-c36e-473f-96fc-d53ed1b4028b' -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": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9",
      "type": "did_groups",
      "attributes": {
        "prefix": "212",
        "features": [
          "voice_in"
        ],
        "is_metered": false,
        "area_name": "New York",
        "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/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/country",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/country"
          }
        },
        "city": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/city",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/city"
          }
        },
        "did_group_type": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/did_group_type",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/did_group_type"
          }
        },
        "region": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/region",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/region"
          }
        },
        "stock_keeping_units": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/stock_keeping_units",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/stock_keeping_units"
          },
          "data": [
            {
              "type": "stock_keeping_units",
              "id": "a7ecfee0-693e-459c-8eff-244121847ac2"
            },
            {
              "type": "stock_keeping_units",
              "id": "e2406add-fd8a-475c-b959-81e9619d7a4b"
            }
          ]
        },
        "requirement": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/requirement",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/requirement"
          }
        }
      },
      "meta": {
        "available_dids_enabled": true,
        "needs_registration": false,
        "is_available": true,
        "total_count": 620
      }
    }
  ],
  "included": [
    {
      "id": "a7ecfee0-693e-459c-8eff-244121847ac2",
      "type": "stock_keeping_units",
      "attributes": {
        "setup_price": "4.0",
        "monthly_price": "4.00",
        "channels_included_count": 0
      }
    },
    {
      "id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
      "type": "stock_keeping_units",
      "attributes": {
        "setup_price": "4.0",
        "monthly_price": "4.0",
        "channels_included_count": 2
      }
    }
  ],
  "meta": {
    "total_records": 1,
    "api_version": "2022-05-10"
  },
  "links": {
    "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
    "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
  }
}

Filter by NANPA Prefix

Use this approach when the inventory was located using nanpa_prefix.id in Step 2.

Then apply filter[nanpa_prefix.id] to retrieve DID Groups that match the selected NANPA prefix.

http

GET /v3/did_groups?include=stock_keeping_units&filter%5Bnanpa_prefix.id%5D=48b91ed5-13db-4920-a4cb-d0260d692053 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=48b91ed5-13db-4920-a4cb-d0260d692053' -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": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9",
      "type": "did_groups",
      "attributes": {
        "prefix": "212",
        "features": [
          "voice_in"
        ],
        "is_metered": false,
        "area_name": "New York",
        "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/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/country",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/country"
          }
        },
        "city": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/city",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/city"
          }
        },
        "did_group_type": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/did_group_type",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/did_group_type"
          }
        },
        "region": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/region",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/region"
          }
        },
        "stock_keeping_units": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/stock_keeping_units",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/stock_keeping_units"
          },
          "data": [
            {
              "type": "stock_keeping_units",
              "id": "a7ecfee0-693e-459c-8eff-244121847ac2"
            },
            {
              "type": "stock_keeping_units",
              "id": "e2406add-fd8a-475c-b959-81e9619d7a4b"
            }
          ]
        },
        "requirement": {
          "links": {
            "self": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/relationships/requirement",
            "related": "https://api.didww.com/v3/did_groups/ef7c258f-19b9-478b-ab68-d6b30d00c9f9/requirement"
          }
        }
      },
      "meta": {
        "available_dids_enabled": true,
        "needs_registration": false,
        "is_available": true,
        "total_count": 620
      }
    }
  ],
  "included": [
    {
      "id": "a7ecfee0-693e-459c-8eff-244121847ac2",
      "type": "stock_keeping_units",
      "attributes": {
        "setup_price": "4.0",
        "monthly_price": "4.00",
        "channels_included_count": 0
      }
    },
    {
      "id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
      "type": "stock_keeping_units",
      "attributes": {
        "setup_price": "4.0",
        "monthly_price": "4.0",
        "channels_included_count": 2
      }
    }
  ],
  "meta": {
    "total_records": 1,
    "api_version": "2022-05-10"
  },
  "links": {
    "first": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50",
    "last": "https://api.didww.com/v3/did_groups?filter%5Bcity.id%5D=368bf92f-c36e-473f-96fc-d53ed1b4028b&include=stock_keeping_units&page%5Bnumber%5D=1&page%5Bsize%5D=50"
  }
}

---

Step 4: Create the DID Order

Create the order using the selected stock_keeping_units.id retrieved in the previous step.

This ensures the order is created for a DID number that matches the selected inventory criteria from 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.

Buy Numbers from Inventory

In Step 3, the inventory was identified using the selected sku.id.

Use the selected sku.id to create an order for an available DID number from the matching inventory.

In this example, we purchase a number with 2 included channels.

For more information, see 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": "e2406add-fd8a-475c-b959-81e9619d7a4b",
            "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": "e2406add-fd8a-475c-b959-81e9619d7a4b", "qty": 1}}]}, "type": "orders"}}'

response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
   "data": {
       "id": "eb23b1a4-f4fd-4960-9f46-750ec920cde8",
       "type": "orders",
       "attributes": {
           "amount": "8.0",
           "status": "Pending",
           "created_at": "2026-03-18T11:41:20.443Z",
           "description": "DID",
           "reference": "RNQ-961086",
           "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": "ef7c258f-19b9-478b-ab68-d6b30d00c9f9"
                   }
               }
           ],
           "callback_method": null,
           "callback_url": null
       }
   },
   "meta": {
       "api_version": "2022-05-10"
   }
}

Buy Numbers with Selected NANPA Prefix

In Step 3, the inventory was identified using the selected nanpa_prefix.id together with sku.id.

Use the selected nanpa_prefix.id together with sku.id to create an order for an available DID number that matches the selected NANPA prefix.

In this example, we purchase a number with 2 included channels.

For more information, see 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": false,
      "items": [
        {
          "type": "did_order_items",
          "attributes": {
            "nanpa_prefix_id": "48b91ed5-13db-4920-a4cb-d0260d692053",
            "sku_id": "e2406add-fd8a-475c-b959-81e9619d7a4b",
            "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": false, "items": [{"type": "did_order_items", "attributes": {"nanpa_prefix_id": "48b91ed5-13db-4920-a4cb-d0260d692053", "sku_id": "e2406add-fd8a-475c-b959-81e9619d7a4b", "qty": 1}}]}, "type": "orders"}}'

response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
   "data": {
       "id": "372cc3c7-49a2-41ef-be64-85b7b297e4e3",
       "type": "orders",
       "attributes": {
           "amount": "0.09",
           "status": "Pending",
           "created_at": "2026-03-18T12:06:49.115Z",
           "description": "DID",
           "reference": "PJB-535885",
           "items": [
               {
                   "type": "did_order_items",
                   "attributes": {
                       "qty": 1,
                       "nrc": "0.0",
                       "mrc": "0.09",
                       "prorated_mrc": false,
                       "billed_from": null,
                       "billed_to": null,
                       "setup_price": "0.0",
                       "monthly_price": "0.09",
                       "did_group_id": "7f3a4f3f-8aba-4447-9cb5-66a4e8e4f6ff"
                   }
               }
           ],
           "callback_method": null,
           "callback_url": null
       }
   },
   "meta": {
       "api_version": "2022-05-10"
   }
}