> Tychron Atlas API & Provisioning Reference — chapter 22 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/did-destinations/ > 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 # DID Destinations ## Schema A did's voice destination __Type__ Object | Name | Type | Description | | --------------- | -------------------------------------- | ------------------------------------ | | `activated` | Boolean | [Desc. `activated`](https://docs.tychron.com/api-reference/did-destinations/#desc-335) | | `auth_identity` | String | The username for a BASIC auth_method | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/did-destinations/#desc-336) | | `auth_secret` | String | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/did-destinations/#desc-337) | | `destination` | String | [Desc. `destination`](https://docs.tychron.com/api-reference/did-destinations/#desc-338) | | `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/did-destinations/#desc-339) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `priority` | Integer | [Desc. `priority`](https://docs.tychron.com/api-reference/did-destinations/#desc-340) | | `type` | [Enum](https://docs.tychron.com/api-reference/did-destinations/#enum-341):String | [Desc. `type`](https://docs.tychron.com/api-reference/did-destinations/#desc-342) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `wait_time` | Integer | [Desc. `wait_time`](https://docs.tychron.com/api-reference/did-destinations/#desc-343) | #### Desc. `activated` {#desc-335} Whether or not the destination is considered for routing #### Desc. `auth_method` {#desc-336} The authorization method to used for HTTP_ROUTE destinations #### Desc. `auth_secret` {#desc-337} The password for a BASIC auth_method or token for BEARER auth_method #### Desc. `destination` {#desc-338} Depending on the type, this field can contain different data. * `VOIP` - destination should be in the form of `local@domain` where local is the destination prefix and domain is the SIP capable server to handle the request * `PSTN` - destination should be a plain format number (e.g. 12003004000), can also be a comma separated list to allow multiple destinations * `HTTP_ROUTE` - destination should be an http uri which will handle the routing request * `TTS` - destination should be one of the pre-approved values (more may be added in the future): * `DISCONNECTED` * `TEXT_ONLY` * `BUSY` * `CONGESTION` * `TTS_CUSTOM` - destination should be the message to be read * `TTS_MESSAGE_SET` - destination will be set to "UNUSED" regardless of provided value, instead the tts_message_set_id MUST be set on the request #### Desc. `id` {#desc-339} A Universally unique identifier, which identifies the resource #### Desc. `priority` {#desc-340} Affects the ordering of destinations for calls, 1 will be first while 9 is the last #### Enum Values type {#enum-341} Allowed values * `VOIP` * `PSTN` * `HTTP_ROUTE` * `TTS` * `TTS_CUSTOM` * `TTS_MESSAGE_SET` #### Desc. `type` {#desc-342} The destination type, see destination field for more detail #### Desc. `wait_time` {#desc-343} How long will calls wait for the destination to connect. __Example__ ```json { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 } ``` ## Summary While switches control the primary routes for SMS and MMS, "destinations" control the primary routes for Voice calls, with the switch providing the fallback route in case all destinations fail, or there is no destination. Destinations provide many protocols/types and can be prioritized to create dial plans, or destinations can be randomized by setting multiple destinations with the same priority. ## Types Destination types affect the routing of the voice calls. ### PSTN PSTN, also called RCF (Remote Call Forwarding) can be used to route an originating/incoming voice call to another number. Note that PSTN calls will effectively charge for both the incoming and the outgoing leg of the call. __Example__ ``` 12003004000 ``` ### VoIP VoIP allows routing a call via a SIP capable server. __Example__ ``` 12003004000@example.com:5544 ``` ### TTS TTS (Text-To-Speech) is a service provided by Tychron to pre-answer or answer a Voice call with a message. This specific variant is used to play a pre-built message back. __Example__ ``` BUSY ``` ### TTS Custom Same function as __TTS__, but allows the client to set a custom message to be played back. Note that custom messages attract a per-character fee everytime the message is played back, even if the caller hangs up before the message finishes. __Example__ ``` Hello, welcome to ACME Corp, please hold while we connect you to our support team. ``` ### TTS Message Set Message Sets allow using multiple custom messages with customized voices for a tts message, like destinations themselves, these can also have priorities and be randomized. ### HTTP Route HTTP Route destinations will send an HTTP request to the specified endpoint in order to receive the intended voice routing for a call. The HTTP Route request will accept the response for any other non-"HTTP Route" destination. This effectively allows a dynamic programmable dial plan. __Example__ ``` https://example.com/how/to/route/my/call ``` __Note__ responses are allowed to be in JSON (`Content-Type: application/json`) or plain text (`Content-Type: text/plain`). Both require that the Content-Type is explictly set, any other content-types will be ignored and treated as a "SKIP" __Available Types__ * `SKIP` to explictly skip the http route destination, this will move unto the next destination in the dial plan * `PSTN` to route the call to another number * `VOIP` to route the call to a VoIP destination * `TTS` to playback a built-in message * `TTS_CUSTOM` to playback a custom message * `TTS_MESSAGE_SET` to utilize a message set for playback, the message set is specified by id __Request Example__ ```http GET https://example.com/how/to/route/call HTTP/1.1 Accept: application/json, text/plain Content-Type: application/json Content-Length: 164 ``` ```json { "id": "01FS2R0G4N8V0TWS3Z7R9TX33E", "inserted_at": "2022-01-10T14:38:35.000000Z", "from": "12003004000", "to": "12003004001", "direction": "INCOMING" } ``` #### Plain Text responses ```http HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 8 TTS:BUSY ``` Plain text responses follow the format: ``` TYPE:DATA ``` __Example 1__ Built-in TTS messages ``` TTS:BUSY ``` __Example 2__ VoIP destination ``` VOIP:12003004000@example.com:5544 ``` #### JSON Responses ```http HTTP/1.1 200 OK Content-Type: application/json Content-Length: 115 ``` ```json { "type": "http_route_response", "data": { "type": "VOIP", "data": "12003004000@example.com:5544" } } ``` JSON responses can also be used, the root level `type` MUST be `"http_route_response"` otherwise the response will be treated as SKIP. ## API ### Create a DID Destination ```http POST /api/v1/numbers/{number_id}/destinations HTTP/1.1 ``` Create a new Number Destination. __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | #### Request application/json ```http POST /api/v1/numbers/{number_id}/destinations HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 333 ``` ```json { "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "priority": 1, "tts_message_set_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "type": "HTTP_ROUTE" }, "type": "number_destination" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### 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" } ] } ``` ### Update a DID's Destination ```http PATCH /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 ``` Update a Number's Destination. __Path Parameters__ | Name | Type | Description | | -------------- | -------------------- | ------------ | | number_id | String! | Number or ID | | destination_id | String(format:uuid)! | ID | #### Request application/json ```http PATCH /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 333 ``` ```json { "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "priority": 1, "tts_message_set_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "type": "HTTP_ROUTE" }, "type": "number_destination" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### 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" } ] } ``` ### Delete a DID's Destination ```http DELETE /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 ``` Delete a Number's Destination. __Path Parameters__ | Name | Type | Description | | -------------- | -------------------- | ------------ | | number_id | String! | Number or ID | | destination_id | String(format:uuid)! | ID | #### Request ```http DELETE /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### 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 DID's Destinations ```http GET /api/v1/numbers/{number_id}/destinations HTTP/1.1 ``` Retrieve a list of all api keys bound to the number __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/did-destinations/#desc-344) | | last | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/did-destinations/#desc-345) | | after | String | [Query Desc. after](https://docs.tychron.com/api-reference/did-destinations/#desc-346) | | before | String | [Query Desc. before](https://docs.tychron.com/api-reference/did-destinations/#desc-347) | #### Query Desc. first {#desc-344} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-345} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-346} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-347} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/numbers/{number_id}/destinations HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 873 ``` ```json { "count": 1, "page_info": { "first": "string", "has_next_page": true, "has_previous_page": true, "last": "string" }, "results": [ { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ] } ``` #### 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" } ] } ``` ### Get DID's Destination ```http GET /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 ``` Retrieve a DID Destination associated with the DID by its ID __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | -------------------------- | | number_id | String! | Number or ID | | id | String(format:uuid)! | [Path Desc. id](https://docs.tychron.com/api-reference/did-destinations/#desc-348) | #### Path Desc. id {#desc-348} Number ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### 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/number-management.md Next chapter: https://docs.tychron.com/api-reference/did-optout-items.md Complete reference in one file: https://docs.tychron.com/llms-full.txt