> Tychron Atlas API & Provisioning Reference — chapter 33 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/schemas/
> Source: https://docs.tychron.com/api-reference/ · Updated 2026-09-09 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it).
> Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled)
> Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/
> Machine index: https://docs.tychron.com/llms.txt

# Schemas

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



## Schema / AddonsData {#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

| Name                | Type                | Description                            |
| ------------------- | ------------------- | -------------------------------------- |
| `messaging`         | `messaging`         | [Desc. `messaging`](https://docs.tychron.com/api-reference/schemas/#desc-485)         |
| `voip_destinations` | `voip_destinations` | [Desc. `voip_destinations`](https://docs.tychron.com/api-reference/schemas/#desc-486) |

#### Desc. `messaging` {#desc-485}

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` {#desc-486}

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

__messaging__

| Name              | Type                      | Description                          |
| ----------------- | ------------------------- | ------------------------------------ |
| `api_key_ids`     | Array:String(format:uuid) | [Desc. `api_key_ids`](https://docs.tychron.com/api-reference/schemas/#desc-487)     |
| `csp_campaign_id` | String(format:uuid)       | [Desc. `csp_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-488) |
| `enabled`         | Boolean                   | [Desc. `enabled`](https://docs.tychron.com/api-reference/schemas/#desc-489)         |
| `mms_enabled`     | Boolean                   | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-490)     |
| `notes`           | String                    | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-491)           |
| `switch_id`       | String(format:uuid)       | [Desc. `switch_id`](https://docs.tychron.com/api-reference/schemas/#desc-492)       |
| `tcr_campaign_id` | String                    | [Desc. `tcr_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-493) |

#### Desc. `api_key_ids` {#desc-487}

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

#### Desc. `csp_campaign_id` {#desc-488}

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

#### Desc. `enabled` {#desc-489}

Whether or not this addon should be applied.

#### Desc. `mms_enabled` {#desc-490}

Should MMS be enabled on the DIDs?

#### Desc. `notes` {#desc-491}

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

#### Desc. `switch_id` {#desc-492}

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

#### Desc. `tcr_campaign_id` {#desc-493}

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



__voip_destinations__

| Name           | Type                         | Description                       |
| -------------- | ---------------------------- | --------------------------------- |
| `destinations` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-501) | [Desc. `destinations`](https://docs.tychron.com/api-reference/schemas/#desc-502) |
| `enabled`      | Boolean                      | [Desc. `enabled`](https://docs.tychron.com/api-reference/schemas/#desc-503)      |
| `switch_id`    | String(format:uuid)          | [Desc. `switch_id`](https://docs.tychron.com/api-reference/schemas/#desc-504)    |

#### SubObject {#type-501}

Sub-Schema

Destination configuration parameters.


__Type__ Object

| Name            | Type                                   | Description                          |
| --------------- | -------------------------------------- | ------------------------------------ |
| `activated`     | Boolean                                | [Desc. `activated`](https://docs.tychron.com/api-reference/schemas/#desc-494)       |
| `auth_identity` | String                                 | The username for a BASIC auth_method |
| `auth_method`   | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-495)     |
| `auth_secret`   | String                                 | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-496)     |
| `destination`   | String                                 | [Desc. `destination`](https://docs.tychron.com/api-reference/schemas/#desc-497)     |
| `priority`      | Integer                                | [Desc. `priority`](https://docs.tychron.com/api-reference/schemas/#desc-498)        |
| `type`          | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-499):String               | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-500)            |

#### Desc. `activated` {#desc-494}

Whether or not the destination is considered for routing

#### Desc. `auth_method` {#desc-495}

The authorization method to used for HTTP_ROUTE destinations

#### Desc. `auth_secret` {#desc-496}

The password for a BASIC auth_method or token for BEARER auth_method

#### Desc. `destination` {#desc-497}

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` {#desc-498}

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

#### Enum Values type {#enum-499}

Allowed values

* `VOIP`
* `PSTN`
* `HTTP_ROUTE`
* `TTS`
* `TTS_CUSTOM`
* `TTS_MESSAGE_SET`

#### Desc. `type` {#desc-500}

The destination type, see destination field for more detail





#### Desc. `destinations` {#desc-502}

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

#### Desc. `enabled` {#desc-503}

Whether or not the VoIP Destinations should be configured.

#### Desc. `switch_id` {#desc-504}

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



__Example__

```json
{
  "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 {#schema-apikey}

An set of authorization details for various APIs

__Type__ Object

| Name             | Type                     | Description                             |
| ---------------- | ------------------------ | --------------------------------------- |
| `active`         | Boolean                  |                                         |
| `id`             | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-505)                 |
| `identity`       | String                   | [Desc. `identity`](https://docs.tychron.com/api-reference/schemas/#desc-506)           |
| `inserted_at`    | String(format:date-time) | An ISO8601 formatted timestamp          |
| `key`            | String                   | Token used for HTTP APIs                |
| `name`           | String(3..255)           | A friendly name to identify the API Key |
| `notes`          | String(0..65535)         | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-507)              |
| `smpp_system_id` | String                   | [Desc. `smpp_system_id`](https://docs.tychron.com/api-reference/schemas/#desc-508)     |
| `updated_at`     | String(format:date-time) | An ISO8601 formatted timestamp          |

#### Desc. `id` {#desc-505}

A Universally unique identifier, which identifies the resource

#### Desc. `identity` {#desc-506}

Acts as the username in the authorization pair for MM4

#### Desc. `notes` {#desc-507}

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

#### Desc. `smpp_system_id` {#desc-508}

Small identifier used when authorizing an SMPP connection



__Example__

```json
{
  "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 {#schema-apikeyresponse}

Single API Key

__Type__ Object

| Name   | Type                     | Description |
| ------ | ------------------------ | ----------- |
| `data` | [ApiKey](https://docs.tychron.com/api-reference/schemas/#schema-apikey) |             |
| `type` | String                   |             |



__Example__

```json
{
  "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 {#schema-apikeysresponse}

API Keys

__Type__ Object

| Name        | Type                                           | Description |
| ----------- | ---------------------------------------------- | ----------- |
| `count`     | Integer                                        |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                   |             |
| `results`   | Array:[ApiKeyResponse](https://docs.tychron.com/api-reference/schemas/#schema-apikeyresponse) |             |



__Example__

```json
{
  "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 {#schema-attachswitchmmsencryptionkeydata}

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

__Type__ Object

| Name                    | Type                                                     | Description |
| ----------------------- | -------------------------------------------------------- | ----------- |
| `mms_encryption_method` | [SwitchEncryptionMethod](https://docs.tychron.com/api-reference/schemas/#schema-switchencryptionmethod) |             |



__Example__

```json
{
  "mms_encryption_method": "NONE"
}
```



## Schema / AttachSwitchMmsEncryptionKeyRequest {#schema-attachswitchmmsencryptionkeyrequest}

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

__Type__ Object

| Name   | Type                                                                         | Description |
| ------ | ---------------------------------------------------------------------------- | ----------- |
| `data` | [AttachSwitchMmsEncryptionKeyData](https://docs.tychron.com/api-reference/schemas/#schema-attachswitchmmsencryptionkeydata) |             |
| `type` | String                                                                       |             |



__Example__

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



## Schema / AttachSwitchMmsSigningKeyData {#schema-attachswitchmmssigningkeydata}

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

__Type__ Object

| Name                 | Type                                               | Description |
| -------------------- | -------------------------------------------------- | ----------- |
| `mms_signing_hash`   | [SwitchSigningHash](https://docs.tychron.com/api-reference/schemas/#schema-switchsigninghash)     |             |
| `mms_signing_scheme` | [SwitchSigningScheme](https://docs.tychron.com/api-reference/schemas/#schema-switchsigningscheme) |             |



__Example__

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



## Schema / AttachSwitchMmsSigningKeyRequest {#schema-attachswitchmmssigningkeyrequest}

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

__Type__ Object

| Name   | Type                                                                   | Description |
| ------ | ---------------------------------------------------------------------- | ----------- |
| `data` | [AttachSwitchMmsSigningKeyData](https://docs.tychron.com/api-reference/schemas/#schema-attachswitchmmssigningkeydata) |             |
| `type` | String                                                                 |             |



__Example__

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



## Schema / AttachSwitchSmsEncryptionKeyData {#schema-attachswitchsmsencryptionkeydata}

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

__Type__ Object

| Name                    | Type                                                     | Description |
| ----------------------- | -------------------------------------------------------- | ----------- |
| `sms_encryption_method` | [SwitchEncryptionMethod](https://docs.tychron.com/api-reference/schemas/#schema-switchencryptionmethod) |             |



__Example__

```json
{
  "sms_encryption_method": "NONE"
}
```



## Schema / AttachSwitchSmsEncryptionKeyRequest {#schema-attachswitchsmsencryptionkeyrequest}

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

__Type__ Object

| Name   | Type                                                                         | Description |
| ------ | ---------------------------------------------------------------------------- | ----------- |
| `data` | [AttachSwitchSmsEncryptionKeyData](https://docs.tychron.com/api-reference/schemas/#schema-attachswitchsmsencryptionkeydata) |             |
| `type` | String                                                                       |             |



__Example__

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



## Schema / AttachSwitchSmsSigningKeyData {#schema-attachswitchsmssigningkeydata}

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

__Type__ Object

| Name                 | Type                                               | Description |
| -------------------- | -------------------------------------------------- | ----------- |
| `sms_signing_hash`   | [SwitchSigningHash](https://docs.tychron.com/api-reference/schemas/#schema-switchsigninghash)     |             |
| `sms_signing_scheme` | [SwitchSigningScheme](https://docs.tychron.com/api-reference/schemas/#schema-switchsigningscheme) |             |



__Example__

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



## Schema / AttachSwitchSmsSigningKeyRequest {#schema-attachswitchsmssigningkeyrequest}

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

__Type__ Object

| Name   | Type                                                                   | Description |
| ------ | ---------------------------------------------------------------------- | ----------- |
| `data` | [AttachSwitchSmsSigningKeyData](https://docs.tychron.com/api-reference/schemas/#schema-attachswitchsmssigningkeydata) |             |
| `type` | String                                                                 |             |



__Example__

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



## Schema / BulkDipTask {#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

| Name                | Type                                   | Description                            |
| ------------------- | -------------------------------------- | -------------------------------------- |
| `done_at`           | String(format:date-time)               | An ISO8601 formatted timestamp         |
| `enable_cdr_export` | Boolean                                | [Desc. `enable_cdr_export`](https://docs.tychron.com/api-reference/schemas/#desc-509) |
| `enhanced`          | Boolean                                | [Desc. `enhanced`](https://docs.tychron.com/api-reference/schemas/#desc-510)          |
| `error_code`        | Enum(`OK`):String                      | [Desc. `error_code`](https://docs.tychron.com/api-reference/schemas/#desc-511)        |
| `format`            | Enum(`CSV`, `MLJSON`):String           | [Desc. `format`](https://docs.tychron.com/api-reference/schemas/#desc-512)            |
| `id`                | String(format:ulid)                    | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-513)                |
| `inserted_at`       | String(format:date-time)               | An ISO8601 formatted timestamp         |
| `messaging_lookup`  | Boolean                                | [Desc. `messaging_lookup`](https://docs.tychron.com/api-reference/schemas/#desc-514)  |
| `numbers`           | Array(0..20000):String(format:tel)     | Numbers to lookup                      |
| `on_done_actions`   | [OnDoneActions](https://docs.tychron.com/api-reference/schemas/#schema-ondoneactions) |                                        |
| `reference_id`      | String(1..255)                         | [Desc. `reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-515)      |
| `status`            | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-516):String               | [Desc. `status`](https://docs.tychron.com/api-reference/schemas/#desc-517)            |
| `type`              | Enum(`LRN`, `MCL`, `CNAM`):String      | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-518)              |
| `updated_at`        | String(format:date-time)               | An ISO8601 formatted timestamp         |

#### Desc. `enable_cdr_export` {#desc-509}

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` {#desc-510}

Used for LRN type, enables enhanced lookup.

Please consult the LRN documentation for additional details.

#### Desc. `error_code` {#desc-511}

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

#### Desc. `format` {#desc-512}

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` {#desc-513}

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

#### Desc. `messaging_lookup` {#desc-514}

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

Please consult the LRN documentation for additional details.

#### Desc. `reference_id` {#desc-515}

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 {#enum-516}

Allowed values

* `NEW`
* `SCHEDULED`
* `PROCESSING`
* `STORING`
* `DELIVERING`
* `COMPLETED`
* `ABORTED`
* `ERROR`

#### Desc. `status` {#desc-517}

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` {#desc-518}

The type of bulk dip that should be performed:

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



__Example__

```json
{
  "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 {#schema-bulkdiptaskresponse}

Single Bulk Dip Task

__Type__ Object

| Name   | Type                               | Description |
| ------ | ---------------------------------- | ----------- |
| `data` | [BulkDipTask](https://docs.tychron.com/api-reference/schemas/#schema-bulkdiptask) |             |
| `type` | String                             |             |



__Example__

```json
{
  "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 {#schema-bulkdiptasksresponse}

Bulk Dip Tasks

__Type__ Object

| Name        | Type                                                     | Description |
| ----------- | -------------------------------------------------------- | ----------- |
| `count`     | Integer                                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                             |             |
| `results`   | Array:[BulkDipTaskResponse](https://docs.tychron.com/api-reference/schemas/#schema-bulkdiptaskresponse) |             |



__Example__

```json
{
  "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 {#schema-cdr}

A single call data record

__Type__ Object

| Name            | Type                                       | Description                        |
| --------------- | ------------------------------------------ | ---------------------------------- |
| `fees`          | Array:[CDRFee](https://docs.tychron.com/api-reference/schemas/#schema-cdrfee)             |                                    |
| `host_number`   | String                                     | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-519)   |
| `id`            | String(format:ulid)                        | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-520)            |
| `inserted_at`   | String(format:date-time)                   | An ISO8601 formatted timestamp     |
| `item_count`    | Integer                                    | [Desc. `item_count`](https://docs.tychron.com/api-reference/schemas/#desc-521)    |
| `item_id`       | String                                     | [Desc. `item_id`](https://docs.tychron.com/api-reference/schemas/#desc-522)       |
| `remote_number` | String                                     | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-523) |
| `sell_rate`     | String(format:decimal)                     | [Desc. `sell_rate`](https://docs.tychron.com/api-reference/schemas/#desc-524)     |
| `status`        | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-525):String                   | Main status of the CDR             |
| `subtype`       | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-526):String                   | [Desc. `subtype`](https://docs.tychron.com/api-reference/schemas/#desc-527)       |
| `surcharges`    | Array:[CDRSurcharge](https://docs.tychron.com/api-reference/schemas/#schema-cdrsurcharge) |                                    |
| `total`         | String(format:decimal)                     | [Desc. `total`](https://docs.tychron.com/api-reference/schemas/#desc-528)         |
| `type`          | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-529):String                   | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-530)          |
| `updated_at`    | String(format:date-time)                   | An ISO8601 formatted timestamp     |

#### Desc. `host_number` {#desc-519}

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

#### Desc. `id` {#desc-520}

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

#### Desc. `item_count` {#desc-521}

How many items does this CDR actually represent

#### Desc. `item_id` {#desc-522}

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

#### Desc. `remote_number` {#desc-523}

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

#### Desc. `sell_rate` {#desc-524}

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

#### Enum Values status {#enum-525}

Allowed values

* `UNKNOWN`
* `OK`
* `MISS`
* `ERROR`
* `REFUND`
* `NO_ANSWER`
* `BUSY`
* `CANCELLED`
* `CHANNEL_UNAVAILABLE`
* `CONGESTION`
* `TEMP_FAILURE`

#### Enum Values subtype {#enum-526}

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` {#desc-527}

Further refines the CDR type, depending on what the

#### Desc. `total` {#desc-528}

The total amount charged (sell_rate+fees+surcharges)

#### Enum Values type {#enum-529}

Allowed values

* `API`
* `MMS`
* `SMS`
* `VOICE`
* `BALANCE`
* `MISC`

#### Desc. `type` {#desc-530}

The main category that the CDR belongs to.



__Example__

```json
{
  "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 {#schema-cdrfee}

Represents a single fee in a CDR

__Type__ Object

| Name   | Type                   | Description |
| ------ | ---------------------- | ----------- |
| `cost` | String(format:decimal) |             |
| `name` | String                 |             |



__Example__

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



## Schema / CDRLookupResultResponse {#schema-cdrlookupresultresponse}

Single cdr

__Type__ Object

| Name      | Type                               | Description                  |
| --------- | ---------------------------------- | ---------------------------- |
| `cdr`     | [CDRResponse](https://docs.tychron.com/api-reference/schemas/#schema-cdrresponse) |                              |
| `lookups` | Array                              | [Desc. `lookups`](https://docs.tychron.com/api-reference/schemas/#desc-531) |

#### Desc. `lookups` {#desc-531}

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



__Example__

```json
{
  "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 {#schema-cdrresponse}

Single CDR record

__Type__ Object

| Name           | Type               | Description |
| -------------- | ------------------ | ----------- |
| `associations` | `associations`     |             |
| `data`         | [CDR](https://docs.tychron.com/api-reference/schemas/#schema-cdr) |             |
| `type`         | String             |             |

__associations__

| Name      | Type      | Description |
| --------- | --------- | ----------- |
| `api_key` | `api_key` |             |

__api_key__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-532) |

#### Desc. `id` {#desc-532}

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__

```json
{
  "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 {#schema-cdrsurcharge}

Represents a single surcharge in a CDR

__Type__ Object

| Name   | Type                   | Description |
| ------ | ---------------------- | ----------- |
| `cost` | String(format:decimal) |             |
| `name` | String                 |             |



__Example__

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



## Schema / CDRsResponse {#schema-cdrsresponse}

CDRs

__Type__ Object

| Name        | Type                                     | Description |
| ----------- | ---------------------------------------- | ----------- |
| `count`     | Integer                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)             |             |
| `results`   | Array:[CDRResponse](https://docs.tychron.com/api-reference/schemas/#schema-cdrresponse) |             |



__Example__

```json
{
  "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 {#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

| Name              | Type                     | Description                          |
| ----------------- | ------------------------ | ------------------------------------ |
| `host_number`     | String                   | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-533)     |
| `id`              | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-534)              |
| `inserted_at`     | String(format:date-time) | An ISO8601 formatted timestamp       |
| `keyword`         | String                   | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-535)         |
| `remote_number`   | String                   | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-536)   |
| `tcr_campaign_id` | String                   | [Desc. `tcr_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-537) |
| `updated_at`      | String(format:date-time) | An ISO8601 formatted timestamp       |

#### Desc. `host_number` {#desc-533}

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

That is the number that received the optout request.

#### Desc. `id` {#desc-534}

A Universally unique identifier, which identifies the resource

#### Desc. `keyword` {#desc-535}

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` {#desc-536}

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

#### Desc. `tcr_campaign_id` {#desc-537}

The Campaign ID, as issued by TCR.



__Example__

```json
{
  "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 {#schema-cspcampaignoptoutitemresponse}

Single Optout Item

__Type__ Object

| Name           | Type                                                   | Description |
| -------------- | ------------------------------------------------------ | ----------- |
| `associations` | `associations`                                         |             |
| `data`         | [CSPCampaignOptoutItem](https://docs.tychron.com/api-reference/schemas/#schema-cspcampaignoptoutitem) |             |
| `type`         | String                                                 |             |

__associations__

| Name           | Type           | Description                       |
| -------------- | -------------- | --------------------------------- |
| `csp_campaign` | `csp_campaign` | [Desc. `csp_campaign`](https://docs.tychron.com/api-reference/schemas/#desc-538) |
| `host_did`     | `host_did`     | [Desc. `host_did`](https://docs.tychron.com/api-reference/schemas/#desc-539)     |
| `sms`          | `sms`          | [Desc. `sms`](https://docs.tychron.com/api-reference/schemas/#desc-540)          |

#### Desc. `csp_campaign` {#desc-538}

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

#### Desc. `host_did` {#desc-539}

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

#### Desc. `sms` {#desc-540}

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__

| Name              | Type                | Description                          |
| ----------------- | ------------------- | ------------------------------------ |
| `id`              | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-541)              |
| `tcr_campaign_id` | String              | [Desc. `tcr_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-542) |

#### Desc. `id` {#desc-541}

A Universally unique identifier, which identifies the resource

#### Desc. `tcr_campaign_id` {#desc-542}

TCR Campaign ID, of the associated campaign.



__host_did__

| Name     | Type                | Description                 |
| -------- | ------------------- | --------------------------- |
| `id`     | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-543)     |
| `number` | String              | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-544) |

#### Desc. `id` {#desc-543}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-544}

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



__sms__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:ulid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-545) |

#### Desc. `id` {#desc-545}

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



__Example__

```json
{
  "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 {#schema-cspcampaignoptoutitemsresponse}

CSP Campaign Optout Items

__Type__ Object

| Name        | Type                                                                         | Description |
| ----------- | ---------------------------------------------------------------------------- | ----------- |
| `count`     | Integer                                                                      |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                                 |             |
| `results`   | Array:[CSPCampaignOptoutItemResponse](https://docs.tychron.com/api-reference/schemas/#schema-cspcampaignoptoutitemresponse) |             |



__Example__

```json
{
  "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 {#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

| Name                  | Type                                   | Description                              |
| --------------------- | -------------------------------------- | ---------------------------------------- |
| `auth_identity`       | String                                 | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-546)       |
| `auth_method`         | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-547)         |
| `auth_name`           | String                                 | [Desc. `auth_name`](https://docs.tychron.com/api-reference/schemas/#desc-548)           |
| `auth_secret`         | String                                 | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-549)         |
| `custom_headers`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-550)           | [Desc. `custom_headers`](https://docs.tychron.com/api-reference/schemas/#desc-551)      |
| `custom_query_params` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-552)           | [Desc. `custom_query_params`](https://docs.tychron.com/api-reference/schemas/#desc-553) |
| `data`                | String                                 | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-554)                |
| `id`                  | String(format:ulid)                    | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-555)                  |
| `inserted_at`         | String(format:date-time)               | An ISO8601 formatted timestamp           |
| `name`                | String(1..255)                         | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-556)                |
| `notes`               | String(0..65535)                       | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-557)               |
| `protocol`            | Enum(`NONE`, `HTTP`, `SFTP`):String    | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-558)            |
| `updated_at`          | String(format:date-time)               | An ISO8601 formatted timestamp           |

#### Desc. `auth_identity` {#desc-546}

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

#### Desc. `auth_method` {#desc-547}

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` {#desc-548}

Reserved for other protocols that may require additional auth information.

#### Desc. `auth_secret` {#desc-549}

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

#### SubObject {#type-550}

Sub-Schema

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_headers` {#desc-551}

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 {#type-552}

Sub-Schema

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_query_params` {#desc-553}

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` {#desc-554}

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` {#desc-555}

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

#### Desc. `name` {#desc-556}

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

#### Desc. `notes` {#desc-557}

Any notes or details about the call data webhook.

#### Desc. `protocol` {#desc-558}

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__

```json
{
  "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 {#schema-calldatawebhookresponse}

Single Call Data Webhook

__Type__ Object

| Name   | Type                                       | Description |
| ------ | ------------------------------------------ | ----------- |
| `data` | [CallDataWebhook](https://docs.tychron.com/api-reference/schemas/#schema-calldatawebhook) |             |
| `type` | String                                     |             |



__Example__

```json
{
  "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 {#schema-calldatawebhooksresponse}

Call Data Webhooks

__Type__ Object

| Name        | Type                                                             | Description |
| ----------- | ---------------------------------------------------------------- | ----------- |
| `count`     | Integer                                                          |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                     |             |
| `results`   | Array:[CallDataWebhookResponse](https://docs.tychron.com/api-reference/schemas/#schema-calldatawebhookresponse) |             |



__Example__

```json
{
  "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 {#schema-cart}

An order being prepared for checkout.


__Type__ Object

| Name          | Type                     | Description                    |
| ------------- | ------------------------ | ------------------------------ |
| `id`          | String(format:ulid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-559)        |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp |
| `name`        | String(3..255)           | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-560)      |
| `notes`       | String                   | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-561)     |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp |

#### Desc. `id` {#desc-559}

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

#### Desc. `name` {#desc-560}

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

#### Desc. `notes` {#desc-561}

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



__Example__

```json
{
  "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 {#schema-cartrequest}

A request being prepared in a cart

__Type__ Object

| Name          | Type                               | Description                    |
| ------------- | ---------------------------------- | ------------------------------ |
| `id`          | String(format:ulid)                | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-562)        |
| `inserted_at` | String(format:date-time)           | An ISO8601 formatted timestamp |
| `name`        | String                             |                                |
| `notes`       | String                             |                                |
| `type`        | [RequestType](https://docs.tychron.com/api-reference/schemas/#schema-requesttype) |                                |
| `updated_at`  | String(format:date-time)           | An ISO8601 formatted timestamp |
| `*`           | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-563)                |                                |

#### Desc. `id` {#desc-562}

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

#### One-Of {#type-563}

Types

* [CartRequestAddCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddcampaignnumbersdata)
* [CartRequestAddMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddmessagingnumbersdata)
* [CartRequestAddVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddvoicenumbersdata)
* [CartRequestNewNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestnewnumbersdata)
* [CartRequestRegisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestregisterbranddata)
* [CartRequestRegisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestregistercampaigndata)
* [CartRequestRemoveCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovecampaignnumbersdata)
* [CartRequestRemoveMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovemessagingnumbersdata)
* [CartRequestRemoveNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovenumbersdata)
* [CartRequestRemoveVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovevoicenumbersdata)
* [CartRequestUnregisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestunregisterbranddata)
* [CartRequestUnregisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestunregistercampaigndata)
* [CartRequestVetBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestvetbranddata)



__Example__

```json
{
  "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 {#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

| Name      | Type                | Description                  |
| --------- | ------------------- | ---------------------------- |
| `numbers` | Array:String        | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-564) |
| `*`       | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-569) |                              |

#### Desc. `numbers` {#desc-564}

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 {#type-566}

Sub-Schema

__Type__ Object

| Name              | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-565) |

#### Desc. `tcr_campaign_id` {#desc-565}

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 {#type-568}

Sub-Schema

__Type__ Object

| Name          | Type                | Description                      |
| ------------- | ------------------- | -------------------------------- |
| `campaign_id` | String(format:uuid) | [Desc. `campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-567) |

#### Desc. `campaign_id` {#desc-567}

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 {#type-569}

Types

* [... tcr_campaign_id](https://docs.tychron.com/api-reference/schemas/#type-566)
* [... campaign_id](https://docs.tychron.com/api-reference/schemas/#type-568)



__Example__

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



## Schema / CartRequestAddMessagingNumbersData {#schema-cartrequestaddmessagingnumbersdata}

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


__Type__ Object

| Name            | Type                      | Description                        |
| --------------- | ------------------------- | ---------------------------------- |
| `api_key_ids`   | Array:String(format:uuid) | [Desc. `api_key_ids`](https://docs.tychron.com/api-reference/schemas/#desc-570)   |
| `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](https://docs.tychron.com/api-reference/schemas/#desc-571) |
| `mms_enabled`   | Boolean                   | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-572)   |
| `numbers`       | Array:String(format:tel)  | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-573)       |
| `switch_id`     | String(format:uuid)       | [Desc. `switch_id`](https://docs.tychron.com/api-reference/schemas/#desc-574)     |

#### Desc. `api_key_ids` {#desc-570}

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` {#desc-571}

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` {#desc-572}

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` {#desc-573}

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` {#desc-574}

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__

```json
{
  "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 {#schema-cartrequestaddvoicenumbersdata}

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


__Type__ Object

| Name        | Type                | Description                    |
| ----------- | ------------------- | ------------------------------ |
| `numbers`   | Array:String        | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-575)   |
| `switch_id` | String(format:uuid) | [Desc. `switch_id`](https://docs.tychron.com/api-reference/schemas/#desc-576) |

#### Desc. `numbers` {#desc-575}

A list of NANP 11-digit numbers to add

#### Desc. `switch_id` {#desc-576}

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



__Example__

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



## Schema / CartRequestNewNumbersData {#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

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `state` | String |             |



__Example__

```json
{
  "state": "string"
}
```



## Schema / CartRequestRegisterBrandData {#schema-cartrequestregisterbranddata}

Request for registering a new CSP Brand.


__Type__ Object

| Name                       | Type                 | Description |
| -------------------------- | -------------------- | ----------- |
| `address1`                 | String               |             |
| `alt_business_id`          | String               |             |
| `alt_business_id_type`     | String               |             |
| `brand_relationship`       | String               |             |
| `business_contact_email`   | String(format:email) |             |
| `city`                     | String               |             |
| `company_name`             | String               |             |
| `country_code`             | String               |             |
| `display_name`             | String               |             |
| `ein`                      | String               |             |
| `ein_issuing_country_code` | String               |             |
| `email`                    | String(format:email) |             |
| `entity_type`              | String               |             |
| `first_name`               | String               |             |
| `last_name`                | String               |             |
| `phone_number`             | String               |             |
| `state`                    | String               |             |
| `stock_exchange`           | String               |             |
| `stock_symbol`             | String               |             |
| `vertical`                 | String               |             |
| `website`                  | String               |             |
| `zip_code`                 | String               |             |



__Example__

```json
{
  "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 {#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

| Name                        | Type                | Description                               |
| --------------------------- | ------------------- | ----------------------------------------- |
| `affiliate_marketing`       | Boolean             |                                           |
| `age_gated`                 | Boolean             |                                           |
| `brand_id`                  | String(format:uuid) | Internal UUID of CSP Brand                |
| `description`               | String              |                                           |
| `direct_lending`            | Boolean             |                                           |
| `embedded_link`             | Boolean             |                                           |
| `embedded_link_sample`      | String              |                                           |
| `embedded_phone`            | Boolean             |                                           |
| `help_keywords`             | String              | [Desc. `help_keywords`](https://docs.tychron.com/api-reference/schemas/#desc-577)        |
| `help_message`              | String              |                                           |
| `message_flow`              | String              |                                           |
| `mno_ids`                   | Array:String        |                                           |
| `number_pool`               | Boolean             |                                           |
| `optin_keywords`            | String              | [Desc. `optin_keywords`](https://docs.tychron.com/api-reference/schemas/#desc-578)       |
| `optin_message`             | String              |                                           |
| `optout_keywords`           | String              | [Desc. `optout_keywords`](https://docs.tychron.com/api-reference/schemas/#desc-579)      |
| `optout_message`            | String              |                                           |
| `privacy_policy_link`       | String              |                                           |
| `reseller_id`               | String(format:uuid) | Internal UUID of CSP Reseller             |
| `samples`                   | Array:String        |                                           |
| `sub_use_cases`             | Array:String        |                                           |
| `subscriber_help`           | Boolean             |                                           |
| `subscriber_optin`          | Boolean             |                                           |
| `subscriber_optout`         | Boolean             |                                           |
| `tcr_brand_id`              | String              | [Desc. `tcr_brand_id`](https://docs.tychron.com/api-reference/schemas/#desc-580)         |
| `tcr_reseller_id`           | String              | [Desc. `tcr_reseller_id`](https://docs.tychron.com/api-reference/schemas/#desc-581)      |
| `terms_and_conditions`      | Boolean             | [Desc. `terms_and_conditions`](https://docs.tychron.com/api-reference/schemas/#desc-582) |
| `terms_and_conditions_link` | String              |                                           |
| `use_case`                  | String              |                                           |

#### Desc. `help_keywords` {#desc-577}

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

Excess spaces will be trimmed around each keyword.

#### Desc. `optin_keywords` {#desc-578}

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

Excess spaces will be trimmed around each keyword.

#### Desc. `optout_keywords` {#desc-579}

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

Excess spaces will be trimmed around each keyword.

#### Desc. `tcr_brand_id` {#desc-580}

TCR issued Brand ID.

#### Desc. `tcr_reseller_id` {#desc-581}

TCR issued Reseller ID.

#### Desc. `terms_and_conditions` {#desc-582}

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__

```json
{
  "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 {#schema-cartrequestremovecampaignnumbersdata}

Request for removing numbers from an existing campaign.


__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-583) |

#### Desc. `numbers` {#desc-583}

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



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / CartRequestRemoveMessagingNumbersData {#schema-cartrequestremovemessagingnumbersdata}

Request for disabling messaging on existing numbers.

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


__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-584) |

#### Desc. `numbers` {#desc-584}

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



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / CartRequestRemoveNumbersData {#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

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-585) |

#### Desc. `numbers` {#desc-585}

A list of NANP 11-digit numbers to remove



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / CartRequestRemoveVoiceNumbersData {#schema-cartrequestremovevoicenumbersdata}

Request for removing voice-only numbers.

Voice-only numbers are typically enabled using `ADD_VOICE_NUMBERS`.


__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-586) |

#### Desc. `numbers` {#desc-586}

A list of NANP 11-digit numbers to remove



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / CartRequestResponse {#schema-cartrequestresponse}

Single request

__Type__ Object

| Name   | Type                               | Description |
| ------ | ---------------------------------- | ----------- |
| `data` | [CartRequest](https://docs.tychron.com/api-reference/schemas/#schema-cartrequest) |             |
| `type` | String                             |             |



__Example__

```json
{
  "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 {#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

| Name             | Type                | Description         |
| ---------------- | ------------------- | ------------------- |
| `tcr_brand_id` ~ | String              | TCR issued Brand ID |
| `brand_id` ~     | String(format:uuid) | Internal UUID       |



__Example__

```json
{
  "tcr_brand_id": "B000000"
}
```



## Schema / CartRequestUnregisterCampaignData {#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

| Name                | Type                | Description   |
| ------------------- | ------------------- | ------------- |
| `tcr_campaign_id` ~ | String              | TCR issued ID |
| `campaign_id` ~     | String(format:uuid) | Internal UUID |



__Example__

```json
{
  "tcr_campaign_id": "B000000"
}
```



## Schema / CartRequestVetBrandData {#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

| Name             | Type                | Description                        |
| ---------------- | ------------------- | ---------------------------------- |
| `tcr_evp_id`     | String              | [Desc. `tcr_evp_id`](https://docs.tychron.com/api-reference/schemas/#desc-587)    |
| `vetting_class`  | String              | [Desc. `vetting_class`](https://docs.tychron.com/api-reference/schemas/#desc-588) |
| `tcr_brand_id` ~ | String              | TCR issued Brand ID                |
| `brand_id` ~     | String(format:uuid) | Internal UUID                      |

#### Desc. `tcr_evp_id` {#desc-587}

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

#### Desc. `vetting_class` {#desc-588}

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



__Example__

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



## Schema / CartRequestsResponse {#schema-cartrequestsresponse}

Requests

__Type__ Object

| Name        | Type                                                     | Description |
| ----------- | -------------------------------------------------------- | ----------- |
| `count`     | Integer                                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                             |             |
| `results`   | Array:[CartRequestResponse](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestresponse) |             |



__Example__

```json
{
  "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 {#schema-cartresponse}

Single cart

__Type__ Object

| Name   | Type                 | Description |
| ------ | -------------------- | ----------- |
| `data` | [Cart](https://docs.tychron.com/api-reference/schemas/#schema-cart) |             |
| `type` | String               |             |



__Example__

```json
{
  "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 {#schema-cartsresponse}

Carts

__Type__ Object

| Name        | Type                                       | Description |
| ----------- | ------------------------------------------ | ----------- |
| `count`     | Integer                                    |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)               |             |
| `results`   | Array:[CartResponse](https://docs.tychron.com/api-reference/schemas/#schema-cartresponse) |             |



__Example__

```json
{
  "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 {#schema-createapikeydata}

Parameters for updating an api key

__Type__ Object

| Name     | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| `active` | Boolean | Whether the API Key is active for use |
| `name`   | String  | A display name for the API Key        |
| `notes`  | String  | Any notes on the API Key              |



__Example__

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



## Schema / CreateApiKeyRequest {#schema-createapikeyrequest}

Request for update an existing API Key

__Type__ Object

| Name   | Type                                         | Description |
| ------ | -------------------------------------------- | ----------- |
| `data` | [CreateApiKeyData](https://docs.tychron.com/api-reference/schemas/#schema-createapikeydata) |             |
| `type` | String                                       |             |



__Example__

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



## Schema / CreateApiKeyResponse {#schema-createapikeyresponse}

Newly created API Key

__Type__ Object

| Name   | Type                                   | Description |
| ------ | -------------------------------------- | ----------- |
| `data` | [CreatedApiKey](https://docs.tychron.com/api-reference/schemas/#schema-createdapikey) |             |
| `type` | String                                 |             |



__Example__

```json
{
  "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 {#schema-createbulkdiptaskdata}

Parameters for creating a new export task.


__Type__ Object

| Name               | Type                                               | Description                           |
| ------------------ | -------------------------------------------------- | ------------------------------------- |
| `enhanced`         | Boolean                                            | [Desc. `enhanced`](https://docs.tychron.com/api-reference/schemas/#desc-589)         |
| `format`           | Enum(`CSV`, `MLJSON`):String                       | [Desc. `format`](https://docs.tychron.com/api-reference/schemas/#desc-590)           |
| `messaging_lookup` | Boolean                                            | [Desc. `messaging_lookup`](https://docs.tychron.com/api-reference/schemas/#desc-591) |
| `numbers`          | Array(0..20000):String(format:tel)                 | Numbers to lookup                     |
| `on_done_actions`  | [CreateOnDoneActions](https://docs.tychron.com/api-reference/schemas/#schema-createondoneactions) |                                       |
| `reference_id`     | String(1..255)                                     | [Desc. `reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-592)     |
| `type`             | Enum(`LRN`, `MCL`, `CNAM`):String                  | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-593)             |

#### Desc. `enhanced` {#desc-589}

Used for LRN type, enables enhanced lookup.

Please consult the LRN documentation for additional details.

#### Desc. `format` {#desc-590}

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` {#desc-591}

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

Please consult the LRN documentation for additional details.

#### Desc. `reference_id` {#desc-592}

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` {#desc-593}

The type of bulk dip that should be performed:

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



__Example__

```json
{
  "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 {#schema-createbulkdiptaskrequest}

Request for creating a new Bulk Dip Task

__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [CreateBulkDipTaskData](https://docs.tychron.com/api-reference/schemas/#schema-createbulkdiptaskdata) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "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 {#schema-createcalldatawebhookdata}

Parameters for creating a new Call Data Webhook.


__Type__ Object

| Name                  | Type                                   | Description                              |
| --------------------- | -------------------------------------- | ---------------------------------------- |
| `auth_identity`       | String                                 | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-594)       |
| `auth_method`         | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-595)         |
| `auth_name`           | String                                 | [Desc. `auth_name`](https://docs.tychron.com/api-reference/schemas/#desc-596)           |
| `auth_secret`         | String                                 | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-597)         |
| `custom_headers`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-598)           | [Desc. `custom_headers`](https://docs.tychron.com/api-reference/schemas/#desc-599)      |
| `custom_query_params` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-600)           | [Desc. `custom_query_params`](https://docs.tychron.com/api-reference/schemas/#desc-601) |
| `data`                | String                                 | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-602)                |
| `name`                | String(1..255)                         | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-603)                |
| `notes`               | String(0..65535)                       | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-604)               |
| `protocol`            | Enum(`NONE`, `HTTP`, `SFTP`):String    | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-605)            |

#### Desc. `auth_identity` {#desc-594}

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

#### Desc. `auth_method` {#desc-595}

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` {#desc-596}

Reserved for other protocols that may require additional auth information.

#### Desc. `auth_secret` {#desc-597}

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

#### SubObject {#type-598}

Sub-Schema

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_headers` {#desc-599}

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 {#type-600}

Sub-Schema

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_query_params` {#desc-601}

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` {#desc-602}

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` {#desc-603}

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

#### Desc. `notes` {#desc-604}

Any notes or details about the call data webhook.

#### Desc. `protocol` {#desc-605}

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__

```json
{
  "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 {#schema-createcalldatawebhookrequest}

Request for creating a new Call Data Webhook

__Type__ Object

| Name   | Type                                                           | Description |
| ------ | -------------------------------------------------------------- | ----------- |
| `data` | [CreateCallDataWebhookData](https://docs.tychron.com/api-reference/schemas/#schema-createcalldatawebhookdata) |             |
| `type` | String                                                         |             |



__Example__

```json
{
  "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 {#schema-createcartdata}

Request for creating a new cart

__Type__ Object

| Name    | Type   | Description                        |
| ------- | ------ | ---------------------------------- |
| `name`  | String | A unique name identifying the cart |
| `notes` | String | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-606)         |

#### Desc. `notes` {#desc-606}

Optional information about the cart, or order.



__Example__

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



## Schema / CreateCartRequest {#schema-createcartrequest}

Request for creating a new cart

__Type__ Object

| Name   | Type                                     | Description |
| ------ | ---------------------------------------- | ----------- |
| `data` | [CreateCartData](https://docs.tychron.com/api-reference/schemas/#schema-createcartdata) |             |
| `type` | String                                   |             |



__Example__

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



## Schema / CreateCartRequestData {#schema-createcartrequestdata}

Request for creating a new cart request

__Type__ Object

| Name    | Type                               | Description |
| ------- | ---------------------------------- | ----------- |
| `name`  | String                             |             |
| `notes` | String                             |             |
| `type`  | [RequestType](https://docs.tychron.com/api-reference/schemas/#schema-requesttype) |             |
| `*`     | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-607)                |             |

#### One-Of {#type-607}

Types

* [CartRequestAddCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddcampaignnumbersdata)
* [CartRequestAddMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddmessagingnumbersdata)
* [CartRequestAddVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddvoicenumbersdata)
* [CartRequestNewNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestnewnumbersdata)
* [CartRequestRegisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestregisterbranddata)
* [CartRequestRegisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestregistercampaigndata)
* [CartRequestRemoveCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovecampaignnumbersdata)
* [CartRequestRemoveMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovemessagingnumbersdata)
* [CartRequestRemoveNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovenumbersdata)
* [CartRequestRemoveVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovevoicenumbersdata)
* [CartRequestUnregisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestunregisterbranddata)
* [CartRequestUnregisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestunregistercampaigndata)
* [CartRequestVetBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestvetbranddata)



__Example__

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



## Schema / CreateCartRequestRequest {#schema-createcartrequestrequest}

Request for creating a new cart

__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [CreateCartRequestData](https://docs.tychron.com/api-reference/schemas/#schema-createcartrequestdata) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "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 {#schema-createdestinationrequest}

Request for creating a new Number Destination

__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [UpsertDestinationData](https://docs.tychron.com/api-reference/schemas/#schema-upsertdestinationdata) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "data": {
    "activated": true,
    "auth_identity": "username",
    "auth_method": "BASIC",
    "auth_secret": "password",
    "destination": "http://example.com/http/route/call",
    "priority": 1,
    "tts_message_set_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "type": "HTTP_ROUTE"
  },
  "type": "number_destination"
}
```



## Schema / CreateExportTaskData {#schema-createexporttaskdata}

Parameters for creating a new export task.


__Type__ Object

| Name              | Type                                               | Description                       |
| ----------------- | -------------------------------------------------- | --------------------------------- |
| `date`            | String(format:date)                                | [Desc. `date`](https://docs.tychron.com/api-reference/schemas/#desc-608)         |
| `format`          | Enum(`CSV`, `MLJSON`):String                       | [Desc. `format`](https://docs.tychron.com/api-reference/schemas/#desc-609)       |
| `on_done_actions` | [CreateOnDoneActions](https://docs.tychron.com/api-reference/schemas/#schema-createondoneactions) |                                   |
| `reference_id`    | String(1..255)                                     | [Desc. `reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-610) |
| `type`            | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-611):String                           | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-612)         |

#### Desc. `date` {#desc-608}

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` {#desc-609}

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` {#desc-610}

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 {#enum-611}

Allowed values

* `API`
* `MMS`
* `SMS`
* `VOICE`
* `BALANCE`
* `MISC`

#### Desc. `type` {#desc-612}

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__

```json
{
  "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 {#schema-createexporttaskrequest}

Request for creating a new CDR Export Task

__Type__ Object

| Name   | Type                                                 | Description |
| ------ | ---------------------------------------------------- | ----------- |
| `data` | [CreateExportTaskData](https://docs.tychron.com/api-reference/schemas/#schema-createexporttaskdata) |             |
| `type` | String                                               |             |



__Example__

```json
{
  "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 {#schema-createmessagerequest}

Request for creating a new tts message

__Type__ Object

| Name   | Type                                           | Description |
| ------ | ---------------------------------------------- | ----------- |
| `data` | [UpsertMessageData](https://docs.tychron.com/api-reference/schemas/#schema-upsertmessagedata) |             |
| `type` | String                                         |             |



__Example__

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



## Schema / CreateMessageSetRequest {#schema-createmessagesetrequest}

Request for creating a new tts message set

__Type__ Object

| Name   | Type                                                 | Description |
| ------ | ---------------------------------------------------- | ----------- |
| `data` | [UpsertMessageSetData](https://docs.tychron.com/api-reference/schemas/#schema-upsertmessagesetdata) |             |
| `type` | String                                               |             |



__Example__

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



## Schema / CreateOnDoneAction {#schema-createondoneaction}

__Type__ Object

| Name             | Type                                        | Description                         |
| ---------------- | ------------------------------------------- | ----------------------------------- |
| `archive_format` | Enum(`NONE`, `TAR`, `TAR_GZ`, `ZIP`):String | [Desc. `archive_format`](https://docs.tychron.com/api-reference/schemas/#desc-613) |
| `auth_identity`  | String                                      | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-614)  |
| `auth_method`    | Enum(`NONE`, `BASIC`, `BEARER`):String      | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-615)    |
| `auth_secret`    | String                                      | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-616)    |
| `data`           | String                                      | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-617)           |
| `filename`       | String                                      | [Desc. `filename`](https://docs.tychron.com/api-reference/schemas/#desc-618)       |
| `protocol`       | Enum(`NONE`, `HTTP`, `SFTP`):String         | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-619)       |
| `reference_id`   | String(0..255)                              | [Desc. `reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-620)   |
| `type`           | Enum(`NONE`, `NOTIFY`, `SEND`):String       | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-621)           |

#### Desc. `archive_format` {#desc-613}

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` {#desc-614}

See `auth_method` for details

#### Desc. `auth_method` {#desc-615}

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` {#desc-616}

See `auth_method` for details

#### Desc. `data` {#desc-617}

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` {#desc-618}

Optional override for SFTP filename.

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

#### Desc. `protocol` {#desc-619}

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` {#desc-620}

Optional client provided id to identify the action.

#### Desc. `type` {#desc-621}

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__

```json
{
  "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 {#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

| Name  | Type                                             | Description |
| ----- | ------------------------------------------------ | ----------- |
| `[n]` | [CreateOnDoneAction](https://docs.tychron.com/api-reference/schemas/#schema-createondoneaction) |             |

__Example__

```json
[
  {
    "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 {#schema-createoptoutitemdata}

Parameters for creating a Number Optout Item

__Type__ Object

| Name            | Type   | Description                        |
| --------------- | ------ | ---------------------------------- |
| `host_number`   | String | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-622)   |
| `remote_number` | String | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-623) |

#### Desc. `host_number` {#desc-622}

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

That is the number that received the optout request.

#### Desc. `remote_number` {#desc-623}

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



__Example__

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



## Schema / CreateOptoutItemRequest {#schema-createoptoutitemrequest}

Request for creating a new Number Optout Item

__Type__ Object

| Name   | Type                                                 | Description |
| ------ | ---------------------------------------------------- | ----------- |
| `data` | [CreateOptoutItemData](https://docs.tychron.com/api-reference/schemas/#schema-createoptoutitemdata) |             |
| `type` | String                                               |             |



__Example__

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



## Schema / CreateRequestDocumentRequest {#schema-createrequestdocumentrequest}

__Type__ Object

| Name        | Type                                 | Description                    |
| ----------- | ------------------------------------ | ------------------------------ |
| `file`      | String(format:binary)                | [Desc. `file`](https://docs.tychron.com/api-reference/schemas/#desc-624)      |
| `file_hint` | Enum(`DEFAULT`, `MMS`, `LOA`):String | [Desc. `file_hint`](https://docs.tychron.com/api-reference/schemas/#desc-625) |
| `filename`  | String                               | [Desc. `filename`](https://docs.tychron.com/api-reference/schemas/#desc-626)  |
| `name`      | String                               | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-627)      |
| `notes`     | String                               | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-628)     |

#### Desc. `file` {#desc-624}

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

Do not be malicious.

#### Desc. `file_hint` {#desc-625}

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` {#desc-626}

Override for the uploaded file's filename.

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

#### Desc. `name` {#desc-627}

A display name for the document.

#### Desc. `notes` {#desc-628}

Any additional information about the document.



__Example__

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



## Schema / CreateRoleData {#schema-createroledata}

Request Data when creating a new role.


__Type__ Object

| Name            | Type                                               | Description                        |
| --------------- | -------------------------------------------------- | ---------------------------------- |
| `default_scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `default_scope`](https://docs.tychron.com/api-reference/schemas/#desc-629) |
| `name`          | String                                             | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-630)          |
| `notes`         | String                                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-631)         |
| `rank`          | Integer(>= 0)                                      | [Desc. `rank`](https://docs.tychron.com/api-reference/schemas/#desc-632)          |
| `resources`     | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-638)                       | [Desc. `resources`](https://docs.tychron.com/api-reference/schemas/#desc-639)     |

#### Desc. `default_scope` {#desc-629}

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` {#desc-630}

Role's display name.

#### Desc. `notes` {#desc-631}

Any notes about the role.

#### Desc. `rank` {#desc-632}

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 {#type-638}

Sub-Schema

__Type__ Object

| Name          | Type                                               | Description                |
| ------------- | -------------------------------------------------- | -------------------------- |
| `actions`     | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-636)                       |                            |
| `resource_id` | String                                             |                            |
| `scope`       | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](https://docs.tychron.com/api-reference/schemas/#desc-637) |

#### SubObject {#type-636}

Sub-Schema

__Type__ Object

| Name    | Type                         | Description                |
| ------- | ---------------------------- | -------------------------- |
| `name`  | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-633):String     | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-634)  |
| `value` | Enum(`true`, `false`):String | [Desc. `value`](https://docs.tychron.com/api-reference/schemas/#desc-635) |

#### Enum Values name {#enum-633}

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` {#desc-634}

The name of the action.

#### Desc. `value` {#desc-635}

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` {#desc-637}

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

IGNORE acts as a fallback to the `default_scope`.





#### Desc. `resources` {#desc-639}

Role's job title, or position



__Example__

```json
{
  "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 {#schema-createrolerequest}

Request for creating a new Role.

__Type__ Object

| Name   | Type                                     | Description |
| ------ | ---------------------------------------- | ----------- |
| `data` | [CreateRoleData](https://docs.tychron.com/api-reference/schemas/#schema-createroledata) |             |
| `type` | String                                   |             |



__Example__

```json
{
  "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 {#schema-createsecretkeydata}

Parameters for updating a Secret Key

__Type__ Object

| Name    | Type                                         | Description                |
| ------- | -------------------------------------------- | -------------------------- |
| `name`  | String(3..255)                               | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-640)  |
| `notes` | String(0..65535)                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-641) |
| `size`  | Enum(`16`, `24`, `32`, `48`, `64`):Number    | [Desc. `size`](https://docs.tychron.com/api-reference/schemas/#desc-642)  |
| `usage` | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](https://docs.tychron.com/api-reference/schemas/#desc-643) |

#### Desc. `name` {#desc-640}

A friendly name to identify the Secret Key

#### Desc. `notes` {#desc-641}

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

#### Desc. `size` {#desc-642}

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` {#desc-643}

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__

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



## Schema / CreateSecretKeyRequest {#schema-createsecretkeyrequest}

Request for update an existing Secret Key

__Type__ Object

| Name   | Type                                               | Description |
| ------ | -------------------------------------------------- | ----------- |
| `data` | [CreateSecretKeyData](https://docs.tychron.com/api-reference/schemas/#schema-createsecretkeydata) |             |
| `type` | String                                             |             |



__Example__

```json
{
  "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 {#schema-createsecretkeyresponse}

Newly created Secret Key

__Type__ Object

| Name   | Type                                         | Description |
| ------ | -------------------------------------------- | ----------- |
| `data` | [CreatedSecretKey](https://docs.tychron.com/api-reference/schemas/#schema-createdsecretkey) |             |
| `type` | String                                       |             |



__Example__

```json
{
  "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 {#schema-createswitchrequest}

Request for creating a new Switch

__Type__ Object

| Name   | Type                                         | Description |
| ------ | -------------------------------------------- | ----------- |
| `data` | [UpsertSwitchData](https://docs.tychron.com/api-reference/schemas/#schema-upsertswitchdata) |             |
| `type` | String                                       |             |



__Example__

```json
{
  "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": "12003004000@example.com",
    "voice_enabled": false,
    "voice_identity": "johndoe",
    "voice_name": "John Doe",
    "voice_protocol": "NONE",
    "voice_secret": "super$ecret"
  },
  "type": "switch"
}
```



## Schema / CreateUserData {#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

| Name                    | Type                 | Description                                |
| ----------------------- | -------------------- | ------------------------------------------ |
| `address`               | `address`            | [Desc. `address`](https://docs.tychron.com/api-reference/schemas/#desc-644)               |
| `email`                 | String(format:email) | [Desc. `email`](https://docs.tychron.com/api-reference/schemas/#desc-645)                 |
| `first_name`            | String               | [Desc. `first_name`](https://docs.tychron.com/api-reference/schemas/#desc-646)            |
| `last_name`             | String               | [Desc. `last_name`](https://docs.tychron.com/api-reference/schemas/#desc-647)             |
| `password`              | String               | [Desc. `password`](https://docs.tychron.com/api-reference/schemas/#desc-648)              |
| `password_confirmation` | String               | [Desc. `password_confirmation`](https://docs.tychron.com/api-reference/schemas/#desc-649) |
| `title`                 | String               | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-650)                 |

#### Desc. `address` {#desc-644}

User Address details, may differ from top-level details

#### Desc. `email` {#desc-645}

User's email

#### Desc. `first_name` {#desc-646}

User's first name

#### Desc. `last_name` {#desc-647}

User's last name

#### Desc. `password` {#desc-648}

User's login password

#### Desc. `password_confirmation` {#desc-649}

User's login password (for confirmation)

#### Desc. `title` {#desc-650}

User's job title, or position

__address__

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `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 |             |



__Example__

```json
{
  "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": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "password": "string",
  "password_confirmation": "string",
  "title": "Operator"
}
```



## Schema / CreateUserRequest {#schema-createuserrequest}

Request for creating a new User

__Type__ Object

| Name   | Type                                     | Description |
| ------ | ---------------------------------------- | ----------- |
| `data` | [CreateUserData](https://docs.tychron.com/api-reference/schemas/#schema-createuserdata) |             |
| `type` | String                                   |             |



__Example__

```json
{
  "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": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "password": "string",
    "password_confirmation": "string",
    "title": "Operator"
  },
  "type": "user"
}
```



## Schema / CreatedApiKey {#schema-createdapikey}

An API key that was newly created

__Type__ Object

| Name             | Type                     | Description                              |
| ---------------- | ------------------------ | ---------------------------------------- |
| `active`         | Boolean                  |                                          |
| `id`             | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-651)                  |
| `identity`       | String                   | [Desc. `identity`](https://docs.tychron.com/api-reference/schemas/#desc-652)            |
| `inserted_at`    | String(format:date-time) | An ISO8601 formatted timestamp           |
| `key`            | String                   | Token used for HTTP APIs                 |
| `name`           | String(3..255)           | A friendly name to identify the API Key  |
| `notes`          | String(0..65535)         | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-653)               |
| `secret`         | String                   | Acts as the password used for Basic auth |
| `smpp_secert`    | String                   | [Desc. `smpp_secert`](https://docs.tychron.com/api-reference/schemas/#desc-654)         |
| `smpp_system_id` | String                   | [Desc. `smpp_system_id`](https://docs.tychron.com/api-reference/schemas/#desc-655)      |
| `updated_at`     | String(format:date-time) | An ISO8601 formatted timestamp           |

#### Desc. `id` {#desc-651}

A Universally unique identifier, which identifies the resource

#### Desc. `identity` {#desc-652}

Acts as the username in the authorization pair for MM4

#### Desc. `notes` {#desc-653}

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

#### Desc. `smpp_secert` {#desc-654}

Used as the password for SMPP connections

#### Desc. `smpp_system_id` {#desc-655}

Small identifier used when authorizing an SMPP connection



__Example__

```json
{
  "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 {#schema-createdsecretkey}

An Secret Key that was newly created

__Type__ Object

| Name          | Type                                         | Description                    |
| ------------- | -------------------------------------------- | ------------------------------ |
| `data`        | String                                       | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-656)      |
| `id`          | String(format:uuid)                          | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-657)        |
| `inserted_at` | String(format:date-time)                     | An ISO8601 formatted timestamp |
| `name`        | String(3..255)                               | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-658)      |
| `notes`       | String(0..65535)                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-659)     |
| `size`        | Enum(`16`, `24`, `32`, `48`, `64`):Number    | [Desc. `size`](https://docs.tychron.com/api-reference/schemas/#desc-660)      |
| `updated_at`  | String(format:date-time)                     | An ISO8601 formatted timestamp |
| `usage`       | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](https://docs.tychron.com/api-reference/schemas/#desc-661)     |

#### Desc. `data` {#desc-656}

Base64 Encoded secret key, only available on creation.

#### Desc. `id` {#desc-657}

A Universally unique identifier, which identifies the resource

#### Desc. `name` {#desc-658}

A friendly name to identify the Secret Key

#### Desc. `notes` {#desc-659}

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

#### Desc. `size` {#desc-660}

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` {#desc-661}

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__

```json
{
  "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 {#schema-cspaltbusinessidtyperesponse}

CSP Alt Business ID Types

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "NONE"
]
```



## Schema / CspBrand {#schema-cspbrand}

A TCR brand associated with the account

__Type__ Object

| Name                       | Type                                  | Description                             |
| -------------------------- | ------------------------------------- | --------------------------------------- |
| `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`                       | String(format:ulid)                   | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-662)                 |
| `inserted_at`              | String(format:date-time)              | An ISO8601 formatted timestamp          |
| `last_name`                | String                                |                                         |
| `name`                     | String                                | A display name to identify the brand    |
| `notes`                    | String                                | Any notes about the brand               |
| `phone_number`             | String                                |                                         |
| `shared`                   | Enum(`NO`, `OWNED`, `PARTNER`):String | [Desc. `shared`](https://docs.tychron.com/api-reference/schemas/#desc-663)             |
| `state`                    | String                                |                                         |
| `stock_exchange`           | String                                |                                         |
| `stock_symbol`             | String                                |                                         |
| `tcr_brand_id`             | String                                | The TCR issued ID of the brand          |
| `tcr_csp_id`               | String                                | The owning campaign service provider ID |
| `universal_ein`            | String                                |                                         |
| `updated_at`               | String(format:date-time)              | An ISO8601 formatted timestamp          |
| `vertical`                 | String                                |                                         |
| `website`                  | String(format:url)                    |                                         |
| `zip_code`                 | String                                |                                         |

#### Desc. `id` {#desc-662}

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

#### Desc. `shared` {#desc-663}

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__

```json
{
  "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 {#schema-cspbrandrelationshipsresponse}

CSP Brand Relationships

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "BASIC_ACCOUNT"
]
```



## Schema / CspBrandResponse {#schema-cspbrandresponse}

Single brand

__Type__ Object

| Name   | Type                         | Description |
| ------ | ---------------------------- | ----------- |
| `data` | [CspBrand](https://docs.tychron.com/api-reference/schemas/#schema-cspbrand) |             |
| `type` | String                       |             |



__Example__

```json
{
  "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 {#schema-cspbrandsresponse}

Brands

__Type__ Object

| Name        | Type                                               | Description |
| ----------- | -------------------------------------------------- | ----------- |
| `count`     | Integer                                            |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                       |             |
| `results`   | Array:[CspBrandResponse](https://docs.tychron.com/api-reference/schemas/#schema-cspbrandresponse) |             |



__Example__

```json
{
  "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 {#schema-cspcampaign}

A TCR campaign

__Type__ Object

| Name                        | Type                                  | Description                             |
| --------------------------- | ------------------------------------- | --------------------------------------- |
| `attributes`                | `attributes`                          |                                         |
| `dca_approved`              | Boolean                               | [Desc. `dca_approved`](https://docs.tychron.com/api-reference/schemas/#desc-664)       |
| `description`               | String                                | Description of the campaign             |
| `embedded_link_sample`      | String                                |                                         |
| `help_keywords`             | String                                |                                         |
| `help_message`              | String                                |                                         |
| `id`                        | String(format:ulid)                   | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-665)                 |
| `inserted_at`               | String(format:date-time)              | An ISO8601 formatted timestamp          |
| `message_flow`              | String                                |                                         |
| `name`                      | String(1..255)                        | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-666)               |
| `notes`                     | String                                | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-667)              |
| `optin_keywords`            | String                                |                                         |
| `optin_message`             | String                                |                                         |
| `optout_keywords`           | String                                |                                         |
| `optout_message`            | String                                |                                         |
| `privacy_policy_link`       | String                                |                                         |
| `sample_messages`           | Array(0..5):String                    | [Desc. `sample_messages`](https://docs.tychron.com/api-reference/schemas/#desc-668)    |
| `shared`                    | Enum(`NO`, `OWNED`, `PARTNER`):String | [Desc. `shared`](https://docs.tychron.com/api-reference/schemas/#desc-669)             |
| `sub_use_case`              | Array:String                          | Additional usecases for a campaign      |
| `tcr_brand_id`              | String                                | The brand the campaign is attached to   |
| `tcr_campaign_id`           | String                                | The TCR issued campaign ID              |
| `tcr_csp_id`                | String                                | The owning campaign service provider ID |
| `tcr_reseller_id`           | String                                | TCR Issued Reseller ID                  |
| `tcr_status`                | String                                | TCR Activation Status                   |
| `terms_and_conditions_link` | String                                |                                         |
| `updated_at`                | String(format:date-time)              | An ISO8601 formatted timestamp          |
| `use_case`                  | String                                | [Desc. `use_case`](https://docs.tychron.com/api-reference/schemas/#desc-670)           |

#### Desc. `dca_approved` {#desc-664}

Whether or not the campaign has been approved by the DCA

#### Desc. `id` {#desc-665}

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

#### Desc. `name` {#desc-666}

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` {#desc-667}

Any notes about the campaign.

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

#### Desc. `sample_messages` {#desc-668}

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

Note that different usecases may require more samples.

#### Desc. `shared` {#desc-669}

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` {#desc-670}

Campaign Usecase, see CSP Enums for possible values

__attributes__

| Name                        | Type    | Description |
| --------------------------- | ------- | ----------- |
| `has_affiliate_marketing`   | Boolean |             |
| `has_age_gated_content`     | Boolean |             |
| `has_direct_lending`        | Boolean |             |
| `has_embedded_link`         | Boolean |             |
| `has_embedded_phone_number` | Boolean |             |
| `has_number_pooling`        | Boolean |             |
| `has_subscriber_help`       | Boolean |             |
| `has_subscriber_opt_in`     | Boolean |             |
| `has_subscriber_opt_out`    | Boolean |             |
| `has_terms_and_conditions`  | Boolean |             |



__Example__

```json
{
  "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 {#schema-cspcampaignresponse}

Single campaign

__Type__ Object

| Name           | Type                               | Description |
| -------------- | ---------------------------------- | ----------- |
| `associations` | `associations`                     |             |
| `data`         | [CspCampaign](https://docs.tychron.com/api-reference/schemas/#schema-cspcampaign) |             |
| `type`         | String                             |             |

__associations__

| Name                    | Type                    | Description                                |
| ----------------------- | ----------------------- | ------------------------------------------ |
| `brand`                 | `brand`                 | The parent CSP Brand of the campaign       |
| `shared_resource_group` | `shared_resource_group` | [Desc. `shared_resource_group`](https://docs.tychron.com/api-reference/schemas/#desc-671) |

#### Desc. `shared_resource_group` {#desc-671}

The Shared Resource Group on the campaign, if any

__brand__

| Name           | Type                        | Description             |
| -------------- | --------------------------- | ----------------------- |
| `id`           | String(format:uuid)         | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-672) |
| `tcr_brand_id` | String(format:tcr_brand_id) |                         |

#### Desc. `id` {#desc-672}

A Universally unique identifier, which identifies the resource



__shared_resource_group__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-673) |

#### Desc. `id` {#desc-673}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "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 {#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

| Name       | Type                     | Description                   |
| ---------- | ------------------------ | ----------------------------- |
| `code`     | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-674):String | [Desc. `code`](https://docs.tychron.com/api-reference/schemas/#desc-675)     |
| `detail`   | String                   | [Desc. `detail`](https://docs.tychron.com/api-reference/schemas/#desc-676)   |
| `params`   | `params`                 | [Desc. `params`](https://docs.tychron.com/api-reference/schemas/#desc-677)   |
| `sub_code` | String                   | [Desc. `sub_code`](https://docs.tychron.com/api-reference/schemas/#desc-678) |
| `title`    | String                   | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-679)    |

#### Enum Values code {#enum-674}

Allowed values

* `conflict.changing_shared_resource_group`

#### Desc. `code` {#desc-675}

Contains static error code representing the error

#### Desc. `detail` {#desc-676}

Contains dynamic description of the error

#### Desc. `params` {#desc-677}

Contains additional parameters based on the permission error

#### Desc. `sub_code` {#desc-678}

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

#### Desc. `title` {#desc-679}

A user friendly title for the error.

__params__

| Name | Type | Description |
| ---- | ---- | ----------- |



__Example__

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



## Schema / CspCampaignSharingConflictErrorsResponse {#schema-cspcampaignsharingconflicterrorsresponse}

Errors Response when a sharing conflict is present

__Type__ Object

| Name     | Type                                                                                           | Description                       |
| -------- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
| `errors` | Array:[CspCampaignSharingConflictErrorsObject](https://docs.tychron.com/api-reference/schemas/#schema-cspcampaignsharingconflicterrorsobject) | A list of errors from the request |



__Example__

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



## Schema / CspCampaignStatusesResponse {#schema-cspcampaignstatusesresponse}

CSP Campaign Statuses

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "ACTIVE"
]
```



## Schema / CspCampaignUnsharingConflictErrorsObject {#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

| Name       | Type                                                 | Description                   |
| ---------- | ---------------------------------------------------- | ----------------------------- |
| `code`     | Enum(`conflict.remove_shared_resource_group`):String | [Desc. `code`](https://docs.tychron.com/api-reference/schemas/#desc-680)     |
| `detail`   | String                                               | [Desc. `detail`](https://docs.tychron.com/api-reference/schemas/#desc-681)   |
| `params`   | `params`                                             | [Desc. `params`](https://docs.tychron.com/api-reference/schemas/#desc-682)   |
| `sub_code` | String                                               | [Desc. `sub_code`](https://docs.tychron.com/api-reference/schemas/#desc-683) |
| `title`    | String                                               | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-684)    |

#### Desc. `code` {#desc-680}

Contains static error code representing the error

#### Desc. `detail` {#desc-681}

Contains dynamic description of the error

#### Desc. `params` {#desc-682}

Contains additional parameters based on the permission error

#### Desc. `sub_code` {#desc-683}

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

#### Desc. `title` {#desc-684}

A user friendly title for the error.

__params__

| Name | Type | Description |
| ---- | ---- | ----------- |



__Example__

```json
{
  "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 {#schema-cspcampaignunsharingconflicterrorsresponse}

Errors Response when a sharing conflict is present

__Type__ Object

| Name     | Type                                                                                               | Description                       |
| -------- | -------------------------------------------------------------------------------------------------- | --------------------------------- |
| `errors` | Array:[CspCampaignUnsharingConflictErrorsObject](https://docs.tychron.com/api-reference/schemas/#schema-cspcampaignunsharingconflicterrorsobject) | A list of errors from the request |



__Example__

```json
{
  "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 {#schema-cspcampaignsresponse}

Campaigns

__Type__ Object

| Name        | Type                                                     | Description |
| ----------- | -------------------------------------------------------- | ----------- |
| `count`     | Integer                                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                             |             |
| `results`   | Array:[CspCampaignResponse](https://docs.tychron.com/api-reference/schemas/#schema-cspcampaignresponse) |             |



__Example__

```json
{
  "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 {#schema-cspcnpsresponse}

CSP Event Categories

__Type__ Object

| Name | Type   | Description |
| ---- | ------ | ----------- |
| `*`  | String |             |



__Example__

```json
{
  "*": "string"
}
```



## Schema / CspDcasResponse {#schema-cspdcasresponse}

CSP DCAs

__Type__ Array

| Name  | Type                   | Description |
| ----- | ---------------------- | ----------- |
| `[n]` | [SubObject](https://docs.tychron.com/api-reference/schemas/#type-685) | DCA         |

__Example__

```json
[
  {
    "displayName": "string",
    "id": "string"
  }
]
```
#### SubObject {#type-685}

Sub-Schema

DCA

__Type__ Object

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| `displayName` | String |             |
| `id`          | String |             |






## Schema / CspEntityTypesResponse {#schema-cspentitytypesresponse}

CSP Entity Types

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "PRIVATE_PROFIT"
]
```



## Schema / CspErrorCodesResponse {#schema-csperrorcodesresponse}

CSP Error Codes

__Type__ Object

| Name | Type   | Description |
| ---- | ------ | ----------- |
| `*`  | String |             |



__Example__

```json
{
  "*": "string"
}
```



## Schema / CspEventCategoriesResponse {#schema-cspeventcategoriesresponse}

CSP Event Categories

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "string"
]
```



## Schema / CspMnoOperationStatusesResponse {#schema-cspmnooperationstatusesresponse}

CSP MNO Operation Statuses

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "REVIEW"
]
```



## Schema / CspMnosResponse {#schema-cspmnosresponse}

CSP MNOs

__Type__ Array

| Name  | Type                   | Description |
| ----- | ---------------------- | ----------- |
| `[n]` | [SubObject](https://docs.tychron.com/api-reference/schemas/#type-686) | MNO         |

__Example__

```json
[
  {
    "displayName": "string",
    "networkId": 0.0,
    "osrBitmaskindex": 0.0
  }
]
```
#### SubObject {#type-686}

Sub-Schema

MNO

__Type__ Object

| Name              | Type   | Description |
| ----------------- | ------ | ----------- |
| `displayName`     | String |             |
| `networkId`       | Number |             |
| `osrBitmaskindex` | Number |             |






## Schema / CspStockExchangesResponse {#schema-cspstockexchangesresponse}

CSP Stock Exchanges

__Type__ Array

| Name  | Type   | Description |
| ----- | ------ | ----------- |
| `[n]` | String |             |

__Example__

```json
[
  "AMEX"
]
```



## Schema / CspUsecase {#schema-cspusecase}

CSP Usecases

__Type__ Object

| Name              | Type    | Description |
| ----------------- | ------- | ----------- |
| `classification`  | String  |             |
| `description`     | String  |             |
| `displayName`     | String  |             |
| `maxSubUsecases`  | Number  |             |
| `minSubUsecases`  | Number  |             |
| `validSubUsecase` | Boolean |             |



__Example__

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



## Schema / CspUsecasesResponse {#schema-cspusecasesresponse}

CSP Usecases

__Type__ Object

| Name | Type                             | Description |
| ---- | -------------------------------- | ----------- |
| `*`  | [CspUsecase](https://docs.tychron.com/api-reference/schemas/#schema-cspusecase) |             |



__Example__

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



## Schema / CspVertical {#schema-cspvertical}

CSP Vertical

__Type__ Object

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| `description` | String |             |
| `displayName` | String |             |
| `industryId`  | String |             |



__Example__

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



## Schema / CspVerticalsResponse {#schema-cspverticalsresponse}

CSP Verticals

__Type__ Object

| Name | Type                               | Description |
| ---- | ---------------------------------- | ----------- |
| `*`  | [CspVertical](https://docs.tychron.com/api-reference/schemas/#schema-cspvertical) |             |



__Example__

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



## Schema / CspVettingClass {#schema-cspvettingclass}

CSP Vetting Class

__Type__ Object

| Name             | Type    | Description |
| ---------------- | ------- | ----------- |
| `description`    | String  |             |
| `displayName`    | String  |             |
| `enabled`        | Boolean |             |
| `id`             | String  |             |
| `validatyMonths` | Number  |             |



__Example__

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



## Schema / CspVettingClassesResponse {#schema-cspvettingclassesresponse}

CSP Vetting Classes

__Type__ Array

| Name  | Type                                       | Description |
| ----- | ------------------------------------------ | ----------- |
| `[n]` | [CspVettingClass](https://docs.tychron.com/api-reference/schemas/#schema-cspvettingclass) |             |

__Example__

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



## Schema / CspVettingFeedbackCode {#schema-cspvettingfeedbackcode}

CSP Vetting Feedback Code

__Type__ Object

| Name   | Type   | Description |
| ------ | ------ | ----------- |
| `code` | String |             |
| `name` | String |             |



__Example__

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



## Schema / CspVettingFeedbackCodesResponse {#schema-cspvettingfeedbackcodesresponse}

CSP Vetting Feedback Codes

__Type__ Array

| Name  | Type                                                     | Description |
| ----- | -------------------------------------------------------- | ----------- |
| `[n]` | [CspVettingFeedbackCode](https://docs.tychron.com/api-reference/schemas/#schema-cspvettingfeedbackcode) |             |

__Example__

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



## Schema / CspVettingProvider {#schema-cspvettingprovider}

CSP Vetting Provider

__Type__ Object

| Name                 | Type                | Description |
| -------------------- | ------------------- | ----------- |
| `displayName`        | String              |             |
| `evpId`              | String              |             |
| `tcrBillable`        | Boolean             |             |
| `vettingClasses`     | Array:String        |             |
| `vettingInstruction` | String(format:json) |             |



__Example__

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



## Schema / CspVettingProvidersResponse {#schema-cspvettingprovidersresponse}

CSP Vetting Providers

__Type__ Array

| Name  | Type                                             | Description |
| ----- | ------------------------------------------------ | ----------- |
| `[n]` | [CspVettingProvider](https://docs.tychron.com/api-reference/schemas/#schema-cspvettingprovider) |             |

__Example__

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



## Schema / Destination {#schema-destination}

A did's voice destination

__Type__ Object

| Name            | Type                                   | Description                          |
| --------------- | -------------------------------------- | ------------------------------------ |
| `activated`     | Boolean                                | [Desc. `activated`](https://docs.tychron.com/api-reference/schemas/#desc-687)       |
| `auth_identity` | String                                 | The username for a BASIC auth_method |
| `auth_method`   | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-688)     |
| `auth_secret`   | String                                 | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-689)     |
| `destination`   | String                                 | [Desc. `destination`](https://docs.tychron.com/api-reference/schemas/#desc-690)     |
| `id`            | String(format:uuid)                    | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-691)              |
| `inserted_at`   | String(format:date-time)               | An ISO8601 formatted timestamp       |
| `priority`      | Integer                                | [Desc. `priority`](https://docs.tychron.com/api-reference/schemas/#desc-692)        |
| `type`          | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-693):String               | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-694)            |
| `updated_at`    | String(format:date-time)               | An ISO8601 formatted timestamp       |
| `wait_time`     | Integer                                | [Desc. `wait_time`](https://docs.tychron.com/api-reference/schemas/#desc-695)       |

#### Desc. `activated` {#desc-687}

Whether or not the destination is considered for routing

#### Desc. `auth_method` {#desc-688}

The authorization method to used for HTTP_ROUTE destinations

#### Desc. `auth_secret` {#desc-689}

The password for a BASIC auth_method or token for BEARER auth_method

#### Desc. `destination` {#desc-690}

Depending on the type, this field can contain different data.

* `VOIP` - destination should be in the form of `local@domain` where local is the destination prefix and domain is the SIP capable server to handle the request
* `PSTN` - destination should be a plain format number (e.g. 12003004000), can also be a comma separated list to allow multiple destinations
* `HTTP_ROUTE` - destination should be an http uri which will handle the routing request
* `TTS` - destination should be one of the pre-approved values (more may be added in the future):
  * `DISCONNECTED`
  * `TEXT_ONLY`
  * `BUSY`
  * `CONGESTION`
* `TTS_CUSTOM` - destination should be the message to be read
* `TTS_MESSAGE_SET` - destination will be set to "UNUSED" regardless of provided value, instead the tts_message_set_id MUST be set on the request

#### Desc. `id` {#desc-691}

A Universally unique identifier, which identifies the resource

#### Desc. `priority` {#desc-692}

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

#### Enum Values type {#enum-693}

Allowed values

* `VOIP`
* `PSTN`
* `HTTP_ROUTE`
* `TTS`
* `TTS_CUSTOM`
* `TTS_MESSAGE_SET`

#### Desc. `type` {#desc-694}

The destination type, see destination field for more detail

#### Desc. `wait_time` {#desc-695}

How long will calls wait for the destination to connect.



__Example__

```json
{
  "activated": true,
  "auth_identity": "username",
  "auth_method": "BASIC",
  "auth_secret": "password",
  "destination": "http://example.com/http/route/call",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "priority": 1,
  "type": "HTTP_ROUTE",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "wait_time": 120
}
```



## Schema / DestinationResponse {#schema-destinationresponse}

Single Number Destination

__Type__ Object

| Name           | Type                               | Description |
| -------------- | ---------------------------------- | ----------- |
| `associations` | `associations`                     |             |
| `data`         | [Destination](https://docs.tychron.com/api-reference/schemas/#schema-destination) |             |
| `type`         | String                             |             |

__associations__

| Name              | Type              | Description |
| ----------------- | ----------------- | ----------- |
| `did`             | `did`             |             |
| `tts_message_set` | `tts_message_set` |             |

__did__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-696) |

#### Desc. `id` {#desc-696}

A Universally unique identifier, which identifies the resource



__tts_message_set__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-697) |

#### Desc. `id` {#desc-697}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "associations": {
    "did": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    },
    "tts_message_set": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "activated": true,
    "auth_identity": "username",
    "auth_method": "BASIC",
    "auth_secret": "password",
    "destination": "http://example.com/http/route/call",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "priority": 1,
    "type": "HTTP_ROUTE",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "wait_time": 120
  },
  "type": "number_destination"
}
```



## Schema / DestinationsResponse {#schema-destinationsresponse}

Number Destinations

__Type__ Object

| Name        | Type                                                     | Description |
| ----------- | -------------------------------------------------------- | ----------- |
| `count`     | Integer                                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                             |             |
| `results`   | Array:[DestinationResponse](https://docs.tychron.com/api-reference/schemas/#schema-destinationresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "did": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        },
        "tts_message_set": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        }
      },
      "data": {
        "activated": true,
        "auth_identity": "username",
        "auth_method": "BASIC",
        "auth_secret": "password",
        "destination": "http://example.com/http/route/call",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "priority": 1,
        "type": "HTTP_ROUTE",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "wait_time": 120
      },
      "type": "number_destination"
    }
  ]
}
```



## Schema / ErrorObject {#schema-errorobject}

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

__Type__ Object

| Name       | Type     | Description                   |
| ---------- | -------- | ----------------------------- |
| `code`     | String   | [Desc. `code`](https://docs.tychron.com/api-reference/schemas/#desc-698)     |
| `detail`   | String   | [Desc. `detail`](https://docs.tychron.com/api-reference/schemas/#desc-699)   |
| `source`   | `source` |                               |
| `sub_code` | String   | [Desc. `sub_code`](https://docs.tychron.com/api-reference/schemas/#desc-700) |
| `title`    | String   | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-701)    |

#### Desc. `code` {#desc-698}

Contains static error code representing the error

#### Desc. `detail` {#desc-699}

Contains dynamic description of the error

#### Desc. `sub_code` {#desc-700}

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

Primarily used by requests

#### Desc. `title` {#desc-701}

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

__source__

| Name      | Type   | Description  |
| --------- | ------ | ------------ |
| `pointer` | String | JSON Pointer |



__Example__

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



## Schema / ErrorsResponse {#schema-errorsresponse}

Common errors response

__Type__ Object

| Name     | Type                                     | Description                       |
| -------- | ---------------------------------------- | --------------------------------- |
| `errors` | Array:[ErrorObject](https://docs.tychron.com/api-reference/schemas/#schema-errorobject) | A list of errors from the request |



__Example__

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



## Schema / EventSubscription {#schema-eventsubscription}

Event Subscription

__Type__ Object

| Name                  | Type                                                 | Description                         |
| --------------------- | ---------------------------------------------------- | ----------------------------------- |
| `auth_identity`       | String                                               | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-702)  |
| `auth_method`         | Enum(`NONE`, `BASIC`, `BEARER`):String               | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-703)    |
| `auth_name`           | String                                               | [Desc. `auth_name`](https://docs.tychron.com/api-reference/schemas/#desc-704)      |
| `auth_secret`         | String                                               | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-705)    |
| `custom_headers`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-706)                         | [Desc. `custom_headers`](https://docs.tychron.com/api-reference/schemas/#desc-707) |
| `custom_query_params` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-708)                         |                                     |
| `data`                | String                                               | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-709)           |
| `enabled`             | Boolean                                              | [Desc. `enabled`](https://docs.tychron.com/api-reference/schemas/#desc-710)        |
| `expired_at`          | String(format:date-time)                             | An ISO8601 formatted timestamp      |
| `id`                  | String(format:uuid)                                  | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-711)             |
| `inserted_at`         | String(format:date-time)                             | An ISO8601 formatted timestamp      |
| `name`                | String(..255)                                        | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-712)           |
| `notes`               | String(..65535)                                      | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-713)          |
| `protocol`            | Enum(`NONE`, `HTTP`, `SMTP`, `SFTP`, `EMAIL`):String | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-714)       |
| `recipient`           | String                                               | [Desc. `recipient`](https://docs.tychron.com/api-reference/schemas/#desc-715)      |
| `started_at`          | String(format:date-time)                             | An ISO8601 formatted timestamp      |
| `topics`              | Array:[Enum](https://docs.tychron.com/api-reference/schemas/#enum-716):String                       | [Desc. `topics`](https://docs.tychron.com/api-reference/schemas/#desc-717)         |
| `updated_at`          | String(format:date-time)                             | An ISO8601 formatted timestamp      |

#### Desc. `auth_identity` {#desc-702}

Acts as the `username` for an auth pair.

#### Desc. `auth_method` {#desc-703}

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` {#desc-704}

Currently unused, but kept for future use.

#### Desc. `auth_secret` {#desc-705}

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

#### SubObject {#type-706}

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

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_headers` {#desc-707}

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

#### SubObject {#type-708}

Sub-Schema

A single query parameter pair.


__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `data` {#desc-709}

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. "john.doe@example.com")

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

#### Desc. `enabled` {#desc-710}

Is the subscription enabled to handle events?

Subscriptions can be toggled on or off as needed.

#### Desc. `id` {#desc-711}

A Universally unique identifier, which identifies the resource

#### Desc. `name` {#desc-712}

The friendly given name for this subscription

#### Desc. `notes` {#desc-713}

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` {#desc-714}

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` {#desc-715}

Only applicable when the `protocol` is SMTP, this will be the recipient address (e.g. "events@example.com")

#### Enum Values topics {#enum-716}

Allowed values

* `NONE`
* `DID`
* `CSP_BRAND`
* `CSP_CAMPAIGN`
* `ORDER`
* `REQUEST`
* `OSR`

#### Desc. `topics` {#desc-717}

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



__Example__

```json
{
  "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": "events@example.com",
  "started_at": "2021-08-13T04:08:44.762841Z",
  "topics": [
    "NONE"
  ],
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / EventSubscriptionResponse {#schema-eventsubscriptionresponse}

Single event subscription record

__Type__ Object

| Name   | Type                                           | Description |
| ------ | ---------------------------------------------- | ----------- |
| `data` | [EventSubscription](https://docs.tychron.com/api-reference/schemas/#schema-eventsubscription) |             |
| `type` | String                                         |             |



__Example__

```json
{
  "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": "events@example.com",
    "started_at": "2021-08-13T04:08:44.762841Z",
    "topics": [
      "NONE"
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "event_subscription"
}
```



## Schema / EventSubscriptionsResponse {#schema-eventsubscriptionsresponse}

Event Subscriptions

__Type__ Object

| Name        | Type                                                                 | Description |
| ----------- | -------------------------------------------------------------------- | ----------- |
| `count`     | Integer                                                              |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                         |             |
| `results`   | Array:[EventSubscriptionResponse](https://docs.tychron.com/api-reference/schemas/#schema-eventsubscriptionresponse) |             |



__Example__

```json
{
  "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": "events@example.com",
        "started_at": "2021-08-13T04:08:44.762841Z",
        "topics": [
          "NONE"
        ],
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "event_subscription"
    }
  ]
}
```



## Schema / ExportTask {#schema-exporttask}

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


__Type__ Object

| Name              | Type                                   | Description                       |
| ----------------- | -------------------------------------- | --------------------------------- |
| `date`            | String(format:date)                    | [Desc. `date`](https://docs.tychron.com/api-reference/schemas/#desc-718)         |
| `error_code`      | Enum(`OK`):String                      | [Desc. `error_code`](https://docs.tychron.com/api-reference/schemas/#desc-719)   |
| `format`          | Enum(`CSV`, `MLJSON`):String           | [Desc. `format`](https://docs.tychron.com/api-reference/schemas/#desc-720)       |
| `id`              | String(format:ulid)                    | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-721)           |
| `inserted_at`     | String(format:date-time)               | An ISO8601 formatted timestamp    |
| `on_done_actions` | [OnDoneActions](https://docs.tychron.com/api-reference/schemas/#schema-ondoneactions) |                                   |
| `reference_id`    | String(1..255)                         | [Desc. `reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-722) |
| `status`          | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-723):String               | [Desc. `status`](https://docs.tychron.com/api-reference/schemas/#desc-724)       |
| `type`            | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-725):String               | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-726)         |
| `updated_at`      | String(format:date-time)               | An ISO8601 formatted timestamp    |

#### Desc. `date` {#desc-718}

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` {#desc-719}

* `OK` - there was no error

#### Desc. `format` {#desc-720}

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` {#desc-721}

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

#### Desc. `reference_id` {#desc-722}

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 {#enum-723}

Allowed values

* `NEW`
* `SCHEDULED`
* `PROCESSING`
* `STORING`
* `DELIVERING`
* `COMPLETED`
* `ABORTED`
* `ERROR`

#### Desc. `status` {#desc-724}

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 {#enum-725}

Allowed values

* `API`
* `MMS`
* `SMS`
* `VOICE`
* `BALANCE`
* `MISC`

#### Desc. `type` {#desc-726}

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__

```json
{
  "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 {#schema-exporttaskresponse}

Single CDR Export Task

__Type__ Object

| Name   | Type                             | Description |
| ------ | -------------------------------- | ----------- |
| `data` | [ExportTask](https://docs.tychron.com/api-reference/schemas/#schema-exporttask) |             |
| `type` | String                           |             |



__Example__

```json
{
  "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 {#schema-exporttasksresponse}

CDR Export Tasks

__Type__ Object

| Name        | Type                                                   | Description |
| ----------- | ------------------------------------------------------ | ----------- |
| `count`     | Integer                                                |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                           |             |
| `results`   | Array:[ExportTaskResponse](https://docs.tychron.com/api-reference/schemas/#schema-exporttaskresponse) |             |



__Example__

```json
{
  "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 {#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__

```json
"string"
```



## Schema / Message {#schema-message}

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


__Type__ Object

| Name          | Type                     | Description                    |
| ------------- | ------------------------ | ------------------------------ |
| `body`        | String(1..4096)          | The text that should be read   |
| `id`          | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-727)        |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp |
| `priority`    | Integer                  | [Desc. `priority`](https://docs.tychron.com/api-reference/schemas/#desc-728)  |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp |

#### Desc. `id` {#desc-727}

A Universally unique identifier, which identifies the resource

#### Desc. `priority` {#desc-728}

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



__Example__

```json
{
  "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 {#schema-messageresponse}

Single message

__Type__ Object

| Name   | Type                       | Description |
| ------ | -------------------------- | ----------- |
| `data` | [Message](https://docs.tychron.com/api-reference/schemas/#schema-message) |             |
| `type` | String                     |             |



__Example__

```json
{
  "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 {#schema-messageset}

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


__Type__ Object

| Name          | Type                     | Description                    |
| ------------- | ------------------------ | ------------------------------ |
| `id`          | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-729)        |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp |
| `name`        | String(1..255)           | Name of the Message Set        |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp |

#### Desc. `id` {#desc-729}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "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 {#schema-messagesetresponse}

Single message set

__Type__ Object

| Name   | Type                             | Description |
| ------ | -------------------------------- | ----------- |
| `data` | [MessageSet](https://docs.tychron.com/api-reference/schemas/#schema-messageset) |             |
| `type` | String                           |             |



__Example__

```json
{
  "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 {#schema-messagesetsresponse}

Message Sets

__Type__ Object

| Name        | Type                                                   | Description |
| ----------- | ------------------------------------------------------ | ----------- |
| `count`     | Integer                                                |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                           |             |
| `results`   | Array:[MessageSetResponse](https://docs.tychron.com/api-reference/schemas/#schema-messagesetresponse) |             |



__Example__

```json
{
  "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 {#schema-messagesresponse}

Messages

__Type__ Object

| Name        | Type                                             | Description |
| ----------- | ------------------------------------------------ | ----------- |
| `count`     | Integer                                          |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                     |             |
| `results`   | Array:[MessageResponse](https://docs.tychron.com/api-reference/schemas/#schema-messageresponse) |             |



__Example__

```json
{
  "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 {#schema-messagingautoresponse}

Messaging Auto Response

__Type__ Object

| Name          | Type                         | Description                       |
| ------------- | ---------------------------- | --------------------------------- |
| `id`          | String(format:uuid)          | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-730)           |
| `inserted_at` | String(format:date-time)     | An ISO8601 formatted timestamp    |
| `keywords`    | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-736) | [Desc. `keywords`](https://docs.tychron.com/api-reference/schemas/#desc-737)     |
| `name`        | String                       | Display name of the Auto Response |
| `notes`       | String                       | Any notes about the auto response |
| `updated_at`  | String(format:date-time)     | An ISO8601 formatted timestamp    |

#### Desc. `id` {#desc-730}

A Universally unique identifier, which identifies the resource

#### SubObject {#type-736}

Sub-Schema

__Type__ Object

| Name          | Type    | Description                      |
| ------------- | ------- | -------------------------------- |
| `intercept`   | Boolean | [Desc. `intercept`](https://docs.tychron.com/api-reference/schemas/#desc-731)   |
| `is_wildcard` | Boolean | [Desc. `is_wildcard`](https://docs.tychron.com/api-reference/schemas/#desc-732) |
| `keyword`     | String  | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-733)     |
| `message`     | String  | [Desc. `message`](https://docs.tychron.com/api-reference/schemas/#desc-734)     |
| `message2`    | String  | [Desc. `message2`](https://docs.tychron.com/api-reference/schemas/#desc-735)    |

#### Desc. `intercept` {#desc-731}

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` {#desc-732}

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` {#desc-733}

The word to trigger this specific keyword.

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

#### Desc. `message` {#desc-734}

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` {#desc-735}

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` {#desc-737}

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



__Example__

```json
{
  "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 {#schema-messagingautoresponseresponse}

Single Messaging Auto Response

__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [MessagingAutoResponse](https://docs.tychron.com/api-reference/schemas/#schema-messagingautoresponse) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "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 {#schema-messagingautoresponsesresponse}

Messaging Auto Responses

__Type__ Object

| Name        | Type                                                                         | Description |
| ----------- | ---------------------------------------------------------------------------- | ----------- |
| `count`     | Integer                                                                      |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                                 |             |
| `results`   | Array:[MessagingAutoResponseResponse](https://docs.tychron.com/api-reference/schemas/#schema-messagingautoresponseresponse) |             |



__Example__

```json
{
  "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 {#schema-number}

A provisioned did

__Type__ Object

| Name                     | Type                              | Description                              |
| ------------------------ | --------------------------------- | ---------------------------------------- |
| `activated`              | Boolean                           | [Desc. `activated`](https://docs.tychron.com/api-reference/schemas/#desc-738)           |
| `brand_name`             | String(0..255)                    | [Desc. `brand_name`](https://docs.tychron.com/api-reference/schemas/#desc-739)          |
| `description`            | String                            | [Desc. `description`](https://docs.tychron.com/api-reference/schemas/#desc-740)         |
| `forward_number`         | String                            | [Desc. `forward_number`](https://docs.tychron.com/api-reference/schemas/#desc-741)      |
| `help_message`           | String(0..255)                    | [Desc. `help_message`](https://docs.tychron.com/api-reference/schemas/#desc-742)        |
| `id`                     | String(format:uuid)               | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-743)                  |
| `inserted_at`            | String(format:date-time)          | An ISO8601 formatted timestamp           |
| `message_class`          | Enum(`NONE`, `A2P`, `P2P`):String |                                          |
| `mms_enabled`            | Boolean                           | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-744)         |
| `number`                 | String                            | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-745)              |
| `rate_center`            | String                            |                                          |
| `segment_overrides`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-750)      | [Desc. `segment_overrides`](https://docs.tychron.com/api-reference/schemas/#desc-751)   |
| `segment_threshold`      | Integer                           | [Desc. `segment_threshold`](https://docs.tychron.com/api-reference/schemas/#desc-752)   |
| `sms_enabled`            | Boolean                           | [Desc. `sms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-753)         |
| `state`                  | String                            |                                          |
| `tier`                   | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-754):String          | [Desc. `tier`](https://docs.tychron.com/api-reference/schemas/#desc-755)                |
| `updated_at`             | String(format:date-time)          | An ISO8601 formatted timestamp           |
| `upgrade_asset_handling` | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-756):String          | The asset handling flag for SMS Upgrades |
| `voice_enabled`          | Boolean                           | [Desc. `voice_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-757)       |

#### Desc. `activated` {#desc-738}

Is the DID active for use?

#### Desc. `brand_name` {#desc-739}

Custom Brand Name when the number is not actively apart of TCR's Campaign setup, this field will be used in place of the brand name.

Added on 2026-05-04.

#### Desc. `description` {#desc-740}

Any notes to attach to the number.

#### Desc. `forward_number` {#desc-741}

When this DID receives an inbound message, the message will be routed to the specified `forward_number`.

Note. using forward_number or its switch equivalent will charge the account for 2 messages, instead of 1:
* Once for the inbound (to the host number)
* Again for the outbound (from the host number to the forward number)

If this field is nil, or blank the `sms_switch` will be used for routing instead

#### Desc. `help_message` {#desc-742}

Custom HELP Message that should be sent when an inbound message matching "HELP" is received.

For help messages longer than 255 characters, they must handled by the receiver.

#### Desc. `id` {#desc-743}

A Universally unique identifier, which identifies the resource

#### Desc. `mms_enabled` {#desc-744}

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

#### Desc. `number` {#desc-745}

The 3 to 15 digit code of the number.

#### SubObject {#type-750}

Sub-Schema

__Type__ Object

| Name                  | Type                | Description                              |
| --------------------- | ------------------- | ---------------------------------------- |
| `encoding`            | Integer             | [Desc. `encoding`](https://docs.tychron.com/api-reference/schemas/#desc-746)            |
| `id`                  | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-747)                  |
| `segment_threshold`   | Integer             | [Desc. `segment_threshold`](https://docs.tychron.com/api-reference/schemas/#desc-748)   |
| `target_reference_id` | String              | [Desc. `target_reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-749) |

#### Desc. `encoding` {#desc-746}

The SMS encoding that this override should trigger on.

#### Desc. `id` {#desc-747}

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

#### Desc. `segment_threshold` {#desc-748}

See number's segment_threshold for more information.

#### Desc. `target_reference_id` {#desc-749}

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` {#desc-751}

While the segment_threshold can be used to apply to all outgoing sms messages, sometimes
its required to tailor fit an upgrade to a particular carrier.

Note, when updating the segment_overrides, all overrides must be provided for the did, any unspecified overrides will be removed.

#### Desc. `segment_threshold` {#desc-752}

How many segments should a outgoing message have before it triggers an MMS upgrade.

Contact support to learn more about MMS upgrades.

0 will disable upgrades, any value greater than 1 will trigger an upgrade when that many sms
segments would have been sent.

Upgrades only apply to HTTP originated traffic, customers using SMPP will not for outbound
are not subject to upgrades.

#### Desc. `sms_enabled` {#desc-753}

Whether or not a number is messaging capable.

Note that this flag also affects mms availability.

#### Enum Values tier {#enum-754}

Allowed values

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

#### Desc. `tier` {#desc-755}

The billing tier associated with the number:

* `L0` - Tychron OCN Tier 0
* `L1` - Tychron OCN Tier 1
* `T1` - Partner Tier 0
* `T2` - Partner Tier 1
* `T3` - Partner Tier 3
* `AK` - Alaska
* `HI` - Hawaii
* `CAN` - Canada
* `PR` - Puerto Rico
* `TF` - Tollfree
* `SHORTCODE` - General Shortcode
* `M0` - Mobile Tier 0
* `M1` - Mobile Tier 1
* `BYON` - Bring-Your-Own-Number

#### Enum Values upgrade_asset_handling {#enum-756}

Allowed values

* `FALLBACK`
* `OFF`
* `ALWAYS_UPGRADE`
* `SEGMENT_UPGRADE`

#### Desc. `voice_enabled` {#desc-757}

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



__Example__

```json
{
  "activated": true,
  "brand_name": "ACME Corp.",
  "description": "Test number used for XYZ.Corp\n",
  "forward_number": "12003004000",
  "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "message_class": "A2P",
  "mms_enabled": true,
  "number": "12003004000",
  "rate_center": "KISSIMEE",
  "segment_overrides": [
    {
      "encoding": 0,
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "segment_threshold": 0,
      "target_reference_id": "us_tmobile"
    }
  ],
  "segment_threshold": 1,
  "sms_enabled": true,
  "state": "FL",
  "tier": "T1",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "upgrade_asset_handling": "FALLBACK",
  "voice_enabled": true
}
```



## Schema / NumberClientSuspension {#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

| Name              | Type                                               | Description                          |
| ----------------- | -------------------------------------------------- | ------------------------------------ |
| `block_direction` | Enum(`NONE`, `INBOUND`, `OUTBOUND`, `BOTH`):String | [Desc. `block_direction`](https://docs.tychron.com/api-reference/schemas/#desc-758) |
| `block_messaging` | Enum(`NONE`, `SMS`, `MMS`, `ALL`):String           | [Desc. `block_messaging`](https://docs.tychron.com/api-reference/schemas/#desc-759) |
| `block_voip`      | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-760):String                           | [Desc. `block_voip`](https://docs.tychron.com/api-reference/schemas/#desc-761)      |
| `host_number`     | String                                             | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-762)     |
| `id`              | String(format:uuid)                                | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-763)              |
| `inserted_at`     | String(format:date-time)                           | An ISO8601 formatted timestamp       |
| `notes`           | String                                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-764)           |
| `updated_at`      | String(format:date-time)                           | An ISO8601 formatted timestamp       |

#### Desc. `block_direction` {#desc-758}

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` {#desc-759}

What type of messaging should be blocked by this suspension?

#### Enum Values block_voip {#enum-760}

Allowed values

* `NONE`
* `ORIGINATION`
* `TERMINATION`
* `ALL`

#### Desc. `block_voip` {#desc-761}

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` {#desc-762}

A reference to the host did's number.

#### Desc. `id` {#desc-763}

A Universally unique identifier, which identifies the resource

#### Desc. `notes` {#desc-764}

Any notes on the suspension.



__Example__

```json
{
  "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 {#schema-numberclientsuspensionresponse}

Single Number Client Suspension

__Type__ Object

| Name           | Type                                                     | Description |
| -------------- | -------------------------------------------------------- | ----------- |
| `associations` | `associations`                                           |             |
| `data`         | [NumberClientSuspension](https://docs.tychron.com/api-reference/schemas/#schema-numberclientsuspension) |             |
| `type`         | String                                                   |             |

__associations__

| Name       | Type       | Description                   |
| ---------- | ---------- | ----------------------------- |
| `host_did` | `host_did` | [Desc. `host_did`](https://docs.tychron.com/api-reference/schemas/#desc-765) |

#### Desc. `host_did` {#desc-765}

A reference to the host number (did) that this client suspension belongs to.

__host_did__

| Name     | Type                | Description                 |
| -------- | ------------------- | --------------------------- |
| `id`     | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-766)     |
| `number` | String              | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-767) |

#### Desc. `id` {#desc-766}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-767}

Will match the host_number from the client suspension, may not be set under certain
circumstances.



__Example__

```json
{
  "associations": {
    "host_did": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "number": "12003004000"
    }
  },
  "data": {
    "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"
  },
  "type": "number_client_suspension"
}
```



## Schema / NumberClientSuspensionsResponse {#schema-numberclientsuspensionsresponse}

Number Client Suspensions

__Type__ Object

| Name        | Type                                                                           | Description |
| ----------- | ------------------------------------------------------------------------------ | ----------- |
| `count`     | Integer                                                                        |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                                   |             |
| `results`   | Array:[NumberClientSuspensionResponse](https://docs.tychron.com/api-reference/schemas/#schema-numberclientsuspensionresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "host_did": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
          "number": "12003004000"
        }
      },
      "data": {
        "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"
      },
      "type": "number_client_suspension"
    }
  ]
}
```



## Schema / NumberInventoryCoverage {#schema-numberinventorycoverage}

Number Inventory Coverage.

Coverage reports a "count" of all potential numbers or codes available.

It simply reports how many are available, and no specific codes.


__Type__ Object

| Name            | Type                         | Description                        |
| --------------- | ---------------------------- | ---------------------------------- |
| `count`         | Integer                      | [Desc. `count`](https://docs.tychron.com/api-reference/schemas/#desc-768)         |
| `items`         | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-773) |                                    |
| `search_params` | `search_params`              | [Desc. `search_params`](https://docs.tychron.com/api-reference/schemas/#desc-774) |

#### Desc. `count` {#desc-768}

The total entries in items.

#### SubObject {#type-773}

Sub-Schema

__Type__ Object

| Name          | Type                              | Description                |
| ------------- | --------------------------------- | -------------------------- |
| `block`       | String(format:nanp-block)         |                            |
| `count`       | Integer                           | [Desc. `count`](https://docs.tychron.com/api-reference/schemas/#desc-769) |
| `lata`        | String                            |                            |
| `npa`         | String(format:npa)                | [Desc. `npa`](https://docs.tychron.com/api-reference/schemas/#desc-770)   |
| `nxx`         | String(format:nxx)                | [Desc. `nxx`](https://docs.tychron.com/api-reference/schemas/#desc-771)   |
| `rate_center` | String                            |                            |
| `state`       | String                            |                            |
| `type`        | Enum(`TENDLC`, `TOLLFREE`):String | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-772)  |

#### Desc. `count` {#desc-769}

How numbers are available based on the parameters in this entry?

#### Desc. `npa` {#desc-770}

The Area Code of the numbers in this entry.

#### Desc. `nxx` {#desc-771}

The Exchange Code of the numbers in this entry.

#### Desc. `type` {#desc-772}

The type of number, primarily TENDLC.





#### Desc. `search_params` {#desc-774}

The search parameters that were used to generate the response.

Note it may differ slightly from input due to defaults, or different enum casings.

__search_params__

| Name          | Type                     | Description |
| ------------- | ------------------------ | ----------- |
| `count_by`    | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-775):String |             |
| `npa`         | String                   |             |
| `nxx`         | String                   |             |
| `rate_center` | String                   |             |
| `state`       | String                   |             |

#### Enum Values count_by {#enum-775}

Allowed values

* `state`
* `rate_center`
* `npa_nxx`
* `block`



__Example__

```json
{
  "count": 10,
  "items": [
    {
      "block": "9",
      "count": 101,
      "lata": "236",
      "npa": "202",
      "nxx": "201",
      "rate_center": "WSHNGTNZN1",
      "state": "DC",
      "type": "TENDLC"
    }
  ],
  "search_params": {
    "count_by": "npa_nxx",
    "npa": "202",
    "nxx": "201",
    "rate_center": "WSHNGTNZN1",
    "state": "DC"
  }
}
```



## Schema / NumberInventoryCoverageResponse {#schema-numberinventorycoverageresponse}

The response body for an number inventory coverage request.

This reports only the count, or number of available codes or numbers based on the search parameters, broken down by the `count_by`.


__Type__ Object

| Name   | Type                                                       | Description |
| ------ | ---------------------------------------------------------- | ----------- |
| `data` | [NumberInventoryCoverage](https://docs.tychron.com/api-reference/schemas/#schema-numberinventorycoverage) |             |
| `type` | String                                                     |             |



__Example__

```json
{
  "data": {
    "count": 10,
    "items": [
      {
        "block": "9",
        "count": 101,
        "lata": "236",
        "npa": "202",
        "nxx": "201",
        "rate_center": "WSHNGTNZN1",
        "state": "DC",
        "type": "TENDLC"
      }
    ],
    "search_params": {
      "count_by": "npa_nxx",
      "npa": "202",
      "nxx": "201",
      "rate_center": "WSHNGTNZN1",
      "state": "DC"
    }
  },
  "type": "number_inventory"
}
```



## Schema / NumberResponse {#schema-numberresponse}

Single number

__Type__ Object

| Name           | Type                     | Description |
| -------------- | ------------------------ | ----------- |
| `associations` | `associations`           |             |
| `data`         | [Number](https://docs.tychron.com/api-reference/schemas/#schema-number) |             |
| `type`         | String                   |             |

__associations__

| Name               | Type               | Description |
| ------------------ | ------------------ | ----------- |
| `campaign`         | `campaign`         |             |
| `messaging_switch` | `messaging_switch` |             |
| `voice_switch`     | `voice_switch`     |             |

__campaign__

| Name              | Type                | Description                           |
| ----------------- | ------------------- | ------------------------------------- |
| `id`              | String(format:ulid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-776)               |
| `tcr_brand_id`    | String              | The brand the campaign is attached to |
| `tcr_campaign_id` | String              | The TCR issued campaign ID            |

#### Desc. `id` {#desc-776}

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



__messaging_switch__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-777) |

#### Desc. `id` {#desc-777}

A Universally unique identifier, which identifies the resource



__voice_switch__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-778) |

#### Desc. `id` {#desc-778}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "associations": {
    "campaign": {
      "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
      "tcr_brand_id": "B000000",
      "tcr_campaign_id": "C000000"
    },
    "messaging_switch": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    },
    "voice_switch": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "activated": true,
    "brand_name": "ACME Corp.",
    "description": "Test number used for XYZ.Corp\n",
    "forward_number": "12003004000",
    "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "message_class": "A2P",
    "mms_enabled": true,
    "number": "12003004000",
    "rate_center": "KISSIMEE",
    "segment_overrides": [
      {
        "encoding": 0,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "segment_threshold": 0,
        "target_reference_id": "us_tmobile"
      }
    ],
    "segment_threshold": 1,
    "sms_enabled": true,
    "state": "FL",
    "tier": "T1",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "upgrade_asset_handling": "FALLBACK",
    "voice_enabled": true
  },
  "type": "number"
}
```



## Schema / NumbersResponse {#schema-numbersresponse}

Numbers

__Type__ Object

| Name        | Type                                           | Description |
| ----------- | ---------------------------------------------- | ----------- |
| `count`     | Integer                                        |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                   |             |
| `results`   | Array:[NumberResponse](https://docs.tychron.com/api-reference/schemas/#schema-numberresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "campaign": {
          "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
          "tcr_brand_id": "B000000",
          "tcr_campaign_id": "C000000"
        },
        "messaging_switch": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        },
        "voice_switch": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        }
      },
      "data": {
        "activated": true,
        "brand_name": "ACME Corp.",
        "description": "Test number used for XYZ.Corp\n",
        "forward_number": "12003004000",
        "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "message_class": "A2P",
        "mms_enabled": true,
        "number": "12003004000",
        "rate_center": "KISSIMEE",
        "segment_overrides": [
          {
            "encoding": 0,
            "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
            "segment_threshold": 0,
            "target_reference_id": "us_tmobile"
          }
        ],
        "segment_threshold": 1,
        "sms_enabled": true,
        "state": "FL",
        "tier": "T1",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "upgrade_asset_handling": "FALLBACK",
        "voice_enabled": true
      },
      "type": "number"
    }
  ]
}
```



## Schema / OnDoneAction {#schema-ondoneaction}

__Type__ Object

| Name             | Type                                                 | Description                         |
| ---------------- | ---------------------------------------------------- | ----------------------------------- |
| `archive_format` | Enum(`NONE`, `TAR`, `TAR_GZ`, `ZIP`):String          | [Desc. `archive_format`](https://docs.tychron.com/api-reference/schemas/#desc-779) |
| `auth_identity`  | String                                               | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-780)  |
| `auth_method`    | Enum(`NONE`, `BASIC`, `BEARER`):String               | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-781)    |
| `auth_secret`    | String                                               | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-782)    |
| `data`           | String                                               | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-783)           |
| `error_code`     | Enum(`OK`):String                                    | [Desc. `error_code`](https://docs.tychron.com/api-reference/schemas/#desc-784)     |
| `filename`       | String                                               | [Desc. `filename`](https://docs.tychron.com/api-reference/schemas/#desc-785)       |
| `protocol`       | Enum(`NONE`, `HTTP`, `SFTP`):String                  | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-786)       |
| `reference_id`   | String(0..255)                                       | [Desc. `reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-787)   |
| `status`         | Enum(`NEW`, `COMPLETED`, `ERROR`, `REJECTED`):String | [Desc. `status`](https://docs.tychron.com/api-reference/schemas/#desc-788)         |
| `type`           | Enum(`NONE`, `NOTIFY`, `SEND`):String                | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-789)           |

#### Desc. `archive_format` {#desc-779}

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` {#desc-780}

See `auth_method` for details

#### Desc. `auth_method` {#desc-781}

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` {#desc-782}

See `auth_method` for details

#### Desc. `data` {#desc-783}

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. `error_code` {#desc-784}

Further description of a status.

* `OK` - no error, all is well

#### Desc. `filename` {#desc-785}

Optional override for SFTP filename.

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

#### Desc. `protocol` {#desc-786}

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` {#desc-787}

Optional client provided id to identify the action.

#### Desc. `status` {#desc-788}

The general status of the action.

* `NEW` - the task has not been executed yet
* `COMPLETED` - the task has been executed and was completed successfully
* `ERROR` - the task has experienced an error, and will retry at a later time
  A task will not be considered completed until ALL actions are completed successfully
* `REJECTED` - the action has been rejected possibly due to an error in the task

#### Desc. `type` {#desc-789}

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__

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



## Schema / OnDoneActions {#schema-ondoneactions}

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

| Name  | Type                                 | Description |
| ----- | ------------------------------------ | ----------- |
| `[n]` | [OnDoneAction](https://docs.tychron.com/api-reference/schemas/#schema-ondoneaction) |             |

__Example__

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



## Schema / OptoutItem {#schema-optoutitem}

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

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


__Type__ Object

| Name            | Type                     | Description                        |
| --------------- | ------------------------ | ---------------------------------- |
| `host_number`   | String                   | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-790)   |
| `id`            | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-791)            |
| `inserted_at`   | String(format:date-time) | An ISO8601 formatted timestamp     |
| `keyword`       | String                   | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-792)       |
| `remote_number` | String                   | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-793) |
| `updated_at`    | String(format:date-time) | An ISO8601 formatted timestamp     |

#### Desc. `host_number` {#desc-790}

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

That is the number that received the optout request.

#### Desc. `id` {#desc-791}

A Universally unique identifier, which identifies the resource

#### Desc. `keyword` {#desc-792}

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` {#desc-793}

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



__Example__

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



## Schema / OptoutItemResponse {#schema-optoutitemresponse}

Single Optout Item

__Type__ Object

| Name           | Type                             | Description |
| -------------- | -------------------------------- | ----------- |
| `associations` | `associations`                   |             |
| `data`         | [OptoutItem](https://docs.tychron.com/api-reference/schemas/#schema-optoutitem) |             |
| `type`         | String                           |             |

__associations__

| Name       | Type       | Description                   |
| ---------- | ---------- | ----------------------------- |
| `host_did` | `host_did` | [Desc. `host_did`](https://docs.tychron.com/api-reference/schemas/#desc-794) |
| `sms`      | `sms`      | [Desc. `sms`](https://docs.tychron.com/api-reference/schemas/#desc-795)      |

#### Desc. `host_did` {#desc-794}

A reference to the host number (did) that this optout belongs to.

#### Desc. `sms` {#desc-795}

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.

__host_did__

| Name     | Type                | Description                 |
| -------- | ------------------- | --------------------------- |
| `id`     | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-796)     |
| `number` | String              | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-797) |

#### Desc. `id` {#desc-796}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-797}

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



__sms__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:ulid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-798) |

#### Desc. `id` {#desc-798}

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



__Example__

```json
{
  "associations": {
    "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",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "number_optout_item"
}
```



## Schema / OptoutItemsResponse {#schema-optoutitemsresponse}

Number Optout Items

__Type__ Object

| Name        | Type                                                   | Description |
| ----------- | ------------------------------------------------------ | ----------- |
| `count`     | Integer                                                |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                           |             |
| `results`   | Array:[OptoutItemResponse](https://docs.tychron.com/api-reference/schemas/#schema-optoutitemresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "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",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "number_optout_item"
    }
  ]
}
```



## Schema / Order {#schema-order}

An order that has been placed.

Orders are a collection record for requests, a means by which requests are grouped together.

Orders themselves do nothing after their checkout.


__Type__ Object

| Name          | Type                                     | Description                    |
| ------------- | ---------------------------------------- | ------------------------------ |
| `error_code`  | [OrderErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-ordererrorcode) |                                |
| `id`          | String(format:ulid)                      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-799)        |
| `inserted_at` | String(format:date-time)                 | An ISO8601 formatted timestamp |
| `name`        | String(3..255)                           | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-800)      |
| `notes`       | String(0..65535)                         | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-801)     |
| `status`      | [OrderStatus](https://docs.tychron.com/api-reference/schemas/#schema-orderstatus)       |                                |
| `updated_at`  | String(format:date-time)                 | An ISO8601 formatted timestamp |

#### Desc. `id` {#desc-799}

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

#### Desc. `name` {#desc-800}

Display name for Order.

#### Desc. `notes` {#desc-801}

Any additional text about the order, useful for informing someone about the order's purpose.



__Example__

```json
{
  "error_code": "OK",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "Add Messaging to 10 Numbers",
  "notes": "Order for Client XYZ\n",
  "status": "NEW",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / OrderErrorCode {#schema-ordererrorcode}

An error code further describes what issues an order or request may have had.

* `OK` - there were no issues, this is the most common error code.
* `NOT_IMPLEMENTED` - unlikely to happen, but in the case of requests that have not been implemented, this will be set.
* `RETRIES_EXHAUSTED` - the order or request has attempted to complete processing enough times to exhaust all of its retries.
* `RECORD_CONFLICT` - there was a conflict with another order or request and the request could not completed as a result.
* `OWNERSHIP_MISMATCH` - an order or request was created which would modify the resource of another account, and has refused to process.
* `MESSAGING_UNAVAILABLE` - the request required the target resource have messaging enabled, but it was not.
* `INVALID_EMAIL_ADDRESS` - the request required an email address for operation but found it to be invalid, either due to secondary validations or upstream.
* `INVALID_PHONE_NUMBER` - the request required a phone number (typically for addressing purposes), but it was found to be invalid.
* `INVALID_ADDRESS` - the request required a valid address but it was found to be invalid.
* `LOA_REQUIRED` - the request requires an loa to release the number from its original provider, or may be known to require additional action
* `DID_NOT_FOUND` - the did or number specified was not found and the request cannot be completed.
* `ASSOCIATED_WITH_DIDS` - the resource is still associated with a did or number and cannot be modified (typically a removal).
* `BRAND_NOT_FOUND` - the CSP Brand specified was not found and the request cannot be completed.
* `UPSTREAM_ERROR` - an unspecified upstream error has prevented the request from being completed, this will typically be resolved by support personel.
* `UPSTREAM_INTERNAL_ERROR` - the upstream has an internal error, this typically gets resolved by itself, but if it persists please contact support.
* `UPSTREAM_TEMPORARY_ERROR` - the upstream has a temporary, this can happen for a myriad of reasons but will typically be resolved with some time.
* `UPSTREAM_PARAMETER_ERROR` - similar to an `UPSTREAM_ERROR`, but the issue is known to be with the upstream request itself, will typically be fixed within twenty-four hours.
* `UPSTREAM_RECORD_NOT_OWNED` - the upstream resource in question has changed ownership since last known, typically happens when a number has been ported without triggering a eco-system event.
* `UPSTREAM_RECORD_NOT_FOUND` - the upstream resource does not exist, or it used to but was removed without warning.
* `UPSTREAM_REJECTED` - the upstream has rejected the request.


__Type__ Enum:String

* `OK`
* `NOT_IMPLEMENTED`
* `RETRIES_EXHAUSTED`
* `RECORD_CONFLICT`
* `OWNERSHIP_MISMATCH`
* `MESSAGING_UNAVAILABLE`
* `INVALID_EMAIL_ADDRESS`
* `INVALID_PHONE_NUMBER`
* `INVALID_ADDRESS`
* `LOA_REQUIRED`
* `DID_NOT_FOUND`
* `ASSOCIATED_WITH_DIDS`
* `BRAND_NOT_FOUND`
* `UPSTREAM_ERROR`
* `UPSTREAM_INTERNAL_ERROR`
* `UPSTREAM_TEMPORARY_ERROR`
* `UPSTREAM_PARAMETER_ERROR`
* `UPSTREAM_RECORD_NOT_OWNED`
* `UPSTREAM_RECORD_NOT_FOUND`
* `UPSTREAM_REJECTED`


__Example__

```json
"OK"
```



## Schema / OrderResponse {#schema-orderresponse}

Single order

__Type__ Object

| Name   | Type                   | Description |
| ------ | ---------------------- | ----------- |
| `data` | [Order](https://docs.tychron.com/api-reference/schemas/#schema-order) |             |
| `type` | String                 |             |



__Example__

```json
{
  "data": {
    "error_code": "OK",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "Add Messaging to 10 Numbers",
    "notes": "Order for Client XYZ\n",
    "status": "NEW",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "order"
}
```



## Schema / OrderStatus {#schema-orderstatus}

An overall status of a respective order or request.

The status will be a summary of an order's requests, or just the status of the request itself.

* `NEW` - the order has not yet been accepted by the ordering system for processing.
* `MANUAL` - the order requires manual intervention, typically from a support personel.
* `AUTHOR_MANUAL` - the order requires manual intervention, specifically from the author.
* `COMPLETED` - the order has been completed without errors (i.e. all requests are `COMPLETED`).
* `COMPLETED_WITH_ERRORS` - the order has been completed, but some requests may have errors.
* `PROCESSING` - the order is being processed.
* `PENDING` - similar to processing, but only applies when an order is delayed.
* `ERROR` - the order has completely failed and all requests have failed.
* `REJECTED` - the order was rejected and was not processed.
* `CANCELLED` - the order has been cancelled, typically by a support personel.
* `EXPIRED` - the order or its requests have all expired.
* `CRON` - the order has been scheduled to process at a later time.
* `CART` - the order is a cart.
* `REVIEW` - the order or cart is pending review from an operations personel.


__Type__ Enum:String

* `NEW`
* `MANUAL`
* `AUTHOR_MANUAL`
* `COMPLETED`
* `COMPLETED_WITH_ERRORS`
* `PROCESSING`
* `PENDING`
* `ERROR`
* `REJECTED`
* `CANCELLED`
* `EXPIRED`
* `CRON`
* `CART`
* `REVIEW`


__Example__

```json
"NEW"
```



## Schema / OrdersResponse {#schema-ordersresponse}

Orders

__Type__ Object

| Name        | Type                                         | Description |
| ----------- | -------------------------------------------- | ----------- |
| `count`     | Integer                                      |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                 |             |
| `results`   | Array:[OrderResponse](https://docs.tychron.com/api-reference/schemas/#schema-orderresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "Add Messaging to 10 Numbers",
        "notes": "Order for Client XYZ\n",
        "status": "NEW",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "order"
    }
  ]
}
```



## Schema / OverwriteRequest {#schema-overwriterequest}

A request created whenever a request to delete or overwrite an sms enabled numbers

__Type__ Object

| Name            | Type                     | Description                            |
| --------------- | ------------------------ | -------------------------------------- |
| `activation`    | String(format:date-time) | An ISO8601 formatted timestamp         |
| `error_code`    | Enum(`OK`):String        | Further explanation of an error status |
| `expires_at`    | String(format:date-time) | An ISO8601 formatted timestamp         |
| `id`            | String(format:ulid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-802)                |
| `inserted_at`   | String(format:date-time) | An ISO8601 formatted timestamp         |
| `is_stale`      | Boolean                  |                                        |
| `review_status` | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-803):String | [Desc. `review_status`](https://docs.tychron.com/api-reference/schemas/#desc-804)     |
| `status`        | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-805):String | [Desc. `status`](https://docs.tychron.com/api-reference/schemas/#desc-806)            |
| `tn`            | String                   |                                        |
| `updated_at`    | String(format:date-time) | An ISO8601 formatted timestamp         |

#### Desc. `id` {#desc-802}

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

#### Enum Values review_status {#enum-803}

Allowed values

* `NONE`
* `APPROVED`
* `REJECTED`
* `AUTO_APPROVED`
* `AUTO_REJECTED`
* `FORCE_DELETED`

#### Desc. `review_status` {#desc-804}

The review status of the request, defaults to NONE.

#### Enum Values status {#enum-805}

Allowed values

* `NEW`
* `REVIEWED`
* `APPROVED`
* `REJECTED`
* `ERROR`
* `STALE`
* `DELETED`

#### Desc. `status` {#desc-806}

The current processing status of the request



__Example__

```json
{
  "activation": "2021-08-13T04:08:44.762841Z",
  "error_code": "OK",
  "expires_at": "2021-08-13T04:08:44.762841Z",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "is_stale": true,
  "review_status": "NONE",
  "status": "NEW",
  "tn": "12003004000",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / OverwriteRequestResponse {#schema-overwriterequestresponse}

Single Overwrite Request

__Type__ Object

| Name           | Type                                         | Description |
| -------------- | -------------------------------------------- | ----------- |
| `associations` | `associations`                               |             |
| `data`         | [OverwriteRequest](https://docs.tychron.com/api-reference/schemas/#schema-overwriterequest) |             |
| `type`         | String                                       |             |

__associations__

| Name             | Type             | Description                        |
| ---------------- | ---------------- | ---------------------------------- |
| `did`            | `did`            | [Desc. `did`](https://docs.tychron.com/api-reference/schemas/#desc-807)           |
| `new_nnid_entry` | `new_nnid_entry` |                                    |
| `reviewed_user`  | `reviewed_user`  | [Desc. `reviewed_user`](https://docs.tychron.com/api-reference/schemas/#desc-808) |

#### Desc. `did` {#desc-807}

The DID associated with this overwrite, note that the number may not
be present if the DID was removed.

As a rule of thumb, if a request has been approved, the ID should not be trusted.

#### Desc. `reviewed_user` {#desc-808}

A limited scope of who reviewed the request (approved/rejected).

Note that an administrator can also approve requests.

__did__

| Name     | Type                | Description             |
| -------- | ------------------- | ----------------------- |
| `id`     | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-809) |
| `number` | String              |                         |

#### Desc. `id` {#desc-809}

A Universally unique identifier, which identifies the resource



__new_nnid_entry__

| Name               | Type   | Description                      |
| ------------------ | ------ | -------------------------------- |
| `service_provider` | String | Name of the new service provider |



__reviewed_user__

| Name         | Type                | Description             |
| ------------ | ------------------- | ----------------------- |
| `first_name` | String              |                         |
| `id`         | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-810) |
| `last_name`  | String              |                         |

#### Desc. `id` {#desc-810}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "associations": {
    "did": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "number": "12003004000"
    },
    "new_nnid_entry": {
      "service_provider": "ACME Corp"
    },
    "reviewed_user": {
      "first_name": "John",
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "last_name": "Doe"
    }
  },
  "data": {
    "activation": "2021-08-13T04:08:44.762841Z",
    "error_code": "OK",
    "expires_at": "2021-08-13T04:08:44.762841Z",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "is_stale": true,
    "review_status": "NONE",
    "status": "NEW",
    "tn": "12003004000",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "osr_overwrite_request"
}
```



## Schema / OverwriteRequestsResponse {#schema-overwriterequestsresponse}

Overwrite Requests

__Type__ Object

| Name        | Type                                                               | Description |
| ----------- | ------------------------------------------------------------------ | ----------- |
| `count`     | Integer                                                            |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                       |             |
| `results`   | Array:[OverwriteRequestResponse](https://docs.tychron.com/api-reference/schemas/#schema-overwriterequestresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "did": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
          "number": "12003004000"
        },
        "new_nnid_entry": {
          "service_provider": "ACME Corp"
        },
        "reviewed_user": {
          "first_name": "John",
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
          "last_name": "Doe"
        }
      },
      "data": {
        "activation": "2021-08-13T04:08:44.762841Z",
        "error_code": "OK",
        "expires_at": "2021-08-13T04:08:44.762841Z",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "is_stale": true,
        "review_status": "NONE",
        "status": "NEW",
        "tn": "12003004000",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "osr_overwrite_request"
    }
  ]
}
```



## Schema / PageInfo {#schema-pageinfo}

Contains pagination cursor information

__Type__ Object

| Name                | Type    | Description |
| ------------------- | ------- | ----------- |
| `first`             | String  |             |
| `has_next_page`     | Boolean |             |
| `has_previous_page` | Boolean |             |
| `last`              | String  |             |



__Example__

```json
{
  "first": "string",
  "has_next_page": true,
  "has_previous_page": true,
  "last": "string"
}
```



## Schema / PermissionErrorObject {#schema-permissionerrorobject}

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

__Type__ Object

| Name       | Type                     | Description                   |
| ---------- | ------------------------ | ----------------------------- |
| `code`     | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-811):String | [Desc. `code`](https://docs.tychron.com/api-reference/schemas/#desc-812)     |
| `detail`   | String                   | [Desc. `detail`](https://docs.tychron.com/api-reference/schemas/#desc-813)   |
| `params`   | `params`                 | [Desc. `params`](https://docs.tychron.com/api-reference/schemas/#desc-814)   |
| `sub_code` | String                   | [Desc. `sub_code`](https://docs.tychron.com/api-reference/schemas/#desc-815) |
| `title`    | String                   | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-816)    |

#### Enum Values code {#enum-811}

Allowed values

* `access_denied.no_scope`
* `access_denied.insufficient_level`
* `access_denied.resource_unavailable`
* `access_denied.action_disabled`
* `access_denied.action_unavailable`

#### Desc. `code` {#desc-812}

Contains static error code representing the error

#### Desc. `detail` {#desc-813}

Contains dynamic description of the error

#### Desc. `params` {#desc-814}

Contains additional parameters based on the permission error

#### Desc. `sub_code` {#desc-815}

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

#### Desc. `title` {#desc-816}

A user friendly title for the error.

__params__

| Name       | Type                                    | Description |
| ---------- | --------------------------------------- | ----------- |
| `action`   | String                                  |             |
| `level`    | Enum(`guest`, `client`, `admin`):String |             |
| `resource` | String                                  |             |



__Example__

```json
{
  "code": "access_denied.no_scope",
  "detail": "No scope available to user role",
  "params": {
    "action": "index",
    "level": "guest",
    "resource": "resource"
  },
  "sub_code": "none",
  "title": "Access Denied, no scope available"
}
```



## Schema / PermissionErrorsResponse {#schema-permissionerrorsresponse}

Common errors response

__Type__ Object

| Name     | Type                                                         | Description                       |
| -------- | ------------------------------------------------------------ | --------------------------------- |
| `errors` | Array:[PermissionErrorObject](https://docs.tychron.com/api-reference/schemas/#schema-permissionerrorobject) | A list of errors from the request |



__Example__

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```



## Schema / Request {#schema-request}

Specific action or operation that should take place

__Type__ Object

| Name          | Type                                     | Description                    |
| ------------- | ---------------------------------------- | ------------------------------ |
| `error_code`  | [OrderErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-ordererrorcode) |                                |
| `id`          | String(format:ulid)                      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-817)        |
| `inserted_at` | String(format:date-time)                 | An ISO8601 formatted timestamp |
| `name`        | String(1..255)                           |                                |
| `notes`       | String                                   |                                |
| `status`      | [OrderStatus](https://docs.tychron.com/api-reference/schemas/#schema-orderstatus)       |                                |
| `type`        | [RequestType](https://docs.tychron.com/api-reference/schemas/#schema-requesttype)       |                                |
| `updated_at`  | String(format:date-time)                 | An ISO8601 formatted timestamp |
| `*`           | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-818)                      |                                |

#### Desc. `id` {#desc-817}

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

#### One-Of {#type-818}

Types

* [RequestAddCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestaddcampaignnumbersdata)
* [RequestAddMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestaddmessagingnumbersdata)
* [RequestAddVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestaddvoicenumbersdata)
* [RequestNewNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestnewnumbersdata)
* [RequestRegisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-requestregisterbranddata)
* [RequestRegisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-requestregistercampaigndata)
* [RequestRemoveCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestremovecampaignnumbersdata)
* [RequestRemoveMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestremovemessagingnumbersdata)
* [RequestRemoveNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestremovenumbersdata)
* [RequestRemoveVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-requestremovevoicenumbersdata)
* [RequestUnregisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-requestunregisterbranddata)
* [RequestUnregisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-requestunregistercampaigndata)
* [RequestVetBrandData](https://docs.tychron.com/api-reference/schemas/#schema-requestvetbranddata)



__Example__

```json
{
  "error_code": "OK",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "SMS Tollfree Numbers 2021-08-12",
  "notes": "SMS Enablements",
  "status": "NEW",
  "type": "ADD_CAMPAIGN_NUMBERS",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "*": {
    "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
    "numbers": [
      "12003004000"
    ],
    "tcr_campaign_id": "C000000",
    "tmobile_enabled": true
  }
}
```



## Schema / RequestAddCampaignNumbersData {#schema-requestaddcampaignnumbersdata}

Request for register numbers under campaign


__Type__ Object

| Name              | Type                | Description                          |
| ----------------- | ------------------- | ------------------------------------ |
| `campaign_id`     | String(format:uuid) | [Desc. `campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-819)     |
| `numbers`         | Array:String        | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-820)         |
| `tcr_campaign_id` | String              | [Desc. `tcr_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-821) |
| `tmobile_enabled` | Boolean             | [Desc. `tmobile_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-822) |

#### Desc. `campaign_id` {#desc-819}

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.

#### Desc. `numbers` {#desc-820}

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.

#### Desc. `tcr_campaign_id` {#desc-821}

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.

#### Desc. `tmobile_enabled` {#desc-822}

Whether or not this request is subject to additional T-Mobile enablement, this will be auto-populated during request processing.

Note that this is based on a campaign's supported MNOs.



__Example__

```json
{
  "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
  "numbers": [
    "12003004000"
  ],
  "tcr_campaign_id": "C000000",
  "tmobile_enabled": true
}
```



## Schema / RequestAddMessagingNumbersData {#schema-requestaddmessagingnumbersdata}

Request for enabling numbers for messaging.

Note that this request handles two different kinds of enablements:

* BYON (Bring Your Own Number) type enablements, wheree a number will be registered for messaging only.
* Enabling messaging on an existing number.


__Type__ Object

| Name            | Type                      | Description                        |
| --------------- | ------------------------- | ---------------------------------- |
| `api_key_ids`   | Array:String(format:uuid) | [Desc. `api_key_ids`](https://docs.tychron.com/api-reference/schemas/#desc-823)   |
| `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](https://docs.tychron.com/api-reference/schemas/#desc-824) |
| `mms_enabled`   | Boolean                   | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-825)   |
| `numbers`       | Array:String(format:tel)  | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-826)       |
| `switch_id`     | String(format:uuid)       | [Desc. `switch_id`](https://docs.tychron.com/api-reference/schemas/#desc-827)     |

#### Desc. `api_key_ids` {#desc-823}

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` {#desc-824}

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` {#desc-825}

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` {#desc-826}

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` {#desc-827}

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__

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



## Schema / RequestAddVoiceNumbersData {#schema-requestaddvoicenumbersdata}

Request for Voice BYOC (Bring Your Own Carrier) Numbers

__Type__ Object

| Name        | Type                | Description                    |
| ----------- | ------------------- | ------------------------------ |
| `numbers`   | Array:String        | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-828)   |
| `switch_id` | String(format:uuid) | [Desc. `switch_id`](https://docs.tychron.com/api-reference/schemas/#desc-829) |

#### Desc. `numbers` {#desc-828}

A list of NANP 11-digit numbers to add

#### Desc. `switch_id` {#desc-829}

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



__Example__

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



## Schema / RequestDocument {#schema-requestdocument}

__Type__ Object

| Name           | Type                     | Description                       |
| -------------- | ------------------------ | --------------------------------- |
| `content_type` | String                   | [Desc. `content_type`](https://docs.tychron.com/api-reference/schemas/#desc-830) |
| `expires_at`   | String(format:date-time) | [Desc. `expires_at`](https://docs.tychron.com/api-reference/schemas/#desc-831)   |
| `filename`     | String                   | [Desc. `filename`](https://docs.tychron.com/api-reference/schemas/#desc-832)     |
| `id`           | String(format:ulid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-833)           |
| `inserted_at`  | String(format:date-time) | An ISO8601 formatted timestamp    |
| `name`         | String(1..128)           | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-834)         |
| `notes`        | String                   | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-835)        |
| `updated_at`   | String(format:date-time) | An ISO8601 formatted timestamp    |

#### Desc. `content_type` {#desc-830}

The mime type of the document, this will be returned as the content-type header when downloading the asset.

#### Desc. `expires_at` {#desc-831}

An ISO8601 timestamp denoting when the document will be considered expired, note you may still be able to retrieve the associated file, but once over the timestamp, it will not be guaranteed.

#### Desc. `filename` {#desc-832}

The filename of the document.

#### Desc. `id` {#desc-833}

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

#### Desc. `name` {#desc-834}

A unique name identifying the document, must be unique to the request

#### Desc. `notes` {#desc-835}

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



__Example__

```json
{
  "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "expires_at": "2021-08-13T04:08:44.762841Z",
  "filename": "acme_corp-lrn-2025-03-03.docx",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "LOA",
  "notes": "string",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / RequestDocumentResponse {#schema-requestdocumentresponse}

Request Document

__Type__ Object

| Name   | Type                                       | Description |
| ------ | ------------------------------------------ | ----------- |
| `data` | [RequestDocument](https://docs.tychron.com/api-reference/schemas/#schema-requestdocument) |             |
| `type` | String                                     |             |



__Example__

```json
{
  "data": {
    "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "expires_at": "2021-08-13T04:08:44.762841Z",
    "filename": "acme_corp-lrn-2025-03-03.docx",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "LOA",
    "notes": "string",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "request_document"
}
```



## Schema / RequestDocumentsResponse {#schema-requestdocumentsresponse}

Request Documents

__Type__ Object

| Name        | Type                                                             | Description |
| ----------- | ---------------------------------------------------------------- | ----------- |
| `count`     | Integer                                                          |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                     |             |
| `results`   | Array:[RequestDocumentResponse](https://docs.tychron.com/api-reference/schemas/#schema-requestdocumentresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "expires_at": "2021-08-13T04:08:44.762841Z",
        "filename": "acme_corp-lrn-2025-03-03.docx",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "LOA",
        "notes": "string",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "request_document"
    }
  ]
}
```



## Schema / RequestNewNumbersData {#schema-requestnewnumbersdata}

Request for acquiring new numbers.

__Type__ Object

| Name           | Type                                      | Description                       |
| -------------- | ----------------------------------------- | --------------------------------- |
| `addons`       | [AddonsData](https://docs.tychron.com/api-reference/schemas/#schema-addonsdata)          |                                   |
| `city`         | String                                    |                                   |
| `min_quantity` | String                                    | [Desc. `min_quantity`](https://docs.tychron.com/api-reference/schemas/#desc-836) |
| `npa`          | String                                    | [Desc. `npa`](https://docs.tychron.com/api-reference/schemas/#desc-837)          |
| `number_type`  | Enum(`NONE`, `TENDLC`, `TOLLFREE`):String | [Desc. `number_type`](https://docs.tychron.com/api-reference/schemas/#desc-838)  |
| `numbers`      | Array:String(format:tel)                  | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-839)      |
| `nxx`          | String                                    | [Desc. `nxx`](https://docs.tychron.com/api-reference/schemas/#desc-840)          |
| `quantity`     | String                                    | [Desc. `quantity`](https://docs.tychron.com/api-reference/schemas/#desc-841)     |
| `rate_center`  | String                                    | [Desc. `rate_center`](https://docs.tychron.com/api-reference/schemas/#desc-842)  |
| `state`        | String                                    | [Desc. `state`](https://docs.tychron.com/api-reference/schemas/#desc-843)        |

#### Desc. `min_quantity` {#desc-836}

Sometimes there are legitimately not enough numbers to fill the order.

The `min_quantity` or minimum quantity informs the system if you are willing to tolerate a smaller quantity.

#### Desc. `npa` {#desc-837}

The 3 digit Area Code.

#### Desc. `number_type` {#desc-838}

The wanted number type either TENDLC or TOLLFREE.

NONE is effectively a no-op or null.

#### Desc. `numbers` {#desc-839}

If the numbers that should be provisioned are known ahead of time, they can be provided in
this field, however normally you'll want to avoid using this due to reservations.

#### Desc. `nxx` {#desc-840}

The 3 digit Exchange Code.

#### Desc. `quantity` {#desc-841}

The maximum numbers that should be requested based on the search critierias.

This pairs with `min_quantity` to form a range.

#### Desc. `rate_center` {#desc-842}

The rate center code.

#### Desc. `state` {#desc-843}

The 2 character state code, such as FL for Florida.



__Example__

```json
{
  "addons": {
    "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"
    }
  },
  "city": "string",
  "min_quantity": 10,
  "npa": "202",
  "number_type": "NONE",
  "numbers": [
    "12004005000"
  ],
  "nxx": "203",
  "quantity": 10,
  "rate_center": "NPLSFLGF3MD",
  "state": "FL"
}
```



## Schema / RequestProvisionRecord {#schema-requestprovisionrecord}

A Request's Provision Record represents a single number or unit of work that a request will
process.

Provision records will reflect the status of a single number in that request.

Provision records may be replaced if a request is reset by a operational personnel to diagnose
issues or to resolve an error.


__Type__ Object

| Name          | Type                                                                       | Description                    |
| ------------- | -------------------------------------------------------------------------- | ------------------------------ |
| `error_code`  | [RequestProvisionRecordErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-requestprovisionrecorderrorcode) |                                |
| `id`          | String(format:ulid)                                                        | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-844)        |
| `inserted_at` | String(format:date-time)                                                   | An ISO8601 formatted timestamp |
| `number`      | String                                                                     |                                |
| `status`      | [RequestProvisionRecordStatus](https://docs.tychron.com/api-reference/schemas/#schema-requestprovisionrecordstatus)       |                                |
| `updated_at`  | String(format:date-time)                                                   | An ISO8601 formatted timestamp |

#### Desc. `id` {#desc-844}

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



__Example__

```json
{
  "error_code": "OK",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "number": "12003004000",
  "status": "NONE",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / RequestProvisionRecordErrorCode {#schema-requestprovisionrecorderrorcode}

Error codes further explain an `ERROR` or error-like status or other authoritative action.

If additional information is required about a PVR's error state, please contact support.

* `OK` - there was no error
* `MANUAL` - the PVR requires manual attention or action from an operational personnel
* `UNKNOWN` - something went wrong, and its unclear what happened, this should never happen normally
* `PROTECTED` - the number or associated resource is currently protected from modification.
* `SUBMISSION_TEMPORARY_ERROR` - while submitting the number to a registry, it encountered a temporary problem, this may resolve on its own with time
* `TIMEOUT` - the PVR took too long to complete and has timed out while processing
* `MESSAGING_UNAVAILABLE` - the number was required to have messaging components but failed secondary sanity checks
* `OWNERSHIP_MISMATCH` - the number once belonged to a different account but changed during processing (very unlikely to happen normally)
* `NOT_FOUND` - the number was expected to exist, but did not
* `FEATURE_NOT_FOUND` - the number required a specific feature to be enabled, but did not meet the criteria
* `REQUIRED_RECORD_NOT_FOUND` - the request required a resource or record for the processing of the number, but it could not be located or was lost before processing
* `CONFLICT` - the request has noticed that the number or resource has already met its condition and will not try again
* `REJECTED` - the request has failed one or more sanity checks and is deemed un-processable
* `OVERWRITE_REJECTED` - the request attempted to overwrite an item in a registry but received a rejection for attempting so
* `WIRELESS_NUMBER_NOT_SUPPORTED` - the PVR's number was determined to be a `WIRELESS` and is not supported for enablement
* `SUBMISSION_CHECKED_FAILED` - the PVR had undergone some initial checks which have failed to determine if it could have been completed
* `SUBMISSION_FAILED` - the number has failed submission, contact support for more details
* `PORTABILITY_CHECK_FAILED` - similar to `SUBMISSION_CHECKED_FAILED` used for cases where the checks themselves could not be completed
* `UNPORTABLE` - similar to `SUBMISSION_CHECKED_FAILED` used for cases where checks had completed but the number ultimately could not be completed
* `CANCELLED` - the PVR has been marked CANCELLED and will be skipped by the ordering system until a reset takes place
* `NOT_IMPLEMENTED` - the request attempted to process a feature that was not implemented, or is no longer implemented
* `INVALID_NUMBER` - the number associated with the provision record is invalid
* `INVALID_NNID` - the number was to be associated with a specific NNID but the ID was invalid, if this happens please contact support immediately.
* `LOA_REQUIRED` - the number requires an LOA to complete its request
* `DID_NOT_FOUND` - the number required that an existing DID exist, but it was not found

## Upstream Errors

The following error codes pertain to Tychron and its partners, but are provided as apart of the error codes for convenience.

Clients are not required to act upon these codes and seeing one or more over the course of a request's lifetime is normal while problems are addressed for special cases.

The following errors codes will normally be addressed by an automatic retry or manual intervention.

* `UPSTREAM_ERROR` - an external error has occurred, this will be addressed normally by an operational personnel
* `UPSTREAM_LIMIT_EXCEEDED` - an external registry has imposed a limit which was exceeded by this number's actions
* `UPSTREAM_TIME_LIMIT_EXCEEDED` - an external registry has imposed a time limit which was exceeded by this number's actions
* `UPSTREAM_RESOURCE_LIMIT_EXCEEDED` - an external registry has imposed a limit on a specific resource related to the number which has been exceeded (e.g. a number pool)
* `UPSTREAM_RESOURCE_UNAVAILABLE` - an external registry has reported a necessary resource for the number as being unavailable, it may or may not return if retried later
* `UPSTREAM_CANCELLED` - an external registry has cancelled a request that may have been made earlier
* `UPSTREAM_TOO_MANY_REQUESTS` - too many requests within a timespan, this will normally be addressed by an automatic retry
* `UPSTREAM_NOT_ALLOWED_TO_PROVISION` - an external registry has prevented the provisioning of the specified number or resource
* `UPSTREAM_NOT_AUTHORIZED_TO_PROVISION` - an external registry requires additional permission to provision the specified resource or number
* `UPSTREAM_UNAUTHORIZED` - a generic authorization error, this will be addressed by a operational personnel
* `UPSTREAM_RECORD_NOT_OWNED` - an external registry has deemed that the resource does not belong to the entity making the change
* `UPSTREAM_RECORD_NOT_FOUND` - an external registry could not locate or find the specified number or resource
* `UPSTREAM_RECORD_IS_DUPLICATE` - an external registry has determined that the resource is or may be a duplicate of another resource and has rejected the request
* `UPSTREAM_PARAMETER_ERROR` - a malformed request was sent to the external registry (this can occur during emergency changes to upstream processes)
* `UPSTREAM_NUMBER_UNUSABLE` - an external registry has deemed the number unusable for the specified action, it is unlikely that this number will change from this status
* `UPSTREAM_TEMPORARY_UNAVAILABLE` - the upstream registry could not be contacted for processing at the time, it may become available later
* `UPSTREAM_PROVISIONING_UNAVAILABLE` - an external registry has disabled, rejected or denied provisioning of the specific resource at this time
* `UPSTREAM_UNEXPECTED_RESPONSE` - the registry returned or responded to a request with something unexpected by the ordering system
* `UPSTREAM_REQUEST_ERROR` - either a very specific error has occurred or something unusual has happened, contact support for more details

## System Errors

System errors are critical failures within host processing systems, if these errors do surface please contact support.

* `SYSTEM_ERROR` - a generic system error
* `SYSTEM_REQUEST_ERROR` - may be used in place of `UPSTREAM_REQUEST_ERROR` if the error was unexpected

## Manual Errors or Flags

These are special case error code, typically used for manual action.

* `REMOVE_FROM_UPSTREAM` - the PVR has been marked for removal from the upstream registry
* `PURGE` - the PVR should be purged and removed from the request itself if possible


__Type__ Enum:String

* `OK`
* `MANUAL`
* `UNKNOWN`
* `PROTECTED`
* `SUBMISSION_TEMPORARY_ERROR`
* `MESSAGING_UNAVAILABLE`
* `OWNERSHIP_MISMATCH`
* `NOT_FOUND`
* `FEATURE_NOT_FOUND`
* `REQUIRED_RECORD_NOT_FOUND`
* `CONFLICT`
* `REJECTED`
* `OVERWRITE_REJECTED`
* `WIRELESS_NUMBER_NOT_SUPPORTED`
* `SUBMISSION_CHECKED_FAILED`
* `SUBMISSION_FAILED`
* `PORTABILITY_CHECK_FAILED`
* `UNPORTABLE`
* `CANCELLED`
* `NOT_IMPLEMENTED`
* `INVALID_NUMBER`
* `INVALID_NNID`
* `LOA_REQUIRED`
* `DID_NOT_FOUND`
* `UPSTREAM_ERROR`
* `UPSTREAM_LIMIT_EXCEEDED`
* `UPSTREAM_TIME_LIMIT_EXCEEDED`
* `UPSTREAM_RESOURCE_LIMIT_EXCEEDED`
* `UPSTREAM_RESOURCE_UNAVAILABLE`
* `UPSTREAM_CANCELLED`
* `UPSTREAM_TOO_MANY_REQUESTS`
* `UPSTREAM_NOT_ALLOWED_TO_PROVISION`
* `UPSTREAM_NOT_AUTHORIZED_TO_PROVISION`
* `UPSTREAM_UNAUTHORIZED`
* `UPSTREAM_RECORD_NOT_OWNED`
* `UPSTREAM_RECORD_NOT_FOUND`
* `UPSTREAM_RECORD_IS_DUPLICATE`
* `UPSTREAM_PARAMETER_ERROR`
* `UPSTREAM_NUMBER_UNUSABLE`
* `UPSTREAM_TEMPORARY_UNAVAILABLE`
* `UPSTREAM_PROVISIONING_UNAVAILABLE`
* `UPSTREAM_UNEXPECTED_RESPONSE`
* `UPSTREAM_REQUEST_ERROR`
* `SYSTEM_ERROR`
* `SYSTEM_REQUEST_ERROR`
* `REMOVE_FROM_UPSTREAM`
* `PURGE`


__Example__

```json
"OK"
```



## Schema / RequestProvisionRecordResponse {#schema-requestprovisionrecordresponse}

A single Provision Record Response.


__Type__ Object

| Name   | Type                                                     | Description |
| ------ | -------------------------------------------------------- | ----------- |
| `data` | [RequestProvisionRecord](https://docs.tychron.com/api-reference/schemas/#schema-requestprovisionrecord) |             |
| `type` | String                                                   |             |



__Example__

```json
{
  "data": {
    "error_code": "OK",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "number": "12003004000",
    "status": "NONE",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "request_provision_record"
}
```



## Schema / RequestProvisionRecordStatus {#schema-requestprovisionrecordstatus}

Provision Record(s) (henceforth PVR(s)) have very different status codes from those of orders and requests.

A PVR represents a single unit (e.g. a `number`, a `campaign` etc...) and its progress within a Request.

Its status can therefore be its `stage` (what step of the process it is currently in).

* `NONE` - the PVR was freshly created and has not been used yet
* `MANUAL` - the PVR is currently requires manual or admin action
* `SUBMITTED_TO_REGISTRY*` - for requests that may undergo multiple submissions to a registry, these statuses represent that action.
* `CONFIRMED_IN_REGISTRY*` - for requests that were awaiting an upstream notification, they can be confirmed (i.e. accepted) once that notification is received.
* `PENDING_IN_REGISTRY*` - for requests that enter a pending state (i.e. waiting on a notification)
* `REMOVED_FROM_REGISTRY*` - can be seen as the reverse of `CONFIRMED_IN_REGISTRY*` specifically when removals are done, not that some requests may do a removal even if it was an ADD due to registry requirements for certain conditions.
* `COMPLETED` - the PVR has completed processing
* `ERROR` - the PVR has a permanent error (see `error_code` field for more details)
* `TEMPORARY_ERROR` - the PVR has encountered a temporary error and may be resolved later with or by an operations personnel
* `EXPIRED` - the request has given up on processing the PVR due to a timeout or other long period condition
* `CANCELLED` - the request or an operational personnel has marked the PVR for cancellation possibly as it could not be completed due to an abnormal condition
* `REJECTED` - the request has deemed that the PVR cannot or should not be processed, (see `error_code`  field for more details)
* `PURGE` - an operational personnel has marked the PVR for PERMANENT removal from the request, possibly as it could not be completed or the item is no longer required/eligible


__Type__ Enum:String

* `NONE`
* `MANUAL`
* `SUBMITTED_TO_REGISTRY`
* `SUBMITTED_TO_REGISTRY1`
* `SUBMITTED_TO_REGISTRY2`
* `SUBMITTED_TO_REGISTRY3`
* `CONFIRMED_IN_REGISTRY`
* `CONFIRMED_IN_REGISTRY1`
* `CONFIRMED_IN_REGISTRY2`
* `CONFIRMED_IN_REGISTRY3`
* `PENDING_IN_REGISTRY`
* `PENDING_IN_REGISTRY1`
* `PENDING_IN_REGISTRY2`
* `PENDING_IN_REGISTRY3`
* `REMOVED_FROM_REGISTRY`
* `REMOVED_FROM_REGISTRY1`
* `REMOVED_FROM_REGISTRY2`
* `REMOVED_FROM_REGISTRY3`
* `COMPLETED`
* `ERROR`
* `TEMPORARY_ERROR`
* `EXPIRED`
* `CANCELLED`
* `REJECTED`
* `PURGE`


__Example__

```json
"NONE"
```



## Schema / RequestProvisionRecordsResponse {#schema-requestprovisionrecordsresponse}

Request Provision Records

__Type__ Object

| Name        | Type                                                                           | Description |
| ----------- | ------------------------------------------------------------------------------ | ----------- |
| `count`     | Integer                                                                        |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                                   |             |
| `results`   | Array:[RequestProvisionRecordResponse](https://docs.tychron.com/api-reference/schemas/#schema-requestprovisionrecordresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "number": "12003004000",
        "status": "NONE",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "request_provision_record"
    }
  ]
}
```



## Schema / RequestRegisterBrandData {#schema-requestregisterbranddata}

Request for registering a TCR Brand.

__Type__ Object

| Name                       | Type                 | Description                   |
| -------------------------- | -------------------- | ----------------------------- |
| `address1`                 | String               |                               |
| `alt_business_id`          | String               |                               |
| `alt_business_id_type`     | String               |                               |
| `brand_id`                 | String(format:uuid)  | [Desc. `brand_id`](https://docs.tychron.com/api-reference/schemas/#desc-845) |
| `brand_relationship`       | String               |                               |
| `business_contact_email`   | String(format:email) |                               |
| `cdr_id`                   | String(format:uuid)  | [Desc. `cdr_id`](https://docs.tychron.com/api-reference/schemas/#desc-846)   |
| `city`                     | String               |                               |
| `company_name`             | String               |                               |
| `country_code`             | String               |                               |
| `display_name`             | String               |                               |
| `ein`                      | String               |                               |
| `ein_issuing_country_code` | String               |                               |
| `email`                    | String(format:email) |                               |
| `entity_type`              | String               |                               |
| `first_name`               | String               |                               |
| `last_name`                | String               |                               |
| `phone_number`             | String               |                               |
| `state`                    | String               |                               |
| `stock_exchange`           | String               |                               |
| `stock_symbol`             | String               |                               |
| `tcr_brand_id`             | String               |                               |
| `tcr_csp_id`               | String               |                               |
| `vertical`                 | String               |                               |
| `website`                  | String               |                               |
| `zip_code`                 | String               |                               |

#### Desc. `brand_id` {#desc-845}

A Universally unique identifier, which identifies the resource

#### Desc. `cdr_id` {#desc-846}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "address1": "string",
  "alt_business_id": "string",
  "alt_business_id_type": "string",
  "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "brand_relationship": "string",
  "business_contact_email": "string",
  "cdr_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "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",
  "tcr_brand_id": "B000000",
  "tcr_csp_id": "S000000",
  "vertical": "string",
  "website": "string",
  "zip_code": "string"
}
```



## Schema / RequestRegisterCampaignData {#schema-requestregistercampaigndata}

Request Data for registering TCR Campaigns.

Please note: the completion of the Request does not signify that the Campaign is ready to
accept numbers, please check for the `dca_approved` flag on the campaign itself, or listen
for the `CSP_CAMPAIGN_REGISTERED` event via Subscription Events.


__Type__ Object

| Name                        | Type                            | Description                               |
| --------------------------- | ------------------------------- | ----------------------------------------- |
| `message_flow`              | String                          |                                           |
| `tcr_campaign_id`           | String                          | [Desc. `tcr_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-847)      |
| `help_message`              | String                          |                                           |
| `embedded_phone`            | Boolean                         |                                           |
| `tcr_brand_id`              | String                          | [Desc. `tcr_brand_id`](https://docs.tychron.com/api-reference/schemas/#desc-848)         |
| `embedded_link`             | Boolean                         |                                           |
| `tcr_reseller_id`           | String                          | [Desc. `tcr_reseller_id`](https://docs.tychron.com/api-reference/schemas/#desc-849)      |
| `age_gated`                 | Boolean                         |                                           |
| `vertical`                  | String                          |                                           |
| `optout_message`            | String                          |                                           |
| `description`               | String                          |                                           |
| `auto_renewal`              | Boolean                         |                                           |
| `embedded_link_sample`      | String                          |                                           |
| `optout_keywords`           | String                          | [Desc. `optout_keywords`](https://docs.tychron.com/api-reference/schemas/#desc-850)      |
| `terms_and_conditions_link` | String                          |                                           |
| `direct_lending`            | Boolean                         |                                           |
| `sub_use_cases`             | Array:String                    |                                           |
| `optin_message`             | String                          |                                           |
| `mno_ids`                   | Array:String                    |                                           |
| `reseller_id`               | String(format:uuid)             | Internal UUID of CSP Reseller             |
| `subscriber_optout`         | Boolean                         |                                           |
| `brand_id`                  | String(format:uuid)             | Internal UUID of CSP Brand                |
| `use_case`                  | String                          |                                           |
| `tcr_csp_id`                | String                          | [Desc. `tcr_csp_id`](https://docs.tychron.com/api-reference/schemas/#desc-851)           |
| `subscriber_optin`          | Boolean                         |                                           |
| `help_keywords`             | String                          | [Desc. `help_keywords`](https://docs.tychron.com/api-reference/schemas/#desc-852)        |
| `expedite_tier`             | Enum(`NONE`, `PRIORITY`):String | [Desc. `expedite_tier`](https://docs.tychron.com/api-reference/schemas/#desc-853)        |
| `affiliate_marketing`       | Boolean                         |                                           |
| `subscriber_help`           | Boolean                         |                                           |
| `samples`                   | Array:String                    |                                           |
| `optin_keywords`            | String                          | [Desc. `optin_keywords`](https://docs.tychron.com/api-reference/schemas/#desc-854)       |
| `privacy_policy_link`       | String                          |                                           |
| `number_pool`               | Boolean                         |                                           |
| `terms_and_conditions`      | Boolean                         | [Desc. `terms_and_conditions`](https://docs.tychron.com/api-reference/schemas/#desc-855) |

#### Desc. `tcr_campaign_id` {#desc-847}

TCR issued Campaign ID.

#### Desc. `tcr_brand_id` {#desc-848}

TCR issued Brand ID.

#### Desc. `tcr_reseller_id` {#desc-849}

TCR issued Reseller ID.

#### Desc. `optout_keywords` {#desc-850}

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

Excess spaces will be trimmed around each keyword.

#### Desc. `tcr_csp_id` {#desc-851}

The Campaign Service Provider ID.

Typically in the form of SNNNNNN.

#### Desc. `help_keywords` {#desc-852}

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

Excess spaces will be trimmed around each keyword.

#### Desc. `expedite_tier` {#desc-853}

Request that the campaign's provisioning be expedited with upstream.

* `NONE` - the default, no expedite, campaign will be processed at its normal rate

#### Desc. `optin_keywords` {#desc-854}

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

Excess spaces will be trimmed around each keyword.

#### Desc. `terms_and_conditions` {#desc-855}

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__

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



## Schema / RequestRemoveCampaignNumbersData {#schema-requestremovecampaignnumbersdata}

Request for detaching numbers from their known campaign.

__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-856) |

#### Desc. `numbers` {#desc-856}

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



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / RequestRemoveMessagingNumbersData {#schema-requestremovemessagingnumbersdata}

Request for disabling messaging on existing numbers.

__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-857) |

#### Desc. `numbers` {#desc-857}

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



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / RequestRemoveNumbersData {#schema-requestremovenumbersdata}

Request data for removing existing numbers regardless of components.

This request can handle the removal of all components safely.


__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-858) |

#### Desc. `numbers` {#desc-858}

A list of NANP 11-digit numbers to remove



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / RequestRemoveVoiceNumbersData {#schema-requestremovevoicenumbersdata}

Request for removing voice BYOC (Bring Your Own Carrier) numbers.

__Type__ Object

| Name      | Type         | Description                  |
| --------- | ------------ | ---------------------------- |
| `numbers` | Array:String | [Desc. `numbers`](https://docs.tychron.com/api-reference/schemas/#desc-859) |

#### Desc. `numbers` {#desc-859}

A list of NANP 11-digit numbers to remove



__Example__

```json
{
  "numbers": [
    "12003004000"
  ]
}
```



## Schema / RequestResponse {#schema-requestresponse}

Single request

__Type__ Object

| Name   | Type                       | Description |
| ------ | -------------------------- | ----------- |
| `data` | [Request](https://docs.tychron.com/api-reference/schemas/#schema-request) |             |
| `type` | String                     |             |



__Example__

```json
{
  "data": {
    "error_code": "OK",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "SMS Tollfree Numbers 2021-08-12",
    "notes": "SMS Enablements",
    "status": "NEW",
    "type": "ADD_CAMPAIGN_NUMBERS",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "*": {
      "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
      "numbers": [
        "12003004000"
      ],
      "tcr_campaign_id": "C000000",
      "tmobile_enabled": true
    }
  },
  "type": "request"
}
```



## Schema / RequestType {#schema-requesttype}

The type of the request denotes what its intention and parameters will be.


__Type__ Enum:String

* `ADD_CAMPAIGN_NUMBERS`
* `ADD_DIRECTORY_LISTING_NUMBERS`
* `ADD_E911_NUMBERS`
* `ADD_GOOGLE_VERIFIED_SMS_NUMBERS`
* `ADD_GOOGLE_VERIFIED_VOICE_NUMBERS`
* `ADD_MESSAGING_NUMBERS`
* `ADD_OUTBOUND_CNAME_NUMBERS`
* `ADD_VOICE_NUMBERS`
* `NEW_NUMBERS`
* `NONE`
* `PORT_NUMBERS`
* `PUBLISH_MESSAGING_NUMBERS`
* `REGISTER_BRAND`
* `REGISTER_CAMPAIGN`
* `REGISTER_GOOGLE_VERIFIED_SMS_AGENT`
* `REGISTER_GOOGLE_VERIFIED_SMS_BRAND`
* `REGISTER_GOOGLE_VERIFIED_VOICE_AGENT`
* `REGISTER_GOOGLE_VERIFIED_VOICE_BRAND`
* `REGISTER_RESELLER`
* `REMOVE_CAMPAIGN_NUMBERS`
* `REMOVE_DIRECTORY_LISTING_NUMBERS`
* `REMOVE_E911_NUMBERS`
* `REMOVE_GOOGLE_VERIFIED_SMS_NUMBERS`
* `REMOVE_GOOGLE_VERIFIED_VOICE_NUMBERS`
* `REMOVE_MESSAGING_NUMBERS`
* `REMOVE_NUMBERS`
* `REMOVE_OUTBOUND_CNAME_NUMBERS`
* `REMOVE_VOICE_NUMBERS`
* `RESUBMIT_CAMPAIGN`
* `UNREGISTER_BRAND`
* `UNREGISTER_CAMPAIGN`
* `UNREGISTER_GOOGLE_VERIFIED_SMS_AGENT`
* `UNREGISTER_GOOGLE_VERIFIED_SMS_BRAND`
* `UNREGISTER_GOOGLE_VERIFIED_VOICE_AGENT`
* `UNREGISTER_GOOGLE_VERIFIED_VOICE_BRAND`
* `UNREGISTER_RESELLER`
* `VET_BRAND`


__Example__

```json
"ADD_CAMPAIGN_NUMBERS"
```



## Schema / RequestUnregisterBrandData {#schema-requestunregisterbranddata}

Request for unregistering a TCR Brand.

__Type__ Object

| Name           | Type                | Description         |
| -------------- | ------------------- | ------------------- |
| `brand_id`     | String(format:uuid) | Internal UUID       |
| `tcr_brand_id` | String              | TCR issued Brand ID |



__Example__

```json
{
  "brand_id": "89900e23-aafc-4b03-954d-0b11d3948042",
  "tcr_brand_id": "B000000"
}
```



## Schema / RequestUnregisterCampaignData {#schema-requestunregistercampaigndata}

Request for unregistering a TCR Campaign.

__Type__ Object

| Name              | Type                | Description   |
| ----------------- | ------------------- | ------------- |
| `campaign_id`     | String(format:uuid) | Internal UUID |
| `tcr_campaign_id` | String              | TCR issued ID |



__Example__

```json
{
  "campaign_id": "89900e23-aafc-4b03-954d-0b11d3948042",
  "tcr_campaign_id": "B000000"
}
```



## Schema / RequestVetBrandData {#schema-requestvetbranddata}

Request for vetting a TCR Brand.

__Type__ Object

| Name            | Type                | Description                        |
| --------------- | ------------------- | ---------------------------------- |
| `brand_id`      | String(format:uuid) | Internal UUID                      |
| `tcr_brand_id`  | String              | TCR issued Brand ID                |
| `tcr_evp_id`    | String              | [Desc. `tcr_evp_id`](https://docs.tychron.com/api-reference/schemas/#desc-860)    |
| `vetting_class` | String              | [Desc. `vetting_class`](https://docs.tychron.com/api-reference/schemas/#desc-861) |

#### Desc. `tcr_evp_id` {#desc-860}

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

#### Desc. `vetting_class` {#desc-861}

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



__Example__

```json
{
  "brand_id": "89900e23-aafc-4b03-954d-0b11d3948042",
  "tcr_brand_id": "B000000",
  "tcr_evp_id": "AEGIS",
  "vetting_class": "STANDARD"
}
```



## Schema / RequestsResponse {#schema-requestsresponse}

Requests

__Type__ Object

| Name        | Type                                             | Description |
| ----------- | ------------------------------------------------ | ----------- |
| `count`     | Integer                                          |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                     |             |
| `results`   | Array:[RequestResponse](https://docs.tychron.com/api-reference/schemas/#schema-requestresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "SMS Tollfree Numbers 2021-08-12",
        "notes": "SMS Enablements",
        "status": "NEW",
        "type": "ADD_CAMPAIGN_NUMBERS",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "*": {
          "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
          "numbers": [
            "12003004000"
          ],
          "tcr_campaign_id": "C000000",
          "tmobile_enabled": true
        }
      },
      "type": "request"
    }
  ]
}
```



## Schema / ResourceNotFoundErrorObject {#schema-resourcenotfounderrorobject}

An object representing a single not-found error.


__Type__ Object

| Name       | Type                     | Description                   |
| ---------- | ------------------------ | ----------------------------- |
| `code`     | Enum(`not_found`):String | [Desc. `code`](https://docs.tychron.com/api-reference/schemas/#desc-862)     |
| `detail`   | String                   | [Desc. `detail`](https://docs.tychron.com/api-reference/schemas/#desc-863)   |
| `params`   | `params`                 | [Desc. `params`](https://docs.tychron.com/api-reference/schemas/#desc-864)   |
| `sub_code` | String                   | [Desc. `sub_code`](https://docs.tychron.com/api-reference/schemas/#desc-865) |
| `title`    | String                   | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-866)    |

#### Desc. `code` {#desc-862}

Contains static error code representing the error

#### Desc. `detail` {#desc-863}

Contains dynamic description of the error

#### Desc. `params` {#desc-864}

Contains additional parameters based on the permission error

#### Desc. `sub_code` {#desc-865}

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

#### Desc. `title` {#desc-866}

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

__params__

| Name       | Type       | Description |
| ---------- | ---------- | ----------- |
| `resource` | `resource` |             |

__resource__

| Name   | Type   | Description             |
| ------ | ------ | ----------------------- |
| `id`   | String | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-867) |
| `type` | String | Name of the resource    |

#### Desc. `id` {#desc-867}

The identifier used to lookup the resource, some resources may allow different
ids for lookup of the same resource.



__Example__

```json
{
  "code": "not_found",
  "detail": "The specified resource could not be found",
  "params": {
    "resource": {
      "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
      "type": "user"
    }
  },
  "sub_code": "none",
  "title": "Not Found"
}
```



## Schema / ResourceNotFoundErrorsResponse {#schema-resourcenotfounderrorsresponse}

Error Response when a resource cannot be found.


__Type__ Object

| Name     | Type                                                                     | Description                       |
| -------- | ------------------------------------------------------------------------ | --------------------------------- |
| `errors` | Array:[ResourceNotFoundErrorObject](https://docs.tychron.com/api-reference/schemas/#schema-resourcenotfounderrorobject) | A list of errors from the request |



__Example__

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```



## Schema / ReviewOverwriteRequestData {#schema-reviewoverwriterequestdata}

Request data for reviewing an Overwrite Request


__Type__ Object

| Name            | Type                     | Description                        |
| --------------- | ------------------------ | ---------------------------------- |
| `review_status` | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-868):String | [Desc. `review_status`](https://docs.tychron.com/api-reference/schemas/#desc-869) |

#### Enum Values review_status {#enum-868}

Allowed values

* `NONE`
* `APPROVED`
* `REJECTED`
* `AUTO_APPROVED`
* `AUTO_REJECTED`
* `FORCE_DELETED`

#### Desc. `review_status` {#desc-869}

The review status of the request, defaults to NONE.



__Example__

```json
{
  "review_status": "NONE"
}
```



## Schema / ReviewOverwriteRequestRequest {#schema-reviewoverwriterequestrequest}

Request for reviewing an Overwrite Request

__Type__ Object

| Name   | Type                                                             | Description |
| ------ | ---------------------------------------------------------------- | ----------- |
| `data` | [ReviewOverwriteRequestData](https://docs.tychron.com/api-reference/schemas/#schema-reviewoverwriterequestdata) |             |
| `type` | String                                                           |             |



__Example__

```json
{
  "data": {
    "review_status": "NONE"
  },
  "type": "osr_overwrite_request"
}
```



## Schema / Role {#schema-role}

A role controls the access to resources and their actions within the API.


__Type__ Object

| Name            | Type                                               | Description                        |
| --------------- | -------------------------------------------------- | ---------------------------------- |
| `default_scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `default_scope`](https://docs.tychron.com/api-reference/schemas/#desc-870) |
| `id`            | String(format:uuid)                                | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-871)            |
| `inserted_at`   | String(format:date-time)                           | An ISO8601 formatted timestamp     |
| `level`         | Enum(`GUEST`, `CLIENT`, `ADMIN`):String            | [Desc. `level`](https://docs.tychron.com/api-reference/schemas/#desc-872)         |
| `name`          | String                                             | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-873)          |
| `notes`         | String                                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-874)         |
| `rank`          | Integer(>= 0)                                      | [Desc. `rank`](https://docs.tychron.com/api-reference/schemas/#desc-875)          |
| `resources`     | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-881)                       | [Desc. `resources`](https://docs.tychron.com/api-reference/schemas/#desc-882)     |
| `updated_at`    | String(format:date-time)                           | An ISO8601 formatted timestamp     |

#### Desc. `default_scope` {#desc-870}

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. `id` {#desc-871}

A Universally unique identifier, which identifies the resource

#### Desc. `level` {#desc-872}

The role's level dictates the overall access the associated user will have.

* `GUEST` - Unprivileged user
* `CLIENT` - This is the default level for Roles created from the API.
* `ADMIN` - System administrators, cannot be set via the API, provided for reference.

#### Desc. `name` {#desc-873}

Role's display name.

#### Desc. `notes` {#desc-874}

Any notes about the role.

#### Desc. `rank` {#desc-875}

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 {#type-881}

Sub-Schema

__Type__ Object

| Name          | Type                                               | Description                |
| ------------- | -------------------------------------------------- | -------------------------- |
| `actions`     | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-879)                       |                            |
| `resource_id` | String                                             |                            |
| `scope`       | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](https://docs.tychron.com/api-reference/schemas/#desc-880) |

#### SubObject {#type-879}

Sub-Schema

__Type__ Object

| Name    | Type                         | Description                |
| ------- | ---------------------------- | -------------------------- |
| `name`  | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-876):String     | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-877)  |
| `value` | Enum(`true`, `false`):String | [Desc. `value`](https://docs.tychron.com/api-reference/schemas/#desc-878) |

#### Enum Values name {#enum-876}

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` {#desc-877}

The name of the action.

#### Desc. `value` {#desc-878}

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` {#desc-880}

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

IGNORE acts as a fallback to the `default_scope`.





#### Desc. `resources` {#desc-882}

Role's job title, or position



__Example__

```json
{
  "default_scope": "ACCOUNT",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "level": "CLIENT",
  "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"
    }
  ],
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / RolePoliciesResponse {#schema-rolepoliciesresponse}

Role Policies

__Type__ Object

| Name        | Type                                                   | Description |
| ----------- | ------------------------------------------------------ | ----------- |
| `count`     | Integer                                                |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                           |             |
| `results`   | Array:[RolePolicyResponse](https://docs.tychron.com/api-reference/schemas/#schema-rolepolicyresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "actions": [
          "sell_rates"
        ],
        "allowed_levels": [
          "GUEST"
        ],
        "allowed_scopes": [
          "ACCOUNT"
        ],
        "hint": "string",
        "label": "Roles",
        "resource_id": "string",
        "topics": [
          "string"
        ]
      },
      "type": "role_policy"
    }
  ]
}
```



## Schema / RolePolicy {#schema-rolepolicy}

A role controls the access to resources and their actions within the API.


__Type__ Object

| Name             | Type                                                     | Description                         |
| ---------------- | -------------------------------------------------------- | ----------------------------------- |
| `actions`        | Array:[Enum](https://docs.tychron.com/api-reference/schemas/#enum-883):String                           | [Desc. `actions`](https://docs.tychron.com/api-reference/schemas/#desc-884)        |
| `allowed_levels` | Array:Enum(`GUEST`, `CLIENT`, `ADMIN`):String            | [Desc. `allowed_levels`](https://docs.tychron.com/api-reference/schemas/#desc-885) |
| `allowed_scopes` | Array:Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `allowed_scopes`](https://docs.tychron.com/api-reference/schemas/#desc-886) |
| `hint`           | String                                                   | [Desc. `hint`](https://docs.tychron.com/api-reference/schemas/#desc-887)           |
| `label`          | String                                                   | [Desc. `label`](https://docs.tychron.com/api-reference/schemas/#desc-888)          |
| `resource_id`    | String                                                   |                                     |
| `topics`         | Array:String                                             | [Desc. `topics`](https://docs.tychron.com/api-reference/schemas/#desc-889)         |

#### Enum Values actions {#enum-883}

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. `actions` {#desc-884}

A list of actions the resource has.

#### Desc. `allowed_levels` {#desc-885}

A list of levels that are allowed to use this resource.

#### Desc. `allowed_scopes` {#desc-886}

A list of scopes that are allowed to be paired with this resource.

#### Desc. `hint` {#desc-887}

Effectively the description of the role from the backend.

#### Desc. `label` {#desc-888}

Resource's primary label.

#### Desc. `topics` {#desc-889}

A list of topics or related groupings the resource belongs to.



__Example__

```json
{
  "actions": [
    "sell_rates"
  ],
  "allowed_levels": [
    "GUEST"
  ],
  "allowed_scopes": [
    "ACCOUNT"
  ],
  "hint": "string",
  "label": "Roles",
  "resource_id": "string",
  "topics": [
    "string"
  ]
}
```



## Schema / RolePolicyResponse {#schema-rolepolicyresponse}

Response when retrieving role policy information.

__Type__ Object

| Name   | Type                             | Description |
| ------ | -------------------------------- | ----------- |
| `data` | [RolePolicy](https://docs.tychron.com/api-reference/schemas/#schema-rolepolicy) |             |
| `type` | String                           |             |



__Example__

```json
{
  "data": {
    "actions": [
      "sell_rates"
    ],
    "allowed_levels": [
      "GUEST"
    ],
    "allowed_scopes": [
      "ACCOUNT"
    ],
    "hint": "string",
    "label": "Roles",
    "resource_id": "string",
    "topics": [
      "string"
    ]
  },
  "type": "role_policy"
}
```



## Schema / RoleResponse {#schema-roleresponse}

Response when retrieving role information.

__Type__ Object

| Name   | Type                 | Description |
| ------ | -------------------- | ----------- |
| `data` | [Role](https://docs.tychron.com/api-reference/schemas/#schema-role) |             |
| `type` | String               |             |



__Example__

```json
{
  "data": {
    "default_scope": "ACCOUNT",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "level": "CLIENT",
    "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"
      }
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "role"
}
```



## Schema / RolesResponse {#schema-rolesresponse}

Roles

__Type__ Object

| Name        | Type                                       | Description |
| ----------- | ------------------------------------------ | ----------- |
| `count`     | Integer                                    |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)               |             |
| `results`   | Array:[RoleResponse](https://docs.tychron.com/api-reference/schemas/#schema-roleresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "default_scope": "ACCOUNT",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "level": "CLIENT",
        "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"
          }
        ],
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "role"
    }
  ]
}
```



## Schema / SearchNumberInventory {#schema-searchnumberinventory}

Search Number Inventory Response Data.

Due to the nature of reservations using search inventory vs coverage is discouraged.

It is possible for clients to obtain the SAME response from searching specifically
for the number vs getting a coverage which is just the count of the parameters.


__Type__ Object

| Name    | Type                         | Description                |
| ------- | ---------------------------- | -------------------------- |
| `count` | Integer                      | [Desc. `count`](https://docs.tychron.com/api-reference/schemas/#desc-890) |
| `items` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-891) | [Desc. `items`](https://docs.tychron.com/api-reference/schemas/#desc-892) |

#### Desc. `count` {#desc-890}

How many numbers total are available from the query.

#### SubObject {#type-891}

Sub-Schema

__Type__ Object

| Name          | Type                              | Description |
| ------------- | --------------------------------- | ----------- |
| `lata`        | String                            |             |
| `number`      | String(format:tel)                |             |
| `rate_center` | String                            |             |
| `state`       | String                            |             |
| `type`        | Enum(`TENDLC`, `TOLLFREE`):String |             |





#### Desc. `items` {#desc-892}

An array of entries containing the numbers in the inventory.



__Example__

```json
{
  "count": 10,
  "items": [
    {
      "lata": "236",
      "number": "12022014000",
      "rate_center": "WSHNGTNZN1",
      "state": "DC",
      "type": "TENDLC"
    }
  ]
}
```



## Schema / SearchNumberInventoryResponse {#schema-searchnumberinventoryresponse}

The response for a Number Inventory search request.

Note that only a maximum of ten results can be returned at a time at for tollfree.


__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [SearchNumberInventory](https://docs.tychron.com/api-reference/schemas/#schema-searchnumberinventory) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "data": {
    "count": 10,
    "items": [
      {
        "lata": "236",
        "number": "12022014000",
        "rate_center": "WSHNGTNZN1",
        "state": "DC",
        "type": "TENDLC"
      }
    ]
  },
  "type": "number_inventory"
}
```



## Schema / SecretKey {#schema-secretkey}

An set of authorization details for various APIs

__Type__ Object

| Name          | Type                                         | Description                    |
| ------------- | -------------------------------------------- | ------------------------------ |
| `id`          | String(format:uuid)                          | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-893)        |
| `inserted_at` | String(format:date-time)                     | An ISO8601 formatted timestamp |
| `name`        | String(3..255)                               | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-894)      |
| `notes`       | String(0..65535)                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-895)     |
| `size`        | Enum(`16`, `24`, `32`, `48`, `64`):Number    | [Desc. `size`](https://docs.tychron.com/api-reference/schemas/#desc-896)      |
| `updated_at`  | String(format:date-time)                     | An ISO8601 formatted timestamp |
| `usage`       | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](https://docs.tychron.com/api-reference/schemas/#desc-897)     |

#### Desc. `id` {#desc-893}

A Universally unique identifier, which identifies the resource

#### Desc. `name` {#desc-894}

A friendly name to identify the Secret Key

#### Desc. `notes` {#desc-895}

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

#### Desc. `size` {#desc-896}

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` {#desc-897}

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__

```json
{
  "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 / SecretKeyResponse {#schema-secretkeyresponse}

Single Secret Key

__Type__ Object

| Name   | Type                           | Description |
| ------ | ------------------------------ | ----------- |
| `data` | [SecretKey](https://docs.tychron.com/api-reference/schemas/#schema-secretkey) |             |
| `type` | String                         |             |



__Example__

```json
{
  "data": {
    "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 / SecretKeysResponse {#schema-secretkeysresponse}

Secret Keys

__Type__ Object

| Name        | Type                                                 | Description |
| ----------- | ---------------------------------------------------- | ----------- |
| `count`     | Integer                                              |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                         |             |
| `results`   | Array:[SecretKeyResponse](https://docs.tychron.com/api-reference/schemas/#schema-secretkeyresponse) |             |



__Example__

```json
{
  "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": "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 / SharedResourceGroup {#schema-sharedresourcegroup}

A Shared Resource Group

__Type__ Object

| Name          | Type                     | Description                            |
| ------------- | ------------------------ | -------------------------------------- |
| `id`          | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-898)                |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp         |
| `name`        | String                   | The display name of the resource group |
| `notes`       | String                   | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-899)             |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp         |

#### Desc. `id` {#desc-898}

A Universally unique identifier, which identifies the resource

#### Desc. `notes` {#desc-899}

Any additional notes about the shared resource group.



__Example__

```json
{
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "ACME Corp Shared Resources",
  "notes": "",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / SharedResourceGroupResponse {#schema-sharedresourcegroupresponse}

Single Shared Resource Group

__Type__ Object

| Name           | Type                                               | Description |
| -------------- | -------------------------------------------------- | ----------- |
| `associations` | `associations`                                     |             |
| `data`         | [SharedResourceGroup](https://docs.tychron.com/api-reference/schemas/#schema-sharedresourcegroup) |             |
| `type`         | String                                             |             |

__associations__

| Name      | Type      | Description                  |
| --------- | --------- | ---------------------------- |
| `account` | `account` | [Desc. `account`](https://docs.tychron.com/api-reference/schemas/#desc-900) |
| `donee`   | `donee`   | [Desc. `donee`](https://docs.tychron.com/api-reference/schemas/#desc-901)   |

#### Desc. `account` {#desc-900}

The source or origin account that resources are shared from.

#### Desc. `donee` {#desc-901}

The destination or target account that resources will be shared with.

__account__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-902) |

#### Desc. `id` {#desc-902}

A Universally unique identifier, which identifies the resource



__donee__

| Name | Type                | Description             |
| ---- | ------------------- | ----------------------- |
| `id` | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-903) |

#### Desc. `id` {#desc-903}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "associations": {
    "account": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    },
    "donee": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "ACME Corp Shared Resources",
    "notes": "",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "shared_resource_group"
}
```



## Schema / SharedResourceGroupsResponse {#schema-sharedresourcegroupsresponse}

Shared Resource Groups

__Type__ Object

| Name        | Type                                                                     | Description |
| ----------- | ------------------------------------------------------------------------ | ----------- |
| `count`     | Integer                                                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                             |             |
| `results`   | Array:[SharedResourceGroupResponse](https://docs.tychron.com/api-reference/schemas/#schema-sharedresourcegroupresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "account": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        },
        "donee": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        }
      },
      "data": {
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "ACME Corp Shared Resources",
        "notes": "",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "shared_resource_group"
    }
  ]
}
```



## Schema / Switch {#schema-switch}

Switches contain the routing information for dids

__Type__ Object

| Name                    | Type                                                     | Description                             |
| ----------------------- | -------------------------------------------------------- | --------------------------------------- |
| `notes`                 | String                                                   | Any notes about the switch              |
| `sms_secret`            | String                                                   | [Desc. `sms_secret`](https://docs.tychron.com/api-reference/schemas/#desc-904)         |
| `mms_signing_scheme`    | [SwitchSigningScheme](https://docs.tychron.com/api-reference/schemas/#schema-switchsigningscheme)       |                                         |
| `voice_data`            | String                                                   | [Desc. `voice_data`](https://docs.tychron.com/api-reference/schemas/#desc-905)         |
| `updated_at`            | String(format:date-time)                                 | An ISO8601 formatted timestamp          |
| `sms_data`              | String                                                   | [Desc. `sms_data`](https://docs.tychron.com/api-reference/schemas/#desc-906)           |
| `sms_signing_scheme`    | [SwitchSigningScheme](https://docs.tychron.com/api-reference/schemas/#schema-switchsigningscheme)       |                                         |
| `voice_protocol`        | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-907):String                                 | [Desc. `voice_protocol`](https://docs.tychron.com/api-reference/schemas/#desc-908)     |
| `inserted_at`           | String(format:date-time)                                 | An ISO8601 formatted timestamp          |
| `mms_options`           | `mms_options`                                            | [Desc. `mms_options`](https://docs.tychron.com/api-reference/schemas/#desc-909)        |
| `sms_message_format`    | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-910):String                                 | [Desc. `sms_message_format`](https://docs.tychron.com/api-reference/schemas/#desc-911) |
| `mms_message_format`    | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-912):String                                 | [Desc. `mms_message_format`](https://docs.tychron.com/api-reference/schemas/#desc-913) |
| `voice_auth_method`     | Enum(`NONE`, `BASIC`, `BEARER`):String                   | [Desc. `voice_auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-914)  |
| `mms_enabled`           | Boolean                                                  | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-915)        |
| `name`                  | String                                                   | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-916)               |
| `sms_auth_method`       | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String    | [Desc. `sms_auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-917)    |
| `mms_secret`            | String                                                   | [Desc. `mms_secret`](https://docs.tychron.com/api-reference/schemas/#desc-918)         |
| `mms_identity`          | String                                                   | Acts as the username in basic auth      |
| `sms_enabled`           | Boolean                                                  | [Desc. `sms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-919)        |
| `mms_encryption_method` | [SwitchEncryptionMethod](https://docs.tychron.com/api-reference/schemas/#schema-switchencryptionmethod) |                                         |
| `voice_enabled`         | Boolean                                                  | [Desc. `voice_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-920)      |
| `sms_signing_hash`      | [SwitchSigningHash](https://docs.tychron.com/api-reference/schemas/#schema-switchsigninghash)           |                                         |
| `sms_encryption_method` | [SwitchEncryptionMethod](https://docs.tychron.com/api-reference/schemas/#schema-switchencryptionmethod) |                                         |
| `voice_identity`        | String                                                   |                                         |
| `mms_name`              | String                                                   | [Desc. `mms_name`](https://docs.tychron.com/api-reference/schemas/#desc-921)           |
| `mms_auth_method`       | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String    | [Desc. `mms_auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-922)    |
| `mms_protocol`          | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-923):String                                 | [Desc. `mms_protocol`](https://docs.tychron.com/api-reference/schemas/#desc-924)       |
| `voice_name`            | String                                                   |                                         |
| `voice_secret`          | String                                                   |                                         |
| `sms_name`              | String                                                   | Reserved for future use                 |
| `mms_signing_hash`      | [SwitchSigningHash](https://docs.tychron.com/api-reference/schemas/#schema-switchsigninghash)           |                                         |
| `mms_data`              | String(format:url)                                       | [Desc. `mms_data`](https://docs.tychron.com/api-reference/schemas/#desc-925)           |
| `sms_protocol`          | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-926):String                                 | [Desc. `sms_protocol`](https://docs.tychron.com/api-reference/schemas/#desc-927)       |
| `sms_identity`          | String                                                   | Acts as the username in basic auth      |
| `sms_options`           | `sms_options`                                            | [Desc. `sms_options`](https://docs.tychron.com/api-reference/schemas/#desc-928)        |
| `id`                    | String(format:uuid)                                      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-929)                 |

#### Desc. `sms_secret` {#desc-904}

Depending on the `auth_method`, this fields usage changes:

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

#### Desc. `voice_data` {#desc-905}

Contains the routing url specific to the requested protocol

#### Desc. `sms_data` {#desc-906}

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

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

#### Enum Values voice_protocol {#enum-907}

Allowed values

* `NONE`
* `VOIP`
* `PSTN`
* `TTS`
* `TTS_CUSTOM`
* `HTTP_ROUTE`

#### Desc. `voice_protocol` {#desc-908}

All protocols supported for fallback VoIP destination.

#### Desc. `mms_options` {#desc-909}

Contains various miscelleanous or experimental feature flags for MMS.

#### Enum Values sms_message_format {#enum-910}

Allowed values

* `TRINITY_JSON_1_0`
* `TRINITY_POST_1_0`
* `TRINITY_POST_2_0`

#### Desc. `sms_message_format` {#desc-911}

All supported message formats for SMS HTTP Protocol

#### Enum Values mms_message_format {#enum-912}

Allowed values

* `OXY_JSON_1_0`
* `OXY_JSONAPI_1_0`
* `OXY_XML_1_0`
* `OXY_MULTIPART_1_0`
* `OXY_MULTIPART_2_0`
* `OXY_RFC822_1_0`

#### Desc. `mms_message_format` {#desc-913}

All supported message formats for MMS HTTP Protocol.

#### Desc. `voice_auth_method` {#desc-914}

Various authorization methods supported.

Primarily used with HTTP ROUTE

#### Desc. `mms_enabled` {#desc-915}

Enable inbound MMS routing?

#### Desc. `name` {#desc-916}

A display name to easily identify the switch

#### Desc. `sms_auth_method` {#desc-917}

Various authorization methods supported by the SMS HTTP Protocol.

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

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

#### Desc. `mms_secret` {#desc-918}

Depending on the `auth_method`, this fields usage changes:

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

#### Desc. `sms_enabled` {#desc-919}

Enable inbound SMS routing?

#### Desc. `voice_enabled` {#desc-920}

Enable voice call fallback routing?

#### Desc. `mms_name` {#desc-921}

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

#### Desc. `mms_auth_method` {#desc-922}

Various authorization methods supported.

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

HTTP supports all available methods.

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

#### Enum Values mms_protocol {#enum-923}

Allowed values

* `NONE`
* `MM4`
* `HTTP`
* `SFTP`
* `FORWARD`
* `TYCHRON_CHAT`

#### Desc. `mms_protocol` {#desc-924}

All protocols supported for MMS delivery.

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

#### Desc. `mms_data` {#desc-925}

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

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

#### Enum Values sms_protocol {#enum-926}

Allowed values

* `NONE`
* `SMPP`
* `HTTP`
* `FORWARD`
* `TYCHRON_CHAT`

#### Desc. `sms_protocol` {#desc-927}

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

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

#### Desc. `sms_options` {#desc-928}

Contains various miscelleanous or experimental feature flags for SMS.

#### Desc. `id` {#desc-929}

A Universally unique identifier, which identifies the resource

__mms_options__

| Name             | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `dlr_on_sent`    | Boolean | [Desc. `dlr_on_sent`](https://docs.tychron.com/api-reference/schemas/#desc-930)    |
| `forward_dlr`    | Boolean | [Desc. `forward_dlr`](https://docs.tychron.com/api-reference/schemas/#desc-931)    |
| `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](https://docs.tychron.com/api-reference/schemas/#desc-932) |

#### Desc. `dlr_on_sent` {#desc-930}

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

#### Desc. `forward_dlr` {#desc-931}

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

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

#### Desc. `pad_shortcodes` {#desc-932}

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



__sms_options__

| Name             | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `dlr_on_sent`    | Boolean | [Desc. `dlr_on_sent`](https://docs.tychron.com/api-reference/schemas/#desc-933)    |
| `forward_dlr`    | Boolean | [Desc. `forward_dlr`](https://docs.tychron.com/api-reference/schemas/#desc-934)    |
| `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](https://docs.tychron.com/api-reference/schemas/#desc-935) |

#### Desc. `dlr_on_sent` {#desc-933}

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

#### Desc. `forward_dlr` {#desc-934}

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

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

#### Desc. `pad_shortcodes` {#desc-935}

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



__Example__

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



## Schema / SwitchEncryptionMethod {#schema-switchencryptionmethod}

Encrypts the request body using the configured secret for the respective message type.

* `NONE` - No encryption is done to the payload, the default
* `AES_128_GCM` - Requires a 16 byte secret key
* `AES_192_GCM` - Requires a 24 byte secret key
* `AES_256_GCM` - Requires a 32 byte secret key

NOTE. Request Headers are NOT encrypted.

Upon encryption the content-type will be replaced by `application/octet-stream`.

The following headers will be added to all HTTP requests that have a non-`NONE` method configured:
* `x-message-iv` - a Base16 (lowercase) encoded value, the initialization vector (IV), SHALL be 12 bytes when decoded
* `x-message-content-type` - the original content-type of the message before it was encrypted

The AES-GCM additional authenticated data (AAD) SHALL be an empty byte string (i.e. "").

The AES-GCM authentication tag is appended directly to the request body and SHALL be the final 16 bytes.
The request body MUST therefore contain at least 16 bytes.

Example (Elixir):

  ciphertext_size = byte_size(body) - 16
  <<ciphertext::binary-size(^ciphertext_size), authentication_tag::binary-size(16)>> = body



__Type__ Enum:String

* `NONE`
* `AES_128_GCM`
* `AES_192_GCM`
* `AES_256_GCM`


__Example__

```json
"NONE"
```



## Schema / SwitchResponse {#schema-switchresponse}

Single switch

__Type__ Object

| Name           | Type                     | Description |
| -------------- | ------------------------ | ----------- |
| `associations` | `associations`           |             |
| `data`         | [Switch](https://docs.tychron.com/api-reference/schemas/#schema-switch) |             |
| `type`         | String                   |             |

__associations__

| Name                 | Type                 | Description                             |
| -------------------- | -------------------- | --------------------------------------- |
| `api_key`            | `api_key`            | [Desc. `api_key`](https://docs.tychron.com/api-reference/schemas/#desc-936)            |
| `mms_encryption_key` | `mms_encryption_key` | [Desc. `mms_encryption_key`](https://docs.tychron.com/api-reference/schemas/#desc-937) |
| `mms_signing_key`    | `mms_signing_key`    | [Desc. `mms_signing_key`](https://docs.tychron.com/api-reference/schemas/#desc-938)    |
| `sms_encryption_key` | `sms_encryption_key` | [Desc. `sms_encryption_key`](https://docs.tychron.com/api-reference/schemas/#desc-939) |
| `sms_signing_key`    | `sms_signing_key`    | [Desc. `sms_signing_key`](https://docs.tychron.com/api-reference/schemas/#desc-940)    |

#### Desc. `api_key` {#desc-936}

The attached and associated API Key used for SMPP routing.

#### Desc. `mms_encryption_key` {#desc-937}

The Secret Key that will be used for MMS encryption if enabled.

#### Desc. `mms_signing_key` {#desc-938}

The Secret Key that will be used for MMS signing if enabled.

#### Desc. `sms_encryption_key` {#desc-939}

The Secret Key that should be used for SMS encryption if enabled.

#### Desc. `sms_signing_key` {#desc-940}

The Secret Key that will be used for SMS signing if enabled.

__api_key__

| Name | Type                | Description |
| ---- | ------------------- | ----------- |
| `id` | String(format:uuid) |             |



__mms_encryption_key__

| Name | Type                | Description |
| ---- | ------------------- | ----------- |
| `id` | String(format:uuid) |             |



__mms_signing_key__

| Name | Type                | Description |
| ---- | ------------------- | ----------- |
| `id` | String(format:uuid) |             |



__sms_encryption_key__

| Name | Type                | Description |
| ---- | ------------------- | ----------- |
| `id` | String(format:uuid) |             |



__sms_signing_key__

| Name | Type                | Description |
| ---- | ------------------- | ----------- |
| `id` | String(format:uuid) |             |



__Example__

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



## Schema / SwitchSigningHash {#schema-switchsigninghash}

Signs the request with the configured signing key for the respective message type.

Signing does NOT replace the auth_method like the `HMAC_SHA256` method would, instead additional headers will be added to the request.

Signing happens AFTER the payload has already been encrypted, to reverse the operation, check the signature first, then decrypt.

* `NONE` - No signature is generated for requests

These should be self-explanatory:
* `SHA2_256`
* `SHA2_384`
* `SHA2_512`
* `SHA3_256`
* `SHA3_384`
* `SHA3_512`

The following headers are added to requests with signing present:
* `x-message-signature-version` consult the respective signature versions for further details on your message type
* `x-message-signature` - a Base16 (lowercase) encoded binary of the signature

Where a header is NOT present in the request, it should be assumed "0x00" (a literal null) for calculation.

## SMS Signature Versions

### `2026-07-27` SMS

Signatures for SMS are generated by applying the follow values in order:

* Request Headers
  * `content-type`
  * `x-message-authorization-version`
  * `x-message-content-type`
  * `x-message-format`
  * `x-message-id`
  * `x-message-iv`
  * `x-message-signature-version`
  * `x-message-timestamp`
  * `x-tychron-csp-campaign-id`
  * `x-tychron-remote-reference-id`
  * `x-tychron-remote-service-provider`
  * `x-tychron-tcr-brand-id`
  * `x-tychron-tcr-campaign-id`
* Request Body

## MMS Signature Versions

Signatures for MMS change depending on the content-type, be sure to consult the correct section for the respective type.

### `2026-07-27` MMS Multipart

When the `content-type` is of `multipart/*`, where its subtype can be any value.

* Request Headers (the main document)
  * `content-type`
  * `x-message-authorization-version`
  * `x-message-content-type`
  * `x-message-format`
  * `x-message-id`
  * `x-message-iv`
  * `x-message-signature-version`
  * `x-message-timestamp`
  * `x-tychron-csp-campaign-id`
  * `x-tychron-remote-reference-id`
  * `x-tychron-remote-service-provider`
  * `x-tychron-tcr-brand-id`
  * `x-tychron-tcr-campaign-id`
* Each Part (repeat for each part in the request, IN ORDER)
  * Part Headers
    * `content-type`
    * `x-message-content-type`
    * `x-message-iv`
  * Part Body

### `2026-07-27` MMS Single Part

For everything else:

* Request Headers (the main document)
  * `content-type`
  * `x-message-authorization-version`
  * `x-message-content-type`
  * `x-message-format`
  * `x-message-id`
  * `x-message-iv`
  * `x-message-signature-version`
  * `x-message-timestamp`
  * `x-tychron-csp-campaign-id`
  * `x-tychron-remote-reference-id`
  * `x-tychron-remote-service-provider`
  * `x-tychron-tcr-brand-id`
  * `x-tychron-tcr-campaign-id`
* Request Body


__Type__ Enum:String

* `NONE`
* `SHA2_256`
* `SHA2_384`
* `SHA2_512`
* `SHA3_256`
* `SHA3_384`
* `SHA3_512`


__Example__

```json
"NONE"
```



## Schema / SwitchSigningScheme {#schema-switchsigningscheme}

The signing scheme that should be used, only NONE (for no signing) and HMAC are available.


__Type__ Enum:String

* `NONE`
* `HMAC`


__Example__

```json
"NONE"
```



## Schema / SwitchesResponse {#schema-switchesresponse}

Switches

__Type__ Object

| Name        | Type                                           | Description |
| ----------- | ---------------------------------------------- | ----------- |
| `count`     | Integer                                        |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                   |             |
| `results`   | Array:[SwitchResponse](https://docs.tychron.com/api-reference/schemas/#schema-switchresponse) |             |



__Example__

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



## Schema / SystemEvent {#schema-systemevent}

Format of the Subscription Event webhook.


__Type__ Object

| Name           | Type                                         | Description                       |
| -------------- | -------------------------------------------- | --------------------------------- |
| `associations` | `associations`                               | [Desc. `associations`](https://docs.tychron.com/api-reference/schemas/#desc-941) |
| `data`         | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-942)                          |                                   |
| `id`           | String(format:ulid)                          | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-943)           |
| `inserted_at`  | String(format:date-time)                     | [Desc. `inserted_at`](https://docs.tychron.com/api-reference/schemas/#desc-944)  |
| `timestamp`    | String(format:date-time)                     | [Desc. `timestamp`](https://docs.tychron.com/api-reference/schemas/#desc-945)    |
| `topic`        | [SystemEventTopic](https://docs.tychron.com/api-reference/schemas/#schema-systemeventtopic) |                                   |
| `type`         | [SystemEventType](https://docs.tychron.com/api-reference/schemas/#schema-systemeventtype)   |                                   |

#### Desc. `associations` {#desc-941}

Depending on the `type`, this field will contain additional associations of the parent record.

For example:

* `ORDER_COMPLETED` - will include `requests`
* `REQUEST_COMPLETED` - will include `provision_records`

#### One-Of {#type-942}

Types

* [SystemEventDataCspCampaignRegistered](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatacspcampaignregistered)
* [SystemEventDataCspCampaignOptoutItemCreated](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatacspcampaignoptoutitemcreated)
* [SystemEventDataCspCampaignOptoutItemDeleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatacspcampaignoptoutitemdeleted)
* [SystemEventDataDidCreated](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcreated)
* [SystemEventDataDidDeleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadiddeleted)
* [SystemEventDataDidComponentCreated](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcomponentcreated)
* [SystemEventDataDidComponentDeleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcomponentdeleted)
* [SystemEventDataDidOptoutItemCreated](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidoptoutitemcreated)
* [SystemEventDataDidOptoutItemDeleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidoptoutitemdeleted)
* [SystemEventDataOsrOverwriteRequestPending](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdataosroverwriterequestpending)
* [SystemEventDataOsrOverwriteRequestCompleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdataosroverwriterequestcompleted)
* [SystemEventDataOrderCompleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdataordercompleted)
* [SystemEventDataRequestCompleted](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatarequestcompleted)

#### Desc. `id` {#desc-943}

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

#### Desc. `inserted_at` {#desc-944}

When was this event first created?

#### Desc. `timestamp` {#desc-945}

When was the event sent from the host system?

__associations__

| Name                | Type                                                                                         | Description |
| ------------------- | -------------------------------------------------------------------------------------------- | ----------- |
| `provision_records` | Array:[SystemEventAssociationProvisionRecord](https://docs.tychron.com/api-reference/schemas/#schema-systemeventassociationprovisionrecord) |             |
| `requests`          | Array:[SystemEventAssociationRequest](https://docs.tychron.com/api-reference/schemas/#schema-systemeventassociationrequest)                 |             |



__Example__

```json
{
  "associations": {
    "provision_records": [
      {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "number": "12003004000",
        "status": "NONE"
      }
    ],
    "requests": [
      {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "status": "NEW"
      }
    ]
  },
  "data": {
    "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "tcr_campaign_id": "C000000"
  },
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "timestamp": "2021-08-13T04:08:44.762841Z",
  "topic": "NONE",
  "type": "DID_CREATED"
}
```



## Schema / SystemEventAssociationProvisionRecord {#schema-systemeventassociationprovisionrecord}

Purely associated with the `REQUEST_COMPLETED` System Event, Provision Records,
henceforth abbreviated as PVR track individual items within a REQUEST.

The `number` of the PVR will typically contain the most relevant ID or value of the resource
it represents.

Examples:

* e.g.1. `ADD_MESSAGING_NUMBERS`'s PVRs has its number correspond to the `numbers`.
* e.g.2. `REGISTER_BRAND`'s PVRs has its number fixed to "0000".
* e.g.3. `REGISTER_CAMPAIGN`'s PVRs has its number fixed to "0000".


__Type__ Object

| Name         | Type                                                                       | Description                 |
| ------------ | -------------------------------------------------------------------------- | --------------------------- |
| `error_code` | [RequestProvisionRecordErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-requestprovisionrecorderrorcode) |                             |
| `id`         | String(format:ulid)                                                        | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-946)     |
| `number`     | String(1..255)                                                             | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-947) |
| `status`     | [RequestProvisionRecordStatus](https://docs.tychron.com/api-reference/schemas/#schema-requestprovisionrecordstatus)       |                             |

#### Desc. `id` {#desc-946}

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

#### Desc. `number` {#desc-947}

The `number` represents the most relevant ID of the item in the REQUEST.

Field will customarily contain digits.

Some requests will use `0000` as their primary number, the events should include additional
data in its body in those cases to help differentiate events.



__Example__

```json
{
  "error_code": "OK",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "number": "12003004000",
  "status": "NONE"
}
```



## Schema / SystemEventAssociationRequest {#schema-systemeventassociationrequest}

__Type__ Object

| Name         | Type                                     | Description             |
| ------------ | ---------------------------------------- | ----------------------- |
| `error_code` | [OrderErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-ordererrorcode) |                         |
| `id`         | String(format:ulid)                      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-948) |
| `status`     | [OrderStatus](https://docs.tychron.com/api-reference/schemas/#schema-orderstatus)       |                         |

#### Desc. `id` {#desc-948}

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



__Example__

```json
{
  "error_code": "OK",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "status": "NEW"
}
```



## Schema / SystemEventDataCspCampaignOptoutItemCreated {#schema-systemeventdatacspcampaignoptoutitemcreated}

`CSP_CAMPAIGN_OPTOUT_ITEM_CREATED`

The creation of an optout item is the explicit action of a subscriber opting out of receiving
messages.


__Type__ Object

| Name              | Type                | Description                          |
| ----------------- | ------------------- | ------------------------------------ |
| `csp_campaign_id` | String(format:ulid) | [Desc. `csp_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-949) |
| `host_number`     | String              | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-950)     |
| `keyword`         | String              | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-951)         |
| `remote_number`   | String              | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-952)   |
| `tcr_campaign_id` | String              | The TCR issued campaign ID           |

#### Desc. `csp_campaign_id` {#desc-949}

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

#### Desc. `host_number` {#desc-950}

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

That is the number that received the optout request.

#### Desc. `keyword` {#desc-951}

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` {#desc-952}

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



__Example__

```json
{
  "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001",
  "tcr_campaign_id": "C000000"
}
```



## Schema / SystemEventDataCspCampaignOptoutItemDeleted {#schema-systemeventdatacspcampaignoptoutitemdeleted}

`CSP_CAMPAIGN_OPTOUT_ITEM_DELETED`

While it may be confusing at first, the deletion of an optout item signifies that a subscriber,
as opted-in to receive messages and a restriction is no longer in place.


__Type__ Object

| Name              | Type                | Description                          |
| ----------------- | ------------------- | ------------------------------------ |
| `csp_campaign_id` | String(format:ulid) | [Desc. `csp_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-953) |
| `host_number`     | String              | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-954)     |
| `keyword`         | String              | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-955)         |
| `remote_number`   | String              | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-956)   |
| `tcr_campaign_id` | String              | The TCR issued campaign ID           |

#### Desc. `csp_campaign_id` {#desc-953}

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

#### Desc. `host_number` {#desc-954}

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

That is the number that received the optout request.

#### Desc. `keyword` {#desc-955}

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` {#desc-956}

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



__Example__

```json
{
  "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001",
  "tcr_campaign_id": "C000000"
}
```



## Schema / SystemEventDataCspCampaignRegistered {#schema-systemeventdatacspcampaignregistered}

`CSP_CAMPAIGN_REGISTERED`


__Type__ Object

| Name              | Type                | Description                          |
| ----------------- | ------------------- | ------------------------------------ |
| `csp_campaign_id` | String(format:ulid) | [Desc. `csp_campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-957) |
| `tcr_campaign_id` | String              | The TCR issued campaign ID           |

#### Desc. `csp_campaign_id` {#desc-957}

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



__Example__

```json
{
  "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "tcr_campaign_id": "C000000"
}
```



## Schema / SystemEventDataDidComponent {#schema-systemeventdatadidcomponent}

The component of the DID that was created or deleted.


__Type__ Enum:String

* `UNKNOWN`
* `MESSAGING`
* `VOICE`
* `CSP_CAMPAIGN`


__Example__

```json
"UNKNOWN"
```



## Schema / SystemEventDataDidComponentCreated {#schema-systemeventdatadidcomponentcreated}

`DID_COMPONENT_CREATED`


__Type__ Object

| Name         | Type                                                                       | Description                     |
| ------------ | -------------------------------------------------------------------------- | ------------------------------- |
| `component`  | [SystemEventDataDidComponent](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcomponent)         |                                 |
| `did_id`     | String(format:uuid)                                                        | [Desc. `did_id`](https://docs.tychron.com/api-reference/schemas/#desc-958)     |
| `number`     | String                                                                     | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-959)     |
| `reason`     | [SystemEventDataDidCreatedReason](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcreatedreason) |                                 |
| `request_id` | String(format:ulid)                                                        | [Desc. `request_id`](https://docs.tychron.com/api-reference/schemas/#desc-960) |

#### Desc. `did_id` {#desc-958}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-959}

The 3 to 15 digit code of the number.

#### Desc. `request_id` {#desc-960}

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



__Example__

```json
{
  "component": "UNKNOWN",
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}
```



## Schema / SystemEventDataDidComponentDeleted {#schema-systemeventdatadidcomponentdeleted}

`DID_COMPONENT_DELETED`


__Type__ Object

| Name         | Type                                                                       | Description                     |
| ------------ | -------------------------------------------------------------------------- | ------------------------------- |
| `component`  | [SystemEventDataDidComponent](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcomponent)         |                                 |
| `did_id`     | String(format:uuid)                                                        | [Desc. `did_id`](https://docs.tychron.com/api-reference/schemas/#desc-961)     |
| `number`     | String                                                                     | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-962)     |
| `reason`     | [SystemEventDataDidDeletedReason](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadiddeletedreason) |                                 |
| `request_id` | String(format:ulid)                                                        | [Desc. `request_id`](https://docs.tychron.com/api-reference/schemas/#desc-963) |

#### Desc. `did_id` {#desc-961}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-962}

The 3 to 15 digit code of the number.

#### Desc. `request_id` {#desc-963}

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



__Example__

```json
{
  "component": "UNKNOWN",
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}
```



## Schema / SystemEventDataDidCreated {#schema-systemeventdatadidcreated}

`DID_CREATED`


__Type__ Object

| Name         | Type                                                                       | Description                     |
| ------------ | -------------------------------------------------------------------------- | ------------------------------- |
| `did_id`     | String(format:uuid)                                                        | [Desc. `did_id`](https://docs.tychron.com/api-reference/schemas/#desc-964)     |
| `number`     | String                                                                     | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-965)     |
| `reason`     | [SystemEventDataDidCreatedReason](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadidcreatedreason) |                                 |
| `request_id` | String(format:ulid)                                                        | [Desc. `request_id`](https://docs.tychron.com/api-reference/schemas/#desc-966) |

#### Desc. `did_id` {#desc-964}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-965}

The 3 to 15 digit code of the number.

#### Desc. `request_id` {#desc-966}

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



__Example__

```json
{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}
```



## Schema / SystemEventDataDidCreatedReason {#schema-systemeventdatadidcreatedreason}

The reason a DID was deleted.


__Type__ Enum:String

* `UNKNOWN`
* `CREATED_BY_REQUEST`


__Example__

```json
"UNKNOWN"
```



## Schema / SystemEventDataDidDeleted {#schema-systemeventdatadiddeleted}

`DID_DELETED`


__Type__ Object

| Name         | Type                                                                       | Description                     |
| ------------ | -------------------------------------------------------------------------- | ------------------------------- |
| `did_id`     | String(format:uuid)                                                        | [Desc. `did_id`](https://docs.tychron.com/api-reference/schemas/#desc-967)     |
| `number`     | String                                                                     | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-968)     |
| `reason`     | [SystemEventDataDidDeletedReason](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatadiddeletedreason) |                                 |
| `request_id` | String(format:ulid)                                                        | [Desc. `request_id`](https://docs.tychron.com/api-reference/schemas/#desc-969) |

#### Desc. `did_id` {#desc-967}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-968}

The 3 to 15 digit code of the number.

#### Desc. `request_id` {#desc-969}

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



__Example__

```json
{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "number": "12003004000",
  "reason": "UNKNOWN",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0"
}
```



## Schema / SystemEventDataDidDeletedReason {#schema-systemeventdatadiddeletedreason}

The reason a DID was deleted.


__Type__ Enum:String

* `UNKNOWN`
* `DELETED_FROM_REGISTRY`
* `DELETED_MANUALLY`
* `DELETED_BY_REQUEST`


__Example__

```json
"UNKNOWN"
```



## Schema / SystemEventDataDidOptoutItemCreated {#schema-systemeventdatadidoptoutitemcreated}

`DID_OPTOUT_ITEM_CREATED`

The creation of an optout item is the explicit action of a subscriber opting out of receiving
messages.


__Type__ Object

| Name            | Type                | Description                        |
| --------------- | ------------------- | ---------------------------------- |
| `host_did_id`   | String(format:uuid) | [Desc. `host_did_id`](https://docs.tychron.com/api-reference/schemas/#desc-970)   |
| `host_number`   | String              | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-971)   |
| `keyword`       | String              | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-972)       |
| `remote_number` | String              | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-973) |

#### Desc. `host_did_id` {#desc-970}

A Universally unique identifier, which identifies the resource

#### Desc. `host_number` {#desc-971}

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

That is the number that received the optout request.

#### Desc. `keyword` {#desc-972}

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` {#desc-973}

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



__Example__

```json
{
  "host_did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001"
}
```



## Schema / SystemEventDataDidOptoutItemDeleted {#schema-systemeventdatadidoptoutitemdeleted}

`DID_OPTOUT_ITEM_DELETED`

While it may be confusing at first, the deletion of an optout item signifies that a subscriber,
as opted-in to receive messages and a restriction is no longer in place.


__Type__ Object

| Name            | Type                | Description                        |
| --------------- | ------------------- | ---------------------------------- |
| `host_did_id`   | String(format:uuid) | [Desc. `host_did_id`](https://docs.tychron.com/api-reference/schemas/#desc-974)   |
| `host_number`   | String              | [Desc. `host_number`](https://docs.tychron.com/api-reference/schemas/#desc-975)   |
| `keyword`       | String              | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-976)       |
| `remote_number` | String              | [Desc. `remote_number`](https://docs.tychron.com/api-reference/schemas/#desc-977) |

#### Desc. `host_did_id` {#desc-974}

A Universally unique identifier, which identifies the resource

#### Desc. `host_number` {#desc-975}

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

That is the number that received the optout request.

#### Desc. `keyword` {#desc-976}

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` {#desc-977}

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



__Example__

```json
{
  "host_did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "host_number": "12003004000",
  "keyword": "STOP",
  "remote_number": "12003004001"
}
```



## Schema / SystemEventDataOrderCompleted {#schema-systemeventdataordercompleted}

`ORDER_COMPLETED`

This event is sent whenever an `ORDER` is considered complete, not necessarily `COMPLETED`.

The `requests` associations will be included in the parent System Event.

Note the `requests` association do not include their PVRs, you must have the REQUEST topic enabled to receive those details.


__Type__ Object

| Name         | Type                                     | Description                   |
| ------------ | ---------------------------------------- | ----------------------------- |
| `error_code` | [OrderErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-ordererrorcode) |                               |
| `order_id`   | String(format:ulid)                      | [Desc. `order_id`](https://docs.tychron.com/api-reference/schemas/#desc-978) |
| `status`     | [OrderStatus](https://docs.tychron.com/api-reference/schemas/#schema-orderstatus)       |                               |

#### Desc. `order_id` {#desc-978}

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



__Example__

```json
{
  "error_code": "OK",
  "order_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "status": "NEW"
}
```



## Schema / SystemEventDataOsrOverwriteRequestCompleted {#schema-systemeventdataosroverwriterequestcompleted}

`OSR_OVERWRITE_REQUEST_COMPLETED`


__Type__ Object

| Name                        | Type                     | Description                                   |
| --------------------------- | ------------------------ | --------------------------------------------- |
| `did_id`                    | String(format:uuid)      | [Desc. `did_id`](https://docs.tychron.com/api-reference/schemas/#desc-979)                   |
| `error_code`                | Enum(`OK`):String        | Further explanation of an error status        |
| `new_nnid_service_provider` | String                   |                                               |
| `number`                    | String                   | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-980)                   |
| `osr_overwrite_request_id`  | String(format:ulid)      | [Desc. `osr_overwrite_request_id`](https://docs.tychron.com/api-reference/schemas/#desc-981) |
| `review_status`             | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-982):String | [Desc. `review_status`](https://docs.tychron.com/api-reference/schemas/#desc-983)            |
| `status`                    | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-984):String | [Desc. `status`](https://docs.tychron.com/api-reference/schemas/#desc-985)                   |

#### Desc. `did_id` {#desc-979}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-980}

The 3 to 15 digit code of the number.

#### Desc. `osr_overwrite_request_id` {#desc-981}

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

#### Enum Values review_status {#enum-982}

Allowed values

* `NONE`
* `APPROVED`
* `REJECTED`
* `AUTO_APPROVED`
* `AUTO_REJECTED`
* `FORCE_DELETED`

#### Desc. `review_status` {#desc-983}

The review status of the request, defaults to NONE.

#### Enum Values status {#enum-984}

Allowed values

* `NEW`
* `REVIEWED`
* `APPROVED`
* `REJECTED`
* `ERROR`
* `STALE`
* `DELETED`

#### Desc. `status` {#desc-985}

The current processing status of the request



__Example__

```json
{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "error_code": "OK",
  "new_nnid_service_provider": "ACME Corp",
  "number": "12003004000",
  "osr_overwrite_request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "review_status": "NONE",
  "status": "NEW"
}
```



## Schema / SystemEventDataOsrOverwriteRequestPending {#schema-systemeventdataosroverwriterequestpending}

`OSR_OVERWRITE_REQUEST_PENDING`


__Type__ Object

| Name                        | Type                     | Description                                   |
| --------------------------- | ------------------------ | --------------------------------------------- |
| `did_id`                    | String(format:uuid)      | [Desc. `did_id`](https://docs.tychron.com/api-reference/schemas/#desc-986)                   |
| `error_code`                | Enum(`OK`):String        | Further explanation of an error status        |
| `new_nnid_service_provider` | String                   |                                               |
| `number`                    | String                   | [Desc. `number`](https://docs.tychron.com/api-reference/schemas/#desc-987)                   |
| `osr_overwrite_request_id`  | String(format:ulid)      | [Desc. `osr_overwrite_request_id`](https://docs.tychron.com/api-reference/schemas/#desc-988) |
| `review_status`             | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-989):String | [Desc. `review_status`](https://docs.tychron.com/api-reference/schemas/#desc-990)            |
| `status`                    | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-991):String | [Desc. `status`](https://docs.tychron.com/api-reference/schemas/#desc-992)                   |

#### Desc. `did_id` {#desc-986}

A Universally unique identifier, which identifies the resource

#### Desc. `number` {#desc-987}

The 3 to 15 digit code of the number.

#### Desc. `osr_overwrite_request_id` {#desc-988}

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

#### Enum Values review_status {#enum-989}

Allowed values

* `NONE`
* `APPROVED`
* `REJECTED`
* `AUTO_APPROVED`
* `AUTO_REJECTED`
* `FORCE_DELETED`

#### Desc. `review_status` {#desc-990}

The review status of the request, defaults to NONE.

#### Enum Values status {#enum-991}

Allowed values

* `NEW`
* `REVIEWED`
* `APPROVED`
* `REJECTED`
* `ERROR`
* `STALE`
* `DELETED`

#### Desc. `status` {#desc-992}

The current processing status of the request



__Example__

```json
{
  "did_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "error_code": "OK",
  "new_nnid_service_provider": "ACME Corp",
  "number": "12003004000",
  "osr_overwrite_request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "review_status": "NONE",
  "status": "NEW"
}
```



## Schema / SystemEventDataRequestCompleted {#schema-systemeventdatarequestcompleted}

`REQUEST_COMPLETED`

This event is sent whenever a `REQUEST` is considered complete (not necessarily `COMPLETED`, it may be an `ERROR` as well).

The parent System Event will contain the `provision_records` associations which give a finer detail of what specific items were completed or had errors.


__Type__ Object

| Name         | Type                                     | Description                     |
| ------------ | ---------------------------------------- | ------------------------------- |
| `data`       | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-993)                      |                                 |
| `error_code` | [OrderErrorCode](https://docs.tychron.com/api-reference/schemas/#schema-ordererrorcode) |                                 |
| `order_id`   | String(format:ulid)                      | [Desc. `order_id`](https://docs.tychron.com/api-reference/schemas/#desc-994)   |
| `request_id` | String(format:ulid)                      | [Desc. `request_id`](https://docs.tychron.com/api-reference/schemas/#desc-995) |
| `status`     | [OrderStatus](https://docs.tychron.com/api-reference/schemas/#schema-orderstatus)       |                                 |
| `type`       | [RequestType](https://docs.tychron.com/api-reference/schemas/#schema-requesttype)       |                                 |

#### One-Of {#type-993}

Types

* [SystemEventDataRequestCompletedDataRegisterBrand](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatarequestcompleteddataregisterbrand)
* [SystemEventDataRequestCompletedDataRegisterCampaign](https://docs.tychron.com/api-reference/schemas/#schema-systemeventdatarequestcompleteddataregistercampaign)

#### Desc. `order_id` {#desc-994}

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

#### Desc. `request_id` {#desc-995}

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



__Example__

```json
{
  "data": {
    "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "tcr_brand_id": "B123456"
  },
  "error_code": "OK",
  "order_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "request_id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "status": "NEW",
  "type": "ADD_CAMPAIGN_NUMBERS"
}
```



## Schema / SystemEventDataRequestCompletedDataRegisterBrand {#schema-systemeventdatarequestcompleteddataregisterbrand}

Data for `REGISTER_BRAND` requests.


__Type__ Object

| Name           | Type                | Description                   |
| -------------- | ------------------- | ----------------------------- |
| `brand_id`     | String(format:uuid) | [Desc. `brand_id`](https://docs.tychron.com/api-reference/schemas/#desc-996) |
| `tcr_brand_id` | String              |                               |

#### Desc. `brand_id` {#desc-996}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "tcr_brand_id": "B123456"
}
```



## Schema / SystemEventDataRequestCompletedDataRegisterCampaign {#schema-systemeventdatarequestcompleteddataregistercampaign}

Data for `REGISTER_CAMPAIGN` requests.


__Type__ Object

| Name              | Type                | Description                      |
| ----------------- | ------------------- | -------------------------------- |
| `brand_id`        | String(format:uuid) | [Desc. `brand_id`](https://docs.tychron.com/api-reference/schemas/#desc-997)    |
| `campaign_id`     | String(format:uuid) | [Desc. `campaign_id`](https://docs.tychron.com/api-reference/schemas/#desc-998) |
| `reseller_id`     | String(format:uuid) | [Desc. `reseller_id`](https://docs.tychron.com/api-reference/schemas/#desc-999) |
| `tcr_brand_id`    | String              |                                  |
| `tcr_campaign_id` | String              |                                  |
| `tcr_reseller_id` | String              |                                  |

#### Desc. `brand_id` {#desc-997}

A Universally unique identifier, which identifies the resource

#### Desc. `campaign_id` {#desc-998}

A Universally unique identifier, which identifies the resource

#### Desc. `reseller_id` {#desc-999}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "campaign_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "reseller_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "tcr_brand_id": "B123456",
  "tcr_campaign_id": "C123456",
  "tcr_reseller_id": "R123456"
}
```



## Schema / SystemEventTopic {#schema-systemeventtopic}

The overall topic that the event belongs to.


__Type__ Enum:String

* `NONE`
* `DID`
* `CSP_BRAND`
* `CSP_CAMPAIGN`
* `ORDER`
* `REQUEST`
* `OSR`


__Example__

```json
"NONE"
```



## Schema / SystemEventType {#schema-systemeventtype}

The type of the event, this denotes what the `data` will contain.


__Type__ Enum:String

* `DID_COMPLETED_CREATED`
* `DID_COMPLETED_DELETED`
* `DID_CREATED`
* `DID_DELETED`
* `ORDER_COMPLETED`
* `REQUEST_COMPLETED`
* `OSR_OVERWRITE_REQUEST_PENDING`
* `OSR_OVERWRITE_REQUEST_COMPLETED`


__Example__

```json
"DID_CREATED"
```



## Schema / UpdateApiKeyData {#schema-updateapikeydata}

Parameters for updating an api key

__Type__ Object

| Name     | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| `active` | Boolean | Whether the API Key is active for use |
| `name`   | String  | A display name for the API Key        |
| `notes`  | String  | Any notes on the API Key              |



__Example__

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



## Schema / UpdateApiKeyRequest {#schema-updateapikeyrequest}

Request for update an existing API Key

__Type__ Object

| Name   | Type                                         | Description |
| ------ | -------------------------------------------- | ----------- |
| `data` | [UpdateApiKeyData](https://docs.tychron.com/api-reference/schemas/#schema-updateapikeydata) |             |
| `type` | String                                       |             |



__Example__

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



## Schema / UpdateCallDataWebhookData {#schema-updatecalldatawebhookdata}

Parameters for creating a new Call Data Webhook.


__Type__ Object

| Name                  | Type                                   | Description                               |
| --------------------- | -------------------------------------- | ----------------------------------------- |
| `auth_identity`       | String                                 | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-1000)       |
| `auth_method`         | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-1001)         |
| `auth_name`           | String                                 | [Desc. `auth_name`](https://docs.tychron.com/api-reference/schemas/#desc-1002)           |
| `auth_secret`         | String                                 | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-1003)         |
| `custom_headers`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1004)          | [Desc. `custom_headers`](https://docs.tychron.com/api-reference/schemas/#desc-1005)      |
| `custom_query_params` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1006)          | [Desc. `custom_query_params`](https://docs.tychron.com/api-reference/schemas/#desc-1007) |
| `data`                | String                                 | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-1008)                |
| `name`                | String(1..255)                         | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-1009)                |
| `notes`               | String(0..65535)                       | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-1010)               |
| `protocol`            | Enum(`NONE`, `HTTP`, `SFTP`):String    | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-1011)            |

#### Desc. `auth_identity` {#desc-1000}

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

#### Desc. `auth_method` {#desc-1001}

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` {#desc-1002}

Reserved for other protocols that may require additional auth information.

#### Desc. `auth_secret` {#desc-1003}

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

#### SubObject {#type-1004}

Sub-Schema

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_headers` {#desc-1005}

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 {#type-1006}

Sub-Schema

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_query_params` {#desc-1007}

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` {#desc-1008}

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` {#desc-1009}

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

#### Desc. `notes` {#desc-1010}

Any notes or details about the call data webhook.

#### Desc. `protocol` {#desc-1011}

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__

```json
{
  "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 / UpdateCallDataWebhookRequest {#schema-updatecalldatawebhookrequest}

Request for update an existing Call Data Webhook

__Type__ Object

| Name   | Type                                                           | Description |
| ------ | -------------------------------------------------------------- | ----------- |
| `data` | [UpdateCallDataWebhookData](https://docs.tychron.com/api-reference/schemas/#schema-updatecalldatawebhookdata) |             |
| `type` | String                                                         |             |



__Example__

```json
{
  "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 / UpdateCartData {#schema-updatecartdata}

Parameters for updating a cart

__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `name`  | String |             |
| `notes` | String |             |



__Example__

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



## Schema / UpdateCartRequest {#schema-updatecartrequest}

Request for update an existing cart

__Type__ Object

| Name   | Type                                     | Description |
| ------ | ---------------------------------------- | ----------- |
| `data` | [UpdateCartData](https://docs.tychron.com/api-reference/schemas/#schema-updatecartdata) |             |
| `type` | String                                   |             |



__Example__

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



## Schema / UpdateCartRequestData {#schema-updatecartrequestdata}

Parameters for updating a cart

__Type__ Object

| Name    | Type                 | Description |
| ------- | -------------------- | ----------- |
| `name`  | String               |             |
| `notes` | String               |             |
| `*`     | [One-Of](https://docs.tychron.com/api-reference/schemas/#type-1012) |             |

#### One-Of {#type-1012}

Types

* [CartRequestAddCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddcampaignnumbersdata)
* [CartRequestAddMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddmessagingnumbersdata)
* [CartRequestAddVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestaddvoicenumbersdata)
* [CartRequestNewNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestnewnumbersdata)
* [CartRequestRegisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestregisterbranddata)
* [CartRequestRegisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestregistercampaigndata)
* [CartRequestRemoveCampaignNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovecampaignnumbersdata)
* [CartRequestRemoveMessagingNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovemessagingnumbersdata)
* [CartRequestRemoveNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovenumbersdata)
* [CartRequestRemoveVoiceNumbersData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestremovevoicenumbersdata)
* [CartRequestUnregisterBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestunregisterbranddata)
* [CartRequestUnregisterCampaignData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestunregistercampaigndata)
* [CartRequestVetBrandData](https://docs.tychron.com/api-reference/schemas/#schema-cartrequestvetbranddata)



__Example__

```json
{
  "name": "string",
  "notes": "string",
  "*": {
    "numbers": [
      "12003004000"
    ],
    "*": {
      "tcr_campaign_id": "C000000"
    }
  }
}
```



## Schema / UpdateCartRequestRequest {#schema-updatecartrequestrequest}

Request for update an existing cart

__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [UpdateCartRequestData](https://docs.tychron.com/api-reference/schemas/#schema-updatecartrequestdata) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "data": {
    "name": "string",
    "notes": "string",
    "*": {
      "numbers": [
        "12003004000"
      ],
      "*": {
        "tcr_campaign_id": "C000000"
      }
    }
  },
  "type": "request"
}
```



## Schema / UpdateDestinationRequest {#schema-updatedestinationrequest}

Request for updating an existing Number Destination

__Type__ Object

| Name   | Type                                                   | Description |
| ------ | ------------------------------------------------------ | ----------- |
| `data` | [UpsertDestinationData](https://docs.tychron.com/api-reference/schemas/#schema-upsertdestinationdata) |             |
| `type` | String                                                 |             |



__Example__

```json
{
  "data": {
    "activated": true,
    "auth_identity": "username",
    "auth_method": "BASIC",
    "auth_secret": "password",
    "destination": "http://example.com/http/route/call",
    "priority": 1,
    "tts_message_set_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "type": "HTTP_ROUTE"
  },
  "type": "number_destination"
}
```



## Schema / UpdateMessageRequest {#schema-updatemessagerequest}

Request for update an existing tts message

__Type__ Object

| Name   | Type                                           | Description |
| ------ | ---------------------------------------------- | ----------- |
| `data` | [UpsertMessageData](https://docs.tychron.com/api-reference/schemas/#schema-upsertmessagedata) |             |
| `type` | String                                         |             |



__Example__

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



## Schema / UpdateMessageSetRequest {#schema-updatemessagesetrequest}

Request for update an existing tts message set

__Type__ Object

| Name   | Type                                                 | Description |
| ------ | ---------------------------------------------------- | ----------- |
| `data` | [UpsertMessageSetData](https://docs.tychron.com/api-reference/schemas/#schema-upsertmessagesetdata) |             |
| `type` | String                                               |             |



__Example__

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



## Schema / UpdateNumberData {#schema-updatenumberdata}

Parameters for updating a number

__Type__ Object

| Name                     | Type                          | Description                              |
| ------------------------ | ----------------------------- | ---------------------------------------- |
| `description`            | String                        | [Desc. `description`](https://docs.tychron.com/api-reference/schemas/#desc-1013)        |
| `forward_number`         | String                        | [Desc. `forward_number`](https://docs.tychron.com/api-reference/schemas/#desc-1014)     |
| `help_message`           | String(0..255)                | [Desc. `help_message`](https://docs.tychron.com/api-reference/schemas/#desc-1015)       |
| `mms_enabled`            | Boolean                       | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-1016)        |
| `segment_overrides`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1021) | [Desc. `segment_overrides`](https://docs.tychron.com/api-reference/schemas/#desc-1022)  |
| `segment_threshold`      | Integer                       | [Desc. `segment_threshold`](https://docs.tychron.com/api-reference/schemas/#desc-1023)  |
| `upgrade_asset_handling` | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1024):String     | The asset handling flag for SMS Upgrades |

#### Desc. `description` {#desc-1013}

Any notes to attach to the number.

#### Desc. `forward_number` {#desc-1014}

When this DID receives an inbound message, the message will be routed to the specified `forward_number`.

Note. using forward_number or its switch equivalent will charge the account for 2 messages, instead of 1:
* Once for the inbound (to the host number)
* Again for the outbound (from the host number to the forward number)

If this field is nil, or blank the `sms_switch` will be used for routing instead

#### Desc. `help_message` {#desc-1015}

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. `mms_enabled` {#desc-1016}

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

#### SubObject {#type-1021}

Sub-Schema

__Type__ Object

| Name                  | Type                | Description                               |
| --------------------- | ------------------- | ----------------------------------------- |
| `encoding`            | Integer             | [Desc. `encoding`](https://docs.tychron.com/api-reference/schemas/#desc-1017)            |
| `id`                  | String(format:uuid) | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-1018)                  |
| `segment_threshold`   | Integer             | [Desc. `segment_threshold`](https://docs.tychron.com/api-reference/schemas/#desc-1019)   |
| `target_reference_id` | String              | [Desc. `target_reference_id`](https://docs.tychron.com/api-reference/schemas/#desc-1020) |

#### Desc. `encoding` {#desc-1017}

The SMS encoding that this override should trigger on.

#### Desc. `id` {#desc-1018}

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

#### Desc. `segment_threshold` {#desc-1019}

See number's segment_threshold for more information.

#### Desc. `target_reference_id` {#desc-1020}

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` {#desc-1022}

While the segment_threshold can be used to apply to all outgoing sms messages, sometimes
its required to tailor fit an upgrade to a particular carrier.

Note, when updating the segment_overrides, all overrides must be provided for the did, any unspecified overrides will be removed.

#### Desc. `segment_threshold` {#desc-1023}

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.

#### Enum Values upgrade_asset_handling {#enum-1024}

Allowed values

* `FALLBACK`
* `OFF`
* `ALWAYS_UPGRADE`
* `SEGMENT_UPGRADE`



__Example__

```json
{
  "description": "Test number used for XYZ.Corp\n",
  "forward_number": "12003004000",
  "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
  "mms_enabled": true,
  "segment_overrides": [
    {
      "encoding": 0,
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "segment_threshold": 0,
      "target_reference_id": "us_tmobile"
    }
  ],
  "segment_threshold": 1,
  "upgrade_asset_handling": "FALLBACK"
}
```



## Schema / UpdateNumberRequest {#schema-updatenumberrequest}

Update an existing number

__Type__ Object

| Name   | Type                                         | Description |
| ------ | -------------------------------------------- | ----------- |
| `data` | [UpdateNumberData](https://docs.tychron.com/api-reference/schemas/#schema-updatenumberdata) |             |
| `type` | String                                       |             |



__Example__

```json
{
  "data": {
    "description": "Test number used for XYZ.Corp\n",
    "forward_number": "12003004000",
    "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
    "mms_enabled": true,
    "segment_overrides": [
      {
        "encoding": 0,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "segment_threshold": 0,
        "target_reference_id": "us_tmobile"
      }
    ],
    "segment_threshold": 1,
    "upgrade_asset_handling": "FALLBACK"
  },
  "type": "number"
}
```



## Schema / UpdateOrderData {#schema-updateorderdata}

Parameters for updating an Order

__Type__ Object

| Name    | Type             | Description                 |
| ------- | ---------------- | --------------------------- |
| `name`  | String(3..255)   | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-1025)  |
| `notes` | String(0..65535) | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-1026) |

#### Desc. `name` {#desc-1025}

Display name for Order.

#### Desc. `notes` {#desc-1026}

Any additional text about the order, useful for informing someone about the order's purpose.



__Example__

```json
{
  "name": "Add Messaging to 10 Numbers",
  "notes": "Order for Client XYZ\n"
}
```



## Schema / UpdateOrderRequest {#schema-updateorderrequest}

Request for update an existing Order

__Type__ Object

| Name   | Type                                       | Description |
| ------ | ------------------------------------------ | ----------- |
| `data` | [UpdateOrderData](https://docs.tychron.com/api-reference/schemas/#schema-updateorderdata) |             |
| `type` | String                                     |             |



__Example__

```json
{
  "data": {
    "name": "Add Messaging to 10 Numbers",
    "notes": "Order for Client XYZ\n"
  },
  "type": "order"
}
```



## Schema / UpdateRoleData {#schema-updateroledata}

Request Data when updating an existing Role.


__Type__ Object

| Name            | Type                                               | Description                         |
| --------------- | -------------------------------------------------- | ----------------------------------- |
| `default_scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `default_scope`](https://docs.tychron.com/api-reference/schemas/#desc-1027) |
| `name`          | String                                             | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-1028)          |
| `notes`         | String                                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-1029)         |
| `rank`          | Integer(>= 0)                                      | [Desc. `rank`](https://docs.tychron.com/api-reference/schemas/#desc-1030)          |
| `resources`     | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1036)                      | [Desc. `resources`](https://docs.tychron.com/api-reference/schemas/#desc-1037)     |

#### Desc. `default_scope` {#desc-1027}

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` {#desc-1028}

Role's display name.

#### Desc. `notes` {#desc-1029}

Any notes about the role.

#### Desc. `rank` {#desc-1030}

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 {#type-1036}

Sub-Schema

__Type__ Object

| Name          | Type                                               | Description                 |
| ------------- | -------------------------------------------------- | --------------------------- |
| `actions`     | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1034)                      |                             |
| `resource_id` | String                                             |                             |
| `scope`       | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](https://docs.tychron.com/api-reference/schemas/#desc-1035) |

#### SubObject {#type-1034}

Sub-Schema

__Type__ Object

| Name    | Type                         | Description                 |
| ------- | ---------------------------- | --------------------------- |
| `name`  | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1031):String    | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-1032)  |
| `value` | Enum(`true`, `false`):String | [Desc. `value`](https://docs.tychron.com/api-reference/schemas/#desc-1033) |

#### Enum Values name {#enum-1031}

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` {#desc-1032}

The name of the action.

#### Desc. `value` {#desc-1033}

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` {#desc-1035}

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

IGNORE acts as a fallback to the `default_scope`.





#### Desc. `resources` {#desc-1037}

Role's job title, or position



__Example__

```json
{
  "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 / UpdateRoleRequest {#schema-updaterolerequest}

Request for updating an existing Role.

__Type__ Object

| Name   | Type                                     | Description |
| ------ | ---------------------------------------- | ----------- |
| `data` | [UpdateRoleData](https://docs.tychron.com/api-reference/schemas/#schema-updateroledata) |             |
| `type` | String                                   |             |



__Example__

```json
{
  "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 / UpdateSecretKeyData {#schema-updatesecretkeydata}

Parameters for updating a Secret Key

__Type__ Object

| Name     | Type    | Description                              |
| -------- | ------- | ---------------------------------------- |
| `active` | Boolean | Whether the Secret Key is active for use |
| `name`   | String  | A display name for the Secret Key        |
| `notes`  | String  | Any notes on the Secret Key              |



__Example__

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



## Schema / UpdateSecretKeyRequest {#schema-updatesecretkeyrequest}

Request for update an existing Secret Key

__Type__ Object

| Name   | Type                                               | Description |
| ------ | -------------------------------------------------- | ----------- |
| `data` | [UpdateSecretKeyData](https://docs.tychron.com/api-reference/schemas/#schema-updatesecretkeydata) |             |
| `type` | String                                             |             |



__Example__

```json
{
  "data": {
    "active": false,
    "name": "string",
    "notes": "string"
  },
  "type": "secret_key"
}
```



## Schema / UpdateSwitchRequest {#schema-updateswitchrequest}

Request for update an existing Switch

__Type__ Object

| Name   | Type                                         | Description |
| ------ | -------------------------------------------- | ----------- |
| `data` | [UpsertSwitchData](https://docs.tychron.com/api-reference/schemas/#schema-upsertswitchdata) |             |
| `type` | String                                       |             |



__Example__

```json
{
  "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": "12003004000@example.com",
    "voice_enabled": false,
    "voice_identity": "johndoe",
    "voice_name": "John Doe",
    "voice_protocol": "NONE",
    "voice_secret": "super$ecret"
  },
  "type": "switch"
}
```



## Schema / UpdateUserData {#schema-updateuserdata}

Request Data when update an existing user


__Type__ Object

| Name         | Type                 | Description                      |
| ------------ | -------------------- | -------------------------------- |
| `address`    | `address`            | [Desc. `address`](https://docs.tychron.com/api-reference/schemas/#desc-1038)    |
| `email`      | String(format:email) | [Desc. `email`](https://docs.tychron.com/api-reference/schemas/#desc-1039)      |
| `first_name` | String               | [Desc. `first_name`](https://docs.tychron.com/api-reference/schemas/#desc-1040) |
| `last_name`  | String               | [Desc. `last_name`](https://docs.tychron.com/api-reference/schemas/#desc-1041)  |
| `title`      | String               | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-1042)      |

#### Desc. `address` {#desc-1038}

User Address details, may differ from top-level details

#### Desc. `email` {#desc-1039}

User's email

#### Desc. `first_name` {#desc-1040}

User's first name

#### Desc. `last_name` {#desc-1041}

User's last name

#### Desc. `title` {#desc-1042}

User's job title, or position

__address__

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `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 |             |



__Example__

```json
{
  "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": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "title": "Operator"
}
```



## Schema / UpdateUserRequest {#schema-updateuserrequest}

Request for updating an existing User

__Type__ Object

| Name   | Type                                     | Description |
| ------ | ---------------------------------------- | ----------- |
| `data` | [UpdateUserData](https://docs.tychron.com/api-reference/schemas/#schema-updateuserdata) |             |
| `type` | String                                   |             |



__Example__

```json
{
  "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": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "title": "Operator"
  },
  "type": "user"
}
```



## Schema / UpsertDestinationData {#schema-upsertdestinationdata}

Parameters for creating or updating a Number Destination

__Type__ Object

| Name                 | Type                                   | Description                              |
| -------------------- | -------------------------------------- | ---------------------------------------- |
| `activated`          | Boolean                                | [Desc. `activated`](https://docs.tychron.com/api-reference/schemas/#desc-1043)          |
| `auth_identity`      | String                                 | The username for a BASIC auth_method     |
| `auth_method`        | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-1044)        |
| `auth_secret`        | String                                 | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-1045)        |
| `destination`        | String                                 | [Desc. `destination`](https://docs.tychron.com/api-reference/schemas/#desc-1046)        |
| `priority`           | Integer                                | [Desc. `priority`](https://docs.tychron.com/api-reference/schemas/#desc-1047)           |
| `tts_message_set_id` | String(format:uuid)                    | [Desc. `tts_message_set_id`](https://docs.tychron.com/api-reference/schemas/#desc-1048) |
| `type`               | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1049):String              | [Desc. `type`](https://docs.tychron.com/api-reference/schemas/#desc-1050)               |

#### Desc. `activated` {#desc-1043}

Whether or not the destination is considered for routing

#### Desc. `auth_method` {#desc-1044}

The authorization method to used for HTTP_ROUTE destinations

#### Desc. `auth_secret` {#desc-1045}

The password for a BASIC auth_method or token for BEARER auth_method

#### Desc. `destination` {#desc-1046}

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` {#desc-1047}

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

#### Desc. `tts_message_set_id` {#desc-1048}

A Universally unique identifier, which identifies the resource

#### Enum Values type {#enum-1049}

Allowed values

* `VOIP`
* `PSTN`
* `HTTP_ROUTE`
* `TTS`
* `TTS_CUSTOM`
* `TTS_MESSAGE_SET`

#### Desc. `type` {#desc-1050}

The destination type, see destination field for more detail



__Example__

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



## Schema / UpsertEventSubscriptionData {#schema-upserteventsubscriptiondata}

Parameters when creating or updating an existing event subscription.

Note that only a `name` is required as the bare minimum for an event subscription.


__Type__ Object

| Name                  | Type                                                 | Description                          |
| --------------------- | ---------------------------------------------------- | ------------------------------------ |
| `auth_identity`       | String                                               | [Desc. `auth_identity`](https://docs.tychron.com/api-reference/schemas/#desc-1051)  |
| `auth_method`         | Enum(`NONE`, `BASIC`, `BEARER`):String               | [Desc. `auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-1052)    |
| `auth_name`           | String                                               | [Desc. `auth_name`](https://docs.tychron.com/api-reference/schemas/#desc-1053)      |
| `auth_secret`         | String                                               | [Desc. `auth_secret`](https://docs.tychron.com/api-reference/schemas/#desc-1054)    |
| `custom_headers`      | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1055)                        | [Desc. `custom_headers`](https://docs.tychron.com/api-reference/schemas/#desc-1056) |
| `custom_query_params` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1057)                        |                                      |
| `data`                | String                                               | [Desc. `data`](https://docs.tychron.com/api-reference/schemas/#desc-1058)           |
| `enabled`             | Boolean                                              | [Desc. `enabled`](https://docs.tychron.com/api-reference/schemas/#desc-1059)        |
| `name`                | String(..255)                                        | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-1060)           |
| `notes`               | String(..65535)                                      | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-1061)          |
| `protocol`            | Enum(`NONE`, `HTTP`, `SMTP`, `SFTP`, `EMAIL`):String | [Desc. `protocol`](https://docs.tychron.com/api-reference/schemas/#desc-1062)       |
| `recipient`           | String                                               | [Desc. `recipient`](https://docs.tychron.com/api-reference/schemas/#desc-1063)      |
| `topics`              | Array:[Enum](https://docs.tychron.com/api-reference/schemas/#enum-1064):String                      | [Desc. `topics`](https://docs.tychron.com/api-reference/schemas/#desc-1065)         |

#### Desc. `auth_identity` {#desc-1051}

Acts as the `username` for an auth pair.

#### Desc. `auth_method` {#desc-1052}

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` {#desc-1053}

Currently unused, but kept for future use.

#### Desc. `auth_secret` {#desc-1054}

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

#### SubObject {#type-1055}

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

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `custom_headers` {#desc-1056}

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

#### SubObject {#type-1057}

Sub-Schema

A single query parameter pair.


__Type__ Object

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| `key`   | String |             |
| `value` | String |             |





#### Desc. `data` {#desc-1058}

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. "john.doe@example.com")

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

#### Desc. `enabled` {#desc-1059}

Is the subscription enabled to handle events?

Subscriptions can be toggled on or off as needed.

#### Desc. `name` {#desc-1060}

The friendly given name for this subscription

#### Desc. `notes` {#desc-1061}

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` {#desc-1062}

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` {#desc-1063}

Only applicable when the `protocol` is SMTP, this will be the recipient address (e.g. "events@example.com")

#### Enum Values topics {#enum-1064}

Allowed values

* `NONE`
* `DID`
* `CSP_BRAND`
* `CSP_CAMPAIGN`
* `ORDER`
* `REQUEST`
* `OSR`

#### Desc. `topics` {#desc-1065}

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



__Example__

```json
{
  "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,
  "name": "CSP Events",
  "notes": "string",
  "protocol": "NONE",
  "recipient": "events@example.com",
  "topics": [
    "NONE"
  ]
}
```



## Schema / UpsertEventSubscriptionRequest {#schema-upserteventsubscriptionrequest}

Update request for an existing Event Subscription

__Type__ Object

| Name   | Type                                                               | Description |
| ------ | ------------------------------------------------------------------ | ----------- |
| `data` | [UpsertEventSubscriptionData](https://docs.tychron.com/api-reference/schemas/#schema-upserteventsubscriptiondata) |             |
| `type` | String                                                             |             |



__Example__

```json
{
  "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,
    "name": "CSP Events",
    "notes": "string",
    "protocol": "NONE",
    "recipient": "events@example.com",
    "topics": [
      "NONE"
    ]
  },
  "type": "event_subscription"
}
```



## Schema / UpsertMessageData {#schema-upsertmessagedata}

Data for creating, or updating a message


__Type__ Object

| Name       | Type           | Description             |
| ---------- | -------------- | ----------------------- |
| `body`     | String(1..255) | Name of the Message Set |
| `priority` | Integer        |                         |



__Example__

```json
{
  "body": "Pre-answer Greeter",
  "priority": 1
}
```



## Schema / UpsertMessageSetData {#schema-upsertmessagesetdata}

Data for creating, or updating a message set


__Type__ Object

| Name   | Type           | Description             |
| ------ | -------------- | ----------------------- |
| `name` | String(1..255) | Name of the Message Set |



__Example__

```json
{
  "name": "Pre-answer Greeter"
}
```



## Schema / UpsertMessagingAutoResponseData {#schema-upsertmessagingautoresponsedata}

Parameters for creating or updating a Messaging Auto Response

__Type__ Object

| Name       | Type                          | Description                       |
| ---------- | ----------------------------- | --------------------------------- |
| `keywords` | Array:[SubObject](https://docs.tychron.com/api-reference/schemas/#type-1071) | [Desc. `keywords`](https://docs.tychron.com/api-reference/schemas/#desc-1072)    |
| `name`     | String                        | Display name of the Auto Response |
| `notes`    | String                        | Any notes about the auto response |

#### SubObject {#type-1071}

Sub-Schema

__Type__ Object

| Name          | Type    | Description                       |
| ------------- | ------- | --------------------------------- |
| `intercept`   | Boolean | [Desc. `intercept`](https://docs.tychron.com/api-reference/schemas/#desc-1066)   |
| `is_wildcard` | Boolean | [Desc. `is_wildcard`](https://docs.tychron.com/api-reference/schemas/#desc-1067) |
| `keyword`     | String  | [Desc. `keyword`](https://docs.tychron.com/api-reference/schemas/#desc-1068)     |
| `message`     | String  | [Desc. `message`](https://docs.tychron.com/api-reference/schemas/#desc-1069)     |
| `message2`    | String  | [Desc. `message2`](https://docs.tychron.com/api-reference/schemas/#desc-1070)    |

#### Desc. `intercept` {#desc-1066}

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` {#desc-1067}

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` {#desc-1068}

The word to trigger this specific keyword.

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

#### Desc. `message` {#desc-1069}

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` {#desc-1070}

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` {#desc-1072}

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



__Example__

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



## Schema / UpsertMessagingAutoResponseRequest {#schema-upsertmessagingautoresponserequest}

Request to create or update an Messaging Auto Response

__Type__ Object

| Name   | Type                                                                       | Description |
| ------ | -------------------------------------------------------------------------- | ----------- |
| `data` | [UpsertMessagingAutoResponseData](https://docs.tychron.com/api-reference/schemas/#schema-upsertmessagingautoresponsedata) |             |
| `type` | String                                                                     |             |



__Example__

```json
{
  "data": {
    "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"
  },
  "type": "messaging_auto_response"
}
```



## Schema / UpsertNumberClientSuspensionData {#schema-upsertnumberclientsuspensiondata}

Parameters for creating a Number Client Suspension

__Type__ Object

| Name              | Type                                               | Description                           |
| ----------------- | -------------------------------------------------- | ------------------------------------- |
| `block_direction` | Enum(`NONE`, `INBOUND`, `OUTBOUND`, `BOTH`):String | [Desc. `block_direction`](https://docs.tychron.com/api-reference/schemas/#desc-1073) |
| `block_messaging` | Enum(`NONE`, `SMS`, `MMS`, `ALL`):String           | [Desc. `block_messaging`](https://docs.tychron.com/api-reference/schemas/#desc-1074) |
| `block_voip`      | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1075):String                          | [Desc. `block_voip`](https://docs.tychron.com/api-reference/schemas/#desc-1076)      |
| `notes`           | String                                             | [Desc. `notes`](https://docs.tychron.com/api-reference/schemas/#desc-1077)           |

#### Desc. `block_direction` {#desc-1073}

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` {#desc-1074}

What type of messaging should be blocked by this suspension?

#### Enum Values block_voip {#enum-1075}

Allowed values

* `NONE`
* `ORIGINATION`
* `TERMINATION`
* `ALL`

#### Desc. `block_voip` {#desc-1076}

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. `notes` {#desc-1077}

Any notes on the suspension.



__Example__

```json
{
  "block_direction": "NONE",
  "block_messaging": "NONE",
  "block_voip": "NONE",
  "notes": "Suspended due to carrier complaint."
}
```



## Schema / UpsertNumberClientSuspensionRequest {#schema-upsertnumberclientsuspensionrequest}

Request for creating a new Number Client Suspension

__Type__ Object

| Name   | Type                                                                         | Description |
| ------ | ---------------------------------------------------------------------------- | ----------- |
| `data` | [UpsertNumberClientSuspensionData](https://docs.tychron.com/api-reference/schemas/#schema-upsertnumberclientsuspensiondata) |             |
| `type` | String                                                                       |             |



__Example__

```json
{
  "data": {
    "block_direction": "NONE",
    "block_messaging": "NONE",
    "block_voip": "NONE",
    "notes": "Suspended due to carrier complaint."
  },
  "type": "number_client_suspension"
}
```



## Schema / UpsertSwitchData {#schema-upsertswitchdata}

Parameters for creating or updating a switch

__Type__ Object

| Name                 | Type                                                  | Description                              |
| -------------------- | ----------------------------------------------------- | ---------------------------------------- |
| `mms_auth_method`    | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `mms_auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-1078)    |
| `mms_data`           | String(format:url)                                    | [Desc. `mms_data`](https://docs.tychron.com/api-reference/schemas/#desc-1079)           |
| `mms_enabled`        | Boolean                                               | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-1080)        |
| `mms_identity`       | String                                                | Acts as the username in basic auth       |
| `mms_message_format` | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1081):String                             | [Desc. `mms_message_format`](https://docs.tychron.com/api-reference/schemas/#desc-1082) |
| `mms_name`           | String                                                | [Desc. `mms_name`](https://docs.tychron.com/api-reference/schemas/#desc-1083)           |
| `mms_options`        | `mms_options`                                         | [Desc. `mms_options`](https://docs.tychron.com/api-reference/schemas/#desc-1084)        |
| `mms_protocol`       | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1085):String                             | [Desc. `mms_protocol`](https://docs.tychron.com/api-reference/schemas/#desc-1086)       |
| `mms_secret`         | String                                                | [Desc. `mms_secret`](https://docs.tychron.com/api-reference/schemas/#desc-1087)         |
| `name`               | String                                                | [Desc. `name`](https://docs.tychron.com/api-reference/schemas/#desc-1088)               |
| `notes`              | String                                                | Any notes about the switch               |
| `sms_auth_method`    | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `sms_auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-1089)    |
| `sms_data`           | String                                                | [Desc. `sms_data`](https://docs.tychron.com/api-reference/schemas/#desc-1090)           |
| `sms_enabled`        | Boolean                                               | [Desc. `sms_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-1091)        |
| `sms_identity`       | String                                                | Acts as the username in basic auth       |
| `sms_message_format` | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1092):String                             | [Desc. `sms_message_format`](https://docs.tychron.com/api-reference/schemas/#desc-1093) |
| `sms_name`           | String                                                | Reserved for future use                  |
| `sms_options`        | `sms_options`                                         | [Desc. `sms_options`](https://docs.tychron.com/api-reference/schemas/#desc-1094)        |
| `sms_protocol`       | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1095):String                             | [Desc. `sms_protocol`](https://docs.tychron.com/api-reference/schemas/#desc-1096)       |
| `sms_secret`         | String                                                | [Desc. `sms_secret`](https://docs.tychron.com/api-reference/schemas/#desc-1097)         |
| `voice_auth_method`  | Enum(`NONE`, `BASIC`, `BEARER`):String                | [Desc. `voice_auth_method`](https://docs.tychron.com/api-reference/schemas/#desc-1098)  |
| `voice_data`         | String                                                | [Desc. `voice_data`](https://docs.tychron.com/api-reference/schemas/#desc-1099)         |
| `voice_enabled`      | Boolean                                               | [Desc. `voice_enabled`](https://docs.tychron.com/api-reference/schemas/#desc-1100)      |
| `voice_identity`     | String                                                |                                          |
| `voice_name`         | String                                                |                                          |
| `voice_protocol`     | [Enum](https://docs.tychron.com/api-reference/schemas/#enum-1101):String                             | [Desc. `voice_protocol`](https://docs.tychron.com/api-reference/schemas/#desc-1102)     |
| `voice_secret`       | String                                                |                                          |

#### Desc. `mms_auth_method` {#desc-1078}

Various authorization methods supported.

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

HTTP supports all available methods.

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

#### Desc. `mms_data` {#desc-1079}

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

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

#### Desc. `mms_enabled` {#desc-1080}

Enable inbound MMS routing?

#### Enum Values mms_message_format {#enum-1081}

Allowed values

* `OXY_JSON_1_0`
* `OXY_JSONAPI_1_0`
* `OXY_XML_1_0`
* `OXY_MULTIPART_1_0`
* `OXY_MULTIPART_2_0`
* `OXY_RFC822_1_0`

#### Desc. `mms_message_format` {#desc-1082}

All supported message formats for MMS HTTP Protocol.

#### Desc. `mms_name` {#desc-1083}

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

#### Desc. `mms_options` {#desc-1084}

Contains various miscelleanous or experimental feature flags for MMS.

#### Enum Values mms_protocol {#enum-1085}

Allowed values

* `NONE`
* `MM4`
* `HTTP`
* `SFTP`
* `FORWARD`
* `TYCHRON_CHAT`

#### Desc. `mms_protocol` {#desc-1086}

All protocols supported for MMS delivery.

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

#### Desc. `mms_secret` {#desc-1087}

Depending on the `auth_method`, this fields usage changes:

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

#### Desc. `name` {#desc-1088}

A display name to easily identify the switch

#### Desc. `sms_auth_method` {#desc-1089}

Various authorization methods supported by the SMS HTTP Protocol.

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

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

#### Desc. `sms_data` {#desc-1090}

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

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

#### Desc. `sms_enabled` {#desc-1091}

Enable inbound SMS routing?

#### Enum Values sms_message_format {#enum-1092}

Allowed values

* `TRINITY_JSON_1_0`
* `TRINITY_POST_1_0`
* `TRINITY_POST_2_0`

#### Desc. `sms_message_format` {#desc-1093}

All supported message formats for SMS HTTP Protocol

#### Desc. `sms_options` {#desc-1094}

Contains various miscelleanous or experimental feature flags for SMS.

#### Enum Values sms_protocol {#enum-1095}

Allowed values

* `NONE`
* `SMPP`
* `HTTP`
* `FORWARD`
* `TYCHRON_CHAT`

#### Desc. `sms_protocol` {#desc-1096}

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

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

#### Desc. `sms_secret` {#desc-1097}

Depending on the `auth_method`, this fields usage changes:

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

#### Desc. `voice_auth_method` {#desc-1098}

Various authorization methods supported.

Primarily used with HTTP ROUTE

#### Desc. `voice_data` {#desc-1099}

Contains the routing url specific to the requested protocol

#### Desc. `voice_enabled` {#desc-1100}

Enable voice call fallback routing?

#### Enum Values voice_protocol {#enum-1101}

Allowed values

* `NONE`
* `VOIP`
* `PSTN`
* `TTS`
* `TTS_CUSTOM`
* `HTTP_ROUTE`

#### Desc. `voice_protocol` {#desc-1102}

All protocols supported for fallback VoIP destination.

__mms_options__

| Name             | Type    | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `dlr_on_sent`    | Boolean | [Desc. `dlr_on_sent`](https://docs.tychron.com/api-reference/schemas/#desc-1103)    |
| `forward_dlr`    | Boolean | [Desc. `forward_dlr`](https://docs.tychron.com/api-reference/schemas/#desc-1104)    |
| `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](https://docs.tychron.com/api-reference/schemas/#desc-1105) |

#### Desc. `dlr_on_sent` {#desc-1103}

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

#### Desc. `forward_dlr` {#desc-1104}

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

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

#### Desc. `pad_shortcodes` {#desc-1105}

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



__sms_options__

| Name             | Type    | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `dlr_on_sent`    | Boolean | [Desc. `dlr_on_sent`](https://docs.tychron.com/api-reference/schemas/#desc-1106)    |
| `forward_dlr`    | Boolean | [Desc. `forward_dlr`](https://docs.tychron.com/api-reference/schemas/#desc-1107)    |
| `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](https://docs.tychron.com/api-reference/schemas/#desc-1108) |

#### Desc. `dlr_on_sent` {#desc-1106}

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

#### Desc. `forward_dlr` {#desc-1107}

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

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

#### Desc. `pad_shortcodes` {#desc-1108}

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



__Example__

```json
{
  "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": "12003004000@example.com",
  "voice_enabled": false,
  "voice_identity": "johndoe",
  "voice_name": "John Doe",
  "voice_protocol": "NONE",
  "voice_secret": "super$ecret"
}
```



## Schema / User {#schema-user}

A user is any agent that can interact with impersonated or portal APIs


__Type__ Object

| Name          | Type                     | Description                      |
| ------------- | ------------------------ | -------------------------------- |
| `address`     | `address`                | [Desc. `address`](https://docs.tychron.com/api-reference/schemas/#desc-1109)    |
| `email`       | String(format:email)     | [Desc. `email`](https://docs.tychron.com/api-reference/schemas/#desc-1110)      |
| `first_name`  | String                   | [Desc. `first_name`](https://docs.tychron.com/api-reference/schemas/#desc-1111) |
| `id`          | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-1112)         |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp   |
| `last_name`   | String                   | [Desc. `last_name`](https://docs.tychron.com/api-reference/schemas/#desc-1113)  |
| `title`       | String                   | [Desc. `title`](https://docs.tychron.com/api-reference/schemas/#desc-1114)      |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp   |

#### Desc. `address` {#desc-1109}

User Address details, may differ from top-level details

#### Desc. `email` {#desc-1110}

User's email

#### Desc. `first_name` {#desc-1111}

User's first name

#### Desc. `id` {#desc-1112}

A Universally unique identifier, which identifies the resource

#### Desc. `last_name` {#desc-1113}

User's last name

#### Desc. `title` {#desc-1114}

User's job title, or position

__address__

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `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 |             |



__Example__

```json
{
  "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": "john.doe@example.com",
  "first_name": "John",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "last_name": "Doe",
  "title": "Operator",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / UserResponse {#schema-userresponse}

Response when retrieving user information

__Type__ Object

| Name   | Type                 | Description |
| ------ | -------------------- | ----------- |
| `data` | [User](https://docs.tychron.com/api-reference/schemas/#schema-user) |             |
| `type` | String               |             |



__Example__

```json
{
  "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": "john.doe@example.com",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}
```



## Schema / UsersResponse {#schema-usersresponse}

Users

__Type__ Object

| Name        | Type                                       | Description |
| ----------- | ------------------------------------------ | ----------- |
| `count`     | Integer                                    |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)               |             |
| `results`   | Array:[UserResponse](https://docs.tychron.com/api-reference/schemas/#schema-userresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "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": "john.doe@example.com",
        "first_name": "John",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "last_name": "Doe",
        "title": "Operator",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "user"
    }
  ]
}
```



## Schema / Voice {#schema-voice}

A TTS Voice is used to denote how the speaker sounds, this affects the gender and language.


__Type__ Object

| Name            | Type                     | Description                       |
| --------------- | ------------------------ | --------------------------------- |
| `accent_code`   | String                   | [Desc. `accent_code`](https://docs.tychron.com/api-reference/schemas/#desc-1115) |
| `id`            | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-1116)          |
| `inserted_at`   | String(format:date-time) | An ISO8601 formatted timestamp    |
| `language_code` | String                   | The language of the voice         |
| `name`          | String(1..255)           | Name of the TTS Voice             |

#### Desc. `accent_code` {#desc-1115}

Any specialized variant or dialect of the language

#### Desc. `id` {#desc-1116}

A Universally unique identifier, which identifies the resource



__Example__

```json
{
  "accent_code": "us",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "language_code": "en",
  "name": "John Doe (en-US)"
}
```



## Schema / VoiceResponse {#schema-voiceresponse}

Single voice

__Type__ Object

| Name   | Type                   | Description |
| ------ | ---------------------- | ----------- |
| `data` | [Voice](https://docs.tychron.com/api-reference/schemas/#schema-voice) |             |
| `type` | String                 |             |



__Example__

```json
{
  "data": {
    "accent_code": "us",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "language_code": "en",
    "name": "John Doe (en-US)"
  },
  "type": "tts_voice"
}
```



## Schema / VoicesResponse {#schema-voicesresponse}

Voices

__Type__ Object

| Name        | Type                                         | Description |
| ----------- | -------------------------------------------- | ----------- |
| `count`     | Integer                                      |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                 |             |
| `results`   | Array:[VoiceResponse](https://docs.tychron.com/api-reference/schemas/#schema-voiceresponse) |             |



__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "accent_code": "us",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "language_code": "en",
        "name": "John Doe (en-US)"
      },
      "type": "tts_voice"
    }
  ]
}
```



## Schema / CreateVoipAllowedClientIpData {#schema-createvoipallowedclientipdata}

Parameters for updating an allowed client ip

__Type__ Object

| Name      | Type              | Description                              |
| --------- | ----------------- | ---------------------------------------- |
| `address` | String(format:ip) | The IP Address that should be allowed    |
| `name`    | String            | A display name for the Allowed Client IP |
| `notes`   | String            | Any notes on the Allowed Client IP       |


__Example__

```json
{
  "address": "203.0.113.10",
  "name": "string",
  "notes": "string"
}
```



## Schema / CreateVoipAllowedClientIpRequest {#schema-createvoipallowedclientiprequest}

Request for update an existing Allowed Client IP

__Type__ Object

| Name   | Type                                                                   | Description |
| ------ | ---------------------------------------------------------------------- | ----------- |
| `data` | [CreateVoipAllowedClientIpData](https://docs.tychron.com/api-reference/schemas/#schema-createvoipallowedclientipdata) |             |
| `type` | String                                                                 |             |


__Example__

```json
{
  "data": {
    "address": "203.0.113.10",
    "name": "string",
    "notes": "string"
  },
  "type": "voip_allowed_client_ip"
}
```



## Schema / UpdateVoipAllowedClientIpData {#schema-updatevoipallowedclientipdata}

Parameters for updating an allowed client ip

__Type__ Object

| Name    | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| `name`  | String | A display name for the Allowed Client IP |
| `notes` | String | Any notes on the Allowed Client IP       |


__Example__

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



## Schema / UpdateVoipAllowedClientIpRequest {#schema-updatevoipallowedclientiprequest}

Request for update an existing Allowed Client IP

__Type__ Object

| Name   | Type                                                                   | Description |
| ------ | ---------------------------------------------------------------------- | ----------- |
| `data` | [UpdateVoipAllowedClientIpData](https://docs.tychron.com/api-reference/schemas/#schema-updatevoipallowedclientipdata) |             |
| `type` | String                                                                 |             |


__Example__

```json
{
  "data": {
    "name": "string",
    "notes": "string"
  },
  "type": "voip_allowed_client_ip"
}
```



## Schema / VoipAllowedClientIp {#schema-voipallowedclientip}

VoipAllowedClientIp

__Type__ Object

| Name          | Type                     | Description                    |
| ------------- | ------------------------ | ------------------------------ |
| `address`     | String(format:ip)        | [Desc. `address`](https://docs.tychron.com/api-reference/schemas/#desc-1117)  |
| `id`          | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/schemas/#desc-1118)       |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp |
| `name`        | String(1..64)            | Any friendly name for the      |
| `notes`       | String(0..65535)         | Any notes about the IP.        |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp |

#### Desc. `address` {#desc-1117}

The IP Address that should be allowed to originate VoIP traffic. Note. This must be unique, if you encounter issues with loading an IP, please contact support for assistance.

#### Desc. `id` {#desc-1118}

A Universally unique identifier, which identifies the resource


__Example__

```json
{
  "address": "203.0.113.10",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "US ACME Call Relay",
  "notes": "US ACME Call Relay Service",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```



## Schema / VoipAllowedClientIpResponse {#schema-voipallowedclientipresponse}

Single Allowed Client IP

__Type__ Object

| Name   | Type                                               | Description |
| ------ | -------------------------------------------------- | ----------- |
| `data` | [VoipAllowedClientIp](https://docs.tychron.com/api-reference/schemas/#schema-voipallowedclientip) |             |
| `type` | String                                             |             |


__Example__

```json
{
  "data": {
    "address": "203.0.113.10",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "US ACME Call Relay",
    "notes": "US ACME Call Relay Service",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "voip_allowed_client_ip"
}
```



## Schema / VoipAllowedClientIpsResponse {#schema-voipallowedclientipsresponse}

Allowed Client IPs

__Type__ Object

| Name        | Type                                                                     | Description |
| ----------- | ------------------------------------------------------------------------ | ----------- |
| `count`     | Integer                                                                  |             |
| `page_info` | [PageInfo](https://docs.tychron.com/api-reference/schemas/#schema-pageinfo)                                             |             |
| `results`   | Array:[VoipAllowedClientIpResponse](https://docs.tychron.com/api-reference/schemas/#schema-voipallowedclientipresponse) |             |


__Example__

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "address": "203.0.113.10",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "US ACME Call Relay",
        "notes": "US ACME Call Relay Service",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "voip_allowed_client_ip"
    }
  ]
}
```



## Schema / CDRType {#schema-cdrtype}

The main category that the CDR belongs to. * `API` - API associated CDRs, such as LRN, MCL, CNAM etc... * `MMS` - MMS CDRs for inbound and outbound messages. * `SMS` - SMS CDRs for inbound and outbound messages. * `VOICE` - Voice or VoIP CDRs. * `BALANCE` - CDRs for direct balance changes * `MISC` - For infrequent charges or those that don't fit neatly into larger categories. * `BYO` - Special case VoIP services CDRs.

__Type__ Enum:String

* `API`
* `MMS`
* `SMS`
* `VOICE`
* `BALANCE`
* `MISC`
* `BYO`


__Example__

```json
"API"
```



## Schema / NumberId {#schema-numberid}

Number ID. Routes that take a number id will typically allow its UUID or it's digits.

__Type__ Object

| Name | Type | Description |
| ---- | ---- | ----------- |


__Example__

```json
null
```

---

Previous chapter: https://docs.tychron.com/api-reference/smpp.md  
Next chapter: https://docs.tychron.com/api-reference/end-notes.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt