Buy a Random Number from a Specific DID Group

To buy a random number, follow these steps:

Get the country and city IDs.

Retrieve the appropriate DID Group and SKU IDs.

Place the order using the selected SKU IDs.

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 a two-letter ISO code. For full details, see the /v3/countries endpoint documentation.

http

GET /v3/countries?filter%5Biso%5D=GB 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=GB' -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": "c8647639-fc9c-47b2-acec-7c9e14465c25",
            "type": "countries",
            "attributes": {
                "name": "United Kingdom",
                "iso": "GB"
            }
        }
    ]
}

From this response, save the country.id.

Step 2: Find the City ID

Use the country.id from Step 1 to get the city ID where you want to buy the number. See the /v3/cities endpoint documentation for more details.

http

GET /v3/cities?filter%5Bcountry.id%5D=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bname%5D=London 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=c8647639-fc9c-47b2-acec-7c9e14465c25&filter%5Bname%5D=London' -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": "e696dec7-9c65-4e99-aab7-55a1f98154f0",
            "type": "cities",
            "attributes": {
                "name": "London"
            }
        }
    ]
}

From this response, save the city.id.

Step 3: Find the DID Group and SKU ID

With the city.id, query the /did_groups endpoint and include stock_keeping_units to find available DIDs and their pricing. See the /v3/did_groups endpoint documentation for more information.

http

GET /v3/did_groups?include=stock_keeping_units&filter%5Bcity.id%5D=e696dec7-9c65-4e99-aab7-55a1f98154f0 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=e696dec7-9c65-4e99-aab7-55a1f98154f0' -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": "fc271bcc-1f9c-4c19-8174-28b7c55a208a",
            "type": "did_groups",
            "attributes": {
                "area_name": "London"
            },
            "relationships": {
                "stock_keeping_units": {
                    "data": [
                        { "type": "stock_keeping_units", "id": "d7b28c79-b505-4995-9b78-d73b016b277d" },
                        { "type": "stock_keeping_units", "id": "74d2af35-0cab-4ad8-aca7-5800baa1daa3" }
                    ]
                }
            }
        }
    ],
    "included": [
        {
            "id": "d7b28c79-b505-4995-9b78-d73b016b277d",
            "type": "stock_keeping_units",
            "attributes": {
                "setup_price": "0.0",
                "monthly_price": "1.2",
                "channels_included_count": 0
            }
        },
        {
            "id": "74d2af35-0cab-4ad8-aca7-5800baa1daa3",
            "type": "stock_keeping_units",
            "attributes": {
                "setup_price": "0.0",
                "monthly_price": "10.0",
                "channels_included_count": 2
            }
        }
    ]
}

From the response, select the sku.id from the included section based on your needs.

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 Capacity.

Step 4: Create the Order

Use the selected sku.id to create the order. In this example, we’ll purchase a number with 2 included channels. Refer to the /v3/orders endpoint documentation for 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": "74d2af35-0cab-4ad8-aca7-5800baa1daa3",
            "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": "74d2af35-0cab-4ad8-aca7-5800baa1daa3", "qty": 1}}]}, "type": "orders"}}'

response

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

{
    "data": {
        "id": "df0f0bc2-5607-4370-8c05-add19974cfbb",
        "type": "orders",
        "attributes": {
            "amount": "12.1",
            "status": "Completed",
            "created_at": "2025-07-07T11:44:51.542Z",
            "description": "1 x United Kingdom - Local - London",
            "reference": "XFX-924453"
        },
        "relationships": {
            "order_items": {
                "data": [
                    {
                        "type": "order_items",
                        "id": "2de14280-92a1-464a-8108-1e43d735af2a"
                    }
                ]
            }
        }
    }
}