Schemas

The schemas below have been extracted from the openapi specification and formatted for easier consumption.

Schema / AddonsData

Some requests may allow specifying "addons", these are additional functions or features that are provisioned with the numbers once they have become available.

An example would be to immediately provision numbers for messaging in a NEW_NUMBERS request.

Type Object

Desc. messaging

The messaging section affects the enablement of SMS, MMS and adding DIDs to Campaigns.

Note typically these properties may be offloaded to a ADD_MESSAGING_NUMBERS request, so all rules from that request apply to this section where applicable.

Desc. voip_destinations

The VoIP Destinations Addons allows configuring the VoIP Destinations on a DID once it's considered generally available.

messaging

Desc. api_key_ids

A list of API Keys that should be assigned to the DIDs.

Desc. csp_campaign_id

Tychron issued ID of a Campaign that should be assigned to the DIDs.

Desc. enabled

Whether or not this addon should be applied.

Desc. mms_enabled

Should MMS be enabled on the DIDs?

Desc. notes

Any notes about the messaging addon, this will be copied into the ADD_MESSAGING_NUMBERS requests.

Desc. switch_id

The ID of the messaging Switch that should be assigned to the DIDs.

Desc. tcr_campaign_id

TCR Campaign ID of the Campaign that should be assigned to the DIDs.

voip_destinations

SubObject

Sub-Schema

Destination configuration parameters.

Type Object

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. 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. destinations

A list of DID Destinations that should be assigned to the DIDs upon creation.

Desc. enabled

Whether or not the VoIP Destinations should be configured.

Desc. switch_id

The ID of the VoIP Fallback Switch that should be assigned to DIDs.

Example

{
  "messaging": {
    "api_key_ids": [
      "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    ],
    "csp_campaign_id": "string",
    "enabled": false,
    "mms_enabled": true,
    "notes": "This is for a state child support centre and will be enabled on Campaign X.\n",
    "switch_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "tcr_campaign_id": "C000000"
  },
  "voip_destinations": {
    "destinations": [
      {
        "activated": true,
        "auth_identity": "username",
        "auth_method": "BASIC",
        "auth_secret": "password",
        "destination": "http://example.com/http/route/call",
        "priority": 1,
        "type": "HTTP_ROUTE"
      }
    ],
    "enabled": true,
    "switch_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  }
}

Schema / ApiKey

An set of authorization details for various APIs

Type Object

Desc. id

A Universally unique identifier, which identifies the resource

Desc. identity

Acts as the username in the authorization pair for MM4

Desc. notes

Any notes about the API Key, like, what it is used for, or other sharable details.

Desc. smpp_system_id

Small identifier used when authorizing an SMPP connection

Example

{
  "active": true,
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
  "name": "My API Key",
  "notes": "This API Key is used for the west datacenter's SMS notifications.",
  "smpp_system_id": "EIIGBT24ZH242U5",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / ApiKeyResponse

Single API Key

Type Object

Example

{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}

Schema / ApiKeysResponse

API Keys

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "active": true,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
        "name": "My API Key",
        "notes": "This API Key is used for the west datacenter's SMS notifications.",
        "smpp_system_id": "EIIGBT24ZH242U5",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "api_key"
    }
  ]
}

Schema / AttachSwitchMmsEncryptionKeyData

Parameters for attaching a Secret Key to a Switch for MMS Encryption

Type Object

Example

{
  "mms_encryption_method": "NONE"
}

Schema / AttachSwitchMmsEncryptionKeyRequest

Request for attaching a Secret Key to a switch for MMS Encryption

Type Object

Example

{
  "data": {
    "mms_encryption_method": "NONE"
  },
  "type": "switch"
}

Schema / AttachSwitchMmsSigningKeyData

Parameters for attaching a Secret Key to a Switch for MMS Signing

Type Object

Example

{
  "mms_signing_hash": "NONE",
  "mms_signing_scheme": "NONE"
}

Schema / AttachSwitchMmsSigningKeyRequest

Request for attaching a Secret Key to a switch for MMS Signing

Type Object

Example

{
  "data": {
    "mms_signing_hash": "NONE",
    "mms_signing_scheme": "NONE"
  },
  "type": "switch"
}

Schema / AttachSwitchSmsEncryptionKeyData

Parameters for attaching a Secret Key to a Switch for SMS Encryption

Type Object

Example

{
  "sms_encryption_method": "NONE"
}

Schema / AttachSwitchSmsEncryptionKeyRequest

Request for attaching a Secret Key to a switch for SMS Encryption

Type Object

Example

{
  "data": {
    "sms_encryption_method": "NONE"
  },
  "type": "switch"
}

Schema / AttachSwitchSmsSigningKeyData

Parameters for attaching a Secret Key to a Switch for SMS Signing

Type Object

Example

{
  "sms_signing_hash": "NONE",
  "sms_signing_scheme": "NONE"
}

Schema / AttachSwitchSmsSigningKeyRequest

Request for attaching a Secret Key to a switch for SMS Signing

Type Object

Example

{
  "data": {
    "sms_signing_hash": "NONE",
    "sms_signing_scheme": "NONE"
  },
  "type": "switch"
}

Schema / BulkDipTask

A Bulk Dip Task is a long-running asynchronous request, numbers are specified in the request and will be dipped by the system internally, once completed, the result will be handled via the on_done_actions.

Note that it is possible to create a Bulk Dip Task without an on_done_action, this will effectively perform a no-op, you will still be charged for the dips, but nothing will be delivered.

Type Object

Desc. enable_cdr_export

Should CDRs generated by the bulk dip process be sent to the CDR Webhook?

By default this is disabled.

Note. This will generate CDRs while the task is processing.

Desc. enhanced

Used for LRN type, enables enhanced lookup.

Please consult the LRN documentation for additional details.

Desc. error_code

• OK - there was no error
• BAD_SOURCE_FILE - there was an issue with the source file

Desc. format

The intended exported format, CSV will export a CSV file as expected. MLJSON exports the cdrs as Multiline-JSON, that is each row in the file is a single record encoded as JSON.

• CSV
• MLJSON

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. messaging_lookup

Used for LRN type, enables messaging lookup, MCL will be added.

Please consult the LRN documentation for additional details.

Desc. reference_id

A unique client provided id for the bulk task.

There is no particular format that is enforced, a general recommendation is to avoid spaces and non-ASCII characters for best experience.

Enum Values status

Allowed values

• NEW
• SCHEDULED
• PROCESSING
• STORING
• DELIVERING
• COMPLETED
• ABORTED
• ERROR

Desc. status

Status gives a brief overview of the state of the task.

• NEW - the export task was freshly created and has not begun processing
• SCHEDULED - the task has been scheduled to execute at a later time (see date field for more information)
• PROCESSING - the task has begun processing
• STORING - the task is currently storing its results on internal storage for later access
• DELIVERING - the task is now attempting to deliver the exported file to the given endpoints (or notifying)
• COMPLETED - the task is completed and it is safe to delete or retrieve the exported details
• ABORTED - the task was aborted, execution was halted
• ERROR - the task experienced an error, error_code will have more details if any

Desc. type

The type of bulk dip that should be performed:

• LRN - Location Routing Number lookups
• MCL - Messaging Carrier Lookup
• CNAM - Caller Name

Example

{
  "done_at": "2021-08-13T04:08:44.762841Z",
  "enable_cdr_export": false,
  "enhanced": false,
  "error_code": "OK",
  "format": "CSV",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "messaging_lookup": false,
  "numbers": [
    "12003004000"
  ],
  "on_done_actions": [
    {
      "archive_format": "TAR_GZ",
      "auth_identity": "upload-user",
      "auth_method": "BASIC",
      "auth_secret": "supersecretsauce",
      "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
      "error_code": "OK",
      "filename": "string",
      "protocol": "SFTP",
      "reference_id": "SFTP-export-action",
      "status": "NEW",
      "type": "SEND"
    }
  ],
  "reference_id": "lrn-bulk-LRN-2022-10-14",
  "status": "NEW",
  "type": "LRN",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / BulkDipTaskResponse

Single Bulk Dip Task

Type Object

Example

{
  "data": {
    "done_at": "2021-08-13T04:08:44.762841Z",
    "enable_cdr_export": false,
    "enhanced": false,
    "error_code": "OK",
    "format": "CSV",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "messaging_lookup": false,
    "numbers": [
      "12003004000"
    ],
    "on_done_actions": [
      {
        "archive_format": "TAR_GZ",
        "auth_identity": "upload-user",
        "auth_method": "BASIC",
        "auth_secret": "supersecretsauce",
        "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
        "error_code": "OK",
        "filename": "string",
        "protocol": "SFTP",
        "reference_id": "SFTP-export-action",
        "status": "NEW",
        "type": "SEND"
      }
    ],
    "reference_id": "lrn-bulk-LRN-2022-10-14",
    "status": "NEW",
    "type": "LRN",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "bulk_dip_task"
}

Schema / BulkDipTasksResponse

Bulk Dip Tasks

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "done_at": "2021-08-13T04:08:44.762841Z",
        "enable_cdr_export": false,
        "enhanced": false,
        "error_code": "OK",
        "format": "CSV",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "messaging_lookup": false,
        "numbers": [
          "12003004000"
        ],
        "on_done_actions": [
          {
            "archive_format": "TAR_GZ",
            "auth_identity": "upload-user",
            "auth_method": "BASIC",
            "auth_secret": "supersecretsauce",
            "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
            "error_code": "OK",
            "filename": "string",
            "protocol": "SFTP",
            "reference_id": "SFTP-export-action",
            "status": "NEW",
            "type": "SEND"
          }
        ],
        "reference_id": "lrn-bulk-LRN-2022-10-14",
        "status": "NEW",
        "type": "LRN",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "bulk_dip_task"
    }
  ]
}

Schema / CDR

A single call data record

Type Object

Desc. host_number

Depending on the CDR type, this can be an actual phone number or some other value

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. item_count

How many items does this CDR actually represent

Desc. item_id

Depending on the CDR type, this will be the id of another record

Desc. remote_number

Depending on the CDR type, this can be an actual phone number or some other value

Desc. sell_rate

The base rate (no fees or surcharges), already includes the count

Enum Values status

Allowed values

• UNKNOWN
• OK
• MISS
• ERROR
• REFUND
• NO_ANSWER
• BUSY
• CANCELLED
• CHANNEL_UNAVAILABLE
• CONGESTION
• TEMP_FAILURE

Enum Values subtype

Allowed values

• NONE
• LRN
• LRNE
• MESSAGING_CARRIER_LOOKUP
• CNAM
• TTS
• OUTBOUND
• INBOUND
• TERMINATION
• SIP_IAX
• DID_RCF
• DID_VOIP
• CALLBACK
• DID
• CHARGE
• PREPAYMENT
• TAX
• PAYMENT
• ADJUSTMENT
• DID_REGISTRY
• DID_REGISTRY_NRC
• DID_REGISTRY_A_MRC
• DEDICATED_ESPID
• DEDICATED_ESPID_NRC
• DEDICATED_ESPID_A_MRC
• DID_TIER
• DID_TIER_NRC
• DID_TIER_A_MRC
• CSP_BRAND
• CSP_BRAND_A_MRC
• CSP_BRAND_VETTING
• CSP_CAMPAIGN
• CSP_CAMPAIGN_MRC
• CSP_CAMPAIGN_A_MRC

Desc. subtype

Further refines the CDR type, depending on what the

Desc. total

The total amount charged (sell_rate+fees+surcharges)

Enum Values type

Allowed values

• API
• MMS
• SMS
• VOICE
• BALANCE
• MISC

Desc. type

The main category that the CDR belongs to.

Example

{
  "fees": [
    {
      "cost": "0.000100",
      "name": "extra_cheese"
    }
  ],
  "host_number": "12003004000",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "item_count": 1,
  "item_id": "01FCYT490ZK2NYF0BFYRFFAJZ8",
  "remote_number": "12003004001",
  "sell_rate": "0.000900",
  "status": "UNKNOWN",
  "subtype": "NONE",
  "surcharges": [
    {
      "cost": "0.000100",
      "name": "ACME Corp"
    }
  ],
  "total": "0.000900",
  "type": "API",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / CDRFee

Represents a single fee in a CDR

Type Object

Example

{
  "cost": "0.000100",
  "name": "extra_cheese"
}

Schema / CDRLookupResultResponse

Single cdr

Type Object

Desc. lookups

Contains a copy of the CDR's dip result, note only API CDRs are supported

Example

{
  "cdr": {
    "associations": {
      "api_key": {
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
      }
    },
    "data": {
      "fees": [
        {
          "cost": "0.000100",
          "name": "extra_cheese"
        }
      ],
      "host_number": "12003004000",
      "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
      "inserted_at": "2021-08-13T04:08:44.762841Z",
      "item_count": 1,
      "item_id": "01FCYT490ZK2NYF0BFYRFFAJZ8",
      "remote_number": "12003004001",
      "sell_rate": "0.000900",
      "status": "UNKNOWN",
      "subtype": "NONE",
      "surcharges": [
        {
          "cost": "0.000100",
          "name": "ACME Corp"
        }
      ],
      "total": "0.000900",
      "type": "API",
      "updated_at": "2021-08-13T04:08:44.762841Z"
    },
    "type": "cdr"
  },
  "lookups": []
}

Schema / CDRResponse

Single CDR record

Type Object

associations

api_key

Desc. id

The UUID of the API Key associated with the CDR.

API Key may not be populated in some cases where an API is not readily available.

For example CDRs for INBOUND messages will typically not have their API Key populated.

Example

{
  "associations": {
    "api_key": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "fees": [
      {
        "cost": "0.000100",
        "name": "extra_cheese"
      }
    ],
    "host_number": "12003004000",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "item_count": 1,
    "item_id": "01FCYT490ZK2NYF0BFYRFFAJZ8",
    "remote_number": "12003004001",
    "sell_rate": "0.000900",
    "status": "UNKNOWN",
    "subtype": "NONE",
    "surcharges": [
      {
        "cost": "0.000100",
        "name": "ACME Corp"
      }
    ],
    "total": "0.000900",
    "type": "API",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cdr"
}

Schema / CDRSurcharge

Represents a single surcharge in a CDR

Type Object

Example

{
  "cost": "0.000100",
  "name": "ACME Corp"
}

Schema / CDRsResponse

CDRs

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "api_key": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        }
      },
      "data": {
        "fees": [
          {
            "cost": "0.000100",
            "name": "extra_cheese"
          }
        ],
        "host_number": "12003004000",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "item_count": 1,
        "item_id": "01FCYT490ZK2NYF0BFYRFFAJZ8",
        "remote_number": "12003004001",
        "sell_rate": "0.000900",
        "status": "UNKNOWN",
        "subtype": "NONE",
        "surcharges": [
          {
            "cost": "0.000100",
            "name": "ACME Corp"
          }
        ],
        "total": "0.000900",
        "type": "API",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "cdr"
    }
  ]
}

Schema / CSPCampaignOptoutItem

A record representing an opt-out for a host and remote number pair under a campaign.

Optouts may be manually added or may be triggered by the remote_number to stop receiving messages.

Type Object

Desc. host_number

A reference to the host number that this optout belongs to.

That is the number that received the optout request.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. keyword

If the optout was triggered by the system, this field will be populated with the keyword used.

Will be some variant of STOP normally.

For more information about keywords and their handling, contact support.

Desc. remote_number

The client number that sent the optout, or is opted out of receiving messages from the host number

Desc. tcr_campaign_id

The Campaign ID, as issued by TCR.

Example

{
  "host_number": "12003004000",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "keyword": "STOP",
  "remote_number": "12003004001",
  "tcr_campaign_id": "C012345",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / CSPCampaignOptoutItemResponse

Single Optout Item

Type Object

associations

Desc. csp_campaign

A reference to the csp campaign that this optout belongs to.

Desc. host_did

A reference to the host number (did) that may have originated the optout.

Desc. sms

If the optout was triggered by an SMS, this association will be set.

Otherwise it will be null.

Note that the SMS may be removed if outside the creation month.

csp_campaign

Desc. id

A Universally unique identifier, which identifies the resource

Desc. tcr_campaign_id

TCR Campaign ID, of the associated campaign.

host_did

Desc. id

A Universally unique identifier, which identifies the resource

Desc. number

Will match the host_number from the optout item, may not be set under certain circumstances.

sms

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Example

{
  "associations": {
    "csp_campaign": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "tcr_campaign_id": "C012345"
    },
    "host_did": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "number": "12003004000"
    },
    "sms": {
      "id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
    }
  },
  "data": {
    "host_number": "12003004000",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keyword": "STOP",
    "remote_number": "12003004001",
    "tcr_campaign_id": "C012345",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "number_optout_item"
}

Schema / CSPCampaignOptoutItemsResponse

CSP Campaign Optout Items

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "csp_campaign": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
          "tcr_campaign_id": "C012345"
        },
        "host_did": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
          "number": "12003004000"
        },
        "sms": {
          "id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
        }
      },
      "data": {
        "host_number": "12003004000",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "keyword": "STOP",
        "remote_number": "12003004001",
        "tcr_campaign_id": "C012345",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "number_optout_item"
    }
  ]
}

Schema / CallDataWebhook

A Call Data Webhook is a registered endpoint where CDRs should be sent once billed by the system.

Prior to July 6, 2026, this would ONLY send SMS and MMS CDRs.

Bulk Dip Tasks can be configured to send their generated CDRs with a enable_cdr_export flag.

LRN, CNAM and MRL can similarly be enabled with the same flag: enable_cdr_export on the request.

Type Object

Desc. auth_identity

Acts a the username in an authorization pair, only applicable if the auth method is BASIC.

Desc. auth_method

Depending on the protocol, this will affect the authorization behaviour.

• NONE - no authorization is provided if not required, otherwise placeholder values will be used
• BASIC - the auth_identity acts as the username while the auth_secret acts as the password
• With HTTP - an Authorization: Basic <BASE64-VALUE> header will be set
• With SFTP - the session will be authenticated using the auth_identity and auth_secret
• BEARER - the auth_identity is ignored and only the auth_secret is used verbatim
• With HTTP - an Authorization: Bearer <VALUE> header will be set
• with SFTP - the username will be a placeholder value and the password will be set

Desc. auth_name

Reserved for other protocols that may require additional auth information.

Desc. auth_secret

Acts as the password in an authorization pair, if using BEARER, it will be the verbatim token.

SubObject

Sub-Schema

Type Object

Desc. custom_headers

A list of custom header values that should be sent on the HTTP request.

Headers are currently unused if the protocol is not HTTP.

SubObject

Sub-Schema

Type Object

Desc. custom_query_params

A list of custom query parameters that should be sent on the HTTP request.

These are currently unused if the protocol is not HTTP.

Desc. data

Depending on the protocol, this will contain the url or address of the endpoint.

For HTTP, it will be an http url, as for SFTP, it will be the hostname and optionally the port.

• HTTP - (e.g. "http://example.com/path/to/upload")
• SFTP - (e.g. "sftp://sftp.example.com/path/to/upload")

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. name

A display name for the call data webhook, used purely for identifying it.

Desc. notes

Any notes or details about the call data webhook.

Desc. protocol

The transport protocol which should be used to send

• NONE - Effectively a no-op.
• HTTP - Send CDRs over HTTP.
• SFTP - Upload CDRs over SFTP.

Example

{
  "auth_identity": "string",
  "auth_method": "NONE",
  "auth_name": "string",
  "auth_secret": "string",
  "custom_headers": [
    {
      "key": "x-my-header",
      "value": "Anything"
    }
  ],
  "custom_query_params": [
    {
      "key": "x-my-header",
      "value": "Anything"
    }
  ],
  "data": "string",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "CDR Webhook us-east",
  "notes": "string",
  "protocol": "NONE",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / CallDataWebhookResponse

Single Call Data Webhook

Type Object

Example

{
  "data": {
    "auth_identity": "string",
    "auth_method": "NONE",
    "auth_name": "string",
    "auth_secret": "string",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "Anything"
      }
    ],
    "custom_query_params": [
      {
        "key": "x-my-header",
        "value": "Anything"
      }
    ],
    "data": "string",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "CDR Webhook us-east",
    "notes": "string",
    "protocol": "NONE",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "call_data_webhook"
}

Schema / CallDataWebhooksResponse

Call Data Webhooks

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "auth_identity": "string",
        "auth_method": "NONE",
        "auth_name": "string",
        "auth_secret": "string",
        "custom_headers": [
          {
            "key": "x-my-header",
            "value": "Anything"
          }
        ],
        "custom_query_params": [
          {
            "key": "x-my-header",
            "value": "Anything"
          }
        ],
        "data": "string",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "CDR Webhook us-east",
        "notes": "string",
        "protocol": "NONE",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "call_data_webhook"
    }
  ]
}

Schema / Cart

An order being prepared for checkout.

Type Object

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. name

A unique name identifying the cart, must be unique to the account

Desc. notes

Any additional information about the request, may be read by an operations personel in case of manual action

Example

{
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "My New Order",
  "notes": "string",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / CartRequest

A request being prepared in a cart

Type Object

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

One-Of

Types

• CartRequestAddCampaignNumbersData
• CartRequestAddMessagingNumbersData
• CartRequestAddVoiceNumbersData
• CartRequestNewNumbersData
• CartRequestRegisterBrandData
• CartRequestRegisterCampaignData
• CartRequestRemoveCampaignNumbersData
• CartRequestRemoveMessagingNumbersData
• CartRequestRemoveNumbersData
• CartRequestRemoveVoiceNumbersData
• CartRequestUnregisterBrandData
• CartRequestUnregisterCampaignData
• CartRequestVetBrandData

Example

{
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "string",
  "notes": "string",
  "type": "ADD_CAMPAIGN_NUMBERS",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "*": {
    "numbers": [
      "12003004000"
    ],
    "*": {
      "tcr_campaign_id": "C000000"
    }
  }
}

Schema / CartRequestAddCampaignNumbersData

Request for registering numbers under a TCR Campaign.

Campaigns must be known to Tychron before submitting this request, either: * Via sharing * Provisioned by Tychron directly

Type Object

Desc. numbers

A list of NANP 11-digit numbers to add campaigns to.

Keep in mind, campaigns are only supported on non-tollfree TenDLC numbers.

For example: 12003004000.

... tcr_campaign_id

Sub-Schema

Type Object

Desc. tcr_campaign_id

The TCR issued Campaign ID, typically in the form of CNNNNNN.

• This field will be backfilled if campaign_id is provided instead.
• If this field AND campaign_id are provided they must resolve to the same campaign.

... campaign_id

Sub-Schema

Type Object

Desc. campaign_id

The internal UUID of a known campaign.

• This field will be backfilled if tcr_campaign_id is provided instead.
• If this field AND tcr_campaign_id are provided they must resolve to the same campaign.

One-Of

Types

• ... tcr_campaign_id
• ... campaign_id

Example

{
  "numbers": [
    "12003004000"
  ],
  "*": {
    "tcr_campaign_id": "C000000"
  }
}

Schema / CartRequestAddMessagingNumbersData

Request for enabling messaging on existing or new numbers; new numbers will be created as needed

Type Object

Desc. api_key_ids

A list of API Keys that should be bound to the numbers once enabled.

If the number is already bound to the listed keys, then nothing will change.

Note that this will add new keys and not replace the existing bindings.

Desc. message_class

The messaging class of the numbers to be provisioned, by default this will be A2P.

• A2P - Application to Person
• P2P - Person to Person

Desc. mms_enabled

Should the numbers be MMS enabled?

MMS can also be enabled later by simply toggling it via the DID API.

Note. If your account does not support MMS by default, then toggling this flag does nothing.

Desc. numbers

A list of NANP 11-digit numbers to enable messaging on.

Non-tollfree numbers can normally be enabled outside of some special cases.

For tollfree, additional action may be required before completion.

Desc. switch_id

The ID of the switch that should be attached to the did for messaging.

Note. This changes the DID's messaging switch, not its voice fallback one.

Leaving this field blank will not overwrite the existing switch.

Example

{
  "api_key_ids": [
    "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  ],
  "message_class": "A2P",
  "mms_enabled": false,
  "numbers": [
    "12003004000"
  ],
  "switch_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
}

Schema / CartRequestAddVoiceNumbersData

Request for enabling voice BYOC (Bring Your Own Carrier) numbers

Type Object

Desc. numbers

A list of NANP 11-digit numbers to add

Desc. switch_id

The ID of the switch that should be attached to the did for voice fallback

Example

{
  "numbers": [
    "12003004000"
  ],
  "switch_id": "9cdb55c0-6e15-4513-8430-4152fc8e07d3"
}

Schema / CartRequestNewNumbersData

Request for acquiring new numbers by search parameters.

Note. While only the quantity is mentioned as required, additional search parameters SHOULD be provided.

Those are: * state - the 2 character state code (e.g. IL, FL, WA) * rate_center - the 9 character rate center code * npa - the 3 digit Area Code (e.g. 455) * nxx - the 3 digit Exchange Code (e.g. 400)

Type Object

Example

{
  "state": "string"
}

Schema / CartRequestRegisterBrandData

Request for registering a new CSP Brand.

Type Object

Example

{
  "address1": "string",
  "alt_business_id": "string",
  "alt_business_id_type": "string",
  "brand_relationship": "string",
  "business_contact_email": "string",
  "city": "string",
  "company_name": "ACME Corp",
  "country_code": "string",
  "display_name": "ACME Corp Brand",
  "ein": "00000000",
  "ein_issuing_country_code": "US",
  "email": "string",
  "entity_type": "string",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "12003004000",
  "state": "string",
  "stock_exchange": "string",
  "stock_symbol": "string",
  "vertical": "string",
  "website": "string",
  "zip_code": "string"
}

Schema / CartRequestRegisterCampaignData

Request for registering a TCR Campaign.

Please note that TCR's Terms And Conditions must be accepted via the terms_and_conditions field in order to register a campaign, the request will be rejected otherwise.

Note some fields are not marked as mandatory due to their hybrid validation requirements.

• tcr_reseller_id - Pairs with reseller_id
• tcr_brand_id - Pairs with brand_id

When these hybrid fields care used either the tcr_* or the base field or BOTH can be used.

That is, to specify a reseller, you may provide its TCR ID (e.g. R00000) or it's UUID (e.g. 00000000-0000-4000-0000-000000000000), or both can be provided.

In the case that both fields are specified, they MUST resolve to the same record.

Please note, brand and reseller are MANDATORY, but must be specified by one or both of its respective fields.

Type Object

Desc. help_keywords

Must be a CSV, that is a comma separated list of keywords.

Excess spaces will be trimmed around each keyword.

Desc. optin_keywords

Must be a CSV, that is a comma separated list of keywords.

Excess spaces will be trimmed around each keyword.

Desc. optout_keywords

Must be a CSV, that is a comma separated list of keywords.

Excess spaces will be trimmed around each keyword.

Desc. tcr_brand_id

TCR issued Brand ID.

Desc. tcr_reseller_id

TCR issued Reseller ID.

Desc. terms_and_conditions

Do you accept TCR's Terms and Conditions, this flag MUST be true in order to register a campaign.

If false the campaign will not be accepted for registration.

Example

{
  "affiliate_marketing": false,
  "age_gated": false,
  "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "description": "string",
  "direct_lending": false,
  "embedded_link": false,
  "embedded_link_sample": "string",
  "embedded_phone": false,
  "help_keywords": "HELP,INFO",
  "help_message": "string",
  "message_flow": "string",
  "mno_ids": [
    "string"
  ],
  "number_pool": false,
  "optin_keywords": "OPTIN,START,SUBSCRIBE",
  "optin_message": "string",
  "optout_keywords": "OPTOUT,STOP,UNSUBSCRIBE",
  "optout_message": "string",
  "privacy_policy_link": "string",
  "reseller_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "samples": [
    "string"
  ],
  "sub_use_cases": [
    "string"
  ],
  "subscriber_help": false,
  "subscriber_optin": false,
  "subscriber_optout": false,
  "tcr_brand_id": "B000000",
  "tcr_reseller_id": "R000000",
  "terms_and_conditions": false,
  "terms_and_conditions_link": "string",
  "use_case": "string"
}

Schema / CartRequestRemoveCampaignNumbersData

Request for removing numbers from an existing campaign.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to disable messaging for

Example

{
  "numbers": [
    "12003004000"
  ]
}

Schema / CartRequestRemoveMessagingNumbersData

Request for disabling messaging on existing numbers.

Note that this will also remove numbers from their campaign automatically.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to disable messaging for

Example

{
  "numbers": [
    "12003004000"
  ]
}

Schema / CartRequestRemoveNumbersData

Request for removing numbers and all of their components from the system.

This request should be used if you wish to completely remove a number and all of its components.

This request can be used to remove voice-only or messaging-only numbers as well, and should be preferred in those cases.

The request itself will create the respective removal requests during processing.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to remove

Example

{
  "numbers": [
    "12003004000"
  ]
}

Schema / CartRequestRemoveVoiceNumbersData

Request for removing voice-only numbers.

Voice-only numbers are typically enabled using ADD_VOICE_NUMBERS.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to remove

Example

{
  "numbers": [
    "12003004000"
  ]
}

Schema / CartRequestResponse

Single request

Type Object

Example

{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "string",
    "notes": "string",
    "type": "ADD_CAMPAIGN_NUMBERS",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "*": {
      "numbers": [
        "12003004000"
      ],
      "*": {
        "tcr_campaign_id": "C000000"
      }
    }
  },
  "type": "request"
}

Schema / CartRequestUnregisterBrandData

Request for unregistering a TCR Brand.

Either the brand_id (UUID) or the tcr_brand_id can be provided to lookup the brand for removal.

Type Object

Example

{
  "tcr_brand_id": "B000000"
}

Schema / CartRequestUnregisterCampaignData

Request for unregistering a TCR Campaign.

Either the campaign_id (UUID) or the tcr_campaign_id can be provided to lookup the respective campaign for removal.

Type Object

Example

{
  "tcr_campaign_id": "B000000"
}

Schema / CartRequestVetBrandData

Request for vetting a TCR Brand.

Either the brand_id (UUID) or the tcr_brand_id can be provided to lookup the brand for removal.

Type Object

Desc. tcr_evp_id

The External Vetting Provider that should perform the brand's vetting.

Desc. vetting_class

Depending on the selected vetting provider, the available vetting classes may change.

Example

{
  "tcr_evp_id": "AEGIS",
  "vetting_class": "STANDARD",
  "tcr_brand_id": "B000000"
}

Schema / CartRequestsResponse

Requests

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "string",
        "notes": "string",
        "type": "ADD_CAMPAIGN_NUMBERS",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "*": {
          "numbers": [
            "12003004000"
          ],
          "*": {
            "tcr_campaign_id": "C000000"
          }
        }
      },
      "type": "request"
    }
  ]
}

Schema / CartResponse

Single cart

Type Object

Example

{
  "data": {
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My New Order",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "cart"
}

Schema / CartsResponse

Carts

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "My New Order",
        "notes": "string",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "cart"
    }
  ]
}

Schema / CreateApiKeyData

Parameters for updating an api key

Type Object

Example

{
  "active": false,
  "name": "string",
  "notes": "string"
}

Schema / CreateApiKeyRequest

Request for update an existing API Key

Type Object

Example

{
  "data": {
    "active": false,
    "name": "string",
    "notes": "string"
  },
  "type": "api_key"
}

Schema / CreateApiKeyResponse

Newly created API Key

Type Object

Example

{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "secret": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "smpp_secert": "FDJX6MO4",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}

Schema / CreateBulkDipTaskData

Parameters for creating a new export task.

Type Object

Desc. enhanced

Used for LRN type, enables enhanced lookup.

Please consult the LRN documentation for additional details.

Desc. format

The intended exported format, CSV will export a CSV file as expected. MLJSON exports the cdrs as Multiline-JSON, that is each row in the file is a single record encoded as JSON.

• CSV
• MLJSON

Desc. messaging_lookup

Used for LRN type, enables messaging lookup, MCL will be added.

Please consult the LRN documentation for additional details.

Desc. reference_id

A unique client provided id for the bulk task.

There is no particular format that is enforced, a general recommendation is to avoid spaces and non-ASCII characters for best experience.

Desc. type

The type of bulk dip that should be performed:

• LRN - Location Routing Number lookups
• MCL - Messaging Carrier Lookup
• CNAM - Caller Name

Example

{
  "enhanced": false,
  "format": "CSV",
  "messaging_lookup": false,
  "numbers": [
    "12003004000"
  ],
  "on_done_actions": [
    {
      "archive_format": "TAR_GZ",
      "auth_identity": "upload-user",
      "auth_method": "BASIC",
      "auth_secret": "supersecretsauce",
      "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
      "filename": "string",
      "protocol": "SFTP",
      "reference_id": "SFTP-export-action",
      "type": "SEND"
    }
  ],
  "reference_id": "lrn-bulk-LRN-2022-10-14",
  "type": "LRN"
}

Schema / CreateBulkDipTaskRequest

Request for creating a new Bulk Dip Task

Type Object

Example

{
  "data": {
    "enhanced": false,
    "format": "CSV",
    "messaging_lookup": false,
    "numbers": [
      "12003004000"
    ],
    "on_done_actions": [
      {
        "archive_format": "TAR_GZ",
        "auth_identity": "upload-user",
        "auth_method": "BASIC",
        "auth_secret": "supersecretsauce",
        "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
        "filename": "string",
        "protocol": "SFTP",
        "reference_id": "SFTP-export-action",
        "type": "SEND"
      }
    ],
    "reference_id": "lrn-bulk-LRN-2022-10-14",
    "type": "LRN"
  },
  "type": "bulk_dip_task"
}

Schema / CreateCallDataWebhookData

Parameters for creating a new Call Data Webhook.

Type Object

Desc. auth_identity

Acts a the username in an authorization pair, only applicable if the auth method is BASIC.

Desc. auth_method

Depending on the protocol, this will affect the authorization behaviour.

• NONE - no authorization is provided if not required, otherwise placeholder values will be used
• BASIC - the auth_identity acts as the username while the auth_secret acts as the password
• With HTTP - an Authorization: Basic <BASE64-VALUE> header will be set
• With SFTP - the session will be authenticated using the auth_identity and auth_secret
• BEARER - the auth_identity is ignored and only the auth_secret is used verbatim
• With HTTP - an Authorization: Bearer <VALUE> header will be set
• with SFTP - the username will be a placeholder value and the password will be set

Desc. auth_name

Reserved for other protocols that may require additional auth information.

Desc. auth_secret

Acts as the password in an authorization pair, if using BEARER, it will be the verbatim token.

SubObject

Sub-Schema

Type Object

Desc. custom_headers

A list of custom header values that should be sent on the HTTP request.

Headers are currently unused if the protocol is not HTTP.

SubObject

Sub-Schema

Type Object

Desc. custom_query_params

A list of custom query parameters that should be sent on the HTTP request.

These are currently unused if the protocol is not HTTP.

Desc. data

Depending on the protocol, this will contain the url or address of the endpoint.

For HTTP, it will be an http url, as for SFTP, it will be the hostname and optionally the port.

• HTTP - (e.g. "http://example.com/path/to/upload")
• SFTP - (e.g. "sftp://sftp.example.com/path/to/upload")

Desc. name

A display name for the call data webhook, used purely for identifying it.

Desc. notes

Any notes or details about the call data webhook.

Desc. protocol

The transport protocol which should be used to send

• NONE - Effectively a no-op.
• HTTP - Send CDRs over HTTP.
• SFTP - Upload CDRs over SFTP.

Example

{
  "auth_identity": "string",
  "auth_method": "NONE",
  "auth_name": "string",
  "auth_secret": "string",
  "custom_headers": [
    {
      "key": "x-my-header",
      "value": "Anything"
    }
  ],
  "custom_query_params": [
    {
      "key": "x-my-header",
      "value": "Anything"
    }
  ],
  "data": "string",
  "name": "CDR Webhook us-east",
  "notes": "string",
  "protocol": "NONE"
}

Schema / CreateCallDataWebhookRequest

Request for creating a new Call Data Webhook

Type Object

Example

{
  "data": {
    "auth_identity": "string",
    "auth_method": "NONE",
    "auth_name": "string",
    "auth_secret": "string",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "Anything"
      }
    ],
    "custom_query_params": [
      {
        "key": "x-my-header",
        "value": "Anything"
      }
    ],
    "data": "string",
    "name": "CDR Webhook us-east",
    "notes": "string",
    "protocol": "NONE"
  },
  "type": "call_data_webhook"
}

Schema / CreateCartData

Request for creating a new cart

Type Object

Desc. notes

Optional information about the cart, or order.

Example

{
  "name": "string",
  "notes": "string"
}

Schema / CreateCartRequest

Request for creating a new cart

Type Object

Example

{
  "data": {
    "name": "string",
    "notes": "string"
  },
  "type": "cart"
}

Schema / CreateCartRequestData

Request for creating a new cart request

Type Object

One-Of

Types

• CartRequestAddCampaignNumbersData
• CartRequestAddMessagingNumbersData
• CartRequestAddVoiceNumbersData
• CartRequestNewNumbersData
• CartRequestRegisterBrandData
• CartRequestRegisterCampaignData
• CartRequestRemoveCampaignNumbersData
• CartRequestRemoveMessagingNumbersData
• CartRequestRemoveNumbersData
• CartRequestRemoveVoiceNumbersData
• CartRequestUnregisterBrandData
• CartRequestUnregisterCampaignData
• CartRequestVetBrandData

Example

{
  "name": "Add Messaging to 1200xxx numbers",
  "notes": "Some note about this request",
  "type": "ADD_CAMPAIGN_NUMBERS",
  "*": {
    "numbers": [
      "12003004000"
    ],
    "*": {
      "tcr_campaign_id": "C000000"
    }
  }
}

Schema / CreateCartRequestRequest

Request for creating a new cart

Type Object

Example

{
  "data": {
    "name": "Add Messaging to 1200xxx numbers",
    "notes": "Some note about this request",
    "type": "ADD_CAMPAIGN_NUMBERS",
    "*": {
      "numbers": [
        "12003004000"
      ],
      "*": {
        "tcr_campaign_id": "C000000"
      }
    }
  },
  "type": "request"
}

Schema / CreateDestinationRequest

Request for creating a new Number Destination

Type Object

Example

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

Schema / CreateExportTaskData

Parameters for creating a new export task.

Type Object

Desc. date

An ISO8601 formatted date. Determines which day's cdrs will be exported.

Note that if a current or future date is provided, the task will be deferred to the day AFTER the given date.

Desc. format

The intended exported format, CSV will export a CSV file as expected. MLJSON exports the cdrs as Multiline-JSON, that is each row in the file is a single CDR record encoded as JSON.

Desc. reference_id

A unique client provided id for the export task.

There is no particular format that is enforced, a general recommendation is to avoid spaces and non-ASCII characters for best experience.

Enum Values type

Allowed values

• API
• MMS
• SMS
• VOICE
• BALANCE
• MISC

Desc. type

The main type of CDR that should be exported

• API - contain any LRN, LRNE, CNAM related calls
• MMS - contain the billed details for MMS records
• SMS - contain the billed details for SMS records
• VOICE - contain any voice related calls (TERMINATION, DID*)
• BALANCE - any balance related changes, including payments, adjustments etc...
• MISC - contains various registry related feees

Example

{
  "date": "string",
  "format": "CSV",
  "on_done_actions": [
    {
      "archive_format": "TAR_GZ",
      "auth_identity": "upload-user",
      "auth_method": "BASIC",
      "auth_secret": "supersecretsauce",
      "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
      "filename": "string",
      "protocol": "SFTP",
      "reference_id": "SFTP-export-action",
      "type": "SEND"
    }
  ],
  "reference_id": "cdr-export-API-2022-03-14",
  "type": "API"
}

Schema / CreateExportTaskRequest

Request for creating a new CDR Export Task

Type Object

Example

{
  "data": {
    "date": "string",
    "format": "CSV",
    "on_done_actions": [
      {
        "archive_format": "TAR_GZ",
        "auth_identity": "upload-user",
        "auth_method": "BASIC",
        "auth_secret": "supersecretsauce",
        "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
        "filename": "string",
        "protocol": "SFTP",
        "reference_id": "SFTP-export-action",
        "type": "SEND"
      }
    ],
    "reference_id": "cdr-export-API-2022-03-14",
    "type": "API"
  },
  "type": "call_data_export_task"
}

Schema / CreateMessageRequest

Request for creating a new tts message

Type Object

Example

{
  "data": {
    "body": "Pre-answer Greeter",
    "priority": 1
  },
  "type": "tts_message"
}

Schema / CreateMessageSetRequest

Request for creating a new tts message set

Type Object

Example

{
  "data": {
    "name": "Pre-answer Greeter"
  },
  "type": "tts_message_set"
}

Schema / CreateOnDoneAction

Type Object

Desc. archive_format

Sometimes it is desirable to send the exported file in some kind of archive or compressed format.

This field can be set to configure that.

Otherwise the file will be returned in its raw form.

• NONE - no archive format, returns the file as-is (default)
• TAR - send the exported file in a tarball
• TAR_GZ - send the exported file in a gzipped tarball
• ZIP - send the exported file in a zipfile

Desc. auth_identity

See auth_method for details

Desc. auth_method

Working with the auth_identity and auth_secret fields, this forms the authorization details for the HTTP and SFTP uploaders.

• NONE - no authorization required HTTP protocol will not send an Authorization header SFTP protocol will default to username "tychron", and password "tychron" for its details
• BASIC - use "Basic" authorization, or a username + password pairing auth_identity will be the username auth_secret will be the password
• BEARER - use a "Bearer" authorization, that is, just the secret HTTP protocol will send a Authorization: Bearer <auth_secret> header SFTP will default its username to "tychron" and set the password as the auth_secret

Desc. auth_secret

See auth_method for details

Desc. data

Depending on the protocol used, this can be a url, or mailing address.

• NONE - empty
• HTTP - Must be a valid HTTP url, query parameters will be passed in as is
• SFTP - Must be of form:

sftp://hostname:port/subpath

Example 1:

Using default ssh port 22 and write the exported file under the given subpath. NOTE. the subpath MUST be created for the upload to complete no attempts will be made to create any new directories by sftp uploader.

sftp://example.com/sub/path/to/store/exported_file/in

Example 2:

Use the explictly set port 22 and write the exported file to wherever the client logged in.

sftp://example.com:22

Desc. filename

Optional override for SFTP filename.

Note. you are responsible for the extensions as well for any archive format it may have.

Desc. protocol

The specific transport protocol to use to delivery notifications or the exported file.

• NONE - use nothing
• HTTP - send notifications or files over HTTP
• SFTP - send exported files over SFTP

Desc. reference_id

Optional client provided id to identify the action.

Desc. type

What kind of action will this be?

• NONE - do nothing
• NOTIFY - notify the specified endpoint that the export has completed (only works with HTTP currently)
• SEND - send the exported file to the specified endpoint (HTTP or SFTP)

Example

{
  "archive_format": "TAR_GZ",
  "auth_identity": "upload-user",
  "auth_method": "BASIC",
  "auth_secret": "supersecretsauce",
  "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
  "filename": "string",
  "protocol": "SFTP",
  "reference_id": "SFTP-export-action",
  "type": "SEND"
}

Schema / CreateOnDoneActions

A list of sub-tasks that should be executed during the DELIVERING status of the task.

These can include: * Notifying a specified endpoint about the completion of the task * Delivering the exported file to a specified endpoint * Doing nothing at all

Type Array

Example

[
  {
    "archive_format": "TAR_GZ",
    "auth_identity": "upload-user",
    "auth_method": "BASIC",
    "auth_secret": "supersecretsauce",
    "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
    "filename": "string",
    "protocol": "SFTP",
    "reference_id": "SFTP-export-action",
    "type": "SEND"
  }
]

Schema / CreateOptoutItemData

Parameters for creating a Number Optout Item

Type Object

Desc. host_number

A reference to the host number that this optout belongs to.

That is the number that received the optout request.

Desc. remote_number

The client number that sent the optout, or is opted out of receiving messages from the host number

Example

{
  "host_number": "12003004000",
  "remote_number": "12003004001"
}

Schema / CreateOptoutItemRequest

Request for creating a new Number Optout Item

Type Object

Example

{
  "data": {
    "host_number": "12003004000",
    "remote_number": "12003004001"
  },
  "type": "number_optout_item"
}

Schema / CreateRequestDocumentRequest

Type Object

Desc. file

Any file is allowed, please note, files may be subject to scanning.

Do not be malicious.

Desc. file_hint

Depending on the request type, there may be a need for different document types.

• DEFAULT is the default, and means the uploaded file will be used for any "default" purposes
• MMS mms hints that the file is related to or to be used for mms purposes
• LOA the document is an loa

To clear things up, REGISTER_CAMPAIGN uses both types for different purposes: DEFAULT is used for all campaign supporting documents while MMS is used for its MMS sample content.

Desc. filename

Override for the uploaded file's filename.

This is optional, otherwise it uses the file's given filename instead.

Desc. name

A display name for the document.

Desc. notes

Any additional information about the document.

Example

{
  "file": "string",
  "file_hint": "DEFAULT",
  "filename": "abc.pdf",
  "name": "LOA",
  "notes": "LOA from client on 2026-05-20."
}

Schema / CreateRoleData

Request Data when creating a new role.

Type Object

Desc. default_scope

Role's default_scope, this is the scope applied when resources specify IGNORE for their own scope.

• IGNORE - When used as the default_scope, effectively disables all resources that use IGNORE as their scope.
• USER - Resources are scoped to the user, or their nearest account where applicable.
• ACCOUNT - Resources are scoped against the user's account.
• SYSTEM - Cannot be set by the API, but provided for reference, this is the system-wide scope.

Desc. name

Role's display name.

Desc. notes

Any notes about the role.

Desc. rank

Levels dictate the access, scopes filter resources, and ranks allow differentiating the same level of access within the account.

Ranks allow organizing roles within the account by importance.

0 is most relevant sometimes referred to as the highest rank. 1+ are ranks lower.

Ranks primarily affect the modification of: * Users - See Roles for information, as a user's Role dictates their permissions. * Roles - Roles of the same rank can modify themselves and those of lower rank, ranks of a higher rank cannot be modified by those of a lower rank.

SubObject

Sub-Schema

Type Object

SubObject

Sub-Schema

Type Object

Enum Values name

Allowed values

• sell_rates
• buy_rates
• count
• full_index
• index
• assoc
• show
• charge
• reset
• create
• update
• delete
• purge
• move
• import
• export
• review
• protect
• share
• unshare
• impersonate
• checkout
• lookup_result
• process
• cancel
• download
• upload
• summarize

Desc. name

The name of the action.

Desc. value

Whether or not the action is enabled.

NOTE. This is not a Boolean.

The field is an enum that happens to use the values true and false as strings.

Desc. scope

See Role's default_scope for more details on the enum.

IGNORE acts as a fallback to the default_scope.

Desc. resources

Role's job title, or position

Example

{
  "default_scope": "ACCOUNT",
  "name": "Ordering Role",
  "notes": "This role governs the Ordering System Access",
  "rank": 0,
  "resources": [
    {
      "actions": [
        {
          "name": "sell_rates",
          "value": "true"
        }
      ],
      "resource_id": "string",
      "scope": "IGNORE"
    }
  ]
}

Schema / CreateRoleRequest

Request for creating a new Role.

Type Object

Example

{
  "data": {
    "default_scope": "ACCOUNT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ]
  },
  "type": "role"
}

Schema / CreateSecretKeyData

Parameters for updating a Secret Key

Type Object

Desc. name

A friendly name to identify the Secret Key

Desc. notes

Any notes about the Secret Key, like, what it is used for, or other sharable details.

Desc. size

The size of the key that should be created in bytes, or the size of the key in the system.

Different use cases or methods will require different length keys.

Desc. usage

What is the intended usage of the Secret Key, this will bar it from being used for other cases.

NONE is placeholder or temporary disablement state reserved for internal usage.

Only SIGNING and ENCRYPTION can be used otherwise.

Example

{
  "name": "My Secret Key",
  "notes": "This Secret Key is used for the west datacenter's SMS notifications.",
  "size": 32,
  "usage": "SIGNING"
}

Schema / CreateSecretKeyRequest

Request for update an existing Secret Key

Type Object

Example

{
  "data": {
    "name": "My Secret Key",
    "notes": "This Secret Key is used for the west datacenter's SMS notifications.",
    "size": 32,
    "usage": "SIGNING"
  },
  "type": "secret_key"
}

Schema / CreateSecretKeyResponse

Newly created Secret Key

Type Object

Example

{
  "data": {
    "data": "string",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "My Secret Key",
    "notes": "This Secret Key is used for the west datacenter's SMS notifications.",
    "size": 32,
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "usage": "SIGNING"
  },
  "type": "secret_key"
}

Schema / CreateSwitchRequest

Request for creating a new Switch

Type Object

Example

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

Schema / CreateUserData

Request Data when create a new user.

The password is optional if the user is not intended to be used for login.

This is recommended for impersonated users who will only be used for API Key based access.

Type Object

Desc. address

User Address details, may differ from top-level details

Desc. email

User's email

Desc. first_name

User's first name

Desc. last_name

User's last name

Desc. password

User's login password

Desc. password_confirmation

User's login password (for confirmation)

Desc. title

User's job title, or position

address

Example

{
  "address": {
    "address1": "string",
    "address2": "string",
    "business_name": "string",
    "city": "string",
    "country": "string",
    "email": "string",
    "fax_number": "string",
    "first_name": "string",
    "house_number": "string",
    "last_name": "string",
    "notes": "string",
    "phone_number": "string",
    "state": "string",
    "zip_code": "string"
  },
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "password": "string",
  "password_confirmation": "string",
  "title": "Operator"
}

Schema / CreateUserRequest

Request for creating a new User

Type Object

Example

{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "password": "string",
    "password_confirmation": "string",
    "title": "Operator"
  },
  "type": "user"
}

Schema / CreatedApiKey

An API key that was newly created

Type Object

Desc. id

A Universally unique identifier, which identifies the resource

Desc. identity

Acts as the username in the authorization pair for MM4

Desc. notes

Any notes about the API Key, like, what it is used for, or other sharable details.

Desc. smpp_secert

Used as the password for SMPP connections

Desc. smpp_system_id

Small identifier used when authorizing an SMPP connection

Example

{
  "active": true,
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
  "name": "My API Key",
  "notes": "This API Key is used for the west datacenter's SMS notifications.",
  "secret": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
  "smpp_secert": "FDJX6MO4",
  "smpp_system_id": "EIIGBT24ZH242U5",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / CreatedSecretKey

An Secret Key that was newly created

Type Object

Desc. data

Base64 Encoded secret key, only available on creation.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. name

A friendly name to identify the Secret Key

Desc. notes

Any notes about the Secret Key, like, what it is used for, or other sharable details.

Desc. size

The size of the key that should be created in bytes, or the size of the key in the system.

Different use cases or methods will require different length keys.

Desc. usage

What is the intended usage of the Secret Key, this will bar it from being used for other cases.

NONE is placeholder or temporary disablement state reserved for internal usage.

Only SIGNING and ENCRYPTION can be used otherwise.

Example

{
  "data": "string",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "My Secret Key",
  "notes": "This Secret Key is used for the west datacenter's SMS notifications.",
  "size": 32,
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "usage": "SIGNING"
}

Schema / CspAltBusinessIdTypeResponse

CSP Alt Business ID Types

Type Array

Example

[
  "NONE"
]

Schema / CspBrand

A TCR brand associated with the account

Type Object

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. shared

Was this brand created directly or was a brand from a partner campaign.

Some fields may contain "UNKNOWN" if a brand is from a partner campaign.

• NO - Should be treated the same as OWNED
• OWNED - The brand was created on site and belongs to this system
• PARTNER - The brand originates from outside of the system

Example

{
  "address1": "string",
  "alt_business_id": "string",
  "alt_business_id_type": "string",
  "brand_relationship": "string",
  "city": "string",
  "company_name": "string",
  "country_code": "string",
  "display_name": "string",
  "ein": "string",
  "ein_issuing_country_code": "string",
  "email": "string",
  "first_name": "string",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "last_name": "string",
  "name": "string",
  "notes": "string",
  "phone_number": "string",
  "shared": "NO",
  "state": "string",
  "stock_exchange": "string",
  "stock_symbol": "string",
  "tcr_brand_id": "B000000",
  "tcr_csp_id": "S000000",
  "universal_ein": "string",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "vertical": "string",
  "website": "string",
  "zip_code": "string"
}

Schema / CspBrandRelationshipsResponse

CSP Brand Relationships

Type Array

Example

[
  "BASIC_ACCOUNT"
]

Schema / CspBrandResponse

Single brand

Type Object

Example

{
  "data": {
    "address1": "string",
    "alt_business_id": "string",
    "alt_business_id_type": "string",
    "brand_relationship": "string",
    "city": "string",
    "company_name": "string",
    "country_code": "string",
    "display_name": "string",
    "ein": "string",
    "ein_issuing_country_code": "string",
    "email": "string",
    "first_name": "string",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "string",
    "name": "string",
    "notes": "string",
    "phone_number": "string",
    "shared": "NO",
    "state": "string",
    "stock_exchange": "string",
    "stock_symbol": "string",
    "tcr_brand_id": "B000000",
    "tcr_csp_id": "S000000",
    "universal_ein": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "vertical": "string",
    "website": "string",
    "zip_code": "string"
  },
  "type": "csp_brand"
}

Schema / CspBrandsResponse

Brands

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "address1": "string",
        "alt_business_id": "string",
        "alt_business_id_type": "string",
        "brand_relationship": "string",
        "city": "string",
        "company_name": "string",
        "country_code": "string",
        "display_name": "string",
        "ein": "string",
        "ein_issuing_country_code": "string",
        "email": "string",
        "first_name": "string",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "last_name": "string",
        "name": "string",
        "notes": "string",
        "phone_number": "string",
        "shared": "NO",
        "state": "string",
        "stock_exchange": "string",
        "stock_symbol": "string",
        "tcr_brand_id": "B000000",
        "tcr_csp_id": "S000000",
        "universal_ein": "string",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "vertical": "string",
        "website": "string",
        "zip_code": "string"
      },
      "type": "csp_brand"
    }
  ]
}

Schema / CspCampaign

A TCR campaign

Type Object

Desc. dca_approved

Whether or not the campaign has been approved by the DCA

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. name

A display name to identify the campaign.

In the case of SHARED campaigns, the name is typically taken from the description and truncated to fit the length requirements.

Desc. notes

Any notes about the campaign.

In the case of SHARED campaigns the notes may always be empty.

Desc. sample_messages

The overall format or example of messages that the campaign will send.

Note that different usecases may require more samples.

Desc. shared

Was this campaign created directly or is a partner campaign.

• NO - Should be treated the same as OWNED
• OWNED - The campaign was created on site and belongs to this system
• PARTNER - The campaign originates from outside of the system

Desc. use_case

Campaign Usecase, see CSP Enums for possible values

attributes

Example

{
  "attributes": {
    "has_affiliate_marketing": true,
    "has_age_gated_content": true,
    "has_direct_lending": true,
    "has_embedded_link": true,
    "has_embedded_phone_number": true,
    "has_number_pooling": true,
    "has_subscriber_help": true,
    "has_subscriber_opt_in": true,
    "has_subscriber_opt_out": true,
    "has_terms_and_conditions": true
  },
  "dca_approved": true,
  "description": "The original description provided to TCR.\n",
  "embedded_link_sample": "https://example.com/something",
  "help_keywords": "HELP",
  "help_message": "string",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "message_flow": "string",
  "name": "Receive 2FA Codes over SMS",
  "notes": "string",
  "optin_keywords": "START,SUBSCRIBE",
  "optin_message": "string",
  "optout_keywords": "STOP,UNSUBSCRIBE",
  "optout_message": "string",
  "privacy_policy_link": "https://example.com/privacy",
  "sample_messages": [
    "string"
  ],
  "shared": "NO",
  "sub_use_case": [
    "2FA"
  ],
  "tcr_brand_id": "B000000",
  "tcr_campaign_id": "C000000",
  "tcr_csp_id": "S000000",
  "tcr_reseller_id": "R000000",
  "tcr_status": "ACTIVE",
  "terms_and_conditions_link": "https://example.com/terms_and_conditions",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "use_case": "MIXED"
}

Schema / CspCampaignResponse

Single campaign

Type Object

associations

Desc. shared_resource_group

The Shared Resource Group on the campaign, if any

brand

Desc. id

A Universally unique identifier, which identifies the resource

shared_resource_group

Desc. id

A Universally unique identifier, which identifies the resource

Example

{
  "associations": {
    "brand": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "tcr_brand_id": "B000000"
    },
    "shared_resource_group": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "attributes": {
      "has_affiliate_marketing": true,
      "has_age_gated_content": true,
      "has_direct_lending": true,
      "has_embedded_link": true,
      "has_embedded_phone_number": true,
      "has_number_pooling": true,
      "has_subscriber_help": true,
      "has_subscriber_opt_in": true,
      "has_subscriber_opt_out": true,
      "has_terms_and_conditions": true
    },
    "dca_approved": true,
    "description": "The original description provided to TCR.\n",
    "embedded_link_sample": "https://example.com/something",
    "help_keywords": "HELP",
    "help_message": "string",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "message_flow": "string",
    "name": "Receive 2FA Codes over SMS",
    "notes": "string",
    "optin_keywords": "START,SUBSCRIBE",
    "optin_message": "string",
    "optout_keywords": "STOP,UNSUBSCRIBE",
    "optout_message": "string",
    "privacy_policy_link": "https://example.com/privacy",
    "sample_messages": [
      "string"
    ],
    "shared": "NO",
    "sub_use_case": [
      "2FA"
    ],
    "tcr_brand_id": "B000000",
    "tcr_campaign_id": "C000000",
    "tcr_csp_id": "S000000",
    "tcr_reseller_id": "R000000",
    "tcr_status": "ACTIVE",
    "terms_and_conditions_link": "https://example.com/terms_and_conditions",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "use_case": "MIXED"
  },
  "type": "csp_campaign"
}

Schema / CspCampaignSharingConflictErrorsObject

An object representing a single sharing conflict error.

Sharing conflicts take place when a request attempts to replace the shared resource group for a campaign.

Type Object

Enum Values code

Allowed values

• conflict.changing_shared_resource_group

Desc. code

Contains static error code representing the error

Desc. detail

Contains dynamic description of the error

Desc. params

Contains additional parameters based on the permission error

Desc. sub_code

Some codes may have sub codes that further describe an error.

Desc. title

A user friendly title for the error.

params

Example

{
  "code": "conflict.changing_shared_resource_group",
  "detail": "Cannot change shared resource group",
  "params": {},
  "sub_code": "none",
  "title": "Conflict"
}

Schema / CspCampaignSharingConflictErrorsResponse

Errors Response when a sharing conflict is present

Type Object

Example

{
  "errors": [
    {
      "code": "conflict.changing_shared_resource_group",
      "detail": "Cannot change shared resource group",
      "params": {},
      "sub_code": "none",
      "title": "Conflict"
    }
  ]
}

Schema / CspCampaignStatusesResponse

CSP Campaign Statuses

Type Array

Example

[
  "ACTIVE"
]

Schema / CspCampaignUnsharingConflictErrorsObject

An object representing a single unsharing conflict error.

These conflicts may happen if a campaign is to be removed from a shared resource group, but is already associated with one or more numbers.

Type Object

Desc. code

Contains static error code representing the error

Desc. detail

Contains dynamic description of the error

Desc. params

Contains additional parameters based on the permission error

Desc. sub_code

Some codes may have sub codes that further describe an error.

Desc. title

A user friendly title for the error.

params

Example

{
  "code": "conflict.remove_shared_resource_group",
  "detail": "Cannot remove shared resource group, may still be associated with numbers",
  "params": {},
  "sub_code": "none",
  "title": "Conflict"
}

Schema / CspCampaignUnsharingConflictErrorsResponse

Errors Response when a sharing conflict is present

Type Object

Example

{
  "errors": [
    {
      "code": "conflict.remove_shared_resource_group",
      "detail": "Cannot remove shared resource group, may still be associated with numbers",
      "params": {},
      "sub_code": "none",
      "title": "Conflict"
    }
  ]
}

Schema / CspCampaignsResponse

Campaigns

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "brand": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
          "tcr_brand_id": "B000000"
        },
        "shared_resource_group": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        }
      },
      "data": {
        "attributes": {
          "has_affiliate_marketing": true,
          "has_age_gated_content": true,
          "has_direct_lending": true,
          "has_embedded_link": true,
          "has_embedded_phone_number": true,
          "has_number_pooling": true,
          "has_subscriber_help": true,
          "has_subscriber_opt_in": true,
          "has_subscriber_opt_out": true,
          "has_terms_and_conditions": true
        },
        "dca_approved": true,
        "description": "The original description provided to TCR.\n",
        "embedded_link_sample": "https://example.com/something",
        "help_keywords": "HELP",
        "help_message": "string",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "message_flow": "string",
        "name": "Receive 2FA Codes over SMS",
        "notes": "string",
        "optin_keywords": "START,SUBSCRIBE",
        "optin_message": "string",
        "optout_keywords": "STOP,UNSUBSCRIBE",
        "optout_message": "string",
        "privacy_policy_link": "https://example.com/privacy",
        "sample_messages": [
          "string"
        ],
        "shared": "NO",
        "sub_use_case": [
          "2FA"
        ],
        "tcr_brand_id": "B000000",
        "tcr_campaign_id": "C000000",
        "tcr_csp_id": "S000000",
        "tcr_reseller_id": "R000000",
        "tcr_status": "ACTIVE",
        "terms_and_conditions_link": "https://example.com/terms_and_conditions",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "use_case": "MIXED"
      },
      "type": "csp_campaign"
    }
  ]
}

Schema / CspCnpsResponse

CSP Event Categories

Type Object

Example

{
  "*": "string"
}

Schema / CspDcasResponse

CSP DCAs

Type Array

Example

[
  {
    "displayName": "string",
    "id": "string"
  }
]

SubObject

Sub-Schema

DCA

Type Object

Schema / CspEntityTypesResponse

CSP Entity Types

Type Array

Example

[
  "PRIVATE_PROFIT"
]

Schema / CspErrorCodesResponse

CSP Error Codes

Type Object

Example

{
  "*": "string"
}

Schema / CspEventCategoriesResponse

CSP Event Categories

Type Array

Example

[
  "string"
]

Schema / CspMnoOperationStatusesResponse

CSP MNO Operation Statuses

Type Array

Example

[
  "REVIEW"
]

Schema / CspMnosResponse

CSP MNOs

Type Array

Example

[
  {
    "displayName": "string",
    "networkId": 0.0,
    "osrBitmaskindex": 0.0
  }
]

SubObject

Sub-Schema

MNO

Type Object

Schema / CspStockExchangesResponse

CSP Stock Exchanges

Type Array

Example

[
  "AMEX"
]

Schema / CspUsecase

CSP Usecases

Type Object

Example

{
  "classification": "string",
  "description": "string",
  "displayName": "string",
  "maxSubUsecases": 5,
  "minSubUsecases": 1,
  "validSubUsecase": true
}

Schema / CspUsecasesResponse

CSP Usecases

Type Object

Example

{
  "*": {
    "classification": "string",
    "description": "string",
    "displayName": "string",
    "maxSubUsecases": 5,
    "minSubUsecases": 1,
    "validSubUsecase": true
  }
}

Schema / CspVertical

CSP Vertical

Type Object

Example

{
  "description": "Information technology and information services.",
  "displayName": "Information Technology Services",
  "industryId": "information-technology-services"
}

Schema / CspVerticalsResponse

CSP Verticals

Type Object

Example

{
  "*": {
    "description": "Information technology and information services.",
    "displayName": "Information Technology Services",
    "industryId": "information-technology-services"
  }
}

Schema / CspVettingClass

CSP Vetting Class

Type Object

Example

{
  "description": "string",
  "displayName": "string",
  "enabled": true,
  "id": "string",
  "validatyMonths": 0.0
}

Schema / CspVettingClassesResponse

CSP Vetting Classes

Type Array

Example

[
  {
    "description": "string",
    "displayName": "string",
    "enabled": true,
    "id": "string",
    "validatyMonths": 0.0
  }
]

Schema / CspVettingFeedbackCode

CSP Vetting Feedback Code

Type Object

Example

{
  "code": "string",
  "name": "string"
}

Schema / CspVettingFeedbackCodesResponse

CSP Vetting Feedback Codes

Type Array

Example

[
  {
    "code": "string",
    "name": "string"
  }
]

Schema / CspVettingProvider

CSP Vetting Provider

Type Object

Example

{
  "displayName": "Demo Vetting Provider",
  "evpId": "DEMO_EVP",
  "tcrBillable": true,
  "vettingClasses": [
    "STANDARD"
  ],
  "vettingInstruction": "string"
}

Schema / CspVettingProvidersResponse

CSP Vetting Providers

Type Array

Example

[
  {
    "displayName": "Demo Vetting Provider",
    "evpId": "DEMO_EVP",
    "tcrBillable": true,
    "vettingClasses": [
      "STANDARD"
    ],
    "vettingInstruction": "string"
  }
]

Schema / Destination

A did's voice destination

Type Object

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
}

Schema / DestinationResponse

Single Number Destination

Type Object

associations

did

Desc. id

A Universally unique identifier, which identifies the resource

tts_message_set

Desc. id

A Universally unique identifier, which identifies the resource

Example

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

Schema / DestinationsResponse

Number Destinations

Type Object

Example

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

Schema / ErrorObject

An object representing a single error, may contain a source if the error was from a field.

Type Object

Desc. code

Contains static error code representing the error

Desc. detail

Contains dynamic description of the error

Desc. sub_code

Some codes may have additional sub codes for identifying a problem.

Primarily used by requests

Desc. title

A user friendly title for the error, will usually reflect the http error code

source

Example

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

Schema / ErrorsResponse

Common errors response

Type Object

Example

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

Schema / EventSubscription

Event Subscription

Type Object

Desc. auth_identity

Acts as the username for an auth pair.

Desc. auth_method

Depending on the protocol this will affect the authorization or authentication that will be performed.

This applies to HTTP, SMTP and SFTP.

• NONE - no auth is required the event will be sent as is
• BASIC - The auth_identity and auth_secret will form the auth pair
• BEARER - Only the auth_secret will be used where applicable, for protocols that require both a username and password, the username will have a placeholder value.

Desc. auth_name

Currently unused, but kept for future use.

Desc. auth_secret

Acts as the password for an auth pair or just the general secret.

SubObject

Sub-Schema

A single header entry, while multiple items can be provided with the same key, the behaviour may not be consistent between destination servers.

When in doubt, only use unique keys.

Type Object

Desc. custom_headers

A list of additional headers that should be provided during the HTTP request.

SubObject

Sub-Schema

A single query parameter pair.

Type Object

Desc. data

Depending on the protocol specified this may be an http endpoint (HTTP), a hostname (SMTP or SFTP) or an email address (EMAIL).

Protocol: * NONE - nothing, this field is unused * HTTP - the http server endpoint (e.g. "http://events.example.com:7654/events/v1/ordering") * SFTP - the sftp server address (e.g. "sftp://sftp.example.com:2231/path/to/upload") * SMTP - the relay server address (e.g. "smtp://smtp.example.com:2554") * EMAIL - the recipient email address (e.g. "[email protected]")

A keen eye may notice there was no mention of the recipient address for SMTP, that is covered in recipient.

Desc. enabled

Is the subscription enabled to handle events?

Subscriptions can be toggled on or off as needed.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. name

The friendly given name for this subscription

Desc. notes

Any additional information about this subscription that otherwise could not fit into the name.

This can be useful to another user or agent that is reviewing the subscription.

Desc. protocol

When the subscription receives an event for handling, it wil be processed and sent using the specified protocol.

Available: * NONE - effectively a no-op. * HTTP - sends the event over HTTP to a specified endpoint data. * SFTP - uploads the event to a specified SFTP server

Planned (currently unavailable, but may become available later): * SMTP - sends the event over SMTP (not email compatible) * EMAIL - emails the event to specified address in data

Desc. recipient

Only applicable when the protocol is SMTP, this will be the recipient address (e.g. "[email protected]")

Enum Values topics

Allowed values

• NONE
• DID
• CSP_BRAND
• CSP_CAMPAIGN
• ORDER
• REQUEST
• OSR

Desc. topics

An event subscription must be list topics it wishes to receive events for.

Example

{
  "auth_identity": "my-username",
  "auth_method": "NONE",
  "auth_name": "something",
  "auth_secret": "my-secret-password",
  "custom_headers": [
    {
      "key": "x-my-header",
      "value": "My Header Value"
    }
  ],
  "custom_query_params": [
    {
      "key": "my_param",
      "value": "ParamValue"
    }
  ],
  "data": "",
  "enabled": true,
  "expired_at": "2021-08-13T04:08:44.762841Z",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "CSP Events",
  "notes": "string",
  "protocol": "NONE",
  "recipient": "[email protected]",
  "started_at": "2021-08-13T04:08:44.762841Z",
  "topics": [
    "NONE"
  ],
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / EventSubscriptionResponse

Single event subscription record

Type Object

Example

{
  "data": {
    "auth_identity": "my-username",
    "auth_method": "NONE",
    "auth_name": "something",
    "auth_secret": "my-secret-password",
    "custom_headers": [
      {
        "key": "x-my-header",
        "value": "My Header Value"
      }
    ],
    "custom_query_params": [
      {
        "key": "my_param",
        "value": "ParamValue"
      }
    ],
    "data": "",
    "enabled": true,
    "expired_at": "2021-08-13T04:08:44.762841Z",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "[email protected]",
    "started_at": "2021-08-13T04:08:44.762841Z",
    "topics": [
      "NONE"
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "event_subscription"
}

Schema / EventSubscriptionsResponse

Event Subscriptions

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "auth_identity": "my-username",
        "auth_method": "NONE",
        "auth_name": "something",
        "auth_secret": "my-secret-password",
        "custom_headers": [
          {
            "key": "x-my-header",
            "value": "My Header Value"
          }
        ],
        "custom_query_params": [
          {
            "key": "my_param",
            "value": "ParamValue"
          }
        ],
        "data": "",
        "enabled": true,
        "expired_at": "2021-08-13T04:08:44.762841Z",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "CSP Events",
        "notes": "string",
        "protocol": "NONE",
        "recipient": "[email protected]",
        "started_at": "2021-08-13T04:08:44.762841Z",
        "topics": [
          "NONE"
        ],
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "event_subscription"
    }
  ]
}

Schema / ExportTask

A CDR Export Task is a long running request to dump cdrs from a certain date into a file.

Type Object

Desc. date

An ISO8601 formatted date. Determines which day's cdrs will be exported.

Note that if a current or future date is provided, the task will be deferred to the day AFTER the given date.

Desc. error_code

• OK - there was no error

Desc. format

The intended exported format, CSV will export a CSV file as expected. MLJSON exports the cdrs as Multiline-JSON, that is each row in the file is a single CDR record encoded as JSON.

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

Desc. reference_id

A unique client provided id for the export task.

There is no particular format that is enforced, a general recommendation is to avoid spaces and non-ASCII characters for best experience.

Enum Values status

Allowed values

• NEW
• SCHEDULED
• PROCESSING
• STORING
• DELIVERING
• COMPLETED
• ABORTED
• ERROR

Desc. status

Status gives a brief overview of the state of the task.

• NEW - the export task was freshly created and has not begun processing
• SCHEDULED - the task has been scheduled to execute at a later time (see date field for more information)
• PROCESSING - the task has begun processing
• STORING - the task is currently storing its results on internal storage for later access
• DELIVERING - the task is now attempting to deliver the exported file to the given endpoints (or notifying)
• COMPLETED - the task is completed and it is safe to delete or retrieve the exported details
• ABORTED - the task was aborted, execution was halted
• ERROR - the task experienced an error, error_code will have more details if any

Enum Values type

Allowed values

• API
• MMS
• SMS
• VOICE
• BALANCE
• MISC

Desc. type

The main type of CDR that should be exported

• API - contain any LRN, LRNE, CNAM related calls
• MMS - contain the billed details for MMS records
• SMS - contain the billed details for SMS records
• VOICE - contain any voice related calls (TERMINATION, DID*)
• BALANCE - any balance related changes, including payments, adjustments etc...
• MISC - contains various registry related feees

Example

{
  "date": "string",
  "error_code": "OK",
  "format": "CSV",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "on_done_actions": [
    {
      "archive_format": "TAR_GZ",
      "auth_identity": "upload-user",
      "auth_method": "BASIC",
      "auth_secret": "supersecretsauce",
      "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
      "error_code": "OK",
      "filename": "string",
      "protocol": "SFTP",
      "reference_id": "SFTP-export-action",
      "status": "NEW",
      "type": "SEND"
    }
  ],
  "reference_id": "cdr-export-API-2022-03-14",
  "status": "NEW",
  "type": "API",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / ExportTaskResponse

Single CDR Export Task

Type Object

Example

{
  "data": {
    "date": "string",
    "error_code": "OK",
    "format": "CSV",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "on_done_actions": [
      {
        "archive_format": "TAR_GZ",
        "auth_identity": "upload-user",
        "auth_method": "BASIC",
        "auth_secret": "supersecretsauce",
        "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
        "error_code": "OK",
        "filename": "string",
        "protocol": "SFTP",
        "reference_id": "SFTP-export-action",
        "status": "NEW",
        "type": "SEND"
      }
    ],
    "reference_id": "cdr-export-API-2022-03-14",
    "status": "NEW",
    "type": "API",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "call_data_export_task"
}

Schema / ExportTasksResponse

CDR Export Tasks

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "date": "string",
        "error_code": "OK",
        "format": "CSV",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "on_done_actions": [
          {
            "archive_format": "TAR_GZ",
            "auth_identity": "upload-user",
            "auth_method": "BASIC",
            "auth_secret": "supersecretsauce",
            "data": "sftp://example.com:22/sub/path/to/store/exported_file/in",
            "error_code": "OK",
            "filename": "string",
            "protocol": "SFTP",
            "reference_id": "SFTP-export-action",
            "status": "NEW",
            "type": "SEND"
          }
        ],
        "reference_id": "cdr-export-API-2022-03-14",
        "status": "NEW",
        "type": "API",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "call_data_export_task"
    }
  ]
}

Schema / FileResponse

Any general binary blob from a file response call.

Depending on the API in, this response may have its content-type header appropriately set, or defaults to application/octet-stream.

Type String

Example

"string"

Schema / Message

A TTS Message contains the text 'body' and is associated with a TTS Voice.

Type Object

Desc. id

A Universally unique identifier, which identifies the resource

Desc. priority

The order in which messages should be played back, messages with the same priority will be randomized

Example

{
  "body": "Hello, World!",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "priority": 1,
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / MessageResponse

Single message

Type Object

Example

{
  "data": {
    "body": "Hello, World!",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "priority": 1,
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "tts_message"
}

Schema / MessageSet

A TTS Message Set contains multiple messages which can be recited to the caller based on their priority.

Type Object

Desc. id

A Universally unique identifier, which identifies the resource

Example

{
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "Pre-answer Greeter",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / MessageSetResponse

Single message set

Type Object

Example

{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "Pre-answer Greeter",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "tts_message_set"
}

Schema / MessageSetsResponse

Message Sets

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "Pre-answer Greeter",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "tts_message_set"
    }
  ]
}

Schema / MessagesResponse

Messages

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "body": "Hello, World!",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "priority": 1,
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "tts_message"
    }
  ]
}

Schema / MessagingAutoResponse

Messaging Auto Response

Type Object

Desc. id

A Universally unique identifier, which identifies the resource

SubObject

Sub-Schema

Type Object

Desc. intercept

Should the messaging system intercept (i.e. not forward to switch) the message?

This can be useful for cases where the keyword is to be handled by the messaging system, but the destination switch can't or does not wish to handle the message.

Desc. is_wildcard

Should this keyword be treated as a wildcard or fallback?

Only one wildcard can exist in a auto response, and will be returned for ALL messages that do not match any existing keywords.

Once is_wildcard is set, the keyword in question is also set to WILDCARD.

NOTE: To update an existing WILDCARD, the keyword must also be passed (i.e. WILDCARD).

Desc. keyword

The word to trigger this specific keyword.

Note that when is_wildcard is true, keyword will always be WILDCARD.

Desc. message

The primary message that should be sent as the reply.

In most scenarios this is the only message that needs to be set, however under the condition that a keyword is shared with the account's existing Keyword Plan (ask support for more information), the message may override it.

Desc. message2

A secondary message which may be selected under certain circumstances.

If a keyword plan is active on the parent account, and the keyword has an OPTOUT or OPTIN behaviour, this message may be used.

In the case of an OPTIN action, this message will be used as the redundant action message (e.g. the subscriber has already opted in or already opted out of the messaging platform).

Desc. keywords

A list of keywords that the auto response has, keywords are stored in uppercase, but are case insensitive upon usage.

Example

{
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "keywords": [
    {
      "intercept": false,
      "is_wildcard": false,
      "keyword": "START",
      "message": "You have been opted in to receive messages from ACME Corp.\n",
      "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
    }
  ],
  "name": "My Auto Responder",
  "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / MessagingAutoResponseResponse

Single Messaging Auto Response

Type Object

Example

{
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "keywords": [
      {
        "intercept": false,
        "is_wildcard": false,
        "keyword": "START",
        "message": "You have been opted in to receive messages from ACME Corp.\n",
        "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
      }
    ],
    "name": "My Auto Responder",
    "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "messaging_auto_response"
}

Schema / MessagingAutoResponsesResponse

Messaging Auto Responses

Type Object

Example

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "keywords": [
          {
            "intercept": false,
            "is_wildcard": false,
            "keyword": "START",
            "message": "You have been opted in to receive messages from ACME Corp.\n",
            "message2": "You have already been opted-in to receive messages from ACME Corp, if you wish to unsubscribed please send STOP instead.\n"
          }
        ],
        "name": "My Auto Responder",
        "notes": "This auto responder is used to notify messagers that the number is not available for SMS.\n",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "messaging_auto_response"
    }
  ]
}

Schema / Number

A provisioned did

Type Object

Desc. activated

Is the DID active for use?

Desc. brand_name

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

Any notes to attach to the number.

Desc. forward_number

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

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

A Universally unique identifier, which identifies the resource

Desc. mms_enabled

Whether or not the number is MMS capable, does not affect SMS or SMS to MMS upgrades.

Desc. number

The 3 to 15 digit code of the number.

SubObject

Sub-Schema

Type Object

Desc. encoding

The SMS encoding that this override should trigger on.

Desc. id

The UUID of the specific segment override, required when changing an existing override.

Desc. segment_threshold

See number's segment_threshold for more information.

Desc. target_reference_id

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:

<country_code>_<name>

Example:

us_tmobile
ca_rogers
dm_digicel

Desc. segment_overrides

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

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

Whether or not a number is messaging capable.

Note that this flag also affects mms availability.

Enum Values tier

Allowed values

• L0
• L1
• T1
• T2
• T3
• AK
• HI
• CAN
• PR
• TF
• SHORTCODE
• M0
• M1
• BYON

Desc. tier

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

Allowed values

• FALLBACK
• OFF
• ALWAYS_UPGRADE
• SEGMENT_UPGRADE

Desc. voice_enabled

Whether or not the specified number is voice-capable (only affects outgoing)

Example

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

Schema / NumberClientSuspension

A record representing a client issued number suspension.

Messages are still charged even if a suspension is in place.

New message requests while a client suspension is in place will reject

Type Object

Desc. block_direction

What direction messages should be blocked to this number, suspensions may apply to inbound or outbound.

On INBOUND, messages will NOT be sent to the endpoint but will be charged. On OUTBOUND, inflight messages will NOT be sent to their destinations (note they would have already been charged). New OUTBOUND messages will be rejected at the their edge (API, SMPP or other methods).

BOTH applies all rules.

Desc. block_messaging

What type of messaging should be blocked by this suspension?

Enum Values block_voip

Allowed values

• NONE
• ORIGINATION
• TERMINATION
• ALL

Desc. block_voip

Calls originating or terminating to the host number may not be terminated to the configured destinations while blocks are in place.

The system MAY choose to answer calls to remain compliant even if a suspension is present.

Desc. host_number

A reference to the host did's number.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. notes

Any notes on the suspension.

Example

{
  "block_direction": "NONE",
  "block_messaging": "NONE",
  "block_voip": "NONE",
  "host_number": "12003004000",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "notes": "Suspended due to carrier complaint.",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Schema / NumberClientSuspensionResponse

Single Number Client Suspension

Type Object

associations