# 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-dids.html).

```
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-did.html).

```
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](update-did.html).

```
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](../order/index.html) | Orders through which DID phone numbers are purchased. |
| [DID Groups](../../coverage-resources/did-group/index.html) | Coverage and inventory groups associated with purchased DIDs. |
| [DID History](../did-history/index.html) | Historical records for DID phone numbers previously associated with the account. |
| [Inbound Trunks](../voice-in-trunks/index.html) | Inbound routing destinations assigned to DIDs. |
| [Inbound Trunk Groups](../voice-in-trunk-groups/index.html) | Groups of inbound trunks used for routing and failover. |
| [Capacity Pools](../capacity-pool/index.html) | Channel capacity that can be assigned to DIDs. |
| [Shared Capacity Groups](../shared-capacity-group/index.html) | Shared channel capacity associated with DIDs. |
| [Address Verifications](../../regulation-resources/address-verifications/index.html) | Address verification records associated with regulated DIDs. |
| [Identities](../../regulation-resources/identities/index.html) | Customer identities associated with DIDs. |
| [Emergency Calling Services](../../emergency-resources/emergency-calling-services/index.html) | Emergency Calling services assigned to DIDs. |

On this page