We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

DID Destinations

Schema

A did's voice destination

Type Object

Name Type Description
activated Boolean Desc. activated
auth_identity String The username for a BASIC auth_method
auth_method Enum(NONE, BASIC, BEARER):String Desc. auth_method
auth_secret String Desc. auth_secret
destination String Desc. destination
id String(format:uuid) Desc. id
inserted_at String(format:date-time) An ISO8601 formatted timestamp
priority Integer Desc. priority
type Enum:String Desc. type
updated_at String(format:date-time) An ISO8601 formatted timestamp
wait_time Integer Desc. wait_time

Desc. activated

Whether or not the destination is considered for routing

Desc. auth_method

The authorization method to used for HTTP_ROUTE destinations

Desc. auth_secret

The password for a BASIC auth_method or token for BEARER auth_method

Desc. destination

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

A Universally unique identifier, which identifies the resource

Desc. priority

Affects the ordering of destinations for calls, 1 will be first while 9 is the last

Enum Values type

Allowed values

  • VOIP
  • PSTN
  • HTTP_ROUTE
  • TTS
  • TTS_CUSTOM
  • TTS_MESSAGE_SET

Desc. type

The destination type, see destination field for more detail

Desc. wait_time

How long will calls wait for the destination to connect.

Example

{
  "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

[email protected]: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

GET https://example.com/how/to/route/call HTTP/1.1
Accept: application/json, text/plain
Content-Type: application/json
Content-Length: 164

{
  "id": "01FS2R0G4N8V0TWS3Z7R9TX33E",
  "inserted_at": "2022-01-10T14:38:35.000000Z",
  "from": "12003004000",
  "to": "12003004001",
  "direction": "INCOMING"
}

Plain Text responses

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:[email protected]:5544

JSON Responses

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 115

{
  "type": "http_route_response",
  "data": {
    "type": "VOIP",
    "data": "[email protected]: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

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

POST /api/v1/numbers/{number_id}/destinations HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 333

{
  "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/1.1 201
Content-Type: application/json
Content-Length: 616

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

PATCH /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 333

{
  "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/1.1 200
Content-Type: application/json
Content-Length: 616

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

DELETE /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 616

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Query Desc. first

The number of items to return starting from the 'after' cursor

Query Desc. last

The number of items to return behind the 'before' cursor

Query Desc. after

The cursor representing the starting point of a 'first' based paging

Query Desc. before

The cursor representing the starting point of a 'last' based paging

Request

GET /api/v1/numbers/{number_id}/destinations HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 873

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

Path Desc. id

Number ID A Universally unique identifier, which identifies the resource

Request

GET /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 616

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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"
    }
  ]
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.