Get DIDs#

Returns a list of DIDs owned by your account.

Request#

HTTP Method: GET

URI Path: /v3/dids

Note

For all returned data attributes, see Did Object.

URI Query Parameters#

Name

Type

Is Required?

Description

include

string

No

Inclusion

filter[<filter_name>]

string, boolean

No

Filtering

fields[dids]

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

order

Order Object

voice_in_trunk

Trunk Object

voice_in_trunk.voice_in_trunk_group

Trunk Group Object

voice_in_trunk_group

Trunk Group Object

sms_trunk

SMS Trunk Object

sms_trunk_group

SMS Trunk Group Object

capacity_pool

Capacity Pool Object

shared_capacity_group

Shared Capacity Group Object

did_group

DID Group Object

identity

Identity Object

emergency_calling_service

Emergency Calling Service Object

emergency_verification

Emergency Verification Object

address_verification

Address Verifications Object

did_group.country

Country Object

did_group.city

City Object

did_group.region

Region Object

did_group.stock_keeping_units

Stock Keeping Unit Object

Filters#

Filter Name

Type

Allow Blank

Allow Array

Filters by:

id

string

No

Yes

The DID id field.

number

string

No

Yes

The DID number field.

description

string

Yes

No

DIDs whose description field contains this value.

terminated

boolean

No

No

The terminated field.

awaiting_registration

boolean

No

No

The awaiting_registration field.

blocked

boolean

No

No

The blocked field.

billing_cycles_count

string

Yes

Yes

The billing_cycles_count field.

did_group.id

string

No

Yes

The ID field of did_group relationship.

country.id

string

Yes

Yes

The ID field of country relationship.

region.id

string

No

Yes

The ID field of region relationship.

city.id

string

No

Yes

The ID field of city relationship.

order.id

string

No

Yes

The ID field of order relationship.

voice_in_trunk.id

string

No

Yes

The ID field of voice_in_trunk relationship.

trunk.id

string

No

Yes

Legacy alias of voice_in_trunk.id.

voice_in_trunk_group.id

string

No

Yes

The ID field of voice_in_trunk_group relationship.

trunk_group.id

string

No

Yes

Legacy alias of voice_in_trunk_group.id.

sms_trunk.id

string

No

Yes

The ID field of sms_trunk relationship.

sms_trunk_group.id

string

No

Yes

The ID field of sms_trunk_group relationship.

shared_capacity_group.id

string

No

Yes

The ID field of shared_capacity_group relationship.

capacity_pool.id

string

No

Yes

The ID field of capacity_pool relationship.

order.reference

string

No

Yes

The reference field of order relationship.

did_group.features

string

No

Yes

DID Group 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.

address_verification.id

string

No

Yes

The ID field of address_verification relationship.

emergency_enabled

boolean

No

No

Filters by the emergency_enabled field. Returns DIDs that have emergency calling enabled when true, or disabled when false.

emergency_calling_service.id

string

No

Yes

The ID field of emergency_calling_service relationship.

Sorting#

Value

Sorts by:

blocked

Blocked status

awaiting_registration

Awaiting registration status

terminated

Termination status

capacity_limit

Capacity limit

billing_cycles_count

Billing cycles count

description

Description text

number

DID number

expires_at

Expiration timestamp

channels_included_count

Included channels count

dedicated_channels_count

Dedicated channels count

created_at

Creation timestamp

Examples#

http

1GET /v3/dids 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/dids -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      {
  7        "id": "ac40fb08-ac14-4a6c-8f20-fe650870c266",
  8        "type": "dids",
  9        "attributes": {
 10          "blocked": false,
 11          "capacity_limit": 1,
 12          "description": "string",
 13          "terminated": false,
 14          "awaiting_registration": false,
 15          "number": "437xxxxxxxxx",
 16          "expires_at": "2017-06-25T08:21:41.795Z",
 17          "channels_included_count": 2,
 18          "created_at": "2017-06-25T08:21:41.795Z",
 19          "dedicated_channels_count": 0,
 20          "billing_cycles_count": null,
 21          "emergency_enabled": false
 22        },
 23        "relationships": {
 24          "did_group": {
 25            "links": {
 26              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/did_group",
 27              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/did_group"
 28            }
 29          },
 30          "order": {
 31            "links": {
 32              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/order",
 33              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/order"
 34            }
 35          },
 36          "voice_in_trunk": {
 37            "links": {
 38              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk",
 39              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk"
 40            }
 41          },
 42          "voice_in_trunk_group": {
 43            "links": {
 44              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/voice_in_trunk_group",
 45              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/voice_in_trunk_group"
 46            }
 47          },
 48          "capacity_pool": {
 49            "links": {
 50              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/capacity_pool",
 51              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/capacity_pool"
 52            }
 53          },
 54          "shared_capacity_group": {
 55            "links": {
 56              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/shared_capacity_group",
 57              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/shared_capacity_group"
 58            }
 59          },
 60          "sms_trunk": {
 61            "links": {
 62              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/sms_trunk",
 63              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/sms_trunk"
 64            }
 65          },
 66          "sms_trunk_group": {
 67            "links": {
 68              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/sms_trunk_group",
 69              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/sms_trunk_group"
 70            }
 71          },
 72          "address_verification": {
 73            "links": {
 74              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/address_verification",
 75              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/address_verification"
 76            }
 77          },
 78          "emergency_calling_service": {
 79            "links": {
 80              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/emergency_calling_service",
 81              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/emergency_calling_service"
 82            }
 83          },
 84          "emergency_verification": {
 85            "links": {
 86              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/emergency_verification",
 87              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/emergency_verification"
 88            }
 89          },
 90          "identity": {
 91            "links": {
 92              "self": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/relationships/identity",
 93              "related": "https://api.didww.com/v3/dids/ac40fb08-ac14-4a6c-8f20-fe650870c266/identity"
 94            }
 95          }
 96        }
 97      },
 98      {
 99        "id": "b37f0fcf-24d0-4799-8e81-a69bcc889f2e",
100        "type": "dids",
101        "attributes": {
102          "blocked": false,
103          "capacity_limit": 1,
104          "description": "string",
105          "terminated": false,
106          "awaiting_registration": false,
107          "number": "437xxxxxxxxx",
108          "expires_at": "2017-06-25T08:21:41.795Z",
109          "channels_included_count": 2,
110          "created_at": "2017-06-25T08:21:41.795Z",
111          "dedicated_channels_count": 0,
112          "billing_cycles_count": null,
113          "emergency_enabled": false
114        },
115        "relationships": {
116          "did_group": {
117            "links": {
118              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/did_group",
119              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/did_group"
120            }
121          },
122          "order": {
123            "links": {
124              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/order",
125              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/order"
126            }
127          },
128          "voice_in_trunk": {
129            "links": {
130              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/voice_in_trunk",
131              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/voice_in_trunk"
132            }
133          },
134          "voice_in_trunk_group": {
135            "links": {
136              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/voice_in_trunk_group",
137              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/voice_in_trunk_group"
138            }
139          },
140          "capacity_pool": {
141            "links": {
142              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/capacity_pool",
143              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/capacity_pool"
144            }
145          },
146          "shared_capacity_group": {
147            "links": {
148              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/shared_capacity_group",
149              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/shared_capacity_group"
150            }
151          },
152          "sms_trunk": {
153            "links": {
154              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/sms_trunk",
155              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/sms_trunk"
156            }
157          },
158          "sms_trunk_group": {
159            "links": {
160              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/sms_trunk_group",
161              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/sms_trunk_group"
162            }
163          },
164          "address_verification": {
165            "links": {
166              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/address_verification",
167              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/address_verification"
168            }
169          },
170          "emergency_calling_service": {
171            "links": {
172              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/emergency_calling_service",
173              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/emergency_calling_service"
174            }
175          },
176          "emergency_verification": {
177            "links": {
178              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/emergency_verification",
179              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/emergency_verification"
180            }
181          },
182          "identity": {
183            "links": {
184              "self": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/relationships/identity",
185              "related": "https://api.didww.com/v3/dids/b37f0fcf-24d0-4799-8e81-a69bcc889f2e/identity"
186            }
187          }
188        }
189      }
190    ],
191    "meta": {
192      "total_records": 2,
193      "api_version": "2026-11-19"
194    },
195    "links": {
196      "first": "https://api.didww.com/v3/dids?page%5Bnumber%5D=1&page%5Bsize%5D=50",
197      "last": "https://api.didww.com/v3/dids?page%5Bnumber%5D=1&page%5Bsize%5D=50"
198    }
199  }

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.