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"
}
]
}
}
}
}