Get DID Groups#

Returns a list of DID Groups, which is essentially a list of the current DIDWW coverage. DID Groups are phone numbers that share a common city or area code.

Request#

HTTP Method: GET

URI Path: /v3/did_groups

Note

For all returned data attributes, see Did Group Object.

URI Query Parameters#

Name

Type

Is Required?

Description

include

string

No

Inclusion

filter[<filter_name>]

string, boolean, Integer

No

Filtering

fields[did_groups]

string

No

Sparse fieldsets

sort

string

No

Sorting

page[number]

integer

No

Page number.

page[size]

integer

No

Page size. Pagination defaults to 50 records per page. The maximum is 100.

Includes#

Value

Description

country

Country Object

region

Region Object

city

City Object

stock_keeping_units

A list of Stock Keeping Unit Objects

address_requirement

Address Requirement Object

Filters#

Filter Name

Type

Allow Blank

Allow Array

Filters by:

id

string

No

Yes

Group id field.

prefix

string

Yes

Yes

The group prefix field.

nanpa_prefix.id

string

No

No

The nanpa prefix id field.

nanpa_prefix.npanxx

string

No

No

The nanpa prefix npa / nxx fields. Takes exactly one six-digit NPA-NXX value (for example 201221).

area_name

string

Yes

Yes

The area_name field (for example London). Case insensitive.

is_metered

boolean

No

No

The is_metered field.

allow_additional_channels

boolean

No

No

The allow_additional_channels field.

available_dids_enabled

boolean

No

No

The available_dids_enabled field.

features

string

No

Yes

The features field. Can be one or several of voice_in, voice_out, t38, sms_in, p2p, a2p, emergency, and cnam_out. Example: voice_in,emergency.

needs_registration

boolean

No

No

The needs_registration field.

is_available

boolean

No

No

The is_available field.

country.id

string

Yes

Yes

The country.id field.

region.id

string

Yes

Yes

The region.id field.

city.id

string

Yes

Yes

The city.id field.

number_type

string

No

Yes

The number_type field. Can be one or several of local, national, mobile, toll_free, shared_cost, and global. A DID Group matches when its number type is any of the listed values. Example: local,mobile.

is_demo

boolean

No

No

The is_demo field.

meta.total_count_gteq

Integer

Yes

No

A filter on the list based on the meta.total_count_gteq field, where gteq stands for greater-equal.

Sorting#

Value

Sorts by:

country.name

The country.name field.

number_type

The number_type field.

prefix

City prefix field.

is_metered

The is_metered field.

area_name

The area_name field.

allow_additional_channels

The allow_additional_channels field.

is_demo

The is_demo field.

service_restrictions

The service_restrictions field.

Note

In version 2026-11-19, the number type of a DID Group is returned in the number_type attribute. The did_group_type include, the did_group_type.id filter, the did_group_type.name sort, and did_group_type in fields[did_groups] are not accepted and return 400 Bad Request. A number_type filter value outside the listed values also returns 400 Bad Request.

Examples#

http

1GET /v3/did_groups HTTP/1.1
2Host: api.didww.com
3Content-Type: application/vnd.api+json
4Accept: application/vnd.api+json
5Authorization: Bearer [access token]

curl

1curl -i -X GET https://api.didww.com/v3/did_groups -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]"

response

 1HTTP/1.1 200 OK
 2Content-Type: application/vnd.api+json
 3
 4{
 5    "data": [{
 6        "id": "ac160b14-e670-490f-b158-d3ba552c623f",
 7        "type": "did_groups",
 8        "attributes": {
 9            "prefix": "241",
10            "features": [
11                "voice_in",
12                "voice_out",
13                "t38"
14            ],
15            "is_metered": false,
16            "area_name": "Aachen",
17            "allow_additional_channels": true,
18            "service_restrictions": null,
19            "number_type": "local",
20            "is_demo": false
21        },
22        "relationships": {
23            "country": {
24                "links": {
25                    "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/country",
26                    "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/country"
27                }
28            },
29            "city": {
30                "links": {
31                    "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/city",
32                    "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/city"
33                }
34            },
35            "region": {
36                "links": {
37                    "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/region",
38                    "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/region"
39                }
40            },
41            "stock_keeping_units": {
42                "links": {
43                    "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/stock_keeping_units",
44                    "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/stock_keeping_units"
45                }
46            },
47            "address_requirement": {
48                "links": {
49                    "self": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/relationships/address_requirement",
50                    "related": "https://api.didww.com/v3/did_groups/ac160b14-e670-490f-b158-d3ba552c623f/address_requirement"
51                }
52            }
53        },
54        "meta": {
55            "available_dids_enabled": false,
56            "needs_registration": true,
57            "is_available": true,
58            "total_count": 21
59        }
60
61    }],
62    "meta": {
63        "total_records": 1,
64        "api_version": "2026-11-19"
65    },
66    "links": {
67        "first": "https://api.didww.com/v3/did_groups?page%5Bnumber%5D=1&page%5Bsize%5D=50",
68        "last": "https://api.didww.com/v3/did_groups?page%5Bnumber%5D=32&page%5Bsize%5D=50"
69    }
70}

Other Responses#

Code

Success

Description

400

No

Bad Request

401

No

Unauthorized

429

No

The request budget of the account for the current window is spent (too_many_requests). Retry-After gives the number of seconds to wait.