Update DID#

Update the settings of a single DID owned by your account. Using this endpoint you can cancel, restore or renew DID.

To cancel a DID, attribute terminated must be true, to renew or restore DID attribute terminated must be false.

Request#

HTTP Method: PATCH

URI Path: /v3/dids/{id}

URI Query Parameters#

Name

Type

Is Required?

Description

id

string

Yes

Unique ID number allocated to this DID

Attributes#

Name

Type

Is Required?

Description

terminated

boolean

Optional

If set to true, it will cancel a DID number. To renew or restore a DID number, the attribute must be set to false.

description

string

Optional

A DID number description.

billing_cycles_count

integer

Optional

The number of Billing Cycles that this DID Number will renew until expiration. If set to 0, then DID will not be renewed. If set to null, then DID will be renewed infinitely. After each renew value will be decreased by 1 if it is set. Maximum value of billing_cycles_count is 999.

dedicated_channels_count

integer

Optional

Amount of dedicated channels to assign.

capacity_limit

integer

Optional

Limits incoming capacity per DID number according to entered value. If set as null, assigned capacity is not limited.

Inbound SMS Routing#

A DID routes inbound SMS to one SMS trunk or to one SMS trunk group, never both. Set the route with the sms_trunk relationship (see SMS Trunks) or the sms_trunk_group relationship (see SMS Trunk Groups).

  • Assigning one of the two relationships replaces the route set through the other one.

  • Sending both sms_trunk and sms_trunk_group with an ID in the same request returns 422 Unprocessable Entity. Sending one of them with an ID and the other with "data": null assigns the ID.

  • The SMS trunk must accept inbound SMS. A trunk with the http_out configuration type is rejected with 422 Unprocessable Entity.

  • The DID Group of the DID must support inbound SMS (its features include sms_in). Otherwise the request returns 422 Unprocessable Entity.

  • An SMS trunk or SMS trunk group that does not exist or does not belong to your account returns 422 Unprocessable Entity.

  • Sending "data": null clears the route only when the DID is currently routed through that relationship. For example, sms_trunk_group with "data": null does not change a DID routed to a single SMS trunk.

Examples#

http

 1PATCH /v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70 HTTP/1.1
 2Host: api.didww.com
 3Content-Type: application/vnd.api+json
 4Accept: application/vnd.api+json
 5Authorization: Bearer [access token]
 6
 7{
 8  "data": {
 9    "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
10    "type": "dids",
11    "attributes": {
12      "terminated": false,
13      "description": "string",
14      "capacity_limit": 1
15    }
16  }
17}

curl

1curl -i -X PATCH https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70 -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"capacity_limit": 1, "description": "string", "terminated": false}, "id": "46e129f1-deaa-44db-8915-2646de4d4c70", "type": "dids"}}'

response

  1HTTP/1.1 200 OK
  2Content-Type: application/vnd.api+json
  3
  4{
  5  "data": {
  6    "id": "46e129f1-deaa-44db-8915-2646de4d4c70",
  7    "type": "dids",
  8    "attributes": {
  9      "blocked": false,
 10      "capacity_limit": 1,
 11      "description": "string",
 12      "terminated": false,
 13      "awaiting_registration": false,
 14      "number": "437xxxxxxxxx",
 15      "expires_at": "2017-06-25T08:21:41.795Z",
 16      "channels_included_count": 2,
 17      "created_at": "2017-06-25T08:21:41.795Z",
 18      "dedicated_channels_count": 0,
 19      "billing_cycles_count": null,
 20      "emergency_enabled": false
 21    },
 22    "relationships": {
 23      "did_group": {
 24        "links": {
 25          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/did_group",
 26          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/did_group"
 27        }
 28      },
 29      "order": {
 30        "links": {
 31          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/order",
 32          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/order"
 33        }
 34      },
 35      "voice_in_trunk": {
 36        "links": {
 37          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/voice_in_trunk",
 38          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/voice_in_trunk"
 39        }
 40      },
 41      "voice_in_trunk_group": {
 42        "links": {
 43          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/voice_in_trunk_group",
 44          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/voice_in_trunk_group"
 45        }
 46      },
 47      "capacity_pool": {
 48        "links": {
 49          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/capacity_pool",
 50          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/capacity_pool"
 51        }
 52      },
 53      "shared_capacity_group": {
 54        "links": {
 55          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/shared_capacity_group",
 56          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/shared_capacity_group"
 57        }
 58      },
 59      "sms_trunk": {
 60        "links": {
 61          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/sms_trunk",
 62          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/sms_trunk"
 63        }
 64      },
 65      "sms_trunk_group": {
 66        "links": {
 67          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/sms_trunk_group",
 68          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/sms_trunk_group"
 69        }
 70      },
 71      "address_verification": {
 72        "links": {
 73          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/address_verification",
 74          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/address_verification"
 75        }
 76      },
 77      "emergency_calling_service": {
 78        "links": {
 79          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/emergency_calling_service",
 80          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/emergency_calling_service"
 81        }
 82      },
 83      "emergency_verification": {
 84        "links": {
 85          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/emergency_verification",
 86          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/emergency_verification"
 87        }
 88      },
 89      "identity": {
 90        "links": {
 91          "self": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/relationships/identity",
 92          "related": "https://api.didww.com/v3/dids/46e129f1-deaa-44db-8915-2646de4d4c70/identity"
 93        }
 94      }
 95    }
 96  },
 97  "meta": {
 98    "api_version": "2026-11-19"
 99  }
100}

Other Responses#

Code

Success

Description

404

No

Not Found

400

No

Bad Request

401

No

Unauthorized

403

No

The access token carries the read scope, which does not cover this method (title Insufficient scope). The response carries WWW-Authenticate: Bearer error="insufficient_scope". See Scopes.

422

No

Unprocessable Entity

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.