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

Switches

Schema

Switches contain the routing information for dids

Type Object

Name Type Description
notes String Any notes about the switch
sms_secret String Desc. sms_secret
mms_signing_scheme SwitchSigningScheme
voice_data String Desc. voice_data
updated_at String(format:date-time) An ISO8601 formatted timestamp
sms_data String Desc. sms_data
sms_signing_scheme SwitchSigningScheme
voice_protocol Enum:String Desc. voice_protocol
inserted_at String(format:date-time) An ISO8601 formatted timestamp
mms_options mms_options Desc. mms_options
sms_message_format Enum:String Desc. sms_message_format
mms_message_format Enum:String Desc. mms_message_format
voice_auth_method Enum(NONE, BASIC, BEARER):String Desc. voice_auth_method
mms_enabled Boolean Desc. mms_enabled
name String Desc. name
sms_auth_method Enum(NONE, BASIC, BEARER, HMAC_SHA256):String Desc. sms_auth_method
mms_secret String Desc. mms_secret
mms_identity String Acts as the username in basic auth
sms_enabled Boolean Desc. sms_enabled
mms_encryption_method SwitchEncryptionMethod
voice_enabled Boolean Desc. voice_enabled
sms_signing_hash SwitchSigningHash
sms_encryption_method SwitchEncryptionMethod
voice_identity String
mms_name String Desc. mms_name
mms_auth_method Enum(NONE, BASIC, BEARER, HMAC_SHA256):String Desc. mms_auth_method
mms_protocol Enum:String Desc. mms_protocol
voice_name String
voice_secret String
sms_name String Reserved for future use
mms_signing_hash SwitchSigningHash
mms_data String(format:url) Desc. mms_data
sms_protocol Enum:String Desc. sms_protocol
sms_identity String Acts as the username in basic auth
sms_options sms_options Desc. sms_options
id String(format:uuid) Desc. id

Desc. sms_secret

Depending on the auth_method, this fields usage changes:

  • NONE - unsued
  • BASIC - Acts as the password component of the Authorization Basic pair.
  • BEARER - Acts as the token
  • HMAC_SHA256 - Used as-is for signature generation, prefer using the dedicated signing keys instead for newer switches.

Desc. voice_data

Contains the routing url specific to the requested protocol

Desc. sms_data

Depending on the SMS Protocol in use, the requirement of this field will change:

  • NONE - ignored
  • SMPP - ignored
  • HTTP - Must be a valid URL, scheme may be http, or https, paths and query parameters are supported.
  • FORWARD - Must be a valid E164 address (can omit plus if needed), messages will be forwarded to the respective number as a new OUTBOUND message (charges apply).
  • TYCHRON_CHAT - Set as UNUSUED.

Enum Values voice_protocol

Allowed values

  • NONE
  • VOIP
  • PSTN
  • TTS
  • TTS_CUSTOM
  • HTTP_ROUTE

Desc. voice_protocol

All protocols supported for fallback VoIP destination.

Desc. mms_options

Contains various miscelleanous or experimental feature flags for MMS.

Enum Values sms_message_format

Allowed values

  • TRINITY_JSON_1_0
  • TRINITY_POST_1_0
  • TRINITY_POST_2_0

Desc. sms_message_format

All supported message formats for SMS HTTP Protocol

Enum Values mms_message_format

Allowed values

  • OXY_JSON_1_0
  • OXY_JSONAPI_1_0
  • OXY_XML_1_0
  • OXY_MULTIPART_1_0
  • OXY_MULTIPART_2_0
  • OXY_RFC822_1_0

Desc. mms_message_format

All supported message formats for MMS HTTP Protocol.

Desc. voice_auth_method

Various authorization methods supported.

Primarily used with HTTP ROUTE

Desc. mms_enabled

Enable inbound MMS routing?

Desc. name

A display name to easily identify the switch

Desc. sms_auth_method

Various authorization methods supported by the SMS HTTP Protocol.

SMPP utilizes an API Key for it's authorization instead.

  • NONE - No authorization header is added to the request
  • BASIC - Uses the sms_identity as the username and sms_secret as the password to form the Basic pair
  • BEARER - Uses ONLY the sms_secret as the token
  • HMAC_SHA256 - Consult the Signing Hash section for details, the signature will be placed into the authorization header with a scheme TYCHRON0-HMAC-SHA256 and Base16 encoded (lowercase).

Desc. mms_secret

Depending on the auth_method, this fields usage changes:

  • NONE - unsued
  • BASIC - Acts as the password component of the Authorization Basic pair.
  • BEARER - Acts as the token
  • HMAC_SHA256 - Used as-is for signature generation, prefer using the dedicated signing keys instead for newer switches.

Desc. sms_enabled

Enable inbound SMS routing?

Desc. voice_enabled

Enable voice call fallback routing?

Desc. mms_name

Only used for MM4, used as the display name for auth

Desc. mms_auth_method

Various authorization methods supported.

Note that bearer and hmac_sha256 will not be used for MM4, only basic is supported.

HTTP supports all available methods.

  • NONE - No authorization header is added to the request
  • BASIC - Uses the mms_identity as the username and mms_secret as the password to form the Basic pair
  • BEARER - Uses ONLY the mms_secret as the token
  • HMAC_SHA256 - Consult the Signing Hash section for details, the signature will be placed into the authorization header with a scheme TYCHRON0-HMAC-SHA256 and Base16 encoded (lowercase).

Enum Values mms_protocol

Allowed values

  • NONE
  • MM4
  • HTTP
  • SFTP
  • FORWARD
  • TYCHRON_CHAT

Desc. mms_protocol

All protocols supported for MMS delivery.

  • NONE - Will discard any inbound messages destined for the switch.
  • MM4 - Delivers messages over MM4 to the configured enpoint in mms_data, use mm4s as the scheme to require TLS, or mm4+s for optional TLS.
  • HTTP - Delivers messages over HTTP (or HTTPS, if the scheme is set to https in the mms_data).
  • SFTP - Uploads the MMS to a SFTP server.
  • FORWARD - Forwards the INBOUND MMS to another number as a new OUTBOUND message.
  • TYCHRON_CHAT - Forwards the MMS to Tychron's chat service.

Desc. mms_data

Depending on the mms_protocol, the value is of a different format:

  • NONE - ignored
  • MM4 - Must be a valid URL, without a path component with schemes: mm4, mm4+s or mm4s for non-tls, optional-tls and mandatory tls respectively.
  • HTTP - Must be a valid URL, scheme may be http, or https, paths and query parameters are supported.
  • SFTP - Must be a valid URL, scheme MUST be sftp, path component is used to change directory if supplied.
  • FORWARD - Must be a valid E164 address (can omit plus if needed), messages will be forwarded to the respective number as a new OUTBOUND message (charges apply).
  • TYCHRON_CHAT - Set to UNUSED.

Enum Values sms_protocol

Allowed values

  • NONE
  • SMPP
  • HTTP
  • FORWARD
  • TYCHRON_CHAT

Desc. sms_protocol

All protocols supported for SMS delivery, note that none will effectively no-op all incoming messages.

  • NONE - No protocol, this will discard any inbound messages destined for the host number associated with the switch
  • HTTP - Uses HTTP (supports HTTPS if the sms_data includes the respective scheme, e.g. https://example.com)
  • SMPP - The switch is configured to use SMPP, note. the switch MUST have an attached API Key to determine the destination, as API Keys contain the SMPP System ID.
  • FORWARD - Forwards any incoming messages to the switch to another number configured as sms_data.
  • TYCHRON_CHAT - Forwards any incoming messages to Tychron's chat service.

Desc. sms_options

Contains various miscelleanous or experimental feature flags for SMS.

Desc. id

A Universally unique identifier, which identifies the resource

mms_options

Name Type Description
dlr_on_sent Boolean Desc. dlr_on_sent
forward_dlr Boolean Desc. forward_dlr
pad_shortcodes Boolean Desc. pad_shortcodes

Desc. dlr_on_sent

Experimental: Whenever a message is sent to the configured endpoint, a dlr will automatically be generated and sent back to the sender.

Desc. forward_dlr

Normally a switch will always attempt to deliver DLRs the same as regular messages.

This flag can be set to stop the delivery of DLRs.

Desc. pad_shortcodes

Experimental: If your endpoint requires 11 or more digits for numbers, this field can be enabled to pad shortcodes with leading zeroes to make them 11 digit where possible.

sms_options

Name Type Description
dlr_on_sent Boolean Desc. dlr_on_sent
forward_dlr Boolean Desc. forward_dlr
pad_shortcodes Boolean Desc. pad_shortcodes

Desc. dlr_on_sent

Experimental: Whenever a message is sent to the configured endpoint, a dlr will automatically be generated and sent back to the sender.

Desc. forward_dlr

Normally a switch will always attempt to deliver DLRs the same as regular messages.

This flag can be set to stop the delivery of DLRs.

Desc. pad_shortcodes

Experimental: If your endpoint requires 11 or more digits for numbers, this field can be enabled to pad shortcodes with leading zeroes to make them 11 digit where possible.

Example

{
  "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
  "sms_secret": "super$ecret",
  "mms_signing_scheme": "NONE",
  "voice_data": "[email protected]",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "sms_data": "https://example.com",
  "sms_signing_scheme": "NONE",
  "voice_protocol": "NONE",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "mms_options": {
    "dlr_on_sent": false,
    "forward_dlr": true,
    "pad_shortcodes": false
  },
  "sms_message_format": "TRINITY_JSON_1_0",
  "mms_message_format": "OXY_JSON_1_0",
  "voice_auth_method": "NONE",
  "mms_enabled": true,
  "name": "Primary Messaging Switch",
  "sms_auth_method": "NONE",
  "mms_secret": "super$ecret",
  "mms_identity": "johndoe",
  "sms_enabled": true,
  "mms_encryption_method": "NONE",
  "voice_enabled": false,
  "sms_signing_hash": "NONE",
  "sms_encryption_method": "NONE",
  "voice_identity": "johndoe",
  "mms_name": "John Doe",
  "mms_auth_method": "NONE",
  "mms_protocol": "NONE",
  "voice_name": "John Doe",
  "voice_secret": "super$ecret",
  "sms_name": "John Doe",
  "mms_signing_hash": "NONE",
  "mms_data": "mm4://example.com:2525",
  "sms_protocol": "NONE",
  "sms_identity": "johndoe",
  "sms_options": {
    "dlr_on_sent": false,
    "forward_dlr": true,
    "pad_shortcodes": false
  },
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
}

Summary

Receiving messages are briefly covered in the Tychron Docs under the SMS and MMS sections respectively.

However there is a lot more available than what the basic documentation covers.

API

Create Switch

POST /api/v1/switches HTTP/1.1

Create a new Switch.

The only required parameter to create a new switch is its name, all other options can be left empty or nil.

Request application/json

POST /api/v1/switches HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1126

{
  "data": {
    "mms_auth_method": "NONE",
    "mms_data": "mm4://example.com:2525",
    "mms_enabled": true,
    "mms_identity": "johndoe",
    "mms_message_format": "OXY_JSON_1_0",
    "mms_name": "John Doe",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "mms_protocol": "NONE",
    "mms_secret": "super$ecret",
    "name": "Primary Messaging Switch",
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_auth_method": "NONE",
    "sms_data": "https://example.com",
    "sms_enabled": true,
    "sms_identity": "johndoe",
    "sms_message_format": "TRINITY_JSON_1_0",
    "sms_name": "John Doe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_protocol": "NONE",
    "sms_secret": "super$ecret",
    "voice_auth_method": "NONE",
    "voice_data": "[email protected]",
    "voice_enabled": false,
    "voice_identity": "johndoe",
    "voice_name": "John Doe",
    "voice_protocol": "NONE",
    "voice_secret": "super$ecret"
  },
  "type": "switch"
}

Response 201

application/json
HTTP/1.1 201
Content-Type: application/json
Content-Length: 1768

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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 422

application/json
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Update Switch

PATCH /api/v1/switches/{id} HTTP/1.1

Update an existing Switch.

Path Parameters

Name Type Description
id String(format:uuid)! Switch ID

Request application/json

PATCH /api/v1/switches/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1126

{
  "data": {
    "mms_auth_method": "NONE",
    "mms_data": "mm4://example.com:2525",
    "mms_enabled": true,
    "mms_identity": "johndoe",
    "mms_message_format": "OXY_JSON_1_0",
    "mms_name": "John Doe",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "mms_protocol": "NONE",
    "mms_secret": "super$ecret",
    "name": "Primary Messaging Switch",
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_auth_method": "NONE",
    "sms_data": "https://example.com",
    "sms_enabled": true,
    "sms_identity": "johndoe",
    "sms_message_format": "TRINITY_JSON_1_0",
    "sms_name": "John Doe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_protocol": "NONE",
    "sms_secret": "super$ecret",
    "voice_auth_method": "NONE",
    "voice_data": "[email protected]",
    "voice_enabled": false,
    "voice_identity": "johndoe",
    "voice_name": "John Doe",
    "voice_protocol": "NONE",
    "voice_secret": "super$ecret"
  },
  "type": "switch"
}

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Response 422

application/json
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Delete Switch

DELETE /api/v1/switches/{id} HTTP/1.1

Delete an existing Switch.

A switch cannot be deleted if it is still attached to one or more numbers.

Path Parameters

Name Type Description
id String(format:uuid)! Switch ID

Request

DELETE /api/v1/switches/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Response 422

application/json
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241

{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

List Switches

GET /api/v1/switches HTTP/1.1

Retrieve a list of switches provisioned on the account

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/switches HTTP/1.1
Accept: application/json

Response 200

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

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "api_key": {
          "id": "string"
        },
        "mms_encryption_key": {
          "id": "string"
        },
        "mms_signing_key": {
          "id": "string"
        },
        "sms_encryption_key": {
          "id": "string"
        },
        "sms_signing_key": {
          "id": "string"
        }
      },
      "data": {
        "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
        "sms_secret": "super$ecret",
        "mms_signing_scheme": "NONE",
        "voice_data": "[email protected]",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "sms_data": "https://example.com",
        "sms_signing_scheme": "NONE",
        "voice_protocol": "NONE",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "mms_options": {
          "dlr_on_sent": false,
          "forward_dlr": true,
          "pad_shortcodes": false
        },
        "sms_message_format": "TRINITY_JSON_1_0",
        "mms_message_format": "OXY_JSON_1_0",
        "voice_auth_method": "NONE",
        "mms_enabled": true,
        "name": "Primary Messaging Switch",
        "sms_auth_method": "NONE",
        "mms_secret": "super$ecret",
        "mms_identity": "johndoe",
        "sms_enabled": true,
        "mms_encryption_method": "NONE",
        "voice_enabled": false,
        "sms_signing_hash": "NONE",
        "sms_encryption_method": "NONE",
        "voice_identity": "johndoe",
        "mms_name": "John Doe",
        "mms_auth_method": "NONE",
        "mms_protocol": "NONE",
        "voice_name": "John Doe",
        "voice_secret": "super$ecret",
        "sms_name": "John Doe",
        "mms_signing_hash": "NONE",
        "mms_data": "mm4://example.com:2525",
        "sms_protocol": "NONE",
        "sms_identity": "johndoe",
        "sms_options": {
          "dlr_on_sent": false,
          "forward_dlr": true,
          "pad_shortcodes": false
        },
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
      },
      "type": "switch"
    }
  ]
}

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

Get Switch

GET /api/v1/switches/{id} HTTP/1.1

Lookup a switch by ID

Path Parameters

Name Type Description
id String(format:uuid)! Switch ID

Request

GET /api/v1/switches/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Attach Messaging Switch to DID

PUT /api/v1/numbers/{number_id}/messaging_switch/{id} HTTP/1.1

Change or set a Number's Messaging Switch

Path Parameters

Name Type Description
number_id String! Number or ID
id String(format:uuid)! Switch ID

Request

PUT /api/v1/numbers/{number_id}/messaging_switch/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Attach VoIP Fallback Switch to DID

PUT /api/v1/numbers/{number_id}/voice_switch/{id} HTTP/1.1

Change or set a Number's Voice Switch

Path Parameters

Name Type Description
number_id String! Number or ID
id String(format:uuid)! Switch ID

Request

PUT /api/v1/numbers/{number_id}/voice_switch/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Detach Messaging Switch From DID

DELETE /api/v1/numbers/{number_id}/messaging_switch HTTP/1.1

Removes the Messaging Switch on a specified Number

Path Parameters

Name Type Description
number_id String! Number or ID

Request

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

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Detach VoIP Fallback Switch From DID

DELETE /api/v1/numbers/{number_id}/voice_switch HTTP/1.1

Removes the Voice Switch on a specified Number

Path Parameters

Name Type Description
number_id String! Number or ID

Request

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

Response 200

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

{
  "associations": {
    "api_key": {
      "id": "string"
    },
    "mms_encryption_key": {
      "id": "string"
    },
    "mms_signing_key": {
      "id": "string"
    },
    "sms_encryption_key": {
      "id": "string"
    },
    "sms_signing_key": {
      "id": "string"
    }
  },
  "data": {
    "notes": "CA Switch for Data-Center #3, do not DELETE AGAIN.",
    "sms_secret": "super$ecret",
    "mms_signing_scheme": "NONE",
    "voice_data": "[email protected]",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "sms_data": "https://example.com",
    "sms_signing_scheme": "NONE",
    "voice_protocol": "NONE",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "mms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "sms_message_format": "TRINITY_JSON_1_0",
    "mms_message_format": "OXY_JSON_1_0",
    "voice_auth_method": "NONE",
    "mms_enabled": true,
    "name": "Primary Messaging Switch",
    "sms_auth_method": "NONE",
    "mms_secret": "super$ecret",
    "mms_identity": "johndoe",
    "sms_enabled": true,
    "mms_encryption_method": "NONE",
    "voice_enabled": false,
    "sms_signing_hash": "NONE",
    "sms_encryption_method": "NONE",
    "voice_identity": "johndoe",
    "mms_name": "John Doe",
    "mms_auth_method": "NONE",
    "mms_protocol": "NONE",
    "voice_name": "John Doe",
    "voice_secret": "super$ecret",
    "sms_name": "John Doe",
    "mms_signing_hash": "NONE",
    "mms_data": "mm4://example.com:2525",
    "sms_protocol": "NONE",
    "sms_identity": "johndoe",
    "sms_options": {
      "dlr_on_sent": false,
      "forward_dlr": true,
      "pad_shortcodes": false
    },
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  },
  "type": "switch"
}

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

Components

SMS

Protocols

SMS offers two major delivery protocols, SMPP and HTTP.

SMPP

SMPP, short for Short-Message-Peer-To-Peer-Protocol is the industry standard for transporting SMS across the internet.

Tychron offers an SMSC (that is a Short-Message-Service-Center) for clients to connect to using their ESME.

SMPP has the benefit of keeping persistent connection up making for high-throughput messaging.

However, it can be quite cumbersome to work with, some features that are provided by the HTTP protocol are also omitted, for example UDH (i.e. concatentated messages) will be transported in their raw split form over SMPP, but will be transported whole (i.e. all message parts) at once to HTTP.

Clients are then required to combine message parts back together to form the entire message in SMPP, while HTTP has this done by the system already.

HTTP

HTTP, short for Hypertext-Transfer-Protocol allows delivering SMS messages over HTTP instead of SMPP.

Relatively easy to setup and utilize, the HTTP protocol will deliver sms messages and their delivery reports to a specified endpoint in a variety of formats.

Message Formats

Message formats only apply to HTTP Protocol messages.

Trinity JSON 1.0

The default format that will be delivered by the system to the client, this is also the format present on the Tychron Docs page.

Trinity POST 1.0

A compatability format.

Trinity POST 2.0

A compatability format.

MMS

Protocols

MM4

MM4, effectively a superset of Simple Mail Transfer Protocol is the industry standard for transferring MMS messages between MMSC (Multimedia-Message-Service-Center) relays.

HTTP

Delivers MMS messages over HTTP in a variety of message formats.

Message Formats

Message formats only apply to HTTP Protocol messages.

Oxy JSON 1.0

The default format that will be delivered by the sytsem to the lcient, this is also the format present on the Tychron Docs page.

Oxy JSONAPI 1.0

A compatability format, similar to the standard Oxy JSON 1.0 format.

Oxy XML 1.0

Experimental format, sends MMS messages as XML documents.

Oxy MULTIPART 1.0

Experimental format, sends MMS messages as HTTP multipart documents.

Oxy RFC822 1.0

Experimental format, sends MMS messages as their raw RFC822 blob

Voice

Switches may enable and provide a Voice fallback destination, this destination will be used as a last resort if the DID's destinations fail to answer.

Protocols

PSTN

PSTN sometimes called RCF (remote call forward) can be used to route a call to another phone number.

VoIP

VoIP routes a call to a SIP capable server to handle the call.

TTS

TTS will play a built-in message back when answered, note that TTS calls will not incur additional charges unlike it's Custom counterpart.

TTS Custom

TTS Custom allows the client to set a special message that should be played back to the caller.

Note that TTS Custom messages attract a per-character fee everytime the message is played, contact support for more information on these fees.

HTTP Route

HTTP Route allows the system to request a custom route from an HTTP Server, this route can be any of the other Voice protocols.

See DID Destination HTTP Routes for more information.

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