DIDs

Use the DIDs resource to retrieve and manage DID phone numbers owned by your DIDWW account.

A DID represents a purchased phone number and provides its service status, description, renewal settings, capacity configuration, and expiration information. It also links to related order, coverage, inbound routing, capacity, registration, identity, and Emergency Calling resources.

DIDs are commonly managed after an Order is completed. Use this resource to find owned phone numbers, inspect their configuration and relationships, update renewal or capacity settings, and cancel, restore, or renew a DID.

Endpoints

Action	Method	Endpoint
Retrieve all DIDs	GET	/v3/dids
Retrieve DID	GET	/v3/dids/{id}
Update DID	PATCH	/v3/dids/{id}

Retrieve all DIDs

Retrieves all DID phone numbers owned by the account.

Use this endpoint to filter DIDs by phone number, description, lifecycle status, renewal settings, coverage, Order, inbound routing, capacity, registration, or Emergency Calling configuration. Related resources can be included in the response.

See Retrieve All DIDs.

GET /v3/dids

Retrieve DID

Retrieves a specific DID by its unique ID.

Use this endpoint to inspect the DID’s status, phone number, description, expiration and renewal settings, capacity configuration, and related resources.

See Retrieve DID.

GET /v3/dids/{id}

Update DID

Updates the settings of a specific DID.

Use this endpoint to update the DID description, renewal cycles, dedicated channel count, or incoming capacity limit. Set terminated to true to cancel the DID at the end of the billing cycle, or set it to false to renew or restore the DID.

See Update DID.

PATCH /v3/dids/{id}

Common DID use cases

Use case	Description
List owned DID numbers	Retrieve the DID phone numbers currently associated with the account.
Search and filter DIDs	Find DIDs by number, description, lifecycle status, coverage, Order, routing, or capacity relationships.
Inspect DID status	Check whether a DID is blocked, awaiting registration, pending removal, or terminated.
Update the DID description	Add or change the customer-defined description used to identify a DID.
Manage DID renewal	Set billing_cycles_count to control automatic renewal or expiration.
Cancel or restore a DID	Update terminated to cancel a DID or renew and restore its service.
Configure DID capacity	Assign dedicated channels or set the maximum incoming capacity for a DID.
Inspect related services	Include routing, capacity, registration, identity, coverage, Order, or Emergency Calling resources in the response.

Related resources

Use DIDs together with ordering, coverage, routing, capacity, regulatory, and Emergency Calling resources to manage purchased phone numbers.

Resource	Description
Orders	Orders through which DID phone numbers are purchased.
DID Groups	Coverage and inventory groups associated with purchased DIDs.
DID History	Historical records for DID phone numbers previously associated with the account.
Inbound Trunks	Inbound routing destinations assigned to DIDs.
Inbound Trunk Groups	Groups of inbound trunks used for routing and failover.
Capacity Pools	Channel capacity that can be assigned to DIDs.
Shared Capacity Groups	Shared channel capacity associated with DIDs.
Address Verifications	Address verification records associated with regulated DIDs.
Identities	Customer identities associated with DIDs.
Emergency Calling Services	Emergency Calling services assigned to DIDs.