> Tychron Atlas API & Provisioning Reference — chapter 20 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/dids/ > Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it). > Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled) > Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/ > Machine index: https://docs.tychron.com/llms.txt # DIDs ## Schema A provisioned did __Type__ Object | Name | Type | Description | | ------------------------ | --------------------------------- | ---------------------------------------- | | `activated` | Boolean | [Desc. `activated`](https://docs.tychron.com/api-reference/dids/#desc-311) | | `brand_name` | String(0..255) | [Desc. `brand_name`](https://docs.tychron.com/api-reference/dids/#desc-312) | | `description` | String | [Desc. `description`](https://docs.tychron.com/api-reference/dids/#desc-313) | | `forward_number` | String | [Desc. `forward_number`](https://docs.tychron.com/api-reference/dids/#desc-314) | | `help_message` | String(0..255) | [Desc. `help_message`](https://docs.tychron.com/api-reference/dids/#desc-315) | | `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/dids/#desc-316) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `message_class` | Enum(`NONE`, `A2P`, `P2P`):String | | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/dids/#desc-317) | | `number` | String | [Desc. `number`](https://docs.tychron.com/api-reference/dids/#desc-318) | | `rate_center` | String | | | `segment_overrides` | Array:[SubObject](https://docs.tychron.com/api-reference/dids/#type-323) | [Desc. `segment_overrides`](https://docs.tychron.com/api-reference/dids/#desc-324) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](https://docs.tychron.com/api-reference/dids/#desc-325) | | `sms_enabled` | Boolean | [Desc. `sms_enabled`](https://docs.tychron.com/api-reference/dids/#desc-326) | | `state` | String | | | `tier` | [Enum](https://docs.tychron.com/api-reference/dids/#enum-327):String | [Desc. `tier`](https://docs.tychron.com/api-reference/dids/#desc-328) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `upgrade_asset_handling` | [Enum](https://docs.tychron.com/api-reference/dids/#enum-329):String | The asset handling flag for SMS Upgrades | | `voice_enabled` | Boolean | [Desc. `voice_enabled`](https://docs.tychron.com/api-reference/dids/#desc-330) | #### Desc. `activated` {#desc-311} Is the DID active for use? #### Desc. `brand_name` {#desc-312} Custom Brand Name when the number is not actively apart of TCR's Campaign setup, this field will be used in place of the brand name. Added on 2026-05-04. #### Desc. `description` {#desc-313} Any notes to attach to the number. #### Desc. `forward_number` {#desc-314} When this DID receives an inbound message, the message will be routed to the specified `forward_number`. Note. using forward_number or its switch equivalent will charge the account for 2 messages, instead of 1: * Once for the inbound (to the host number) * Again for the outbound (from the host number to the forward number) If this field is nil, or blank the `sms_switch` will be used for routing instead #### Desc. `help_message` {#desc-315} Custom HELP Message that should be sent when an inbound message matching "HELP" is received. For help messages longer than 255 characters, they must handled by the receiver. #### Desc. `id` {#desc-316} A Universally unique identifier, which identifies the resource #### Desc. `mms_enabled` {#desc-317} Whether or not the number is MMS capable, does not affect SMS or SMS to MMS upgrades. #### Desc. `number` {#desc-318} The 3 to 15 digit code of the number. #### SubObject {#type-323} Sub-Schema __Type__ Object | Name | Type | Description | | --------------------- | ------------------- | ---------------------------------------- | | `encoding` | Integer | [Desc. `encoding`](https://docs.tychron.com/api-reference/dids/#desc-319) | | `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/dids/#desc-320) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](https://docs.tychron.com/api-reference/dids/#desc-321) | | `target_reference_id` | String | [Desc. `target_reference_id`](https://docs.tychron.com/api-reference/dids/#desc-322) | #### Desc. `encoding` {#desc-319} The SMS encoding that this override should trigger on. #### Desc. `id` {#desc-320} The UUID of the specific segment override, required when changing an existing override. #### Desc. `segment_threshold` {#desc-321} See number's segment_threshold for more information. #### Desc. `target_reference_id` {#desc-322} Internal reference_id for a carrier, contact support for details or if a required carrier is not available. Reference ids tend to have the form: _ Example: us_tmobile ca_rogers dm_digicel #### Desc. `segment_overrides` {#desc-324} While the segment_threshold can be used to apply to all outgoing sms messages, sometimes its required to tailor fit an upgrade to a particular carrier. Note, when updating the segment_overrides, all overrides must be provided for the did, any unspecified overrides will be removed. #### Desc. `segment_threshold` {#desc-325} How many segments should a outgoing message have before it triggers an MMS upgrade. Contact support to learn more about MMS upgrades. 0 will disable upgrades, any value greater than 1 will trigger an upgrade when that many sms segments would have been sent. Upgrades only apply to HTTP originated traffic, customers using SMPP will not for outbound are not subject to upgrades. #### Desc. `sms_enabled` {#desc-326} Whether or not a number is messaging capable. Note that this flag also affects mms availability. #### Enum Values tier {#enum-327} Allowed values * `L0` * `L1` * `T1` * `T2` * `T3` * `AK` * `HI` * `CAN` * `PR` * `TF` * `SHORTCODE` * `M0` * `M1` * `BYON` #### Desc. `tier` {#desc-328} The billing tier associated with the number: * `L0` - Tychron OCN Tier 0 * `L1` - Tychron OCN Tier 1 * `T1` - Partner Tier 0 * `T2` - Partner Tier 1 * `T3` - Partner Tier 3 * `AK` - Alaska * `HI` - Hawaii * `CAN` - Canada * `PR` - Puerto Rico * `TF` - Tollfree * `SHORTCODE` - General Shortcode * `M0` - Mobile Tier 0 * `M1` - Mobile Tier 1 * `BYON` - Bring-Your-Own-Number #### Enum Values upgrade_asset_handling {#enum-329} Allowed values * `FALLBACK` * `OFF` * `ALWAYS_UPGRADE` * `SEGMENT_UPGRADE` #### Desc. `voice_enabled` {#desc-330} Whether or not the specified number is voice-capable (only affects outgoing) __Example__ ```json { "activated": true, "brand_name": "ACME Corp.", "description": "Test number used for XYZ.Corp\n", "forward_number": "12003004000", "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "message_class": "A2P", "mms_enabled": true, "number": "12003004000", "rate_center": "KISSIMEE", "segment_overrides": [ { "encoding": 0, "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "segment_threshold": 0, "target_reference_id": "us_tmobile" } ], "segment_threshold": 1, "sms_enabled": true, "state": "FL", "tier": "T1", "updated_at": "2021-08-13T04:08:44.762841Z", "upgrade_asset_handling": "FALLBACK", "voice_enabled": true } ``` ## Summary DIDs, or Numbers represent a Longcode (10DLC, Tollfree, International), Shortcode or Sender ID. They are the primary resource for messaging and VoIP operations. ## API ### Update DID ```http PATCH /api/v1/numbers/{id} HTTP/1.1 ``` Update some features on the specified number. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------ | | id | String(format:uuid)! | Number or ID | #### Request application/json ```http PATCH /api/v1/numbers/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 505 ``` ```json { "data": { "description": "Test number used for XYZ.Corp\n", "forward_number": "12003004000", "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.", "mms_enabled": true, "segment_overrides": [ { "encoding": 0, "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "segment_threshold": 0, "target_reference_id": "us_tmobile" } ], "segment_threshold": 1, "upgrade_asset_handling": "FALLBACK" }, "type": "number" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1209 ``` ```json { "associations": { "campaign": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "tcr_brand_id": "B000000", "tcr_campaign_id": "C000000" }, "messaging_switch": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "voice_switch": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "brand_name": "ACME Corp.", "description": "Test number used for XYZ.Corp\n", "forward_number": "12003004000", "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "message_class": "A2P", "mms_enabled": true, "number": "12003004000", "rate_center": "KISSIMEE", "segment_overrides": [ { "encoding": 0, "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "segment_threshold": 0, "target_reference_id": "us_tmobile" } ], "segment_threshold": 1, "sms_enabled": true, "state": "FL", "tier": "T1", "updated_at": "2021-08-13T04:08:44.762841Z", "upgrade_asset_handling": "FALLBACK", "voice_enabled": true }, "type": "number" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List DIDs ```http GET /api/v1/numbers HTTP/1.1 ``` Retrieve a list of numbers provisioned on the account. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/dids/#desc-331) | | last | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/dids/#desc-332) | | after | String | [Query Desc. after](https://docs.tychron.com/api-reference/dids/#desc-333) | | before | String | [Query Desc. before](https://docs.tychron.com/api-reference/dids/#desc-334) | #### Query Desc. first {#desc-331} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-332} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-333} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-334} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/numbers HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1546 ``` ```json { "count": 1, "page_info": { "first": "string", "has_next_page": true, "has_previous_page": true, "last": "string" }, "results": [ { "associations": { "campaign": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "tcr_brand_id": "B000000", "tcr_campaign_id": "C000000" }, "messaging_switch": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "voice_switch": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "brand_name": "ACME Corp.", "description": "Test number used for XYZ.Corp\n", "forward_number": "12003004000", "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "message_class": "A2P", "mms_enabled": true, "number": "12003004000", "rate_center": "KISSIMEE", "segment_overrides": [ { "encoding": 0, "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "segment_threshold": 0, "target_reference_id": "us_tmobile" } ], "segment_threshold": 1, "sms_enabled": true, "state": "FL", "tier": "T1", "updated_at": "2021-08-13T04:08:44.762841Z", "upgrade_asset_handling": "FALLBACK", "voice_enabled": true }, "type": "number" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get DID ```http GET /api/v1/numbers/{id} HTTP/1.1 ``` Lookup a number by ID or it's number __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------ | | id | String(format:uuid)! | Number or ID | #### Request ```http GET /api/v1/numbers/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1209 ``` ```json { "associations": { "campaign": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "tcr_brand_id": "B000000", "tcr_campaign_id": "C000000" }, "messaging_switch": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "voice_switch": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "brand_name": "ACME Corp.", "description": "Test number used for XYZ.Corp\n", "forward_number": "12003004000", "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "message_class": "A2P", "mms_enabled": true, "number": "12003004000", "rate_center": "KISSIMEE", "segment_overrides": [ { "encoding": 0, "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "segment_threshold": 0, "target_reference_id": "us_tmobile" } ], "segment_threshold": 1, "sms_enabled": true, "state": "FL", "tier": "T1", "updated_at": "2021-08-13T04:08:44.762841Z", "upgrade_asset_handling": "FALLBACK", "voice_enabled": true }, "type": "number" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` --- Previous chapter: https://docs.tychron.com/api-reference/messaging-auto-responses.md Next chapter: https://docs.tychron.com/api-reference/number-management.md Complete reference in one file: https://docs.tychron.com/llms-full.txt