# Atlas API & Provisioning Reference (complete) > Tychron Atlas API & Provisioning Reference — all 35 chapters in one file, for AI assistants and coding agents. > 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 # Introduction __Date__ 2026-08-12 __Status__ Public Greetings and Salutations, you, the "client" are reading this document in an effort to connect with Tychron via the available APIs and channels henceforth referred to as the "system", or to understand processes that Tychron has. This document should be considered a companion document to the publicly available documentation: * [Tychron Docs](https://docs.tychron.com/) * [API Reference](https://api.atlas.tychron.online/api/v1/swaggerui) The Tychron Docs provides information on the publicly available APIs, it only houses more mainline features: SMS, MMS, CNAM, LRN/E and Messaging Carrier Lookup (MCL). The API Reference page with the Open API document shows the availability of the management and provisioning APIs, however it does not contain usage examples, neither the order in which API calls should be made for certain processes. This document covers the processes and examples of using those APIs. If after reading this document, you are still unclear of how to complete an action, do not be afraid to contact Tychron Support for further support. __Note__ The information provided in this document is subject to change in a non-breaking manner, it may include additional information or corrections, but fundamental functionality shall remain similar. # Your Resources Before you continue charging ahead and start implementing parts of the API in your own applications, it's best to understand what each `resource` is and their purpose in the overall system. ## Account At the top of the resources is the *Account*. The account contains all the information about your company, business or entity, as well as your billing information. The Account will then parent all other resources. ## DID The DID is a phone number or sender ID provisioned in the system for various telecom services. A DID may be simply referred to as a 'Number'. ## Switch The Switch is a routing record used by the system to determine where: * Incoming SMS Messages should be delivered, format, and any additional authorization * Incoming MMS Messages should be delivered, format, and any additional authorization * Fallback destination for incoming Voice calls As one may notice, the switch handles *inbound*, or *incoming* actions only. Outbound routing is handled by various internal systems and is beyond the scope of this document. ## Messaging Auto Responses Messaging Auto Responses, sometimes just referred to as Auto Responses, or Auto Responders are user defined keyword plans. You, the user can create an auto resposne with one or more keywords, when an inbound message is received, it will be checked against the auto response to determine if a reply can or should be generated. Note. If your account was assigned a keyword plan, an auto response can be used to customize the network-level responses generated (while keeping the same functionality). If the keyword plan contains a STOP keyword, and the auto response contains a STOP keyword, the latter's messages will be used. ## Role A role is a collection of permissions that a user may have. ## User A user or agent is an entity that has a `Role` which affects their permission to access some resources. Note that some APIs do not require a user and its permissions will be affected by the account's settings instead. ## API Key An API Key is the token and or auth required to access any of Tychron's APIs, there are two types of API Keys: * Standard API Keys * Impersonated API Keys ### Standard API Keys Standard API Keys are those that can be used for SMS, MMS, LRN and CNAM services, as these services do not require additional permissions outside of those set on the account. ### Impersonated API Keys Impersonated API Keys are those that perform actions on behalf of a user, such as requesting messaging for a set of numbers, or disconnecting a number from service. Impersonated keys are required to access most `/api/v1` routes outside of LRN and CNAM and some select routes. ## Bulk Dip Tasks __Note__ Experimental A new feature, the bulk dip tasks allows you to request a specific dipping action for up to 20000 numbers at a time, you can create as many tasks as you wish. Please note, standard dipping rates apply, going over your account's balance will return errors for all subsequent rows in the task. ## CSP CSP Resources are records from the [TCR](https://www.campaignregistry.com/). If you have any questions about TCR related issues or services, please contact support. ### CSP Brands A brand describes business entity that will be running messaging campaigns. The brand by itself does nothing, you must create campaigns in order to make use of it. There can be multiple brands bound to the account. ### CSP Campaigns A campaign describes a specific messaging case, such as sending notices or notifications to a client when something happens. There can be multiple campaigns under the same brand, normally for different use cases. ## Shared Resource Groups Shared Resource Groups allow donating resources (currently only CSP Campaigns) to other accounts for usage as if it were their own. This is used to allow another account to utilize a resource that is owned by the account without requiring the donee (i.e. the account that is being donated to) to manage that resource. Contact support for more information if you require shared resources. # API ## Pagination Parameters Pagination is based on a cursor, rather than a offset. `after` and `before` are the cursor values, while `first` and `last` control how many records should be returned. If the first 20 records are needed for example, only the `first` parameter needs to be provided. | Name | Type | Description | | -------- | --------- | ------------------------------------------------------ | | `first` | `Integer` | How many records should be returned after the cursors | | `last` | `Integer` | How many records should be returned before the cursors | | `after` | `String` | The pagination cursor, taken from the page_info.last | | `before` | `String` | The pagination cursor taken from the page_info.first | | `query` | `String` | A query string to filter the records by. | Note that routes that use pagination, will require at least `first` or `last` to be specified. The cursor values can be obtained from the document returned by those APIs under its paginat The pagination works in pairs: * `first` and `after` * `last` and `before` Specifying both `first` and `last` at the same time will result in an error, or undesired behaviour. `query` varies by resource, see their respective sections on the expected values. ## Common Parameters All management APIs have a similar root structure, where the document contains a `data` field and `type` field on request. Depending on the resource being handled the type and data changes accordingly. __RequestDocument__ ```json { "data": {}, "type": "document_type" } ``` | Name | Type | Description | | -------- | -------------- | -------------------------------------------------------------------------------- | | `data` * | `T` | Depends on the resource, each resource section will specify their data structure | | `type` * | `DocumentType` | Depends on the resource, each resource has its own type | Request documents are used when performing a request to the API, these are normally associated with `POST`, `PATCH`, and `PUT` routes. __ResponseDetailDocument__ ```json { "data": {}, "type": "document_type" } ``` | Name | Type | Description | | -------- | -------------- | ----------------------- | | `data` * | `T` | Depends on the resource | | `type` * | `DocumentType` | Depends on the resource | Resposne Detail documents are returned whenver a single resource is needed or modified. __ResponseIndexDocument__ ```json { "results": [], "count": 0, "page_info": { "first": "", "last": "", "has_next_page": false, "has_previous_page": false } } ``` | Name | Type | Description | | ------------- | ---------------------------------- | ------------------------------------------ | | `results` * | `Array>` | A list of detail documents with their type | | `count` * | `Integer` | How many records are in the results? | | `page_info` * | `PageInfo` | Contains pagination information | Response Index documents are returned from index routes (i.e. `GET /api/v1/:resource`) __PageInfo__ ```json { "first": "", "last": "", "has_next_page": false, "has_previous_page": false } ``` | Name | Type | Description | | ------------------- | --------- | ------------------------------------- | | `first` | `String` | Cursor of the first record on this page; pass it as `before` to fetch the previous page | | `last` | `String` | Cursor of the last record on this page; pass it as `after` to fetch the next page | | `has_next_page` | `Boolean` | Is there another page after this one? | | `has_previous_page` | `Boolean` | Is there a page before this one? | Page Info is an object that contains any additional pagination information from an index request. `first` and `last` are the individual cursors and should not be confused with the `first` and `last` pagination values (i.e. page size). `has_next_page` and `has_previous_page` are convenience fields that denote whether or not there are any more pages in either direction. For example, fetching the first 20 DIDs, if the account has more dids, then `has_next_page` will be true and the `last` cursor will be populated. To get to the next page, simple change the pagination parameters accordingly: ```javascript if (page_info.has_next_page) { let after = page_info.last; fetch_more({ after, first: 20, }); } ``` ## Paths The following are all the available paths, note that some may not be covered in this document. * `GET|POST /api/v1/api_keys` * `GET /api/v1/api_keys/{api_key_id}/switches` * `DELETE|GET|PATCH|PUT /api/v1/api_keys/{id}` * `GET|POST /api/v1/auto_responses` * `DELETE|GET|PATCH|PUT /api/v1/auto_responses/{id}` * `GET /api/v1/brands` * `GET /api/v1/brands/{id}` * `GET|POST /api/v1/bulk_dip_tasks` * `GET /api/v1/bulk_dip_tasks/{id}` * `GET|POST /api/v1/call_data_webhooks` * `DELETE|GET|PATCH|PUT /api/v1/call_data_webhooks/{id}` * `GET /api/v1/campaign_optout_items` * `DELETE|GET /api/v1/campaign_optout_items/{id}` * `GET /api/v1/campaigns` * `POST /api/v1/campaigns/{campaign_id}/share_with/accounts/{account_id}` * `POST /api/v1/campaigns/{campaign_id}/share_with/shared_resource_groups/{shared_resource_group_id}` * `DELETE|GET /api/v1/campaigns/{campaign_id}/shared_resource_group` * `GET /api/v1/campaigns/{id}` * `GET|POST /api/v1/carts` * `POST /api/v1/carts/{cart_id}/checkout` * `GET|POST /api/v1/carts/{cart_id}/requests` * `DELETE|GET|PATCH|PUT /api/v1/carts/{cart_id}/requests/{id}` * `GET|POST /api/v1/carts/{cart_id}/requests/{request_id}/documents` * `GET /api/v1/carts/{cart_id}/requests/{request_id}/documents/{document_id}/download` * `DELETE|GET /api/v1/carts/{cart_id}/requests/{request_id}/documents/{id}` * `DELETE|GET|PATCH|PUT /api/v1/carts/{id}` * `GET|POST /api/v1/cdr_export_tasks` * `DELETE|GET /api/v1/cdr_export_tasks/{id}` * `GET /api/v1/cdrs` * `GET /api/v1/cdrs/{cdr_id}/result` * `GET /api/v1/cdrs/{id}` * `GET /api/v1/cdrs_by_type/{type}` * `GET /api/v1/csp/enum/alt_business_id_types` * `GET /api/v1/csp/enum/brand_relationships` * `GET /api/v1/csp/enum/campaign_statuses` * `GET /api/v1/csp/enum/cnps` * `GET /api/v1/csp/enum/dcas` * `GET /api/v1/csp/enum/entity_types` * `GET /api/v1/csp/enum/error_codes` * `GET /api/v1/csp/enum/event_categories` * `GET /api/v1/csp/enum/mno_operation_statuses` * `GET /api/v1/csp/enum/mnos` * `GET /api/v1/csp/enum/stock_exchanges` * `GET /api/v1/csp/enum/sub_usecases` * `GET /api/v1/csp/enum/usecases` * `GET /api/v1/csp/enum/verticals` * `GET /api/v1/csp/enum/vetting_classes` * `GET /api/v1/csp/enum/vetting_feedback_codes` * `GET /api/v1/csp/enum/vetting_providers` * `GET|POST /api/v1/event_subscriptions` * `DELETE|GET|PATCH|PUT /api/v1/event_subscriptions/{id}` * `GET /api/v1/number_client_suspensions` * `DELETE|GET|PATCH|PUT /api/v1/number_client_suspensions/{id}` * `GET /api/v1/number_inventory/{type}/coverage` * `GET /api/v1/number_inventory/{type}/numbers` * `GET /api/v1/numbers` * `GET|PATCH|PUT /api/v1/numbers/{id}` * `GET /api/v1/numbers/{number_id}/api_keys` * `DELETE|POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind` * `POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/unbind` * `GET /api/v1/numbers/{number_id}/api_keys/{id}` * `DELETE|GET /api/v1/numbers/{number_id}/auto_response` * `PUT /api/v1/numbers/{number_id}/auto_response/{id}` * `GET /api/v1/numbers/{number_id}/campaign` * `GET|POST /api/v1/numbers/{number_id}/client_suspensions` * `GET|POST /api/v1/numbers/{number_id}/destinations` * `DELETE|GET|PATCH|PUT /api/v1/numbers/{number_id}/destinations/{id}` * `DELETE|GET /api/v1/numbers/{number_id}/messaging_switch` * `PUT /api/v1/numbers/{number_id}/messaging_switch/{id}` * `GET|POST /api/v1/numbers/{number_id}/optout_items` * `DELETE|GET /api/v1/numbers/{number_id}/voice_switch` * `PUT /api/v1/numbers/{number_id}/voice_switch/{id}` * `GET /api/v1/optout_items` * `DELETE|GET /api/v1/optout_items/{id}` * `GET /api/v1/orders` * `GET|PATCH|PUT /api/v1/orders/{id}` * `GET /api/v1/orders/{order_id}/requests` * `GET /api/v1/osr/overwrite_requests` * `GET /api/v1/osr/overwrite_requests/{id}` * `POST /api/v1/osr/overwrite_requests/{overwrite_request_id}/review` * `GET /api/v1/provision_records` * `GET /api/v1/provision_records/{id}` * `GET /api/v1/requests` * `GET|PATCH|PUT /api/v1/requests/{id}` * `GET|POST /api/v1/requests/{request_id}/documents` * `GET /api/v1/requests/{request_id}/documents/{document_id}/download` * `DELETE|GET /api/v1/requests/{request_id}/documents/{id}` * `GET /api/v1/requests/{request_id}/provision_records` * `GET /api/v1/role_policies` * `GET|POST /api/v1/roles` * `DELETE|GET|PATCH|PUT /api/v1/roles/{id}` * `GET|POST /api/v1/secret_keys` * `DELETE|GET|PATCH|PUT /api/v1/secret_keys/{id}` * `GET /api/v1/secret_keys/{secret_key_id}/mms_encrypted_switches` * `GET /api/v1/secret_keys/{secret_key_id}/mms_signed_switches` * `GET /api/v1/secret_keys/{secret_key_id}/sms_encrypted_switches` * `GET /api/v1/secret_keys/{secret_key_id}/sms_signed_switches` * `GET /api/v1/shared_resource_groups` * `GET /api/v1/shared_resource_groups/{id}` * `GET|POST /api/v1/switches` * `DELETE|GET|PATCH|PUT /api/v1/switches/{id}` * `DELETE|GET /api/v1/switches/{switch_id}/api_key` * `PUT /api/v1/switches/{switch_id}/api_key/{id}` * `DELETE|GET /api/v1/switches/{switch_id}/mms_encryption_key` * `PUT /api/v1/switches/{switch_id}/mms_encryption_key/{id}` * `DELETE|GET /api/v1/switches/{switch_id}/mms_signing_key` * `PUT /api/v1/switches/{switch_id}/mms_signing_key/{id}` * `DELETE|GET /api/v1/switches/{switch_id}/sms_encryption_key` * `PUT /api/v1/switches/{switch_id}/sms_encryption_key/{id}` * `DELETE|GET /api/v1/switches/{switch_id}/sms_signing_key` * `PUT /api/v1/switches/{switch_id}/sms_signing_key/{id}` * `GET|POST /api/v1/tts/message_sets` * `DELETE|GET|PATCH|PUT /api/v1/tts/message_sets/{id}` * `GET|POST /api/v1/tts/message_sets/{message_set_id}/messages` * `DELETE|GET|PATCH|PUT /api/v1/tts/message_sets/{message_set_id}/messages/{id}` * `GET /api/v1/tts/voices` * `GET /api/v1/tts/voices/{id}` * `GET|POST /api/v1/users` * `DELETE|GET|PATCH|PUT /api/v1/users/{id}` * `GET /api/v1/users/{user_id}/role` * `GET|POST /api/v1/voip/allowed_client_ips` * `DELETE|GET /api/v1/voip/allowed_client_ips/{allowed_client_ip_id}/api_key` * `PUT /api/v1/voip/allowed_client_ips/{allowed_client_ip_id}/api_key/{id}` * `DELETE|GET|PATCH|PUT /api/v1/voip/allowed_client_ips/{id}` * `GET|POST /api/v1/voip/tts/message_sets` * `DELETE|GET|PATCH|PUT /api/v1/voip/tts/message_sets/{id}` * `GET|POST /api/v1/voip/tts/message_sets/{message_set_id}/messages` * `DELETE|GET|PATCH|PUT /api/v1/voip/tts/message_sets/{message_set_id}/messages/{id}` * `GET /api/v1/voip/tts/voices` * `GET /api/v1/voip/tts/voices/{id}` # Number Inventory ### Coverage ```http GET /api/v1/number_inventory/{type}/coverage HTTP/1.1 ``` Searches inventory coverage. __Path Parameters__ | Name | Type | Description | | ---- | ---------------------------------- | ------------------------- | | type | Enum(`TENDLC`, `TOLLFREE`):String! | Either TENDLC or TOLLFREE | __Query Parameters__ | Name | Type | Description | | ----------- | ---------------------- | ---------------------------------- | | npa | String | [Query Desc. npa](#desc-1) | | nxx | String | [Query Desc. nxx](#desc-2) | | state | String | [Query Desc. state](#desc-3) | | rate_center | String | [Query Desc. rate_center](#desc-4) | | count_by | [Enum](#enum-5):String | [Query Desc. count_by](#desc-6) | #### Query Desc. npa {#desc-1} A simplified format of the pattern, where only the NPA (Area Code) is provided. This field can be used in conjuction with the `nxx` field to form a NPANXX pattern internally. #### Query Desc. nxx {#desc-2} A simplified format of the pattern, where only the NXX (Exchange Code) is provided. This field can be used in conjuction with the `npa` field to form a NPANXX pattern internally. #### Query Desc. state {#desc-3} A state code used to filter on, it can be used in conjuction with rate_center typically. #### Query Desc. rate_center {#desc-4} A rate center's code used to filter the coverage. #### Enum Values count_by {#enum-5} Allowed values * `STATE` * `RATE_CENTER` * `NPA_NXX` * `BLOCK` #### Query Desc. count_by {#desc-6} What should the coverage group its results by, the default is NPA_NXX. #### Request ```http GET /api/v1/number_inventory/{type}/coverage HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 453 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` # Ordering System Reference This section will give a further explantation on Tychron's ordering APIs and provides examples of how to request numbers for messaging and other features. ## Ordering Overview The client is expected to make several HTTP requests to the system in order to request provisioning numbers for messaging or to setup TCR campaigns on existing numbers. A general overview of the workflow would be the following: * `POST /api/v1/carts` once * `POST /api/v1/carts/:cart_id/requests` one or more times * `POST /api/v1/carts/:cart_id/checkout` once per cart The ordering system is based around the concept of carts. A cart is an order before checkout, within that cart are various requests that can be made (e.g. enable this number for CNAM, enable this number for messaging, remove this number, etc...), an order can contain multiple requests, and some requests allow multiple numbers within them to perform batch processing. __WARNING__ A request with multiple numbers is treated as a single unit for processing, each stage in the processing of a request will wait for the completion of **all** numbers, if a number in the batch experiences any difficulties (e.g. upstream conflicts with registry) it may stall the entire enablement until it is resolved, therefore it is recommended for critical numbers a request with only that number is issued, for non-critical numbers batching is recommended. When in doubt, use a single number per request. Requests are processed asynchronously, therefore checkout will return immediately with the order id (which will be the same as the cart, as it is the same record just being transitioned to a new state). ## Carts At the very start of a new request process a new cart **must** be created (or if one was created before, it can be used instead). ### Type The type string for carts is `cart` ### Data Structures __RequestData__ ```json { "name": "A unique name", "notes": "Optional notes" } ``` | Name | Type | Description | | -------- | -------- | ----------------------------- | | `name` * | `String` | A unique name for the cart | | `notes` | `String` | Optional notes about the cart | For creating or updating an existing cart, only the `name` and `notes` can be supplied. __ResponseData__ ```json { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "An unique order name", "notes": "Optional notes, describing what this order is for", "updated_at": "2021-08-04T10:00:00.000000Z" } ``` | Name | Type | Description | | --------------- | ---------- | --------------------------------------------------------------------------- | | `id` * | `ULID` | A unique identfier for the cart | | `inserted_at` * | `Datetime` | An ISO8601 formatted timestamp, representing when the cart was created | | `updated_at` * | `Datetime` | An ISO8601 formatted timestamp, representing when the cart was last updated | | `name` * | `String` | A unique name for the cart | | `notes` | `String` | Optional notes about the cart | ### Creating A New Cart ```http POST /api/v1/carts HTTP/1.1 ``` Create a new cart #### Request application/json ```http POST /api/v1/carts HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 81 ``` ```json { "data": { "name": "string", "notes": "string" }, "type": "cart" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 226 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Updating An Existing Cart ```http PATCH /api/v1/carts/{id} HTTP/1.1 ``` Update an existing account __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:ulid)! | Cart ID | #### Request application/json ```http PATCH /api/v1/carts/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 81 ``` ```json { "data": { "name": "string", "notes": "string" }, "type": "cart" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 226 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Deleting An Existing Cart ```http DELETE /api/v1/carts/{id} HTTP/1.1 ``` Delete an existing cart, if the cart contains any requests this action will fail, if the purge flag is provided the cart will be deleted along with all of its requests. The default action is to prevent accidental deletions with requests present. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:ulid)! | Cart ID | __Query Parameters__ | Name | Type | Description | | ----- | ------- | ---------------------------- | | purge | Boolean | [Query Desc. purge](#desc-7) | #### Query Desc. purge {#desc-7} Typically a Cart cannot be removed if it has any requests still associated with it. With the purge option, the cart and its associated requests can all be removed at once. #### Request ```http DELETE /api/v1/carts/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 226 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Checkout Cart ```http POST /api/v1/carts/{cart_id}/checkout HTTP/1.1 ``` Finalize a given cart and process it as an order, the cart and its requests can no longer be modified after this. __Path Parameters__ | Name | Type | Description | | ------- | -------------------- | ----------- | | cart_id | String(format:ulid)! | Cart ID | #### Request ```http POST /api/v1/carts/{cart_id}/checkout HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 303 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Existing Carts ```http GET /api/v1/carts HTTP/1.1 ``` Retrieve a list of carts __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------ | | first | Integer | [Query Desc. first](#desc-8) | | last | Integer | [Query Desc. last](#desc-9) | | after | String | [Query Desc. after](#desc-10) | | before | String | [Query Desc. before](#desc-11) | #### Query Desc. first {#desc-8} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-9} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-10} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-11} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/carts HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 427 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Cart ```http GET /api/v1/carts/{id} HTTP/1.1 ``` Lookup cart by id __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:ulid)! | Cart ID | #### Request ```http GET /api/v1/carts/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 226 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Cart Requests Requests for carts, these are the same as normal Requests, but are designated by a special status. ## Schema A request being prepared in a cart __Type__ Object | Name | Type | Description | | ------------- | ---------------------------------- | ------------------------------ | | `id` | String(format:ulid) | [Desc. `id`](#desc-12) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String | | | `notes` | String | | | `type` | [RequestType](#schema-requesttype) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `*` | [One-Of](#type-13) | | #### Desc. `id` {#desc-12} Another format for UUID, used primarily for tasks, requests and messages. #### One-Of {#type-13} Types * [CartRequestAddCampaignNumbersData](#schema-cartrequestaddcampaignnumbersdata) * [CartRequestAddMessagingNumbersData](#schema-cartrequestaddmessagingnumbersdata) * [CartRequestAddVoiceNumbersData](#schema-cartrequestaddvoicenumbersdata) * [CartRequestNewNumbersData](#schema-cartrequestnewnumbersdata) * [CartRequestRegisterBrandData](#schema-cartrequestregisterbranddata) * [CartRequestRegisterCampaignData](#schema-cartrequestregistercampaigndata) * [CartRequestRemoveCampaignNumbersData](#schema-cartrequestremovecampaignnumbersdata) * [CartRequestRemoveMessagingNumbersData](#schema-cartrequestremovemessagingnumbersdata) * [CartRequestRemoveNumbersData](#schema-cartrequestremovenumbersdata) * [CartRequestRemoveVoiceNumbersData](#schema-cartrequestremovevoicenumbersdata) * [CartRequestUnregisterBrandData](#schema-cartrequestunregisterbranddata) * [CartRequestUnregisterCampaignData](#schema-cartrequestunregistercampaigndata) * [CartRequestVetBrandData](#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" } } } ``` ## API ### Creating A New Cart's Request ```http POST /api/v1/carts/{cart_id}/requests HTTP/1.1 ``` Create a new request under the specified Cart __Path Parameters__ | Name | Type | Description | | ------- | -------------------- | ------------------------------ | | cart_id | String(format:ulid)! | [Path Desc. cart_id](#desc-14) | #### Path Desc. cart_id {#desc-14} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request application/json ```http POST /api/v1/carts/{cart_id}/requests HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 294 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 385 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Updating An Existing Cart's Request ```http PATCH /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1 ``` Update an existing cart request given the Cart ID and Request ID __Path Parameters__ | Name | Type | Description | | ------- | -------------------- | ------------------------------ | | cart_id | String(format:ulid)! | [Path Desc. cart_id](#desc-15) | | id | String(format:ulid)! | [Path Desc. id](#desc-16) | #### Path Desc. cart_id {#desc-15} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Path Desc. id {#desc-16} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request application/json ```http PATCH /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 210 ``` ```json { "data": { "name": "string", "notes": "string", "*": { "numbers": [ "12003004000" ], "*": { "tcr_campaign_id": "C000000" } } }, "type": "request" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 385 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Deleting An Existing Cart's Request ```http DELETE /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1 ``` Delete an existing request under the specified Cart __Path Parameters__ | Name | Type | Description | | ------- | -------------------- | ------------------------------ | | cart_id | String(format:ulid)! | [Path Desc. cart_id](#desc-17) | | id | String(format:ulid)! | [Path Desc. id](#desc-18) | #### Path Desc. cart_id {#desc-17} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Path Desc. id {#desc-18} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request ```http DELETE /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 385 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Existing Cart's Requests ```http GET /api/v1/carts/{cart_id}/requests HTTP/1.1 ``` Retrieve a list of requests under the specified Cart __Path Parameters__ | Name | Type | Description | | ------- | -------------------- | ------------------------------ | | cart_id | String(format:ulid)! | [Path Desc. cart_id](#desc-19) | __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------ | | first | Integer | [Query Desc. first](#desc-20) | | last | Integer | [Query Desc. last](#desc-21) | | after | String | [Query Desc. after](#desc-22) | | before | String | [Query Desc. before](#desc-23) | #### Path Desc. cart_id {#desc-19} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Query Desc. first {#desc-20} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-21} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-22} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-23} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/carts/{cart_id}/requests HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 622 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Cart's Request ```http GET /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1 ``` Retrieve a cart's request by ID __Path Parameters__ | Name | Type | Description | | ------- | -------------------- | ------------------------------ | | cart_id | String(format:ulid)! | [Path Desc. cart_id](#desc-24) | | id | String(format:ulid)! | [Path Desc. id](#desc-25) | #### Path Desc. cart_id {#desc-24} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Path Desc. id {#desc-25} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request ```http GET /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 385 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ## Request Types Requests have many subtypes which determine what kind of action will be taken, this can range from adding messaging-only numbers to removing existing numbers or just some of their components. ### New Numbers Request new numbers from inventory. #### Parameters Request for acquiring new numbers. __Type__ Object | Name | Type | Description | | -------------- | ----------------------------------------- | -------------------------------- | | `addons` | [AddonsData](#schema-addonsdata) | | | `city` | String | | | `min_quantity` | String | [Desc. `min_quantity`](#desc-26) | | `npa` | String | [Desc. `npa`](#desc-27) | | `number_type` | Enum(`NONE`, `TENDLC`, `TOLLFREE`):String | [Desc. `number_type`](#desc-28) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-29) | | `nxx` | String | [Desc. `nxx`](#desc-30) | | `quantity` | String | [Desc. `quantity`](#desc-31) | | `rate_center` | String | [Desc. `rate_center`](#desc-32) | | `state` | String | [Desc. `state`](#desc-33) | #### Desc. `min_quantity` {#desc-26} 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-27} The 3 digit Area Code. #### Desc. `number_type` {#desc-28} The wanted number type either TENDLC or TOLLFREE. NONE is effectively a no-op or null. #### Desc. `numbers` {#desc-29} 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-30} The 3 digit Exchange Code. #### Desc. `quantity` {#desc-31} 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-32} The rate center code. #### Desc. `state` {#desc-33} 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" } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Request new numbers for NPA 201", "notes": "We'd like around 5 to number of these numbers", "type": "NEW_NUMBERS", "npa": "201", "min_quantity": 5, "quantity": 10 }, "type": "request" } ``` ##### Response ### Remove Numbers A number can be deprovisioned with a `REMOVE_NUMBERS` request: #### Parameters 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`](#desc-34) | #### Desc. `numbers` {#desc-34} A list of NANP 11-digit numbers to remove __Example__ ```json { "numbers": [ "12003004000" ] } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Remove 12003004000", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "REMOVE_NUMBERS" }, "type": "request" } ``` ##### Response ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "Remove 12003004000", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "REMOVE_NUMBERS", "updated_at": "2021-08-04T10:00:00.000000Z" }, "type": "request" } ``` Unlike `REMOVE_MESSAGING_NUMBERS` which only removes the messaging component of a number, remove numbers will attempt to completely decommission the specified number, regardless of components. Note that this may create additional sub requests, as such a `REMOVE_NUMBERS` request may create `REMOVE_MESSAGING_NUMBERS`, `REMOVE_CAMPAIGN_NUMBERS` and other such requests to complete its own process. ### Add Messaging Numbers The next step is to create one or more requests that will perform the actual provisioning of the numbers for messaging (or other features). #### Parameters 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`](#desc-35) | | `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](#desc-36) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-37) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-38) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#desc-39) | #### Desc. `api_key_ids` {#desc-35} 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-36} 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-37} 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-38} 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-39} 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" } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "api_key_ids": [ "ca78c61f-b6ca-4ed5-91d5-1f3458e16258" ], "mms_enabled": false, "name": "Add messaging for 12003004000", "notes": "Some notes", "numbers": [ "12003004000" ], "switch_id": "ff473e3d-6e0d-4649-9a09-be69611fbc23", "type": "ADD_MESSAGING_NUMBERS" }, "type": "request" } ``` ##### Response ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "Add messaging for 12003004000", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "ADD_MESSAGING_NUMBERS", "updated_at": "2021-08-04T10:00:00.000000Z" }, "type": "request" } ``` There is a lot to digest here; provisioning a number for messaging requires some additional details that are system related. __API Keys__ the system allows numbers to be bound to zero or more api keys, these api keys are necessary in order to send messages from the client to the system, the system may also utilize an api key to send to the client when utilizing SMPP as the transport protocol. Switches affect the inbound routing from the system to the client, they also control the protocol, message format and any additional options. As of this writing, switches and api keys will be provided by the support team for the client, clients may check the configuration of their switch at any time using `GET /api/v1/switches/:switch_id`, where `:switch_id` is the switch's UUID. The requests also allows requesting mms enablement for the number, by default this will be false. Finally the `name` like with orders must be unique within the parent cart. ### Remove Messaging Numbers A number can have its messaging be deprovisioned with a `REMOVE_MESSAGING_NUMBERS` request: #### Parameters 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`](#desc-40) | #### Desc. `numbers` {#desc-40} A list of NANP 11-digit numbers to disable messaging for __Example__ ```json { "numbers": [ "12003004000" ] } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Remove messaging for 12003004000", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "REMOVE_MESSAGING_NUMBERS" }, "type": "request" } ``` ##### Response ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "Remove messaging for 12003004000", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "REMOVE_MESSAGING_NUMBERS", "updated_at": "2021-08-04T10:00:00.000000Z" }, "type": "request" } ``` __Note__ VoIP provisioned numbers will only have their messaging removed by this request and will remain provisioned in the system otherwise, but will not be available for messaging until a `ADD_MESSAGING_NUMBERS` is issued for it again. ### Register Brand TCR Brands can be registered using a `REGISTER_BRAND` request. If you are a CSP who is sharing a Campaign (and by extension brand) with Tychron, please use the TCR API and select Tychron as the CNP. #### Parameters 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" } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Create my new fancy brand", "notes": "Some notes", "type": "REGISTER_BRAND" }, "type": "request" } ``` ##### Response ### Unregister Brand Brands registered using `REGISTER_BRAND` can be removed using `UNREGISTER_BRAND`. #### Parameters 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" } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Remove Brand B000001", "notes": "Some notes", "tcr_brand_id": "B000001", "type": "UNREGISTER_BRAND" }, "type": "request" } ``` ##### Response ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2022-10-13T19:54:35.000000Z", "name": "Add 12003004000 to Campaign C00113", "notes": "Some notes", "tcr_brand_id": "B000001", "brand_id": "ca6407a4-9e3b-449b-9fee-2d144fb4b3db", "type": "UNREGISTER_BRAND", "updated_at": "2022-10-13T19:54:35.000000Z" }, "type": "request" } ``` ### Register Campaign #### Parameters 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`](#desc-41) | | `help_message` | String | | | `message_flow` | String | | | `mno_ids` | Array:String | | | `number_pool` | Boolean | | | `optin_keywords` | String | [Desc. `optin_keywords`](#desc-42) | | `optin_message` | String | | | `optout_keywords` | String | [Desc. `optout_keywords`](#desc-43) | | `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`](#desc-44) | | `tcr_reseller_id` | String | [Desc. `tcr_reseller_id`](#desc-45) | | `terms_and_conditions` | Boolean | [Desc. `terms_and_conditions`](#desc-46) | | `terms_and_conditions_link` | String | | | `use_case` | String | | #### Desc. `help_keywords` {#desc-41} Must be a CSV, that is a comma separated list of keywords. Excess spaces will be trimmed around each keyword. #### Desc. `optin_keywords` {#desc-42} Must be a CSV, that is a comma separated list of keywords. Excess spaces will be trimmed around each keyword. #### Desc. `optout_keywords` {#desc-43} 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-44} TCR issued Brand ID. #### Desc. `tcr_reseller_id` {#desc-45} TCR issued Reseller ID. #### Desc. `terms_and_conditions` {#desc-46} 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" } ``` #### Request & Response ##### Request ##### Response ### Unregister Campaign #### Parameters 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" } ``` #### Request & Response ##### Request ##### Response ### TCR Campaign Before any numbers can be added to a campaign, the campaign must be either created by Tychron, or be shared by a valid CSP with Tychron and approved. Please contact Tychron Support on the setup process for campaign sharing before attempting to provision any numbers with campaigns. If there are existing campaigns (see `GET /api/v1/campaigns`), you can provision numbers under a campaign, if it has been `dca_approved`. ### Add Campaign Numbers Numbers can be added to an existing campaign with with a `ADD_CAMPAIGN_NUMBERS` request: #### Parameters 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`](#desc-47) | | `*` | [One-Of](#type-52) | | #### Desc. `numbers` {#desc-47} 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-49} Sub-Schema __Type__ Object | Name | Type | Description | | ----------------- | ------ | ----------------------------------- | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#desc-48) | #### Desc. `tcr_campaign_id` {#desc-48} 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-51} Sub-Schema __Type__ Object | Name | Type | Description | | ------------- | ------------------- | ------------------------------- | | `campaign_id` | String(format:uuid) | [Desc. `campaign_id`](#desc-50) | #### Desc. `campaign_id` {#desc-50} 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-52} Types * [... tcr_campaign_id](#type-49) * [... campaign_id](#type-51) __Example__ ```json { "numbers": [ "12003004000" ], "*": { "tcr_campaign_id": "C000000" } } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Add 12003004000 to Campaign C00113", "notes": "Some notes", "numbers": [ "12003004000" ], "tcr_campaign_id": "C00113", "type": "ADD_CAMPAIGN_NUMBERS" }, "type": "request" } ``` ##### Response ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "Add 12003004000 to Campaign C00113", "notes": "Some notes", "numbers": [ "12003004000" ], "tcr_campaign_id": "C00113", "type": "ADD_CAMPAIGN_NUMBERS", "updated_at": "2021-08-04T10:00:00.000000Z" }, "type": "request" } ``` In the above example the TCR issued Campaign ID was used, however the UUID provided by Tychron when a campaign is shared with or created by Tychron can be used as well: __Request__ ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Add 12003004000 to Campaign C00113", "notes": "Some notes", "numbers": [ "12003004000" ], "campaign_id": "82e9c3c4-0abb-4765-a3fd-5da03625b9ad", "type": "ADD_CAMPAIGN_NUMBERS" }, "type": "request" } ``` __Response__ ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "Add 12003004000 to Campaign C00113", "notes": "Some notes", "numbers": [ "12003004000" ], "campaign_id": "82e9c3c4-0abb-4765-a3fd-5da03625b9ad", "type": "ADD_CAMPAIGN_NUMBERS", "updated_at": "2021-08-04T10:00:00.000000Z" }, "type": "request" } ``` Either or both are completely valid, however the `campaign_id` must resolve to the same campaign that is identified by the `tcr_campaign_id` if both are given. ### Remove Campaign Numbers Numbers can be removed from their campaign with a `REMOVE_CAMPAIGN_NUMBERS` request: #### Parameters Request for removing numbers from an existing campaign. __Type__ Object | Name | Type | Description | | --------- | ------------ | --------------------------- | | `numbers` | Array:String | [Desc. `numbers`](#desc-53) | #### Desc. `numbers` {#desc-53} A list of NANP 11-digit numbers to disable messaging for __Example__ ```json { "numbers": [ "12003004000" ] } ``` #### Request & Response ##### Request ```http POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1 Authorization: Bearer HTTP_TOKEN Accept: application/json Content-Type: application/json ``` ```json { "data": { "name": "Remove 12003004000 from Campaign", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "REMOVE_CAMPAIGN_NUMBERS" }, "type": "request" } ``` ##### Response ```http HTTP/1.1 201 Created Content-Type: application/json ``` ```json { "data": { "id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "inserted_at": "2021-08-04T10:00:00.000000Z", "name": "Remove 12003004000 from Campaign", "notes": "Some notes", "numbers": [ "12003004000" ], "type": "REMOVE_CAMPAIGN_NUMBERS", "updated_at": "2021-08-04T10:00:00.000000Z" }, "type": "request" } ``` There is no need to specify which campaign or campaigns a number belongs to within this request. If the number is provisioned with a campaign, then it will be removed, if it is not, then creation of this request will fail. # Cart Request Documents Before checkout, it's possible to upload request documents to help streamline the process. There are no hard requirements for any content, but keep in mind access may be restricted if abused. Files should be no larger than 4MB, while larger files MAY be accepted, they are not guaranteed to be supported moving forward, only a limit of 4MB will be guaranteed. ## Schema __Type__ Object | Name | Type | Description | | -------------- | ------------------------ | -------------------------------- | | `content_type` | String | [Desc. `content_type`](#desc-54) | | `expires_at` | String(format:date-time) | [Desc. `expires_at`](#desc-55) | | `filename` | String | [Desc. `filename`](#desc-56) | | `id` | String(format:ulid) | [Desc. `id`](#desc-57) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..128) | [Desc. `name`](#desc-58) | | `notes` | String | [Desc. `notes`](#desc-59) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `content_type` {#desc-54} The mime type of the document, this will be returned as the content-type header when downloading the asset. #### Desc. `expires_at` {#desc-55} 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-56} The filename of the document. #### Desc. `id` {#desc-57} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `name` {#desc-58} A unique name identifying the document, must be unique to the request #### Desc. `notes` {#desc-59} 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" } ``` ## API ### Upload Cart Request Document ```http POST /api/v1/carts/{cart_id}/requests/{request_id}/documents HTTP/1.1 ``` Attach a document or any file to the request currently in a cart, these documents can be removed later if needed. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | --------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-60) | #### Path Desc. request_id {#desc-60} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request multipart/form-data ```http POST /api/v1/carts/{cart_id}/requests/{request_id}/documents HTTP/1.1 Accept: application/json Content-Type: multipart/form-data; boundary=ExampleBoundary7MA4YWxkTrZu0gW Content-Length: 592 --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="example.bin" Content-Type: application/octet-stream --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file_hint" DEFAULT --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="filename" abc.pdf --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="name" LOA --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="notes" LOA from client on 2026-05-20. --ExampleBoundary7MA4YWxkTrZu0gW-- ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 422 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Cart Request Document ```http DELETE /api/v1/carts/{cart_id}/requests/{request_id}/documents/{id} HTTP/1.1 ``` Removes a request document and any associated uploaded files. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | --------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-61) | #### Path Desc. request_id {#desc-61} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request ```http DELETE /api/v1/carts/{cart_id}/requests/{request_id}/documents/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 422 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Cart Request Documents ```http GET /api/v1/carts/{cart_id}/requests/{request_id}/documents HTTP/1.1 ``` List request documents. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | --------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-62) | __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------ | | first | Integer | [Query Desc. first](#desc-63) | | last | Integer | [Query Desc. last](#desc-64) | | after | String | [Query Desc. after](#desc-65) | | before | String | [Query Desc. before](#desc-66) | #### Path Desc. request_id {#desc-62} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Query Desc. first {#desc-63} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-64} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-65} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-66} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/carts/{cart_id}/requests/{request_id}/documents HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 635 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Get Cart Request Document ```http GET /api/v1/carts/{cart_id}/requests/{request_id}/documents/{id} HTTP/1.1 ``` Retrieve a Request Document record by its ID. Note this is the "record" and not the uploaded file. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | --------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-67) | #### Path Desc. request_id {#desc-67} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request ```http GET /api/v1/carts/{cart_id}/requests/{request_id}/documents/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 422 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Orders When a Cart has undergone checkout, it will be treated as an Order. ## Schema 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](#schema-ordererrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-68) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](#desc-69) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-70) | | `status` | [OrderStatus](#schema-orderstatus) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `id` {#desc-68} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `name` {#desc-69} Display name for Order. #### Desc. `notes` {#desc-70} 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" } ``` ## API ### Updating An Existing Order ```http PATCH /api/v1/orders/{id} HTTP/1.1 ``` Update an existing order. Only the name and notes can be updated on the order once it has been checked out. __Path Parameters__ | Name | Type | Description | | ---- | ------- | ----------- | | id | String! | Order ID | #### Request application/json ```http PATCH /api/v1/orders/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 119 ``` ```json { "data": { "name": "Add Messaging to 10 Numbers", "notes": "Order for Client XYZ\n" }, "type": "order" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 303 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Existing Orders ```http GET /api/v1/orders HTTP/1.1 ``` Retrieve a list of orders, ordered by descending order by inserted_at (i.e. most recent is first) __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------ | | first | Integer | [Query Desc. first](#desc-71) | | last | Integer | [Query Desc. last](#desc-72) | | after | String | [Query Desc. after](#desc-73) | | before | String | [Query Desc. before](#desc-74) | #### Query Desc. first {#desc-71} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-72} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-73} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-74} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/orders HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 512 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Order ```http GET /api/v1/orders/{id} HTTP/1.1 ``` Lookup an order by ID __Path Parameters__ | Name | Type | Description | | ---- | ------- | ----------- | | id | String! | Order ID | #### Request ```http GET /api/v1/orders/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 303 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Requests ## Schema Specific action or operation that should take place __Type__ Object | Name | Type | Description | | ------------- | ---------------------------------------- | ------------------------------ | | `error_code` | [OrderErrorCode](#schema-ordererrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-75) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..255) | | | `notes` | String | | | `status` | [OrderStatus](#schema-orderstatus) | | | `type` | [RequestType](#schema-requesttype) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `*` | [One-Of](#type-76) | | #### Desc. `id` {#desc-75} Another format for UUID, used primarily for tasks, requests and messages. #### One-Of {#type-76} Types * [RequestAddCampaignNumbersData](#schema-requestaddcampaignnumbersdata) * [RequestAddMessagingNumbersData](#schema-requestaddmessagingnumbersdata) * [RequestAddVoiceNumbersData](#schema-requestaddvoicenumbersdata) * [RequestNewNumbersData](#schema-requestnewnumbersdata) * [RequestRegisterBrandData](#schema-requestregisterbranddata) * [RequestRegisterCampaignData](#schema-requestregistercampaigndata) * [RequestRemoveCampaignNumbersData](#schema-requestremovecampaignnumbersdata) * [RequestRemoveMessagingNumbersData](#schema-requestremovemessagingnumbersdata) * [RequestRemoveNumbersData](#schema-requestremovenumbersdata) * [RequestRemoveVoiceNumbersData](#schema-requestremovevoicenumbersdata) * [RequestUnregisterBrandData](#schema-requestunregisterbranddata) * [RequestUnregisterCampaignData](#schema-requestunregistercampaigndata) * [RequestVetBrandData](#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 } } ``` ## API ### Updating An Existing Request ```http PATCH /api/v1/requests/{id} HTTP/1.1 ``` Update an existing request. Only the name and notes can be updated on the request once it has been checked out. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:ulid)! | Request ID | #### Request ```http PATCH /api/v1/requests/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 533 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Existing Requests ```http GET /api/v1/requests HTTP/1.1 ``` Retrieve a list of all requests under the parent account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------ | | first | Integer | [Query Desc. first](#desc-77) | | last | Integer | [Query Desc. last](#desc-78) | | after | String | [Query Desc. after](#desc-79) | | before | String | [Query Desc. before](#desc-80) | #### Query Desc. first {#desc-77} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-78} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-79} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-80} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/requests HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 778 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Request ```http GET /api/v1/requests/{id} HTTP/1.1 ``` Lookup a request by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:ulid)! | Request ID | #### Request ```http GET /api/v1/requests/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 533 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ## Request Types Requests have many subtypes which determine what kind of action will be taken, this can range from adding messaging-only numbers to removing existing numbers or just some of their components. ### New Numbers Request new numbers from inventory. #### Parameters Request for acquiring new numbers. __Type__ Object | Name | Type | Description | | -------------- | ----------------------------------------- | -------------------------------- | | `addons` | [AddonsData](#schema-addonsdata) | | | `city` | String | | | `min_quantity` | String | [Desc. `min_quantity`](#desc-81) | | `npa` | String | [Desc. `npa`](#desc-82) | | `number_type` | Enum(`NONE`, `TENDLC`, `TOLLFREE`):String | [Desc. `number_type`](#desc-83) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-84) | | `nxx` | String | [Desc. `nxx`](#desc-85) | | `quantity` | String | [Desc. `quantity`](#desc-86) | | `rate_center` | String | [Desc. `rate_center`](#desc-87) | | `state` | String | [Desc. `state`](#desc-88) | #### Desc. `min_quantity` {#desc-81} 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-82} The 3 digit Area Code. #### Desc. `number_type` {#desc-83} The wanted number type either TENDLC or TOLLFREE. NONE is effectively a no-op or null. #### Desc. `numbers` {#desc-84} 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-85} The 3 digit Exchange Code. #### Desc. `quantity` {#desc-86} 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-87} The rate center code. #### Desc. `state` {#desc-88} 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" } ``` ### Remove Numbers A number can be deprovisioned with a `REMOVE_NUMBERS` request. #### Parameters 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`](#desc-89) | #### Desc. `numbers` {#desc-89} A list of NANP 11-digit numbers to remove __Example__ ```json { "numbers": [ "12003004000" ] } ``` ### Add Messaging Numbers Messaging can be added to an existing number or messaging-only numbers provisioned using a `ADD_MESSAGING_NUMBERS` request. Numbers provisioned by this request that are new to the parent account will be treated as as BYON (Bring-Your-Own-Number). #### Parameters 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`](#desc-90) | | `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](#desc-91) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-92) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-93) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#desc-94) | #### Desc. `api_key_ids` {#desc-90} 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-91} 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-92} 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-93} 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-94} 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" } ``` ### Remove Messaging Numbers A number can have its messaging be deprovisioned with a `REMOVE_MESSAGING_NUMBERS` request. #### Parameters Request for disabling messaging on existing numbers. __Type__ Object | Name | Type | Description | | --------- | ------------ | --------------------------- | | `numbers` | Array:String | [Desc. `numbers`](#desc-95) | #### Desc. `numbers` {#desc-95} A list of NANP 11-digit numbers to disable messaging for __Example__ ```json { "numbers": [ "12003004000" ] } ``` ### Register Brand TCR Brands can be registered using a `REGISTER_BRAND` request. If you are a CSP who is sharing a Campaign (and by extension brand) with Tychron, please use the TCR API and select Tychron as the CNP. #### Parameters 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`](#desc-96) | | `brand_relationship` | String | | | `business_contact_email` | String(format:email) | | | `cdr_id` | String(format:uuid) | [Desc. `cdr_id`](#desc-97) | | `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-96} A Universally unique identifier, which identifies the resource #### Desc. `cdr_id` {#desc-97} 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" } ``` ### Unregister Brand Brands registered using `REGISTER_BRAND` can be removed using `UNREGISTER_BRAND`. #### Parameters 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" } ``` ### Register Campaign Registering a new campaign can be done with a `REGISTER_CAMPAIGN` request. #### Parameters 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`](#desc-98) | | `help_message` | String | | | `embedded_phone` | Boolean | | | `tcr_brand_id` | String | [Desc. `tcr_brand_id`](#desc-99) | | `embedded_link` | Boolean | | | `tcr_reseller_id` | String | [Desc. `tcr_reseller_id`](#desc-100) | | `age_gated` | Boolean | | | `vertical` | String | | | `optout_message` | String | | | `description` | String | | | `auto_renewal` | Boolean | | | `embedded_link_sample` | String | | | `optout_keywords` | String | [Desc. `optout_keywords`](#desc-101) | | `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`](#desc-102) | | `subscriber_optin` | Boolean | | | `help_keywords` | String | [Desc. `help_keywords`](#desc-103) | | `expedite_tier` | Enum(`NONE`, `PRIORITY`):String | [Desc. `expedite_tier`](#desc-104) | | `affiliate_marketing` | Boolean | | | `subscriber_help` | Boolean | | | `samples` | Array:String | | | `optin_keywords` | String | [Desc. `optin_keywords`](#desc-105) | | `privacy_policy_link` | String | | | `number_pool` | Boolean | | | `terms_and_conditions` | Boolean | [Desc. `terms_and_conditions`](#desc-106) | #### Desc. `tcr_campaign_id` {#desc-98} TCR issued Campaign ID. #### Desc. `tcr_brand_id` {#desc-99} TCR issued Brand ID. #### Desc. `tcr_reseller_id` {#desc-100} TCR issued Reseller ID. #### Desc. `optout_keywords` {#desc-101} 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-102} The Campaign Service Provider ID. Typically in the form of SNNNNNN. #### Desc. `help_keywords` {#desc-103} Must be a CSV, that is a comma separated list of keywords. Excess spaces will be trimmed around each keyword. #### Desc. `expedite_tier` {#desc-104} 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-105} 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-106} 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 } ``` ### Unregister Campaign #### Parameters 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" } ``` ### TCR Campaign Before any numbers can be added to a campaign, the campaign must be either created by Tychron, or be shared by a valid CSP with Tychron and approved. Please contact Tychron Support on the setup process for campaign sharing before attempting to provision any numbers with campaigns. If there are existing campaigns (see `GET /api/v1/campaigns`), you can provision numbers under a campaign, if it has been `dca_approved`. ### Add Campaign Numbers Numbers can be added to an existing campaign with with a `ADD_CAMPAIGN_NUMBERS` request. #### Parameters Request for register numbers under campaign __Type__ Object | Name | Type | Description | | ----------------- | ------------------- | ------------------------------------ | | `campaign_id` | String(format:uuid) | [Desc. `campaign_id`](#desc-107) | | `numbers` | Array:String | [Desc. `numbers`](#desc-108) | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#desc-109) | | `tmobile_enabled` | Boolean | [Desc. `tmobile_enabled`](#desc-110) | #### Desc. `campaign_id` {#desc-107} 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-108} 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-109} 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-110} 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 } ``` ### Remove Campaign Numbers Numbers can be removed from their campaign with a `REMOVE_CAMPAIGN_NUMBERS` request. #### Parameters Request for detaching numbers from their known campaign. __Type__ Object | Name | Type | Description | | --------- | ------------ | ---------------------------- | | `numbers` | Array:String | [Desc. `numbers`](#desc-111) | #### Desc. `numbers` {#desc-111} A list of NANP 11-digit numbers to disable messaging for __Example__ ```json { "numbers": [ "12003004000" ] } ``` # Request Documents Request documents are any file that can be uploaded to accompany a request for the purpose of review, or help approve a process. This a mirror of the Cart Request Documents, the difference is when things are allowed to be changed. Request Documents can only be uploaded, or deleted when the parent request is: * `NEW` * `MANUAL` * `REVIEW` * `AUTHOR_REVIEW` * `ERROR` Note you cannot change documents once the request is completed. Uploading a new document MAY cause the request take longer if it has to be shared with other systems. ## Schema __Type__ Object | Name | Type | Description | | -------------- | ------------------------ | --------------------------------- | | `content_type` | String | [Desc. `content_type`](#desc-112) | | `expires_at` | String(format:date-time) | [Desc. `expires_at`](#desc-113) | | `filename` | String | [Desc. `filename`](#desc-114) | | `id` | String(format:ulid) | [Desc. `id`](#desc-115) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..128) | [Desc. `name`](#desc-116) | | `notes` | String | [Desc. `notes`](#desc-117) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `content_type` {#desc-112} The mime type of the document, this will be returned as the content-type header when downloading the asset. #### Desc. `expires_at` {#desc-113} 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-114} The filename of the document. #### Desc. `id` {#desc-115} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `name` {#desc-116} A unique name identifying the document, must be unique to the request #### Desc. `notes` {#desc-117} 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" } ``` ## API ### Upload Request Document ```http POST /api/v1/requests/{request_id}/documents HTTP/1.1 ``` Attach a document or any file to the respective request, these documents can be removed later if needed. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | ---------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-118) | #### Path Desc. request_id {#desc-118} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request multipart/form-data ```http POST /api/v1/requests/{request_id}/documents HTTP/1.1 Accept: application/json Content-Type: multipart/form-data; boundary=ExampleBoundary7MA4YWxkTrZu0gW Content-Length: 592 --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file"; filename="example.bin" Content-Type: application/octet-stream --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="file_hint" DEFAULT --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="filename" abc.pdf --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="name" LOA --ExampleBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="notes" LOA from client on 2026-05-20. --ExampleBoundary7MA4YWxkTrZu0gW-- ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 422 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Request Document ```http DELETE /api/v1/requests/{request_id}/documents/{id} HTTP/1.1 ``` Removes a request document and any associated uploaded files. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | ---------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-119) | #### Path Desc. request_id {#desc-119} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request ```http DELETE /api/v1/requests/{request_id}/documents/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 422 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Request Documents ```http GET /api/v1/requests/{request_id}/documents HTTP/1.1 ``` List request documents. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | ---------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-120) | __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-121) | | last | Integer | [Query Desc. last](#desc-122) | | after | String | [Query Desc. after](#desc-123) | | before | String | [Query Desc. before](#desc-124) | #### Path Desc. request_id {#desc-120} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Query Desc. first {#desc-121} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-122} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-123} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-124} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/requests/{request_id}/documents HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 635 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Get Request Document ```http GET /api/v1/requests/{request_id}/documents/{id} HTTP/1.1 ``` Retrieve a Request Document record by its ID. Note this is the "record" and not the uploaded file. __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | ---------------------------------- | | request_id | String(format:ulid)! | [Path Desc. request_id](#desc-125) | #### Path Desc. request_id {#desc-125} ULID Another format for UUID, used primarily for tasks, requests and messages. #### Request ```http GET /api/v1/requests/{request_id}/documents/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 422 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Request Provision Records A provision record represents a single number or unit resource that is processed by the request. These records may be removed or added over the lifetime of the request and may be replaced upon reset of their parent request. You are not expected to ever keep a reference to a provision record as it may be removed without notice. ## Schema 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](#schema-requestprovisionrecorderrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-126) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `number` | String | | | `status` | [RequestProvisionRecordStatus](#schema-requestprovisionrecordstatus) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `id` {#desc-126} 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" } ``` ## API ### List Existing Request's Provision Records ```http GET /api/v1/requests/{request_id}/provision_records HTTP/1.1 ``` Retrieve the provision records associated with the parent request. Note that for requests that have a `number` or `numbers` field, this mapping tends to be 1:1. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-127) | | last | Integer | [Query Desc. last](#desc-128) | | after | String | [Query Desc. after](#desc-129) | | before | String | [Query Desc. before](#desc-130) | #### Query Desc. first {#desc-127} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-128} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-129} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-130} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/requests/{request_id}/provision_records HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 475 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Existing Request Provision Records ```http GET /api/v1/provision_records HTTP/1.1 ``` Retrieve Provision Records allocated for this account. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-131) | | last | Integer | [Query Desc. last](#desc-132) | | after | String | [Query Desc. after](#desc-133) | | before | String | [Query Desc. before](#desc-134) | #### Query Desc. first {#desc-131} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-132} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-133} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-134} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/provision_records HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 475 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Request Provision Record ```http GET /api/v1/provision_records/{id} HTTP/1.1 ``` Lookup an Provision Record by its ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------------- | | id | String(format:ulid)! | Provision Record ID | #### Request ```http GET /api/v1/provision_records/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 270 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Roles ## Schema 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`](#desc-135) | | `id` | String(format:uuid) | [Desc. `id`](#desc-136) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `level` | Enum(`GUEST`, `CLIENT`, `ADMIN`):String | [Desc. `level`](#desc-137) | | `name` | String | [Desc. `name`](#desc-138) | | `notes` | String | [Desc. `notes`](#desc-139) | | `rank` | Integer(>= 0) | [Desc. `rank`](#desc-140) | | `resources` | Array:[SubObject](#type-146) | [Desc. `resources`](#desc-147) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `default_scope` {#desc-135} 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-136} A Universally unique identifier, which identifies the resource #### Desc. `level` {#desc-137} 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-138} Role's display name. #### Desc. `notes` {#desc-139} Any notes about the role. #### Desc. `rank` {#desc-140} 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-146} Sub-Schema __Type__ Object | Name | Type | Description | | ------------- | -------------------------------------------------- | -------------------------- | | `actions` | Array:[SubObject](#type-144) | | | `resource_id` | String | | | `scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](#desc-145) | #### SubObject {#type-144} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ---------------------------- | -------------------------- | | `name` | [Enum](#enum-141):String | [Desc. `name`](#desc-142) | | `value` | Enum(`true`, `false`):String | [Desc. `value`](#desc-143) | #### Enum Values name {#enum-141} 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-142} The name of the action. #### Desc. `value` {#desc-143} 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-145} See Role's default_scope for more details on the enum. IGNORE acts as a fallback to the `default_scope`. #### Desc. `resources` {#desc-147} 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" } ``` ## Summary Roles control the permissions a user can have. ## API ### Create Role __Data__ | Name | Type | Description | | --------------- | -------------------------------------------------- | ---------------------------------- | | `default_scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `default_scope`](#desc-148) | | `name` | String | [Desc. `name`](#desc-149) | | `notes` | String | [Desc. `notes`](#desc-150) | | `rank` | Integer(>= 0) | [Desc. `rank`](#desc-151) | | `resources` | Array:[SubObject](#type-157) | [Desc. `resources`](#desc-158) | #### Desc. `default_scope` {#desc-148} 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-149} Role's display name. #### Desc. `notes` {#desc-150} Any notes about the role. #### Desc. `rank` {#desc-151} 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-157} Sub-Schema __Type__ Object | Name | Type | Description | | ------------- | -------------------------------------------------- | -------------------------- | | `actions` | Array:[SubObject](#type-155) | | | `resource_id` | String | | | `scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](#desc-156) | #### SubObject {#type-155} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ---------------------------- | -------------------------- | | `name` | [Enum](#enum-152):String | [Desc. `name`](#desc-153) | | `value` | Enum(`true`, `false`):String | [Desc. `value`](#desc-154) | #### Enum Values name {#enum-152} 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-153} The name of the action. #### Desc. `value` {#desc-154} 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-156} See Role's default_scope for more details on the enum. IGNORE acts as a fallback to the `default_scope`. #### Desc. `resources` {#desc-158} Role's job title, or position ```http POST /api/v1/roles HTTP/1.1 ``` Create a new Role. Note that newly created Roles will return their secrets, however all subsequent GET requests will not contain the secrets. #### Request application/json ```http POST /api/v1/roles HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 392 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 564 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Update Role __Data__ | Name | Type | Description | | --------------- | -------------------------------------------------- | ---------------------------------- | | `default_scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `default_scope`](#desc-159) | | `name` | String | [Desc. `name`](#desc-160) | | `notes` | String | [Desc. `notes`](#desc-161) | | `rank` | Integer(>= 0) | [Desc. `rank`](#desc-162) | | `resources` | Array:[SubObject](#type-168) | [Desc. `resources`](#desc-169) | #### Desc. `default_scope` {#desc-159} 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-160} Role's display name. #### Desc. `notes` {#desc-161} Any notes about the role. #### Desc. `rank` {#desc-162} 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-168} Sub-Schema __Type__ Object | Name | Type | Description | | ------------- | -------------------------------------------------- | -------------------------- | | `actions` | Array:[SubObject](#type-166) | | | `resource_id` | String | | | `scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](#desc-167) | #### SubObject {#type-166} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ---------------------------- | -------------------------- | | `name` | [Enum](#enum-163):String | [Desc. `name`](#desc-164) | | `value` | Enum(`true`, `false`):String | [Desc. `value`](#desc-165) | #### Enum Values name {#enum-163} 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-164} The name of the action. #### Desc. `value` {#desc-165} 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-167} See Role's default_scope for more details on the enum. IGNORE acts as a fallback to the `default_scope`. #### Desc. `resources` {#desc-169} Role's job title, or position ```http PATCH /api/v1/roles/{id} HTTP/1.1 ``` Update an existing Role __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | Role ID | #### Request application/json ```http PATCH /api/v1/roles/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 392 ``` ```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" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 564 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Role ```http DELETE /api/v1/roles/{id} HTTP/1.1 ``` Delete a Role. Note that a Role cannot be deleted if it is still associated with any switches or numbers. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | Role ID | #### Request ```http DELETE /api/v1/roles/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 564 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Roles ```http GET /api/v1/roles HTTP/1.1 ``` Retrieve a list of all roles under the parent account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-170) | | last | Integer | [Query Desc. last](#desc-171) | | after | String | [Query Desc. after](#desc-172) | | before | String | [Query Desc. before](#desc-173) | #### Query Desc. first {#desc-170} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-171} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-172} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-173} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/roles HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 825 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Role ```http GET /api/v1/roles/{id} HTTP/1.1 ``` Lookup a request by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | Role ID | #### Request ```http GET /api/v1/roles/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 564 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Users ## Schema A user is any agent that can interact with impersonated or portal APIs __Type__ Object | Name | Type | Description | | ------------- | ------------------------ | ------------------------------- | | `address` | `address` | [Desc. `address`](#desc-174) | | `email` | String(format:email) | [Desc. `email`](#desc-175) | | `first_name` | String | [Desc. `first_name`](#desc-176) | | `id` | String(format:uuid) | [Desc. `id`](#desc-177) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `last_name` | String | [Desc. `last_name`](#desc-178) | | `title` | String | [Desc. `title`](#desc-179) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `address` {#desc-174} User Address details, may differ from top-level details #### Desc. `email` {#desc-175} User's email #### Desc. `first_name` {#desc-176} User's first name #### Desc. `id` {#desc-177} A Universally unique identifier, which identifies the resource #### Desc. `last_name` {#desc-178} User's last name #### Desc. `title` {#desc-179} 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" } ``` ## Summary Users are agents or actual human beings who are capable of utilizing the portal or API (via an Impersonated API Key). Users are assigned a `role` which affect their permissions and access levels. ## API ### Create User __Data__ | Name | Type | Description | | ----------------------- | -------------------- | ------------------------------------------ | | `address` | `address` | [Desc. `address`](#desc-180) | | `email` | String(format:email) | [Desc. `email`](#desc-181) | | `first_name` | String | [Desc. `first_name`](#desc-182) | | `last_name` | String | [Desc. `last_name`](#desc-183) | | `password` | String | [Desc. `password`](#desc-184) | | `password_confirmation` | String | [Desc. `password_confirmation`](#desc-185) | | `title` | String | [Desc. `title`](#desc-186) | #### Desc. `address` {#desc-180} User Address details, may differ from top-level details #### Desc. `email` {#desc-181} User's email #### Desc. `first_name` {#desc-182} User's first name #### Desc. `last_name` {#desc-183} User's last name #### Desc. `password` {#desc-184} User's login password #### Desc. `password_confirmation` {#desc-185} User's login password (for confirmation) #### Desc. `title` {#desc-186} 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 | | ```http POST /api/v1/users HTTP/1.1 ``` Create a new User, they will be automatically assigned to the same role as current user. #### Request application/json ```http POST /api/v1/users HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 632 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 716 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update User __Data__ | Name | Type | Description | | ------------ | -------------------- | ------------------------------- | | `address` | `address` | [Desc. `address`](#desc-187) | | `email` | String(format:email) | [Desc. `email`](#desc-188) | | `first_name` | String | [Desc. `first_name`](#desc-189) | | `last_name` | String | [Desc. `last_name`](#desc-190) | | `title` | String | [Desc. `title`](#desc-191) | #### Desc. `address` {#desc-187} User Address details, may differ from top-level details #### Desc. `email` {#desc-188} User's email #### Desc. `first_name` {#desc-189} User's first name #### Desc. `last_name` {#desc-190} User's last name #### Desc. `title` {#desc-191} 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 | | ```http PATCH /api/v1/users/{id} HTTP/1.1 ``` Update an existing User. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | User ID | #### Request application/json ```http PATCH /api/v1/users/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 567 ``` ```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" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 716 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete User ```http DELETE /api/v1/users/{id} HTTP/1.1 ``` Delete an existing User by ID. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | User ID | #### Request ```http DELETE /api/v1/users/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 716 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Users ```http GET /api/v1/users HTTP/1.1 ``` Retrieve a list of users assigned to the parent account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-192) | | last | Integer | [Query Desc. last](#desc-193) | | after | String | [Query Desc. after](#desc-194) | | before | String | [Query Desc. before](#desc-195) | #### Query Desc. first {#desc-192} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-193} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-194} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-195} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/users HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 989 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get User ```http GET /api/v1/users/{id} HTTP/1.1 ``` Lookup a user by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | User ID | #### Request ```http GET /api/v1/users/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 716 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # API Keys ## Schema An set of authorization details for various APIs __Type__ Object | Name | Type | Description | | ---------------- | ------------------------ | --------------------------------------- | | `active` | Boolean | | | `id` | String(format:uuid) | [Desc. `id`](#desc-196) | | `identity` | String | [Desc. `identity`](#desc-197) | | `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`](#desc-198) | | `smpp_system_id` | String | [Desc. `smpp_system_id`](#desc-199) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `id` {#desc-196} A Universally unique identifier, which identifies the resource #### Desc. `identity` {#desc-197} Acts as the username in the authorization pair for MM4 #### Desc. `notes` {#desc-198} Any notes about the API Key, like, what it is used for, or other sharable details. #### Desc. `smpp_system_id` {#desc-199} 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" } ``` ## Summary API Keys are your credentials for doing any form of transaction or requests with the system. API Keys are used for: * LRN * CNAM * MCL * SMS * SMPP * HTTP * MMS * MM4 * HTTP * All other Atlas API (e.g. GET /api/v1/switches) While API Keys are a single record, there are two types. ### Standard API Key? A standard API Key, as covered in [Your Resources](#your-resources), is used to access messaging (i.e. SMS, MMS) and informational services (i.e. LRN, CNAM, MCL). Standard keys can be made either through the self-service portal, or via the API from an allowed Impersonated API Key. Standard keys cannot be used to perform ordering, or any of the functions not mentioned. ### Impersonated API Key? An Impersonated API Key, or user attached API Key is one used to perform extended API operations, it can also be used for messaging and informational services as well. The API Key will act on behalf of a user present in the system, which also makes the API Key subject to the same permissions and restrictions as the actual user. This also means that if a user is suspended, the API Key's extended functions will also be suspended. Messaging and informational services will continue to work as intended. Impersonated keys cannot be created normally, and require action from support. You will normally receive an impersonated key on initial account setup. If you require an additional impersonated key, or wish to further isolate your services, please contact support. ## Where are my secrets? Upon creating an API Key you should receive the key with all of its secrets generated. However, subsequent requests to retrieve the key will not return the secrets, the secrets cannot be covered, even by support. If SMPP, or MM4 access is needed, and the secrets from the API Key are lost, a new one will need to be created. All dids and switches will need to be re-assigned to the new API Key, where applicable. ## API ### Create API Key __Data__ | 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 | ```http POST /api/v1/api_keys HTTP/1.1 ``` Create a new API Key. Note that newly created API Keys will return their secrets, however all subsequent GET requests will not contain the secrets. #### Request application/json ```http POST /api/v1/api_keys HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 105 ``` ```json { "data": { "active": false, "name": "string", "notes": "string" }, "type": "api_key" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 569 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update API Key __Data__ | 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 | ```http PATCH /api/v1/api_keys/{id} HTTP/1.1 ``` Update an existing API Key __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | API Key ID | #### Request application/json ```http PATCH /api/v1/api_keys/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 105 ``` ```json { "data": { "active": false, "name": "string", "notes": "string" }, "type": "api_key" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 488 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete API Key ```http DELETE /api/v1/api_keys/{id} HTTP/1.1 ``` Delete an API Key. Note that an API Key cannot be deleted if it is still associated with any switches or numbers. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | API Key ID | #### Request ```http DELETE /api/v1/api_keys/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 488 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List API Keys ```http GET /api/v1/api_keys HTTP/1.1 ``` Retrieve API Keys allocated for this account. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-200) | | last | Integer | [Query Desc. last](#desc-201) | | after | String | [Query Desc. after](#desc-202) | | before | String | [Query Desc. before](#desc-203) | #### Query Desc. first {#desc-200} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-201} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-202} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-203} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/api_keys HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 705 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get API Key ```http GET /api/v1/api_keys/{id} HTTP/1.1 ``` Lookup an API Key by its ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | API Key ID | #### Request ```http GET /api/v1/api_keys/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 488 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Bind API Key to DID ```http POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1 ``` Bind specified API Key to the number __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | ---------------------------------- | | number_id | String! | Number or ID | | api_key_id | String(format:uuid)! | [Path Desc. api_key_id](#desc-204) | #### Path Desc. api_key_id {#desc-204} API Key ID A Universally unique identifier, which identifies the resource #### Request ```http POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 488 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Unbind API Key from DID ```http DELETE /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1 ``` Unbind specified API Key from the number __Path Parameters__ | Name | Type | Description | | ---------- | -------------------- | ---------------------------------- | | number_id | String! | Number or ID | | api_key_id | String(format:uuid)! | [Path Desc. api_key_id](#desc-205) | #### Path Desc. api_key_id {#desc-205} API Key ID A Universally unique identifier, which identifies the resource #### Request ```http DELETE /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 488 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Bulk Dip Tasks ## Schema 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`](#desc-206) | | `enhanced` | Boolean | [Desc. `enhanced`](#desc-207) | | `error_code` | Enum(`OK`):String | [Desc. `error_code`](#desc-208) | | `format` | Enum(`CSV`, `MLJSON`):String | [Desc. `format`](#desc-209) | | `id` | String(format:ulid) | [Desc. `id`](#desc-210) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `messaging_lookup` | Boolean | [Desc. `messaging_lookup`](#desc-211) | | `numbers` | Array(0..20000):String(format:tel) | Numbers to lookup | | `on_done_actions` | [OnDoneActions](#schema-ondoneactions) | | | `reference_id` | String(1..255) | [Desc. `reference_id`](#desc-212) | | `status` | [Enum](#enum-213):String | [Desc. `status`](#desc-214) | | `type` | Enum(`LRN`, `MCL`, `CNAM`):String | [Desc. `type`](#desc-215) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `enable_cdr_export` {#desc-206} 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-207} Used for LRN type, enables enhanced lookup. Please consult the LRN documentation for additional details. #### Desc. `error_code` {#desc-208} * `OK` - there was no error * `BAD_SOURCE_FILE` - there was an issue with the source file #### Desc. `format` {#desc-209} 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-210} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `messaging_lookup` {#desc-211} Used for LRN type, enables messaging lookup, MCL will be added. Please consult the LRN documentation for additional details. #### Desc. `reference_id` {#desc-212} 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-213} Allowed values * `NEW` * `SCHEDULED` * `PROCESSING` * `STORING` * `DELIVERING` * `COMPLETED` * `ABORTED` * `ERROR` #### Desc. `status` {#desc-214} 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-215} 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" } ``` ## Summary Bulk Dip Tasks are an experimental feature, they will allow you, the client to perform CNAM, LRN, or MCL dips in bulk, the finished dip will be delivered to a configured endpoint. Note that the creation API for bulk dip tasks, is asynchronous, it will return immediately after performing basic validation. ## API ### Create Bulk Dip Task __Data__ | Name | Type | Description | | ------------------ | -------------------------------------------------- | ------------------------------------- | | `enhanced` | Boolean | [Desc. `enhanced`](#desc-216) | | `format` | Enum(`CSV`, `MLJSON`):String | [Desc. `format`](#desc-217) | | `messaging_lookup` | Boolean | [Desc. `messaging_lookup`](#desc-218) | | `numbers` | Array(0..20000):String(format:tel) | Numbers to lookup | | `on_done_actions` | [CreateOnDoneActions](#schema-createondoneactions) | | | `reference_id` | String(1..255) | [Desc. `reference_id`](#desc-219) | | `type` | Enum(`LRN`, `MCL`, `CNAM`):String | [Desc. `type`](#desc-220) | #### Desc. `enhanced` {#desc-216} Used for LRN type, enables enhanced lookup. Please consult the LRN documentation for additional details. #### Desc. `format` {#desc-217} 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-218} Used for LRN type, enables messaging lookup, MCL will be added. Please consult the LRN documentation for additional details. #### Desc. `reference_id` {#desc-219} 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-220} The type of bulk dip that should be performed: * `LRN` - Location Routing Number lookups * `MCL` - Messaging Carrier Lookup * `CNAM` - Caller Name ```http POST /api/v1/bulk_dip_tasks HTTP/1.1 ``` Create a new Bulk Dip Task. Note that bulk dip tasks can be created without setting any on_done_actions, however it may prove difficult to retrieve the completed file without assistance if done so. Therefore it is recommended that an on_done_action is set with an appropriate endpoint to deliver the completed file to. #### Request application/json ```http POST /api/v1/bulk_dip_tasks HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 632 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 947 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Bulk Dip Tasks ```http GET /api/v1/bulk_dip_tasks HTTP/1.1 ``` Retrieve Bulk Dip Tasks __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-221) | | last | Integer | [Query Desc. last](#desc-222) | | after | String | [Query Desc. after](#desc-223) | | before | String | [Query Desc. before](#desc-224) | #### Query Desc. first {#desc-221} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-222} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-223} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-224} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/bulk_dip_tasks HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1248 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Bulk Dip Tasks ```http GET /api/v1/bulk_dip_tasks/{id} HTTP/1.1 ``` Retrieve a Bulk Dip Task by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ---------------- | | id | String(format:ulid)! | Bulk Dip Task ID | #### Request ```http GET /api/v1/bulk_dip_tasks/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 947 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ## Webhook Integration While tasks are allowed to be created without any `on_done_actions`, it is strongly recommended to do so. ### File Formats Below are ALL fields that can appear in the CSV and MLJSON file uploaded upon completion. | Name | Type | Description | Dip Type | | ------------------------ | ------ | ------------------------------------------------------ | ------------------------------------- | | `number` * | String | The phone number that was dipped | ALL | | `lrn` * | String | The Local Routing Number | LRN | | `lrn_activated_at` * | String | ISO8601 Timestamp of when the LRN was activated | LRN | | `enhanced_carrier` | String | | LRN (when enhanced=true) | | `enhanced_carrier_type` | String | | LRN (when enhanced=true) | | `enhanced_city` | String | | LRN (when enhanced=true) | | `enhanced_zip_code` | String | | LRN (when enhanced=true) | | `enhanced_county` | String | | LRN (when enhanced=true) | | `enhanced_timezone` | String | | LRN (when enhanced=true) | | `enhanced_state` | String | | LRN (when enhanced=true) | | `enhanced_rate_center` | String | | LRN (when enhanced=true) | | `enhanced_lata` | String | | LRN (when enhanced=true) | | `enhanced_ocn` | String | | LRN (when enhanced=true) | | `enhanced_country_code` | String | | LRN (when enhanced=true) | | `messaging_enabled` | String | Is the number messaging capable? | LRN (when messaging_lookup=true), MCL | | `messaging_provider` | String | | LRN (when messaging_lookup=true), MCL | | `messaging_country` | String | | LRN (when messaging_lookup=true), MCL | | `messaging_country_code` | String | ISO Country Code (e.g. US) | LRN (when messaging_lookup=true), MCL | | `messaging_reference_id` | String | Tychron Assigned Internal ID | LRN (when messaging_lookup=true), MCL | | `cnam` | String | The Caller ID result | CNAM | | `spam_type` | String | Spam type hint | CNAM | | `cdr_id` | String | The CDR for the row, can be empty if there is an error | ALL | | `errors` | String | A semi-colon separated list of error codes | ALL | Note that depending on the Dip Type, some fields may be omitted or included in the file. For example if LRN is performed without enhanced and messaging_lookup, it will look like this: __CSV__ ```csv number,lrn,cdr_id,errros 12003004000,12003004001,01GFRKXW88KFERW32T79AGZXHE, ``` __MLJSON__ ```json {"number":"12003004000","lrn":"12003004001","cdr_id":"01GFRKXW88KFERW32T79AGZXHE","errors":""} ``` But, if enhanced was enabled: __CSV__ ```csv number,lrn,enhanced_carrier,enhanced_carrier_type,enhanced_city,enhanced_zip_code,enhanced_county,enhanced_timezone,enhanced_state,enhanced_rate_center,enhanced_lata,enhanced_ocn,cdr_id,errors ``` A keen eye may realize that this mostly a 1:1 mapping with the existing CNAM, LRN, and MCL APIs, without sub objects. __Carrier Types__ | Value | Description | | -------- | ------------------------------------------------- | | ILEC | Incumbent Local Exchange Carrier | | ICO | Independent Telephone Company | | ULEC | Unbundled Local Exchange Carrier | | RBOC | Regional Bell Operating Company | | CLEC | Competitive Local Exchange Carrier | | CAP | Competitive Access Provider | | IXC | Inter-exchange Carrier | | WRSL | Wireless Reseller | | IPES | Internet Protocol Enabled Services | | ETHX | Ethernet Exchange | | INTL | International Telecommunications Service Provider | | LRSL | Local Reseller | | WIRELESS | Wireless | | PCS | Personal Communications Service | | PCSR | Personal Communications Service Reseller | | PAGING | Paging and messaging | ### Errors * `account_balance_insufficient` - the dip was aborted because the parent account did not have a sufficient balance to perform it ### Protocols While the protocols were covered in the Open API spec, this section will give some additional details on each field present in the OnDoneAction. #### Archive Format __Required__ NO In case an archive containing the final file is needed, an archive format can be specified for the specific action. The file will be the only content of that archive. For example, if `ZIP` is requested, a `.zip` file will be uploaded to the specified path, or sent via the specified channel. Without an Archive Format, the file will be uploaded as is. #### Auth Method, Auth Identity, Auth Secret As with most webhook formats, some form of Authorization fields are provided. Auth Method denotes what kind of authorization should be done (if any), while Auth Identity and Auth Secret act as the username and password respectively. Basic uses both, and Bearer only uses the Auth Secret. Some protocols may not support both method/schemes, in those cases the missing value will be a placeholder, the client is expected to ignore the placeholder. HTTP supports both, while SFTP only works with Basic, the username will be a placeholder. #### Protocol & Data Protocol and Data denote, how and where a notification or file should be uploaded. If one is familiar with the switch, the protocol and data here should feel right at home. * `HTTP` - `http://example.com:port/path/to/upload?query_params#fragment` the url will be maintained as given. * `SFTP` - `sftp://example.com:port/path/to/upload` - sftp is special in that it will be deconstructed into host:port finally the SFTP client will change directories to the specified path component. #### Reference ID Unlike the parent record (BulkDipTask), the reference id here is optional, it is provided for the client to identify a specific action that may be causing problems with delivery. #### Type Type denotes what kind of action will be taken, either NONE, NOTIFY or SEND. NONE is effectively a no-op, the action will be marked as completed regardless. NOTIFY will only tell the endpoint that the dip was completed. SEND will attempt to upload the completed file or archive to the endpoint. #### Status Status provides a rough overview of the current state of the action. * `NEW` means the action hasn't been executed yet * `REJECTED` generally happens before any dipping is performed in case the source data has errors * `ERROR` can either be a permanent error or a temporary error * `COMPLETED` the action was completed successfully # Call Data Webhooks ## Schema 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`](#desc-225) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-226) | | `auth_name` | String | [Desc. `auth_name`](#desc-227) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-228) | | `custom_headers` | Array:[SubObject](#type-229) | [Desc. `custom_headers`](#desc-230) | | `custom_query_params` | Array:[SubObject](#type-231) | [Desc. `custom_query_params`](#desc-232) | | `data` | String | [Desc. `data`](#desc-233) | | `id` | String(format:ulid) | [Desc. `id`](#desc-234) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..255) | [Desc. `name`](#desc-235) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-236) | | `protocol` | Enum(`NONE`, `HTTP`, `SFTP`):String | [Desc. `protocol`](#desc-237) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `auth_identity` {#desc-225} Acts a the username in an authorization pair, only applicable if the auth method is `BASIC`. #### Desc. `auth_method` {#desc-226} 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 ` 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 ` header will be set * with `SFTP` - the username will be a placeholder value and the password will be set #### Desc. `auth_name` {#desc-227} Reserved for other protocols that may require additional auth information. #### Desc. `auth_secret` {#desc-228} Acts as the password in an authorization pair, if using `BEARER`, it will be the verbatim token. #### SubObject {#type-229} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ------ | ----------- | | `key` | String | | | `value` | String | | #### Desc. `custom_headers` {#desc-230} 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-231} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ------ | ----------- | | `key` | String | | | `value` | String | | #### Desc. `custom_query_params` {#desc-232} 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-233} 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-234} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `name` {#desc-235} A display name for the call data webhook, used purely for identifying it. #### Desc. `notes` {#desc-236} Any notes or details about the call data webhook. #### Desc. `protocol` {#desc-237} 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" } ``` ## Summary CallDataWebhooks are an experimental feature for delivering your CallData or CDR records in realtime to a specified endpoint. At the moment only SMS and MMS CDRs are supported. ## API ### Create Call Data Webhook ```http POST /api/v1/call_data_webhooks HTTP/1.1 ``` Create a new CDR Webhook. You are limited to one cdr webhook record per-account. #### Request application/json ```http POST /api/v1/call_data_webhooks HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 482 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 621 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update Call Data Webhook ```http POST /api/v1/call_data_webhooks HTTP/1.1 ``` Create a new CDR Webhook. You are limited to one cdr webhook record per-account. #### Request application/json ```http POST /api/v1/call_data_webhooks HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 482 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 621 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Call Data Webhook ```http POST /api/v1/call_data_webhooks HTTP/1.1 ``` Create a new CDR Webhook. You are limited to one cdr webhook record per-account. #### Request application/json ```http POST /api/v1/call_data_webhooks HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 482 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 621 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Call Data Webhooks ```http POST /api/v1/call_data_webhooks HTTP/1.1 ``` Create a new CDR Webhook. You are limited to one cdr webhook record per-account. #### Request application/json ```http POST /api/v1/call_data_webhooks HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 482 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 621 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Get Call Data Webhook ```http POST /api/v1/call_data_webhooks HTTP/1.1 ``` Create a new CDR Webhook. You are limited to one cdr webhook record per-account. #### Request application/json ```http POST /api/v1/call_data_webhooks HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 482 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 621 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ## Webhook As this feature is a delivery configuration, it will forward or upload the respective CDR to the configured endpoint. In both the HTTP and SFTP protocols, a standard CDR response is sent or uploaded. The choice to use the same CDR format is to simplify implementation, as the structure should be familiar. ### HTTP #### Request ```http POST http://example.com/configured/path HTTP/1.1 Content-Type: application/json ``` A single call data record __Type__ Object | Name | Type | Description | | --------------- | ------------------------------------------ | ---------------------------------- | | `fees` | Array:[CDRFee](#schema-cdrfee) | | | `host_number` | String | [Desc. `host_number`](#desc-238) | | `id` | String(format:ulid) | [Desc. `id`](#desc-239) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `item_count` | Integer | [Desc. `item_count`](#desc-240) | | `item_id` | String | [Desc. `item_id`](#desc-241) | | `remote_number` | String | [Desc. `remote_number`](#desc-242) | | `sell_rate` | String(format:decimal) | [Desc. `sell_rate`](#desc-243) | | `status` | [Enum](#enum-244):String | Main status of the CDR | | `subtype` | [Enum](#enum-245):String | [Desc. `subtype`](#desc-246) | | `surcharges` | Array:[CDRSurcharge](#schema-cdrsurcharge) | | | `total` | String(format:decimal) | [Desc. `total`](#desc-247) | | `type` | [Enum](#enum-248):String | [Desc. `type`](#desc-249) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `host_number` {#desc-238} Depending on the CDR type, this can be an actual phone number or some other value #### Desc. `id` {#desc-239} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `item_count` {#desc-240} How many items does this CDR actually represent #### Desc. `item_id` {#desc-241} Depending on the CDR type, this will be the id of another record #### Desc. `remote_number` {#desc-242} Depending on the CDR type, this can be an actual phone number or some other value #### Desc. `sell_rate` {#desc-243} The base rate (no fees or surcharges), already includes the count #### Enum Values status {#enum-244} Allowed values * `UNKNOWN` * `OK` * `MISS` * `ERROR` * `REFUND` * `NO_ANSWER` * `BUSY` * `CANCELLED` * `CHANNEL_UNAVAILABLE` * `CONGESTION` * `TEMP_FAILURE` #### Enum Values subtype {#enum-245} 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-246} Further refines the CDR type, depending on what the #### Desc. `total` {#desc-247} The total amount charged (sell_rate+fees+surcharges) #### Enum Values type {#enum-248} Allowed values * `API` * `MMS` * `SMS` * `VOICE` * `BALANCE` * `MISC` #### Desc. `type` {#desc-249} 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" } ``` #### Response Any 2xx status is accepted, but it's recommended to send a 204 status back once received. Any other status will trigger a redelivery of the event. ```http HTTP/1.1 204 No Content ``` ### SFTP There is no real example for SFTP, however a file in the form `cdr-ID.json` will be uploaded at the path, where ID is replaced with the ID of the CDR. The format is the same as the HTTP Request CDR format. # Secret Keys ## Schema An set of authorization details for various APIs __Type__ Object | Name | Type | Description | | ------------- | -------------------------------------------- | ------------------------------ | | `id` | String(format:uuid) | [Desc. `id`](#desc-250) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](#desc-251) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-252) | | `size` | Enum(`16`, `24`, `32`, `48`, `64`):Number | [Desc. `size`](#desc-253) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `usage` | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](#desc-254) | #### Desc. `id` {#desc-250} A Universally unique identifier, which identifies the resource #### Desc. `name` {#desc-251} A friendly name to identify the Secret Key #### Desc. `notes` {#desc-252} Any notes about the Secret Key, like, what it is used for, or other sharable details. #### Desc. `size` {#desc-253} 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-254} 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" } ``` ## Summary ## Where are my secrets? Similar to API Keys, once a SecretKey is created, its `data` is returned once, all subsequent requests afterwards do not return the `data`. ## API ### Create Secret Key __Data__ | Name | Type | Description | | ------- | -------------------------------------------- | -------------------------- | | `name` | String(3..255) | [Desc. `name`](#desc-255) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-256) | | `size` | Enum(`16`, `24`, `32`, `48`, `64`):Number | [Desc. `size`](#desc-257) | | `usage` | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](#desc-258) | #### Desc. `name` {#desc-255} A friendly name to identify the Secret Key #### Desc. `notes` {#desc-256} Any notes about the Secret Key, like, what it is used for, or other sharable details. #### Desc. `size` {#desc-257} 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-258} 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. ```http POST /api/v1/secret_keys HTTP/1.1 ``` Create a new Secret Key. Note that newly created Secret Keys will return their secrets, however all subsequent GET requests will not contain the secrets. #### Request application/json ```http POST /api/v1/secret_keys HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 196 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 367 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update Secret Key __Data__ | 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 | ```http PATCH /api/v1/secret_keys/{id} HTTP/1.1 ``` Update an existing Secret Key __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------- | | id | String(format:uuid)! | Secret Key ID | #### Request application/json ```http PATCH /api/v1/secret_keys/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 108 ``` ```json { "data": { "active": false, "name": "string", "notes": "string" }, "type": "secret_key" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Secret Key ```http DELETE /api/v1/secret_keys/{id} HTTP/1.1 ``` Delete an Secret Key. Note that an Secret Key cannot be deleted if it is still associated with any Switches. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------- | | id | String(format:uuid)! | Secret Key ID | #### Request ```http DELETE /api/v1/secret_keys/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Secret Keys ```http GET /api/v1/secret_keys HTTP/1.1 ``` Retrieve Secret Keys allocated for this account. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-259) | | last | Integer | [Query Desc. last](#desc-260) | | after | String | [Query Desc. after](#desc-261) | | before | String | [Query Desc. before](#desc-262) | #### Query Desc. first {#desc-259} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-260} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-261} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-262} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/secret_keys HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 554 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Secret Key ```http GET /api/v1/secret_keys/{id} HTTP/1.1 ``` Lookup an Secret Key by its ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------- | | id | String(format:uuid)! | Secret Key ID | #### Request ```http GET /api/v1/secret_keys/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach Secret Key to Switch as MMS Encryption Key ```http PUT /api/v1/switches/{switch_id}/mms_encryption_key/{id} HTTP/1.1 ``` Attach a Secret Key to a Switch for MMS Encryption. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ------------- | | switch_id | String(format:uuid)! | Switch ID | | id | String(format:uuid)! | Secret Key ID | #### Request application/json ```http PUT /api/v1/switches/{switch_id}/mms_encryption_key/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 75 ``` ```json { "data": { "mms_encryption_method": "NONE" }, "type": "switch" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach MMS Encryption Key from Switch ```http DELETE /api/v1/switches/{switch_id}/mms_encryption_key HTTP/1.1 ``` Detach Secret Key from Switch used for MMS Encryption. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ----------- | | switch_id | String(format:uuid)! | Switch ID | #### Request ```http DELETE /api/v1/switches/{switch_id}/mms_encryption_key HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach Secret Key to Switch as MMS Signing Key ```http PUT /api/v1/switches/{switch_id}/mms_signing_key/{id} HTTP/1.1 ``` Attach a Secret Key to a Switch for MMS Signing. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ------------- | | switch_id | String(format:uuid)! | Switch ID | | id | String(format:uuid)! | Secret Key ID | #### Request application/json ```http PUT /api/v1/switches/{switch_id}/mms_signing_key/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 104 ``` ```json { "data": { "mms_signing_hash": "NONE", "mms_signing_scheme": "NONE" }, "type": "switch" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach MMS Signing Key from Switch ```http DELETE /api/v1/switches/{switch_id}/mms_signing_key HTTP/1.1 ``` Detach Secret Key from Switch used for MMS Signing. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ----------- | | switch_id | String(format:uuid)! | Switch ID | #### Request ```http DELETE /api/v1/switches/{switch_id}/mms_signing_key HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach Secret Key to Switch as SMS Encryption Key ```http PUT /api/v1/switches/{switch_id}/sms_encryption_key/{id} HTTP/1.1 ``` Attach a Secret Key to a Switch for SMS Encryption. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ------------- | | switch_id | String(format:uuid)! | Switch ID | | id | String(format:uuid)! | Secret Key ID | #### Request application/json ```http PUT /api/v1/switches/{switch_id}/sms_encryption_key/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 75 ``` ```json { "data": { "sms_encryption_method": "NONE" }, "type": "switch" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach SMS Encryption Key from Switch ```http DELETE /api/v1/switches/{switch_id}/sms_encryption_key HTTP/1.1 ``` Detach Secret Key from Switch used for SMS Encryption. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ----------- | | switch_id | String(format:uuid)! | Switch ID | #### Request ```http DELETE /api/v1/switches/{switch_id}/sms_encryption_key HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach Secret Key to Switch as SMS Signing Key ```http PUT /api/v1/switches/{switch_id}/sms_signing_key/{id} HTTP/1.1 ``` Attach a Secret Key to a Switch for SMS Signing. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ------------- | | switch_id | String(format:uuid)! | Switch ID | | id | String(format:uuid)! | Secret Key ID | #### Request application/json ```http PUT /api/v1/switches/{switch_id}/sms_signing_key/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 104 ``` ```json { "data": { "sms_signing_hash": "NONE", "sms_signing_scheme": "NONE" }, "type": "switch" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach SMS Signing Key from Switch ```http DELETE /api/v1/switches/{switch_id}/sms_signing_key HTTP/1.1 ``` Detach Secret Key from Switch used for SMS Signing. __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ----------- | | switch_id | String(format:uuid)! | Switch ID | #### Request ```http DELETE /api/v1/switches/{switch_id}/sms_signing_key HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 345 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Switches ## Schema Switches contain the routing information for dids __Type__ Object | Name | Type | Description | | ----------------------- | -------------------------------------------------------- | --------------------------------------- | | `notes` | String | Any notes about the switch | | `sms_secret` | String | [Desc. `sms_secret`](#desc-263) | | `mms_signing_scheme` | [SwitchSigningScheme](#schema-switchsigningscheme) | | | `voice_data` | String | [Desc. `voice_data`](#desc-264) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `sms_data` | String | [Desc. `sms_data`](#desc-265) | | `sms_signing_scheme` | [SwitchSigningScheme](#schema-switchsigningscheme) | | | `voice_protocol` | [Enum](#enum-266):String | [Desc. `voice_protocol`](#desc-267) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `mms_options` | `mms_options` | [Desc. `mms_options`](#desc-268) | | `sms_message_format` | [Enum](#enum-269):String | [Desc. `sms_message_format`](#desc-270) | | `mms_message_format` | [Enum](#enum-271):String | [Desc. `mms_message_format`](#desc-272) | | `voice_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `voice_auth_method`](#desc-273) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-274) | | `name` | String | [Desc. `name`](#desc-275) | | `sms_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `sms_auth_method`](#desc-276) | | `mms_secret` | String | [Desc. `mms_secret`](#desc-277) | | `mms_identity` | String | Acts as the username in basic auth | | `sms_enabled` | Boolean | [Desc. `sms_enabled`](#desc-278) | | `mms_encryption_method` | [SwitchEncryptionMethod](#schema-switchencryptionmethod) | | | `voice_enabled` | Boolean | [Desc. `voice_enabled`](#desc-279) | | `sms_signing_hash` | [SwitchSigningHash](#schema-switchsigninghash) | | | `sms_encryption_method` | [SwitchEncryptionMethod](#schema-switchencryptionmethod) | | | `voice_identity` | String | | | `mms_name` | String | [Desc. `mms_name`](#desc-280) | | `mms_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `mms_auth_method`](#desc-281) | | `mms_protocol` | [Enum](#enum-282):String | [Desc. `mms_protocol`](#desc-283) | | `voice_name` | String | | | `voice_secret` | String | | | `sms_name` | String | Reserved for future use | | `mms_signing_hash` | [SwitchSigningHash](#schema-switchsigninghash) | | | `mms_data` | String(format:url) | [Desc. `mms_data`](#desc-284) | | `sms_protocol` | [Enum](#enum-285):String | [Desc. `sms_protocol`](#desc-286) | | `sms_identity` | String | Acts as the username in basic auth | | `sms_options` | `sms_options` | [Desc. `sms_options`](#desc-287) | | `id` | String(format:uuid) | [Desc. `id`](#desc-288) | #### Desc. `sms_secret` {#desc-263} 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-264} Contains the routing url specific to the requested protocol #### Desc. `sms_data` {#desc-265} 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-266} Allowed values * `NONE` * `VOIP` * `PSTN` * `TTS` * `TTS_CUSTOM` * `HTTP_ROUTE` #### Desc. `voice_protocol` {#desc-267} All protocols supported for fallback VoIP destination. #### Desc. `mms_options` {#desc-268} Contains various miscelleanous or experimental feature flags for MMS. #### Enum Values sms_message_format {#enum-269} Allowed values * `TRINITY_JSON_1_0` * `TRINITY_POST_1_0` * `TRINITY_POST_2_0` #### Desc. `sms_message_format` {#desc-270} All supported message formats for SMS HTTP Protocol #### Enum Values mms_message_format {#enum-271} 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-272} All supported message formats for MMS HTTP Protocol. #### Desc. `voice_auth_method` {#desc-273} Various authorization methods supported. Primarily used with HTTP ROUTE #### Desc. `mms_enabled` {#desc-274} Enable inbound MMS routing? #### Desc. `name` {#desc-275} A display name to easily identify the switch #### Desc. `sms_auth_method` {#desc-276} 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-277} 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-278} Enable inbound SMS routing? #### Desc. `voice_enabled` {#desc-279} Enable voice call fallback routing? #### Desc. `mms_name` {#desc-280} Only used for MM4, used as the display name for auth #### Desc. `mms_auth_method` {#desc-281} 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-282} Allowed values * `NONE` * `MM4` * `HTTP` * `SFTP` * `FORWARD` * `TYCHRON_CHAT` #### Desc. `mms_protocol` {#desc-283} 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-284} 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-285} Allowed values * `NONE` * `SMPP` * `HTTP` * `FORWARD` * `TYCHRON_CHAT` #### Desc. `sms_protocol` {#desc-286} 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-287} Contains various miscelleanous or experimental feature flags for SMS. #### Desc. `id` {#desc-288} A Universally unique identifier, which identifies the resource __mms_options__ | Name | Type | Description | | ---------------- | ------- | ----------------------------------- | | `dlr_on_sent` | Boolean | [Desc. `dlr_on_sent`](#desc-289) | | `forward_dlr` | Boolean | [Desc. `forward_dlr`](#desc-290) | | `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](#desc-291) | #### Desc. `dlr_on_sent` {#desc-289} 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-290} 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-291} 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`](#desc-292) | | `forward_dlr` | Boolean | [Desc. `forward_dlr`](#desc-293) | | `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](#desc-294) | #### Desc. `dlr_on_sent` {#desc-292} 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-293} 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-294} 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" } ``` ## Summary Receiving messages are briefly covered in the Tychron Docs under the SMS and MMS sections respectively. However there is a lot more available than what the basic documentation covers. ## API ### Create Switch ```http POST /api/v1/switches HTTP/1.1 ``` Create a new Switch. The only required parameter to create a new switch is its name, all other options can be left empty or nil. #### Request application/json ```http POST /api/v1/switches HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 1126 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update Switch ```http PATCH /api/v1/switches/{id} HTTP/1.1 ``` Update an existing Switch. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | Switch ID | #### Request application/json ```http PATCH /api/v1/switches/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 1126 ``` ```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" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Switch ```http DELETE /api/v1/switches/{id} HTTP/1.1 ``` Delete an existing Switch. A switch cannot be deleted if it is still attached to one or more numbers. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | Switch ID | #### Request ```http DELETE /api/v1/switches/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Switches ```http GET /api/v1/switches HTTP/1.1 ``` Retrieve a list of switches provisioned on the account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-295) | | last | Integer | [Query Desc. last](#desc-296) | | after | String | [Query Desc. after](#desc-297) | | before | String | [Query Desc. before](#desc-298) | #### Query Desc. first {#desc-295} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-296} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-297} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-298} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/switches HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 2193 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Switch ```http GET /api/v1/switches/{id} HTTP/1.1 ``` Lookup a switch by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | Switch ID | #### Request ```http GET /api/v1/switches/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach Messaging Switch to DID ```http PUT /api/v1/numbers/{number_id}/messaging_switch/{id} HTTP/1.1 ``` Change or set a Number's Messaging Switch __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ------------ | | number_id | String! | Number or ID | | id | String(format:uuid)! | Switch ID | #### Request ```http PUT /api/v1/numbers/{number_id}/messaging_switch/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach VoIP Fallback Switch to DID ```http PUT /api/v1/numbers/{number_id}/voice_switch/{id} HTTP/1.1 ``` Change or set a Number's Voice Switch __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | ------------ | | number_id | String! | Number or ID | | id | String(format:uuid)! | Switch ID | #### Request ```http PUT /api/v1/numbers/{number_id}/voice_switch/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach Messaging Switch From DID ```http DELETE /api/v1/numbers/{number_id}/messaging_switch HTTP/1.1 ``` Removes the Messaging Switch on a specified Number __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | #### Request ```http DELETE /api/v1/numbers/{number_id}/messaging_switch HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach VoIP Fallback Switch From DID ```http DELETE /api/v1/numbers/{number_id}/voice_switch HTTP/1.1 ``` Removes the Voice Switch on a specified Number __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | #### Request ```http DELETE /api/v1/numbers/{number_id}/voice_switch HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1768 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ## Components ### SMS #### Protocols SMS offers two major delivery protocols, SMPP and HTTP. ##### SMPP SMPP, short for Short-Message-Peer-To-Peer-Protocol is the industry standard for transporting SMS across the internet. Tychron offers an SMSC (that is a Short-Message-Service-Center) for clients to connect to using their ESME. SMPP has the benefit of keeping persistent connection up making for high-throughput messaging. However, it can be quite cumbersome to work with, some features that are provided by the HTTP protocol are also omitted, for example UDH (i.e. concatentated messages) will be transported in their raw split form over SMPP, but will be transported whole (i.e. all message parts) at once to HTTP. Clients are then required to combine message parts back together to form the entire message in SMPP, while HTTP has this done by the system already. ##### HTTP HTTP, short for Hypertext-Transfer-Protocol allows delivering SMS messages over HTTP instead of SMPP. Relatively easy to setup and utilize, the HTTP protocol will deliver sms messages and their delivery reports to a specified endpoint in a [variety of formats](SMS/Message+Formats). #### Message Formats Message formats only apply to HTTP Protocol messages. ##### Trinity JSON 1.0 The default format that will be delivered by the system to the client, this is also the format present on the Tychron Docs page. ##### Trinity POST 1.0 A compatability format. ##### Trinity POST 2.0 A compatability format. ### MMS #### Protocols ##### MM4 MM4, effectively a superset of Simple Mail Transfer Protocol is the industry standard for transferring MMS messages between MMSC (Multimedia-Message-Service-Center) relays. ##### HTTP Delivers MMS messages over HTTP in a variety of message formats. #### Message Formats Message formats only apply to HTTP Protocol messages. ##### Oxy JSON 1.0 The default format that will be delivered by the sytsem to the lcient, this is also the format present on the Tychron Docs page. ##### Oxy JSONAPI 1.0 A compatability format, similar to the standard `Oxy JSON 1.0` format. ##### Oxy XML 1.0 Experimental format, sends MMS messages as XML documents. ##### Oxy MULTIPART 1.0 Experimental format, sends MMS messages as HTTP multipart documents. ##### Oxy RFC822 1.0 Experimental format, sends MMS messages as their raw RFC822 blob ### Voice Switches may enable and provide a Voice fallback destination, this destination will be used as a last resort if the DID's destinations fail to answer. #### Protocols ##### PSTN PSTN sometimes called RCF (remote call forward) can be used to route a call to another phone number. ##### VoIP VoIP routes a call to a SIP capable server to handle the call. ##### TTS TTS will play a built-in message back when answered, note that TTS calls will not incur additional charges unlike it's Custom counterpart. ##### TTS Custom TTS Custom allows the client to set a special message that should be played back to the caller. Note that TTS Custom messages attract a per-character fee everytime the message is played, contact support for more information on these fees. ##### HTTP Route HTTP Route allows the system to request a custom route from an HTTP Server, this route can be any of the other Voice protocols. See DID Destination HTTP Routes for more information. # Messaging Auto Responses ## Schema Messaging Auto Response __Type__ Object | Name | Type | Description | | ------------- | ---------------------------- | --------------------------------- | | `id` | String(format:uuid) | [Desc. `id`](#desc-299) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `keywords` | Array:[SubObject](#type-305) | [Desc. `keywords`](#desc-306) | | `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-299} A Universally unique identifier, which identifies the resource #### SubObject {#type-305} Sub-Schema __Type__ Object | Name | Type | Description | | ------------- | ------- | -------------------------------- | | `intercept` | Boolean | [Desc. `intercept`](#desc-300) | | `is_wildcard` | Boolean | [Desc. `is_wildcard`](#desc-301) | | `keyword` | String | [Desc. `keyword`](#desc-302) | | `message` | String | [Desc. `message`](#desc-303) | | `message2` | String | [Desc. `message2`](#desc-304) | #### Desc. `intercept` {#desc-300} 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-301} 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-302} The word to trigger this specific keyword. Note that when is_wildcard is true, keyword will always be `WILDCARD`. #### Desc. `message` {#desc-303} 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-304} 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-306} 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" } ``` ## Summary User customizable keyword plans, or auto responder. ## API ### Create Messaging Auto Response ```http POST /api/v1/auto_responses HTTP/1.1 ``` Create a new Messaging Auto Response. #### Request application/json ```http POST /api/v1/auto_responses HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 551 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 700 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update Messaging Auto Response ```http PATCH /api/v1/auto_responses/{id} HTTP/1.1 ``` Update an existing Messaging Auto Response __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | Messaging Auto Response ID | #### Request application/json ```http PATCH /api/v1/auto_responses/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 551 ``` ```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" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 700 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Messaging Auto Response ```http DELETE /api/v1/auto_responses/{id} HTTP/1.1 ``` Delete an existing Messaging Auto Response by ID. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | Messaging Auto Response ID | #### Request ```http DELETE /api/v1/auto_responses/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 700 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Messaging Auto Responses ```http GET /api/v1/auto_responses HTTP/1.1 ``` Retrieve all Messaging Auto Responses for Account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-307) | | last | Integer | [Query Desc. last](#desc-308) | | after | String | [Query Desc. after](#desc-309) | | before | String | [Query Desc. before](#desc-310) | #### Query Desc. first {#desc-307} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-308} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-309} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-310} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/auto_responses HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 937 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Messaging Auto Response ```http GET /api/v1/auto_responses/{id} HTTP/1.1 ``` Lookup an Messaging Auto Response by its ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | Messaging Auto Response ID | #### Request ```http GET /api/v1/auto_responses/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 700 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Attach Messaging Auto Response to DID ```http PUT /api/v1/numbers/{number_id}/auto_response/{id} HTTP/1.1 ``` Change or set a Number's Messaging Auto Response __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | -------------------------- | | number_id | String! | Number or ID | | id | String(format:uuid)! | Messaging Auto Response ID | #### Request ```http PUT /api/v1/numbers/{number_id}/auto_response/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 700 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Detach Messaging Auto Response from DID ```http DELETE /api/v1/numbers/{number_id}/auto_response HTTP/1.1 ``` Removes the Messaging Auto Response on a specified Number __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | #### Request ```http DELETE /api/v1/numbers/{number_id}/auto_response HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 700 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # DIDs ## Schema A provisioned did __Type__ Object | Name | Type | Description | | ------------------------ | --------------------------------- | ---------------------------------------- | | `activated` | Boolean | [Desc. `activated`](#desc-311) | | `brand_name` | String(0..255) | [Desc. `brand_name`](#desc-312) | | `description` | String | [Desc. `description`](#desc-313) | | `forward_number` | String | [Desc. `forward_number`](#desc-314) | | `help_message` | String(0..255) | [Desc. `help_message`](#desc-315) | | `id` | String(format:uuid) | [Desc. `id`](#desc-316) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `message_class` | Enum(`NONE`, `A2P`, `P2P`):String | | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-317) | | `number` | String | [Desc. `number`](#desc-318) | | `rate_center` | String | | | `segment_overrides` | Array:[SubObject](#type-323) | [Desc. `segment_overrides`](#desc-324) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](#desc-325) | | `sms_enabled` | Boolean | [Desc. `sms_enabled`](#desc-326) | | `state` | String | | | `tier` | [Enum](#enum-327):String | [Desc. `tier`](#desc-328) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `upgrade_asset_handling` | [Enum](#enum-329):String | The asset handling flag for SMS Upgrades | | `voice_enabled` | Boolean | [Desc. `voice_enabled`](#desc-330) | #### Desc. `activated` {#desc-311} Is the DID active for use? #### Desc. `brand_name` {#desc-312} 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-313} Any notes to attach to the number. #### Desc. `forward_number` {#desc-314} 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-315} 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-316} A Universally unique identifier, which identifies the resource #### Desc. `mms_enabled` {#desc-317} Whether or not the number is MMS capable, does not affect SMS or SMS to MMS upgrades. #### Desc. `number` {#desc-318} The 3 to 15 digit code of the number. #### SubObject {#type-323} Sub-Schema __Type__ Object | Name | Type | Description | | --------------------- | ------------------- | ---------------------------------------- | | `encoding` | Integer | [Desc. `encoding`](#desc-319) | | `id` | String(format:uuid) | [Desc. `id`](#desc-320) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](#desc-321) | | `target_reference_id` | String | [Desc. `target_reference_id`](#desc-322) | #### Desc. `encoding` {#desc-319} The SMS encoding that this override should trigger on. #### Desc. `id` {#desc-320} The UUID of the specific segment override, required when changing an existing override. #### Desc. `segment_threshold` {#desc-321} See number's segment_threshold for more information. #### Desc. `target_reference_id` {#desc-322} 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: _ Example: us_tmobile ca_rogers dm_digicel #### Desc. `segment_overrides` {#desc-324} 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-325} 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-326} Whether or not a number is messaging capable. Note that this flag also affects mms availability. #### Enum Values tier {#enum-327} Allowed values * `L0` * `L1` * `T1` * `T2` * `T3` * `AK` * `HI` * `CAN` * `PR` * `TF` * `SHORTCODE` * `M0` * `M1` * `BYON` #### Desc. `tier` {#desc-328} 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-329} Allowed values * `FALLBACK` * `OFF` * `ALWAYS_UPGRADE` * `SEGMENT_UPGRADE` #### Desc. `voice_enabled` {#desc-330} 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 } ``` ## Summary DIDs, or Numbers represent a Longcode (10DLC, Tollfree, International), Shortcode or Sender ID. They are the primary resource for messaging and VoIP operations. ## API ### Update DID ```http PATCH /api/v1/numbers/{id} HTTP/1.1 ``` Update some features on the specified number. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------ | | id | String(format:uuid)! | Number or ID | #### Request application/json ```http PATCH /api/v1/numbers/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 505 ``` ```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" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1209 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List DIDs ```http GET /api/v1/numbers HTTP/1.1 ``` Retrieve a list of numbers provisioned on the account. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-331) | | last | Integer | [Query Desc. last](#desc-332) | | after | String | [Query Desc. after](#desc-333) | | before | String | [Query Desc. before](#desc-334) | #### Query Desc. first {#desc-331} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-332} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-333} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-334} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/numbers HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1546 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get DID ```http GET /api/v1/numbers/{id} HTTP/1.1 ``` Lookup a number by ID or it's number __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------ | | id | String(format:uuid)! | Number or ID | #### Request ```http GET /api/v1/numbers/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1209 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Number Management ## Toggling MMS on an existing number MMS is available for any and all sms enabled numbers, as long as the account allows it, it can be toggled at anytime. Toggling MMS can be done via the Numbers update route: __Structure__ ```http PATCH /api/v1/numbers/:number Accept: application/json Content-Type: application/json Authorization: Bearer API_KEY_HTTP_KEY ``` ```javascript { "type": "number", "data": { "mms_enabled": boolean } } ``` __Example 1__ To enable MMS on an existing number: ```http PATCH /api/v1/numbers/12003004000 Accept: application/json Content-Type: application/json Authorization: Bearer API_KEY_HTTP_KEY ``` ```json { "type": "number", "data": { "mms_enabled": true } } ``` __Example 2__ To disable MMS on an existing number: ```http PATCH /api/v1/numbers/12003004000 Accept: application/json Content-Type: application/json Authorization: Bearer API_KEY_HTTP_KEY ``` ```json { "type": "number", "data": { "mms_enabled": false } } ``` # DID Destinations ## Schema A did's voice destination __Type__ Object | Name | Type | Description | | --------------- | -------------------------------------- | ------------------------------------ | | `activated` | Boolean | [Desc. `activated`](#desc-335) | | `auth_identity` | String | The username for a BASIC auth_method | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-336) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-337) | | `destination` | String | [Desc. `destination`](#desc-338) | | `id` | String(format:uuid) | [Desc. `id`](#desc-339) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `priority` | Integer | [Desc. `priority`](#desc-340) | | `type` | [Enum](#enum-341):String | [Desc. `type`](#desc-342) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `wait_time` | Integer | [Desc. `wait_time`](#desc-343) | #### Desc. `activated` {#desc-335} Whether or not the destination is considered for routing #### Desc. `auth_method` {#desc-336} The authorization method to used for HTTP_ROUTE destinations #### Desc. `auth_secret` {#desc-337} The password for a BASIC auth_method or token for BEARER auth_method #### Desc. `destination` {#desc-338} Depending on the type, this field can contain different data. * `VOIP` - destination should be in the form of `local@domain` where local is the destination prefix and domain is the SIP capable server to handle the request * `PSTN` - destination should be a plain format number (e.g. 12003004000), can also be a comma separated list to allow multiple destinations * `HTTP_ROUTE` - destination should be an http uri which will handle the routing request * `TTS` - destination should be one of the pre-approved values (more may be added in the future): * `DISCONNECTED` * `TEXT_ONLY` * `BUSY` * `CONGESTION` * `TTS_CUSTOM` - destination should be the message to be read * `TTS_MESSAGE_SET` - destination will be set to "UNUSED" regardless of provided value, instead the tts_message_set_id MUST be set on the request #### Desc. `id` {#desc-339} A Universally unique identifier, which identifies the resource #### Desc. `priority` {#desc-340} Affects the ordering of destinations for calls, 1 will be first while 9 is the last #### Enum Values type {#enum-341} Allowed values * `VOIP` * `PSTN` * `HTTP_ROUTE` * `TTS` * `TTS_CUSTOM` * `TTS_MESSAGE_SET` #### Desc. `type` {#desc-342} The destination type, see destination field for more detail #### Desc. `wait_time` {#desc-343} How long will calls wait for the destination to connect. __Example__ ```json { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 } ``` ## Summary While switches control the primary routes for SMS and MMS, "destinations" control the primary routes for Voice calls, with the switch providing the fallback route in case all destinations fail, or there is no destination. Destinations provide many protocols/types and can be prioritized to create dial plans, or destinations can be randomized by setting multiple destinations with the same priority. ## Types Destination types affect the routing of the voice calls. ### PSTN PSTN, also called RCF (Remote Call Forwarding) can be used to route an originating/incoming voice call to another number. Note that PSTN calls will effectively charge for both the incoming and the outgoing leg of the call. __Example__ ``` 12003004000 ``` ### VoIP VoIP allows routing a call via a SIP capable server. __Example__ ``` 12003004000@example.com:5544 ``` ### TTS TTS (Text-To-Speech) is a service provided by Tychron to pre-answer or answer a Voice call with a message. This specific variant is used to play a pre-built message back. __Example__ ``` BUSY ``` ### TTS Custom Same function as __TTS__, but allows the client to set a custom message to be played back. Note that custom messages attract a per-character fee everytime the message is played back, even if the caller hangs up before the message finishes. __Example__ ``` Hello, welcome to ACME Corp, please hold while we connect you to our support team. ``` ### TTS Message Set Message Sets allow using multiple custom messages with customized voices for a tts message, like destinations themselves, these can also have priorities and be randomized. ### HTTP Route HTTP Route destinations will send an HTTP request to the specified endpoint in order to receive the intended voice routing for a call. The HTTP Route request will accept the response for any other non-"HTTP Route" destination. This effectively allows a dynamic programmable dial plan. __Example__ ``` https://example.com/how/to/route/my/call ``` __Note__ responses are allowed to be in JSON (`Content-Type: application/json`) or plain text (`Content-Type: text/plain`). Both require that the Content-Type is explictly set, any other content-types will be ignored and treated as a "SKIP" __Available Types__ * `SKIP` to explictly skip the http route destination, this will move unto the next destination in the dial plan * `PSTN` to route the call to another number * `VOIP` to route the call to a VoIP destination * `TTS` to playback a built-in message * `TTS_CUSTOM` to playback a custom message * `TTS_MESSAGE_SET` to utilize a message set for playback, the message set is specified by id __Request Example__ ```http GET https://example.com/how/to/route/call HTTP/1.1 Accept: application/json, text/plain Content-Type: application/json Content-Length: 164 ``` ```json { "id": "01FS2R0G4N8V0TWS3Z7R9TX33E", "inserted_at": "2022-01-10T14:38:35.000000Z", "from": "12003004000", "to": "12003004001", "direction": "INCOMING" } ``` #### Plain Text responses ```http HTTP/1.1 200 OK Content-Type: text/plain Content-Length: 8 TTS:BUSY ``` Plain text responses follow the format: ``` TYPE:DATA ``` __Example 1__ Built-in TTS messages ``` TTS:BUSY ``` __Example 2__ VoIP destination ``` VOIP:12003004000@example.com:5544 ``` #### JSON Responses ```http HTTP/1.1 200 OK Content-Type: application/json Content-Length: 115 ``` ```json { "type": "http_route_response", "data": { "type": "VOIP", "data": "12003004000@example.com:5544" } } ``` JSON responses can also be used, the root level `type` MUST be `"http_route_response"` otherwise the response will be treated as SKIP. ## API ### Create a DID Destination ```http POST /api/v1/numbers/{number_id}/destinations HTTP/1.1 ``` Create a new Number Destination. __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | #### Request application/json ```http POST /api/v1/numbers/{number_id}/destinations HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 333 ``` ```json { "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "priority": 1, "tts_message_set_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "type": "HTTP_ROUTE" }, "type": "number_destination" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update a DID's Destination ```http PATCH /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 ``` Update a Number's Destination. __Path Parameters__ | Name | Type | Description | | -------------- | -------------------- | ------------ | | number_id | String! | Number or ID | | destination_id | String(format:uuid)! | ID | #### Request application/json ```http PATCH /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 333 ``` ```json { "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "priority": 1, "tts_message_set_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "type": "HTTP_ROUTE" }, "type": "number_destination" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete a DID's Destination ```http DELETE /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 ``` Delete a Number's Destination. __Path Parameters__ | Name | Type | Description | | -------------- | -------------------- | ------------ | | number_id | String! | Number or ID | | destination_id | String(format:uuid)! | ID | #### Request ```http DELETE /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List DID's Destinations ```http GET /api/v1/numbers/{number_id}/destinations HTTP/1.1 ``` Retrieve a list of all api keys bound to the number __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-344) | | last | Integer | [Query Desc. last](#desc-345) | | after | String | [Query Desc. after](#desc-346) | | before | String | [Query Desc. before](#desc-347) | #### Query Desc. first {#desc-344} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-345} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-346} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-347} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/numbers/{number_id}/destinations HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 873 ``` ```json { "count": 1, "page_info": { "first": "string", "has_next_page": true, "has_previous_page": true, "last": "string" }, "results": [ { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Get DID's Destination ```http GET /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 ``` Retrieve a DID Destination associated with the DID by its ID __Path Parameters__ | Name | Type | Description | | --------- | -------------------- | -------------------------- | | number_id | String! | Number or ID | | id | String(format:uuid)! | [Path Desc. id](#desc-348) | #### Path Desc. id {#desc-348} Number ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/numbers/{number_id}/destinations/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 616 ``` ```json { "associations": { "did": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" }, "tts_message_set": { "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48" } }, "data": { "activated": true, "auth_identity": "username", "auth_method": "BASIC", "auth_secret": "password", "destination": "http://example.com/http/route/call", "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48", "inserted_at": "2021-08-13T04:08:44.762841Z", "priority": 1, "type": "HTTP_ROUTE", "updated_at": "2021-08-13T04:08:44.762841Z", "wait_time": 120 }, "type": "number_destination" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # DID - Optout Items ## Schema 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`](#desc-349) | | `id` | String(format:uuid) | [Desc. `id`](#desc-350) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `keyword` | String | [Desc. `keyword`](#desc-351) | | `remote_number` | String | [Desc. `remote_number`](#desc-352) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `host_number` {#desc-349} A reference to the host number that this optout belongs to. That is the number that received the optout request. #### Desc. `id` {#desc-350} A Universally unique identifier, which identifies the resource #### Desc. `keyword` {#desc-351} 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-352} 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" } ``` ## Summary Optout Items control which remote numbers are allowed to be sent to from a host number, subscribers can optout via supported network keywords (e.g. STOP) or optin (e.g. START). ## API ### Create Optout Item ```http POST /api/v1/numbers/{number_id}/optout_items HTTP/1.1 ``` Create a new Number Optout Item. __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | #### Request application/json ```http POST /api/v1/numbers/{number_id}/optout_items HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 120 ``` ```json { "data": { "host_number": "12003004000", "remote_number": "12003004001" }, "type": "number_optout_item" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 484 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Optout Item ```http DELETE /api/v1/optout_items/{id} HTTP/1.1 ``` Delete an existing Number Optout Item by ID. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | [Path Desc. id](#desc-353) | #### Path Desc. id {#desc-353} Optout Item ID A Universally unique identifier, which identifies the resource #### Request ```http DELETE /api/v1/optout_items/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 484 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List all Optout Items ```http GET /api/v1/optout_items HTTP/1.1 ``` Retrieve a list of optouts assigned to the parent account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-354) | | last | Integer | [Query Desc. last](#desc-355) | | after | String | [Query Desc. after](#desc-356) | | before | String | [Query Desc. before](#desc-357) | #### Query Desc. first {#desc-354} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-355} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-356} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-357} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/optout_items HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 725 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List all Optout Items for DID / Number ```http GET /api/v1/numbers/{number_id}/optout_items HTTP/1.1 ``` Retrieve a list of optouts assigned to the parent number __Path Parameters__ | Name | Type | Description | | --------- | ------- | ------------ | | number_id | String! | Number or ID | __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-358) | | last | Integer | [Query Desc. last](#desc-359) | | after | String | [Query Desc. after](#desc-360) | | before | String | [Query Desc. before](#desc-361) | #### Query Desc. first {#desc-358} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-359} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-360} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-361} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/numbers/{number_id}/optout_items HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 725 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Optout Item ```http GET /api/v1/optout_items/{id} HTTP/1.1 ``` Lookup a optout item by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | [Path Desc. id](#desc-362) | #### Path Desc. id {#desc-362} Optout Item ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/optout_items/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 484 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # OSR Overwrite Requests ## Schema 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`](#desc-363) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `is_stale` | Boolean | | | `review_status` | [Enum](#enum-364):String | [Desc. `review_status`](#desc-365) | | `status` | [Enum](#enum-366):String | [Desc. `status`](#desc-367) | | `tn` | String | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `id` {#desc-363} Another format for UUID, used primarily for tasks, requests and messages. #### Enum Values review_status {#enum-364} Allowed values * `NONE` * `APPROVED` * `REJECTED` * `AUTO_APPROVED` * `AUTO_REJECTED` * `FORCE_DELETED` #### Desc. `review_status` {#desc-365} The review status of the request, defaults to NONE. #### Enum Values status {#enum-366} Allowed values * `NEW` * `REVIEWED` * `APPROVED` * `REJECTED` * `ERROR` * `STALE` * `DELETED` #### Desc. `status` {#desc-367} 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" } ``` ## Summary ## API ### Review OSR Overwrite Request ```http POST /api/v1/osr/overwrite_requests/{overwrite_request_id}/review HTTP/1.1 ``` Review an existing Overwrite Request. Note a request that has already been reviewed wil perform a no-op. #### Request application/json ```http POST /api/v1/osr/overwrite_requests/{overwrite_request_id}/review HTTP/1.1 Accept: application/json, Content-Type: application/json Content-Length: 82 ``` ```json { "data": { "review_status": "NONE" }, "type": "osr_overwrite_request" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 741 ``` ```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" } ``` #### Response 204 ##### No Content ```http HTTP/1.1 204 ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List OSR Overwrite Requests ```http GET /api/v1/osr/overwrite_requests HTTP/1.1 ``` Retrieve a list of overwrite requests, latest requests are always first __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-368) | | last | Integer | [Query Desc. last](#desc-369) | | after | String | [Query Desc. after](#desc-370) | | before | String | [Query Desc. before](#desc-371) | #### Query Desc. first {#desc-368} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-369} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-370} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-371} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/osr/overwrite_requests HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1018 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get OSR Overwrite Request ```http GET /api/v1/osr/overwrite_requests/{id} HTTP/1.1 ``` Lookup an Overwrite Request by its ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ------------------------ | | id | String(format:uuid)! | OSR Overwrite Request ID | #### Request ```http GET /api/v1/osr/overwrite_requests/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 741 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # CSP Enums Provided for your convenience are cached versions of TCR's enum values. These caches are guaranteed to be up to date within a minute of any changes. ## Schemas CSP Usecases __Type__ Object | Name | Type | Description | | ---- | -------------------------------- | ----------- | | `*` | [CspUsecase](#schema-cspusecase) | | __Example__ ```json { "*": { "classification": "string", "description": "string", "displayName": "string", "maxSubUsecases": 5, "minSubUsecases": 1, "validSubUsecase": true } } ``` CSP Error Codes __Type__ Object | Name | Type | Description | | ---- | ------ | ----------- | | `*` | String | | __Example__ ```json { "*": "string" } ``` CSP Campaign Statuses __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "ACTIVE" ] ``` CSP Stock Exchanges __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "AMEX" ] ``` CSP MNO Operation Statuses __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "REVIEW" ] ``` CSP Verticals __Type__ Object | Name | Type | Description | | ---- | ---------------------------------- | ----------- | | `*` | [CspVertical](#schema-cspvertical) | | __Example__ ```json { "*": { "description": "Information technology and information services.", "displayName": "Information Technology Services", "industryId": "information-technology-services" } } ``` CSP Vetting Providers __Type__ Array | Name | Type | Description | | ----- | ------------------------------------------------ | ----------- | | `[n]` | [CspVettingProvider](#schema-cspvettingprovider) | | __Example__ ```json [ { "displayName": "Demo Vetting Provider", "evpId": "DEMO_EVP", "tcrBillable": true, "vettingClasses": [ "STANDARD" ], "vettingInstruction": "string" } ] ``` CSP Vetting Classes __Type__ Array | Name | Type | Description | | ----- | ------------------------------------------ | ----------- | | `[n]` | [CspVettingClass](#schema-cspvettingclass) | | __Example__ ```json [ { "description": "string", "displayName": "string", "enabled": true, "id": "string", "validatyMonths": 0.0 } ] ``` CSP MNOs __Type__ Array | Name | Type | Description | | ----- | ---------------------- | ----------- | | `[n]` | [SubObject](#type-372) | MNO | __Example__ ```json [ { "displayName": "string", "networkId": 0.0, "osrBitmaskindex": 0.0 } ] ``` #### SubObject {#type-372} Sub-Schema MNO __Type__ Object | Name | Type | Description | | ----------------- | ------ | ----------- | | `displayName` | String | | | `networkId` | Number | | | `osrBitmaskindex` | Number | | CSP DCAs __Type__ Array | Name | Type | Description | | ----- | ---------------------- | ----------- | | `[n]` | [SubObject](#type-373) | DCA | __Example__ ```json [ { "displayName": "string", "id": "string" } ] ``` #### SubObject {#type-373} Sub-Schema DCA __Type__ Object | Name | Type | Description | | ------------- | ------ | ----------- | | `displayName` | String | | | `id` | String | | CSP Entity Types __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "PRIVATE_PROFIT" ] ``` CSP Brand Relationships __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "BASIC_ACCOUNT" ] ``` CSP Alt Business ID Types __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "NONE" ] ``` CSP Event Categories __Type__ Array | Name | Type | Description | | ----- | ------ | ----------- | | `[n]` | String | | __Example__ ```json [ "string" ] ``` CSP Event Categories __Type__ Object | Name | Type | Description | | ---- | ------ | ----------- | | `*` | String | | __Example__ ```json { "*": "string" } ``` ## API ### List Usecases ```http GET /api/v1/csp/enum/usecases HTTP/1.1 ``` Retrieve #### Request ```http GET /api/v1/csp/enum/usecases HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 184 ``` ```json { "*": { "classification": "string", "description": "string", "displayName": "string", "maxSubUsecases": 5, "minSubUsecases": 1, "validSubUsecase": true } } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Sub-Usecases ```http GET /api/v1/csp/enum/sub_usecases HTTP/1.1 ``` Retrieve #### Request ```http GET /api/v1/csp/enum/sub_usecases HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 184 ``` ```json { "*": { "classification": "string", "description": "string", "displayName": "string", "maxSubUsecases": 5, "minSubUsecases": 1, "validSubUsecase": true } } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Campaign Statuses ```http GET /api/v1/csp/enum/campaign_statuses HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/campaign_statuses HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 14 ``` ```json [ "ACTIVE" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Error Codes ```http GET /api/v1/csp/enum/error_codes HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/error_codes HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 19 ``` ```json { "*": "string" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Vetting Providers ```http GET /api/v1/csp/enum/vetting_providers HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/vetting_providers HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 188 ``` ```json [ { "displayName": "Demo Vetting Provider", "evpId": "DEMO_EVP", "tcrBillable": true, "vettingClasses": [ "STANDARD" ], "vettingInstruction": "string" } ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Stock Exchanges ```http GET /api/v1/csp/enum/stock_exchanges HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/stock_exchanges HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 12 ``` ```json [ "AMEX" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List MNO Operation Statuses ```http GET /api/v1/csp/enum/mno_operation_statuses HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/mno_operation_statuses HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 14 ``` ```json [ "REVIEW" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Verticals ```http GET /api/v1/csp/enum/verticals HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/verticals HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 193 ``` ```json { "*": { "description": "Information technology and information services.", "displayName": "Information Technology Services", "industryId": "information-technology-services" } } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Vetting Classes ```http GET /api/v1/csp/enum/vetting_classes HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/vetting_classes HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 136 ``` ```json [ { "description": "string", "displayName": "string", "enabled": true, "id": "string", "validatyMonths": 0.0 } ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List MNOs ```http GET /api/v1/csp/enum/mnos HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/mnos HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 89 ``` ```json [ { "displayName": "string", "networkId": 0.0, "osrBitmaskindex": 0.0 } ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List DCAs ```http GET /api/v1/csp/enum/dcas HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/dcas HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 59 ``` ```json [ { "displayName": "string", "id": "string" } ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Entity Types ```http GET /api/v1/csp/enum/entity_types HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/entity_types HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 22 ``` ```json [ "PRIVATE_PROFIT" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Brand Relationships ```http GET /api/v1/csp/enum/brand_relationships HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/brand_relationships HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 21 ``` ```json [ "BASIC_ACCOUNT" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Alt-Business ID Types ```http GET /api/v1/csp/enum/alt_business_id_types HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/alt_business_id_types HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 12 ``` ```json [ "NONE" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List Event Categories ```http GET /api/v1/csp/enum/event_categories HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/event_categories HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 14 ``` ```json [ "string" ] ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### List CNPs ```http GET /api/v1/csp/enum/cnps HTTP/1.1 ``` #### Request ```http GET /api/v1/csp/enum/cnps HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 19 ``` ```json { "*": "string" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` # CSP Brands ## Schema 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`](#desc-374) | | `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`](#desc-375) | | `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-374} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `shared` {#desc-375} 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" } ``` ## API ### List CSP Brands ```http GET /api/v1/brands HTTP/1.1 ``` Retrieve a list of brands associated with the account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-376) | | last | Integer | [Query Desc. last](#desc-377) | | after | String | [Query Desc. after](#desc-378) | | before | String | [Query Desc. before](#desc-379) | #### Query Desc. first {#desc-376} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-377} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-378} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-379} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/brands HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1211 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get CSP Brand ```http GET /api/v1/brands/{id} HTTP/1.1 ``` Lookup a Brand by its internal UUID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | [Path Desc. id](#desc-380) | #### Path Desc. id {#desc-380} Brand ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/brands/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 914 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # CSP Campaigns ## Schema A TCR campaign __Type__ Object | Name | Type | Description | | --------------------------- | ------------------------------------- | --------------------------------------- | | `attributes` | `attributes` | | | `dca_approved` | Boolean | [Desc. `dca_approved`](#desc-381) | | `description` | String | Description of the campaign | | `embedded_link_sample` | String | | | `help_keywords` | String | | | `help_message` | String | | | `id` | String(format:ulid) | [Desc. `id`](#desc-382) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `message_flow` | String | | | `name` | String(1..255) | [Desc. `name`](#desc-383) | | `notes` | String | [Desc. `notes`](#desc-384) | | `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`](#desc-385) | | `shared` | Enum(`NO`, `OWNED`, `PARTNER`):String | [Desc. `shared`](#desc-386) | | `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`](#desc-387) | #### Desc. `dca_approved` {#desc-381} Whether or not the campaign has been approved by the DCA #### Desc. `id` {#desc-382} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `name` {#desc-383} 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-384} Any notes about the campaign. In the case of `SHARED` campaigns the notes may always be empty. #### Desc. `sample_messages` {#desc-385} The overall format or example of messages that the campaign will send. Note that different usecases may require more samples. #### Desc. `shared` {#desc-386} 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-387} 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" } ``` ## API ### Share CSP Campaign With Account ```http POST /api/v1/campaigns/{campaign_id}/share_with/accounts/{account_id} HTTP/1.1 ``` Shares the campaign with another account, either by specifying the account id, or the resource group that it should be shared via. __Path Parameters__ | Name | Type | Description | | ----------- | -------------------- | ----------------------------------- | | campaign_id | String(format:uuid)! | [Path Desc. campaign_id](#desc-388) | #### Path Desc. campaign_id {#desc-388} Campaign ID A Universally unique identifier, which identifies the resource #### Request ```http POST /api/v1/campaigns/{campaign_id}/share_with/accounts/{account_id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1674 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 409 ##### application/json ```http HTTP/1.1 409 Content-Type: application/json Content-Length: 217 ``` ```json { "errors": [ { "code": "conflict.changing_shared_resource_group", "detail": "Cannot change shared resource group", "params": {}, "sub_code": "none", "title": "Conflict" } ] } ``` ### Share CSP Campaign With Shared Resource Group ```http POST /api/v1/campaigns/{campaign_id}/share_with/shared_resource_groups/{shared_resource_group_id} HTTP/1.1 ``` Shares the campaign with another account, either by specifying the account id, or the resource group that it should be shared via. __Path Parameters__ | Name | Type | Description | | ----------- | -------------------- | ----------------------------------- | | campaign_id | String(format:uuid)! | [Path Desc. campaign_id](#desc-389) | #### Path Desc. campaign_id {#desc-389} Campaign ID A Universally unique identifier, which identifies the resource #### Request ```http POST /api/v1/campaigns/{campaign_id}/share_with/shared_resource_groups/{shared_resource_group_id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1674 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 409 ##### application/json ```http HTTP/1.1 409 Content-Type: application/json Content-Length: 217 ``` ```json { "errors": [ { "code": "conflict.changing_shared_resource_group", "detail": "Cannot change shared resource group", "params": {}, "sub_code": "none", "title": "Conflict" } ] } ``` ### Unshare CSP Campaign ```http DELETE /api/v1/campaigns/{campaign_id}/shared_resource_group HTTP/1.1 ``` Removes any associated Shared Resource Group from the campaign. Note that if the campaign is inuse (has numbers associated with it), it cannot be removed. __Path Parameters__ | Name | Type | Description | | ----------- | -------------------- | ----------------------------------- | | campaign_id | String(format:uuid)! | [Path Desc. campaign_id](#desc-390) | #### Path Desc. campaign_id {#desc-390} Campaign ID A Universally unique identifier, which identifies the resource #### Request ```http DELETE /api/v1/campaigns/{campaign_id}/shared_resource_group HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1674 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 409 ##### application/json ```http HTTP/1.1 409 Content-Type: application/json Content-Length: 253 ``` ```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" } ] } ``` ### Get CSP Campaign Shared Resource Group ```http GET /api/v1/campaigns/{campaign_id}/shared_resource_group HTTP/1.1 ``` Retrieves the shared resource group associated with the campaign, if any. __Path Parameters__ | Name | Type | Description | | ----------- | -------------------- | ----------------------------------- | | campaign_id | String(format:uuid)! | [Path Desc. campaign_id](#desc-391) | #### Path Desc. campaign_id {#desc-391} Campaign ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/campaigns/{campaign_id}/shared_resource_group HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 433 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List CSP Campaigns ```http GET /api/v1/campaigns HTTP/1.1 ``` Retrieve a list of campaigns associated with the account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-392) | | last | Integer | [Query Desc. last](#desc-393) | | after | String | [Query Desc. after](#desc-394) | | before | String | [Query Desc. before](#desc-395) | #### Query Desc. first {#desc-392} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-393} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-394} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-395} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/campaigns HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 2059 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get CSP Campaign ```http GET /api/v1/campaigns/{id} HTTP/1.1 ``` Lookup a Campaign by its internal UUID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | [Path Desc. id](#desc-396) | #### Path Desc. id {#desc-396} Campaign ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/campaigns/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1674 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # CSP - Campaign - Optout Items ## Schema 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`](#desc-397) | | `id` | String(format:uuid) | [Desc. `id`](#desc-398) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `keyword` | String | [Desc. `keyword`](#desc-399) | | `remote_number` | String | [Desc. `remote_number`](#desc-400) | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#desc-401) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `host_number` {#desc-397} A reference to the host number that this optout belongs to. That is the number that received the optout request. #### Desc. `id` {#desc-398} A Universally unique identifier, which identifies the resource #### Desc. `keyword` {#desc-399} 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-400} The client number that sent the optout, or is opted out of receiving messages from the host number #### Desc. `tcr_campaign_id` {#desc-401} 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" } ``` ## Summary Campaign level optout items control a campaign-wide subscription, regardless of host number. ## API ### List all CSP Campaign Optout Items ```http GET /api/v1/campaign_optout_items HTTP/1.1 ``` Retrieve a list of csp campaign optouts. __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-402) | | last | Integer | [Query Desc. last](#desc-403) | | after | String | [Query Desc. after](#desc-404) | | before | String | [Query Desc. before](#desc-405) | #### Query Desc. first {#desc-402} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-403} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-404} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-405} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/campaign_optout_items HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 895 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get CSP Campaign Optout Item ```http GET /api/v1/campaign_optout_items/{id} HTTP/1.1 ``` Lookup a optout item by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | -------------------------- | | id | String(format:uuid)! | [Path Desc. id](#desc-406) | #### Path Desc. id {#desc-406} Optout Item ID A Universally unique identifier, which identifies the resource #### Request ```http GET /api/v1/campaign_optout_items/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 634 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Shared Resource Groups Shared Resource Groups are a specialized "resource" sharing mechanism, in other words, it allows accounts to donate their CSP Campaigns to other accounts (only campaigns at the moment). This allows the "donee" account to utilize these resources as if they were their own, however the "donee" account can neither remove or change the donated records. ## Schema A Shared Resource Group __Type__ Object | Name | Type | Description | | ------------- | ------------------------ | -------------------------------------- | | `id` | String(format:uuid) | [Desc. `id`](#desc-407) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String | The display name of the resource group | | `notes` | String | [Desc. `notes`](#desc-408) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `id` {#desc-407} A Universally unique identifier, which identifies the resource #### Desc. `notes` {#desc-408} 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" } ``` ## Summary ## API ### List Shared Resource Groups ```http GET /api/v1/shared_resource_groups HTTP/1.1 ``` Retrieve a list of shared resource groups assigned to the parent account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-409) | | last | Integer | [Query Desc. last](#desc-410) | | after | String | [Query Desc. after](#desc-411) | | before | String | [Query Desc. before](#desc-412) | #### Query Desc. first {#desc-409} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-410} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-411} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-412} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/shared_resource_groups HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 666 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Shared Resource Group ```http GET /api/v1/shared_resource_groups/{id} HTTP/1.1 ``` Lookup a shared resource group by ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | ----------- | | id | String(format:uuid)! | User ID | #### Request ```http GET /api/v1/shared_resource_groups/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 433 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` ## Shared Resource Groups - Notes At the moment, the client is not able to create or delete shared resource groups, since this is a very specific binding between different accounts they must be setup by a system administrator. # Event Subscriptions ## Schema Event Subscription __Type__ Object | Name | Type | Description | | --------------------- | ---------------------------------------------------- | ----------------------------------- | | `auth_identity` | String | [Desc. `auth_identity`](#desc-413) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-414) | | `auth_name` | String | [Desc. `auth_name`](#desc-415) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-416) | | `custom_headers` | Array:[SubObject](#type-417) | [Desc. `custom_headers`](#desc-418) | | `custom_query_params` | Array:[SubObject](#type-419) | | | `data` | String | [Desc. `data`](#desc-420) | | `enabled` | Boolean | [Desc. `enabled`](#desc-421) | | `expired_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `id` | String(format:uuid) | [Desc. `id`](#desc-422) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(..255) | [Desc. `name`](#desc-423) | | `notes` | String(..65535) | [Desc. `notes`](#desc-424) | | `protocol` | Enum(`NONE`, `HTTP`, `SMTP`, `SFTP`, `EMAIL`):String | [Desc. `protocol`](#desc-425) | | `recipient` | String | [Desc. `recipient`](#desc-426) | | `started_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `topics` | Array:[Enum](#enum-427):String | [Desc. `topics`](#desc-428) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | #### Desc. `auth_identity` {#desc-413} Acts as the `username` for an auth pair. #### Desc. `auth_method` {#desc-414} 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-415} Currently unused, but kept for future use. #### Desc. `auth_secret` {#desc-416} Acts as the `password` for an auth pair or just the general secret. #### SubObject {#type-417} 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-418} A list of additional headers that should be provided during the HTTP request. #### SubObject {#type-419} Sub-Schema A single query parameter pair. __Type__ Object | Name | Type | Description | | ------- | ------ | ----------- | | `key` | String | | | `value` | String | | #### Desc. `data` {#desc-420} 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-421} Is the subscription enabled to handle events? Subscriptions can be toggled on or off as needed. #### Desc. `id` {#desc-422} A Universally unique identifier, which identifies the resource #### Desc. `name` {#desc-423} The friendly given name for this subscription #### Desc. `notes` {#desc-424} 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-425} 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-426} Only applicable when the `protocol` is SMTP, this will be the recipient address (e.g. "events@example.com") #### Enum Values topics {#enum-427} Allowed values * `NONE` * `DID` * `CSP_BRAND` * `CSP_CAMPAIGN` * `ORDER` * `REQUEST` * `OSR` #### Desc. `topics` {#desc-428} 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" } ``` ## Summary Event Subscriptions are records used to define event related webhook configuration. These events are typically sent from the ordering system in response to an order or request being completed, a did being updated, or an overwrite request pending action. ## API ### Create Event Subscription ```http POST /api/v1/event_subscriptions HTTP/1.1 ``` Create a new Event Subscription. #### Request application/json ```http POST /api/v1/event_subscriptions HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 590 ``` ```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" } ``` #### Response 201 ##### application/json ```http HTTP/1.1 201 Content-Type: application/json Content-Length: 837 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Update Event Subscription ```http PATCH /api/v1/event_subscriptions/{id} HTTP/1.1 ``` Update an existing Event Subscription __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | --------------------- | | id | String(format:uuid)! | Event Subscription ID | #### Request application/json ```http PATCH /api/v1/event_subscriptions/{id} HTTP/1.1 Accept: application/json Content-Type: application/json Content-Length: 590 ``` ```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" } ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 837 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### Delete Event Subscription ```http DELETE /api/v1/event_subscriptions/{id} HTTP/1.1 ``` Delete an existing Event Subscription by ID. __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | --------------------- | | id | String(format:uuid)! | Event Subscription ID | #### Request ```http DELETE /api/v1/event_subscriptions/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 837 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` #### Response 422 ##### application/json ```http HTTP/1.1 422 Content-Type: application/json Content-Length: 241 ``` ```json { "errors": [ { "code": "invalid_parameter", "detail": "The specified resource could not be found", "source": { "pointer": "/data/type" }, "sub_code": "none", "title": "Not Found" } ] } ``` ### List Event Subscriptions ```http GET /api/v1/event_subscriptions HTTP/1.1 ``` Retrieve all event subscriptions for account __Query Parameters__ | Name | Type | Description | | ------ | ------- | ------------------------------- | | first | Integer | [Query Desc. first](#desc-429) | | last | Integer | [Query Desc. last](#desc-430) | | after | String | [Query Desc. after](#desc-431) | | before | String | [Query Desc. before](#desc-432) | #### Query Desc. first {#desc-429} The number of items to return starting from the 'after' cursor #### Query Desc. last {#desc-430} The number of items to return behind the 'before' cursor #### Query Desc. after {#desc-431} The cursor representing the starting point of a 'first' based paging #### Query Desc. before {#desc-432} The cursor representing the starting point of a 'last' based paging #### Request ```http GET /api/v1/event_subscriptions HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 1138 ``` ```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" } ] } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` ### Get Event Subscription ```http GET /api/v1/event_subscriptions/{id} HTTP/1.1 ``` Lookup an Event Subscription by its ID __Path Parameters__ | Name | Type | Description | | ---- | -------------------- | --------------------- | | id | String(format:uuid)! | Event Subscription ID | #### Request ```http GET /api/v1/event_subscriptions/{id} HTTP/1.1 Accept: application/json ``` #### Response 200 ##### application/json ```http HTTP/1.1 200 Content-Type: application/json Content-Length: 837 ``` ```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" } ``` #### Response 403 ##### application/json ```http HTTP/1.1 403 Content-Type: application/json Content-Length: 312 ``` ```json { "errors": [ { "code": "access_denied.no_scope", "detail": "No scope available to user role", "params": { "action": "index", "level": "guest", "resource": "resource" }, "sub_code": "none", "title": "Access Denied, no scope available" } ] } ``` #### Response 404 ##### application/json ```http HTTP/1.1 404 Content-Type: application/json Content-Length: 314 ``` ```json { "errors": [ { "code": "not_found", "detail": "The specified resource could not be found", "params": { "resource": { "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69", "type": "user" } }, "sub_code": "none", "title": "Not Found" } ] } ``` # Events Events that can be sent from the system to a configured event subscription. See [Event Subscriptions](#event-subscriptions) for details on registering your own subscription to receive these events. Events are sent during the processing of a request, typically they are sent when: * An `order` is completed (whether successful or failure) * A `request` is completed (whether successful or failure) * When a `DID` is created via request * When a `DID` is deleted via request * When a `DID` has a feature added (i.e. messaging, csp campaign, etc...) * When a `DID` has a feature removed (i.e. messaging, csp campaign, etc...) More events may be added in the future as needed. ## Schema Format of the Subscription Event webhook. __Type__ Object | Name | Type | Description | | -------------- | -------------------------------------------- | --------------------------------- | | `associations` | `associations` | [Desc. `associations`](#desc-433) | | `data` | [One-Of](#type-434) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-435) | | `inserted_at` | String(format:date-time) | [Desc. `inserted_at`](#desc-436) | | `timestamp` | String(format:date-time) | [Desc. `timestamp`](#desc-437) | | `topic` | [SystemEventTopic](#schema-systemeventtopic) | | | `type` | [SystemEventType](#schema-systemeventtype) | | #### Desc. `associations` {#desc-433} 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-434} Types * [SystemEventDataCspCampaignRegistered](#schema-systemeventdatacspcampaignregistered) * [SystemEventDataCspCampaignOptoutItemCreated](#schema-systemeventdatacspcampaignoptoutitemcreated) * [SystemEventDataCspCampaignOptoutItemDeleted](#schema-systemeventdatacspcampaignoptoutitemdeleted) * [SystemEventDataDidCreated](#schema-systemeventdatadidcreated) * [SystemEventDataDidDeleted](#schema-systemeventdatadiddeleted) * [SystemEventDataDidComponentCreated](#schema-systemeventdatadidcomponentcreated) * [SystemEventDataDidComponentDeleted](#schema-systemeventdatadidcomponentdeleted) * [SystemEventDataDidOptoutItemCreated](#schema-systemeventdatadidoptoutitemcreated) * [SystemEventDataDidOptoutItemDeleted](#schema-systemeventdatadidoptoutitemdeleted) * [SystemEventDataOsrOverwriteRequestPending](#schema-systemeventdataosroverwriterequestpending) * [SystemEventDataOsrOverwriteRequestCompleted](#schema-systemeventdataosroverwriterequestcompleted) * [SystemEventDataOrderCompleted](#schema-systemeventdataordercompleted) * [SystemEventDataRequestCompleted](#schema-systemeventdatarequestcompleted) #### Desc. `id` {#desc-435} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `inserted_at` {#desc-436} When was this event first created? #### Desc. `timestamp` {#desc-437} When was the event sent from the host system? __associations__ | Name | Type | Description | | ------------------- | -------------------------------------------------------------------------------------------- | ----------- | | `provision_records` | Array:[SystemEventAssociationProvisionRecord](#schema-systemeventassociationprovisionrecord) | | | `requests` | Array:[SystemEventAssociationRequest](#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" } ``` ## Request Event Subscriptions control the request that will be made to the endpoint, while multiple protocols are listed, only HTTP is fully supported. Requests will be retried up to 17 times of the course of 3 days. The webhook system will accept any 2xx status as a success. It is recommended that a `204 No Content` be returned while using the event subscription in case a response is supported by the webhook later. ## Types ### CSP Campaign Registered #### Schema `CSP_CAMPAIGN_REGISTERED` __Type__ Object | Name | Type | Description | | ----------------- | ------------------- | ------------------------------------ | | `csp_campaign_id` | String(format:ulid) | [Desc. `csp_campaign_id`](#desc-438) | | `tcr_campaign_id` | String | The TCR issued campaign ID | #### Desc. `csp_campaign_id` {#desc-438} Another format for UUID, used primarily for tasks, requests and messages. __Example__ ```json { "csp_campaign_id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "tcr_campaign_id": "C000000" } ``` ### CSP Campaign - Optout Item - Created #### Schema `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`](#desc-439) | | `host_number` | String | [Desc. `host_number`](#desc-440) | | `keyword` | String | [Desc. `keyword`](#desc-441) | | `remote_number` | String | [Desc. `remote_number`](#desc-442) | | `tcr_campaign_id` | String | The TCR issued campaign ID | #### Desc. `csp_campaign_id` {#desc-439} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `host_number` {#desc-440} A reference to the host number that this optout belongs to. That is the number that received the optout request. #### Desc. `keyword` {#desc-441} 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-442} 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" } ``` ### CSP Campaign - Optout Item - Deleted #### Schema `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`](#desc-443) | | `host_number` | String | [Desc. `host_number`](#desc-444) | | `keyword` | String | [Desc. `keyword`](#desc-445) | | `remote_number` | String | [Desc. `remote_number`](#desc-446) | | `tcr_campaign_id` | String | The TCR issued campaign ID | #### Desc. `csp_campaign_id` {#desc-443} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `host_number` {#desc-444} A reference to the host number that this optout belongs to. That is the number that received the optout request. #### Desc. `keyword` {#desc-445} 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-446} 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" } ``` ### DID Component Created #### Schema `DID_COMPONENT_CREATED` __Type__ Object | Name | Type | Description | | ------------ | -------------------------------------------------------------------------- | ------------------------------- | | `component` | [SystemEventDataDidComponent](#schema-systemeventdatadidcomponent) | | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-447) | | `number` | String | [Desc. `number`](#desc-448) | | `reason` | [SystemEventDataDidCreatedReason](#schema-systemeventdatadidcreatedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#desc-449) | #### Desc. `did_id` {#desc-447} A Universally unique identifier, which identifies the resource #### Desc. `number` {#desc-448} The 3 to 15 digit code of the number. #### Desc. `request_id` {#desc-449} 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" } ``` ### DID Component Deleted #### Schema `DID_COMPONENT_DELETED` __Type__ Object | Name | Type | Description | | ------------ | -------------------------------------------------------------------------- | ------------------------------- | | `component` | [SystemEventDataDidComponent](#schema-systemeventdatadidcomponent) | | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-450) | | `number` | String | [Desc. `number`](#desc-451) | | `reason` | [SystemEventDataDidDeletedReason](#schema-systemeventdatadiddeletedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#desc-452) | #### Desc. `did_id` {#desc-450} A Universally unique identifier, which identifies the resource #### Desc. `number` {#desc-451} The 3 to 15 digit code of the number. #### Desc. `request_id` {#desc-452} 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" } ``` ### DID Created #### Schema `DID_CREATED` __Type__ Object | Name | Type | Description | | ------------ | -------------------------------------------------------------------------- | ------------------------------- | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-453) | | `number` | String | [Desc. `number`](#desc-454) | | `reason` | [SystemEventDataDidCreatedReason](#schema-systemeventdatadidcreatedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#desc-455) | #### Desc. `did_id` {#desc-453} A Universally unique identifier, which identifies the resource #### Desc. `number` {#desc-454} The 3 to 15 digit code of the number. #### Desc. `request_id` {#desc-455} 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" } ``` ### DID Deleted #### Schema `DID_DELETED` __Type__ Object | Name | Type | Description | | ------------ | -------------------------------------------------------------------------- | ------------------------------- | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-456) | | `number` | String | [Desc. `number`](#desc-457) | | `reason` | [SystemEventDataDidDeletedReason](#schema-systemeventdatadiddeletedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#desc-458) | #### Desc. `did_id` {#desc-456} A Universally unique identifier, which identifies the resource #### Desc. `number` {#desc-457} The 3 to 15 digit code of the number. #### Desc. `request_id` {#desc-458} 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" } ``` ### DID - Optout Item - Created #### Schema `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`](#desc-459) | | `host_number` | String | [Desc. `host_number`](#desc-460) | | `keyword` | String | [Desc. `keyword`](#desc-461) | | `remote_number` | String | [Desc. `remote_number`](#desc-462) | #### Desc. `host_did_id` {#desc-459} A Universally unique identifier, which identifies the resource #### Desc. `host_number` {#desc-460} A reference to the host number that this optout belongs to. That is the number that received the optout request. #### Desc. `keyword` {#desc-461} 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-462} 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" } ``` ### DID - Optout Item - Deleted #### Schema `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`](#desc-463) | | `host_number` | String | [Desc. `host_number`](#desc-464) | | `keyword` | String | [Desc. `keyword`](#desc-465) | | `remote_number` | String | [Desc. `remote_number`](#desc-466) | #### Desc. `host_did_id` {#desc-463} A Universally unique identifier, which identifies the resource #### Desc. `host_number` {#desc-464} A reference to the host number that this optout belongs to. That is the number that received the optout request. #### Desc. `keyword` {#desc-465} 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-466} 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" } ``` ### Order Completed #### Schema `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](#schema-ordererrorcode) | | | `order_id` | String(format:ulid) | [Desc. `order_id`](#desc-467) | | `status` | [OrderStatus](#schema-orderstatus) | | #### Desc. `order_id` {#desc-467} Another format for UUID, used primarily for tasks, requests and messages. __Example__ ```json { "error_code": "OK", "order_id": "01EH2Y28M6KXG14QMPM3HSP1Y0", "status": "NEW" } ``` ### Request Completed #### Schema `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](#type-468) | | | `error_code` | [OrderErrorCode](#schema-ordererrorcode) | | | `order_id` | String(format:ulid) | [Desc. `order_id`](#desc-469) | | `request_id` | String(format:ulid) | [Desc. `request_id`](#desc-470) | | `status` | [OrderStatus](#schema-orderstatus) | | | `type` | [RequestType](#schema-requesttype) | | #### One-Of {#type-468} Types * [SystemEventDataRequestCompletedDataRegisterBrand](#schema-systemeventdatarequestcompleteddataregisterbrand) * [SystemEventDataRequestCompletedDataRegisterCampaign](#schema-systemeventdatarequestcompleteddataregistercampaign) #### Desc. `order_id` {#desc-469} Another format for UUID, used primarily for tasks, requests and messages. #### Desc. `request_id` {#desc-470} 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" } ``` ### OSR Overwrite Request Pending #### Schema `OSR_OVERWRITE_REQUEST_PENDING` __Type__ Object | Name | Type | Description | | --------------------------- | ------------------------ | --------------------------------------------- | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-471) | | `error_code` | Enum(`OK`):String | Further explanation of an error status | | `new_nnid_service_provider` | String | | | `number` | String | [Desc. `number`](#desc-472) | | `osr_overwrite_request_id` | String(format:ulid) | [Desc. `osr_overwrite_request_id`](#desc-473) | | `review_status` | [Enum](#enum-474):String | [Desc. `review_status`](#desc-475) | | `status` | [Enum](#enum-476):String | [Desc. `status`](#desc-477) | #### Desc. `did_id` {#desc-471} A Universally unique identifier, which identifies the resource #### Desc. `number` {#desc-472} The 3 to 15 digit code of the number. #### Desc. `osr_overwrite_request_id` {#desc-473} Another format for UUID, used primarily for tasks, requests and messages. #### Enum Values review_status {#enum-474} Allowed values * `NONE` * `APPROVED` * `REJECTED` * `AUTO_APPROVED` * `AUTO_REJECTED` * `FORCE_DELETED` #### Desc. `review_status` {#desc-475} The review status of the request, defaults to NONE. #### Enum Values status {#enum-476} Allowed values * `NEW` * `REVIEWED` * `APPROVED` * `REJECTED` * `ERROR` * `STALE` * `DELETED` #### Desc. `status` {#desc-477} 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" } ``` ### OSR Overwrite Request Completed #### Schema `OSR_OVERWRITE_REQUEST_COMPLETED` __Type__ Object | Name | Type | Description | | --------------------------- | ------------------------ | --------------------------------------------- | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-478) | | `error_code` | Enum(`OK`):String | Further explanation of an error status | | `new_nnid_service_provider` | String | | | `number` | String | [Desc. `number`](#desc-479) | | `osr_overwrite_request_id` | String(format:ulid) | [Desc. `osr_overwrite_request_id`](#desc-480) | | `review_status` | [Enum](#enum-481):String | [Desc. `review_status`](#desc-482) | | `status` | [Enum](#enum-483):String | [Desc. `status`](#desc-484) | #### Desc. `did_id` {#desc-478} A Universally unique identifier, which identifies the resource #### Desc. `number` {#desc-479} The 3 to 15 digit code of the number. #### Desc. `osr_overwrite_request_id` {#desc-480} Another format for UUID, used primarily for tasks, requests and messages. #### Enum Values review_status {#enum-481} Allowed values * `NONE` * `APPROVED` * `REJECTED` * `AUTO_APPROVED` * `AUTO_REJECTED` * `FORCE_DELETED` #### Desc. `review_status` {#desc-482} The review status of the request, defaults to NONE. #### Enum Values status {#enum-483} Allowed values * `NEW` * `REVIEWED` * `APPROVED` * `REJECTED` * `ERROR` * `STALE` * `DELETED` #### Desc. `status` {#desc-484} 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" } ``` # SMPP ## Supported TLVs | Name | Hex | Type | Description | | -------------------- | -------- | ------- | ------------------------------------------- | | `sar_msg_ref_num` | `0x020C` | Integer | SAR Reference Number | | `sar_total_segments` | `0x020E` | Integer | SAR Total Segments | | `sar_segment_seqnum` | `0x020F` | Integer | SAR Segment Sequence Number | | `custom_message_id` | `0x3040` | String | Contains the `id` (ULID) of the SMS segment | ### SAR Segmentation and Reassembly If one is familiar with UDH based concatenation, then SAR shouldn't be a foreign concept, it is essentially the same structure: * `sar_msg_ref_num` - Used to identify which "complete" message this segment refers to, combined with the destination and source addresses to make the unique key * `sar_total_segments` - The total number of segemnts in the complete message * `sar_segment_seqnum` - Which segment of the message it is # 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`](#desc-485) | | `voip_destinations` | `voip_destinations` | [Desc. `voip_destinations`](#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`](#desc-487) | | `csp_campaign_id` | String(format:uuid) | [Desc. `csp_campaign_id`](#desc-488) | | `enabled` | Boolean | [Desc. `enabled`](#desc-489) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-490) | | `notes` | String | [Desc. `notes`](#desc-491) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#desc-492) | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#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](#type-501) | [Desc. `destinations`](#desc-502) | | `enabled` | Boolean | [Desc. `enabled`](#desc-503) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#desc-504) | #### SubObject {#type-501} Sub-Schema Destination configuration parameters. __Type__ Object | Name | Type | Description | | --------------- | -------------------------------------- | ------------------------------------ | | `activated` | Boolean | [Desc. `activated`](#desc-494) | | `auth_identity` | String | The username for a BASIC auth_method | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-495) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-496) | | `destination` | String | [Desc. `destination`](#desc-497) | | `priority` | Integer | [Desc. `priority`](#desc-498) | | `type` | [Enum](#enum-499):String | [Desc. `type`](#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`](#desc-505) | | `identity` | String | [Desc. `identity`](#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`](#desc-507) | | `smpp_system_id` | String | [Desc. `smpp_system_id`](#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](#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](#schema-pageinfo) | | | `results` | Array:[ApiKeyResponse](#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](#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](#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](#schema-switchsigninghash) | | | `mms_signing_scheme` | [SwitchSigningScheme](#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](#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](#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](#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](#schema-switchsigninghash) | | | `sms_signing_scheme` | [SwitchSigningScheme](#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](#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`](#desc-509) | | `enhanced` | Boolean | [Desc. `enhanced`](#desc-510) | | `error_code` | Enum(`OK`):String | [Desc. `error_code`](#desc-511) | | `format` | Enum(`CSV`, `MLJSON`):String | [Desc. `format`](#desc-512) | | `id` | String(format:ulid) | [Desc. `id`](#desc-513) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `messaging_lookup` | Boolean | [Desc. `messaging_lookup`](#desc-514) | | `numbers` | Array(0..20000):String(format:tel) | Numbers to lookup | | `on_done_actions` | [OnDoneActions](#schema-ondoneactions) | | | `reference_id` | String(1..255) | [Desc. `reference_id`](#desc-515) | | `status` | [Enum](#enum-516):String | [Desc. `status`](#desc-517) | | `type` | Enum(`LRN`, `MCL`, `CNAM`):String | [Desc. `type`](#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](#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](#schema-pageinfo) | | | `results` | Array:[BulkDipTaskResponse](#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](#schema-cdrfee) | | | `host_number` | String | [Desc. `host_number`](#desc-519) | | `id` | String(format:ulid) | [Desc. `id`](#desc-520) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `item_count` | Integer | [Desc. `item_count`](#desc-521) | | `item_id` | String | [Desc. `item_id`](#desc-522) | | `remote_number` | String | [Desc. `remote_number`](#desc-523) | | `sell_rate` | String(format:decimal) | [Desc. `sell_rate`](#desc-524) | | `status` | [Enum](#enum-525):String | Main status of the CDR | | `subtype` | [Enum](#enum-526):String | [Desc. `subtype`](#desc-527) | | `surcharges` | Array:[CDRSurcharge](#schema-cdrsurcharge) | | | `total` | String(format:decimal) | [Desc. `total`](#desc-528) | | `type` | [Enum](#enum-529):String | [Desc. `type`](#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](#schema-cdrresponse) | | | `lookups` | Array | [Desc. `lookups`](#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](#schema-cdr) | | | `type` | String | | __associations__ | Name | Type | Description | | --------- | --------- | ----------- | | `api_key` | `api_key` | | __api_key__ | Name | Type | Description | | ---- | ------------------- | ----------------------- | | `id` | String(format:uuid) | [Desc. `id`](#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](#schema-pageinfo) | | | `results` | Array:[CDRResponse](#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`](#desc-533) | | `id` | String(format:uuid) | [Desc. `id`](#desc-534) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `keyword` | String | [Desc. `keyword`](#desc-535) | | `remote_number` | String | [Desc. `remote_number`](#desc-536) | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#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](#schema-cspcampaignoptoutitem) | | | `type` | String | | __associations__ | Name | Type | Description | | -------------- | -------------- | --------------------------------- | | `csp_campaign` | `csp_campaign` | [Desc. `csp_campaign`](#desc-538) | | `host_did` | `host_did` | [Desc. `host_did`](#desc-539) | | `sms` | `sms` | [Desc. `sms`](#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`](#desc-541) | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#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`](#desc-543) | | `number` | String | [Desc. `number`](#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`](#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](#schema-pageinfo) | | | `results` | Array:[CSPCampaignOptoutItemResponse](#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`](#desc-546) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-547) | | `auth_name` | String | [Desc. `auth_name`](#desc-548) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-549) | | `custom_headers` | Array:[SubObject](#type-550) | [Desc. `custom_headers`](#desc-551) | | `custom_query_params` | Array:[SubObject](#type-552) | [Desc. `custom_query_params`](#desc-553) | | `data` | String | [Desc. `data`](#desc-554) | | `id` | String(format:ulid) | [Desc. `id`](#desc-555) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..255) | [Desc. `name`](#desc-556) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-557) | | `protocol` | Enum(`NONE`, `HTTP`, `SFTP`):String | [Desc. `protocol`](#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 ` 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 ` 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](#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](#schema-pageinfo) | | | `results` | Array:[CallDataWebhookResponse](#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`](#desc-559) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](#desc-560) | | `notes` | String | [Desc. `notes`](#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`](#desc-562) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String | | | `notes` | String | | | `type` | [RequestType](#schema-requesttype) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `*` | [One-Of](#type-563) | | #### Desc. `id` {#desc-562} Another format for UUID, used primarily for tasks, requests and messages. #### One-Of {#type-563} Types * [CartRequestAddCampaignNumbersData](#schema-cartrequestaddcampaignnumbersdata) * [CartRequestAddMessagingNumbersData](#schema-cartrequestaddmessagingnumbersdata) * [CartRequestAddVoiceNumbersData](#schema-cartrequestaddvoicenumbersdata) * [CartRequestNewNumbersData](#schema-cartrequestnewnumbersdata) * [CartRequestRegisterBrandData](#schema-cartrequestregisterbranddata) * [CartRequestRegisterCampaignData](#schema-cartrequestregistercampaigndata) * [CartRequestRemoveCampaignNumbersData](#schema-cartrequestremovecampaignnumbersdata) * [CartRequestRemoveMessagingNumbersData](#schema-cartrequestremovemessagingnumbersdata) * [CartRequestRemoveNumbersData](#schema-cartrequestremovenumbersdata) * [CartRequestRemoveVoiceNumbersData](#schema-cartrequestremovevoicenumbersdata) * [CartRequestUnregisterBrandData](#schema-cartrequestunregisterbranddata) * [CartRequestUnregisterCampaignData](#schema-cartrequestunregistercampaigndata) * [CartRequestVetBrandData](#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`](#desc-564) | | `*` | [One-Of](#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`](#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`](#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](#type-566) * [... campaign_id](#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`](#desc-570) | | `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](#desc-571) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-572) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-573) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#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`](#desc-575) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#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`](#desc-577) | | `help_message` | String | | | `message_flow` | String | | | `mno_ids` | Array:String | | | `number_pool` | Boolean | | | `optin_keywords` | String | [Desc. `optin_keywords`](#desc-578) | | `optin_message` | String | | | `optout_keywords` | String | [Desc. `optout_keywords`](#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`](#desc-580) | | `tcr_reseller_id` | String | [Desc. `tcr_reseller_id`](#desc-581) | | `terms_and_conditions` | Boolean | [Desc. `terms_and_conditions`](#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`](#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`](#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`](#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`](#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](#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`](#desc-587) | | `vetting_class` | String | [Desc. `vetting_class`](#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](#schema-pageinfo) | | | `results` | Array:[CartRequestResponse](#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](#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](#schema-pageinfo) | | | `results` | Array:[CartResponse](#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](#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](#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`](#desc-589) | | `format` | Enum(`CSV`, `MLJSON`):String | [Desc. `format`](#desc-590) | | `messaging_lookup` | Boolean | [Desc. `messaging_lookup`](#desc-591) | | `numbers` | Array(0..20000):String(format:tel) | Numbers to lookup | | `on_done_actions` | [CreateOnDoneActions](#schema-createondoneactions) | | | `reference_id` | String(1..255) | [Desc. `reference_id`](#desc-592) | | `type` | Enum(`LRN`, `MCL`, `CNAM`):String | [Desc. `type`](#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](#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`](#desc-594) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-595) | | `auth_name` | String | [Desc. `auth_name`](#desc-596) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-597) | | `custom_headers` | Array:[SubObject](#type-598) | [Desc. `custom_headers`](#desc-599) | | `custom_query_params` | Array:[SubObject](#type-600) | [Desc. `custom_query_params`](#desc-601) | | `data` | String | [Desc. `data`](#desc-602) | | `name` | String(1..255) | [Desc. `name`](#desc-603) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-604) | | `protocol` | Enum(`NONE`, `HTTP`, `SFTP`):String | [Desc. `protocol`](#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 ` 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 ` 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](#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`](#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](#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](#schema-requesttype) | | | `*` | [One-Of](#type-607) | | #### One-Of {#type-607} Types * [CartRequestAddCampaignNumbersData](#schema-cartrequestaddcampaignnumbersdata) * [CartRequestAddMessagingNumbersData](#schema-cartrequestaddmessagingnumbersdata) * [CartRequestAddVoiceNumbersData](#schema-cartrequestaddvoicenumbersdata) * [CartRequestNewNumbersData](#schema-cartrequestnewnumbersdata) * [CartRequestRegisterBrandData](#schema-cartrequestregisterbranddata) * [CartRequestRegisterCampaignData](#schema-cartrequestregistercampaigndata) * [CartRequestRemoveCampaignNumbersData](#schema-cartrequestremovecampaignnumbersdata) * [CartRequestRemoveMessagingNumbersData](#schema-cartrequestremovemessagingnumbersdata) * [CartRequestRemoveNumbersData](#schema-cartrequestremovenumbersdata) * [CartRequestRemoveVoiceNumbersData](#schema-cartrequestremovevoicenumbersdata) * [CartRequestUnregisterBrandData](#schema-cartrequestunregisterbranddata) * [CartRequestUnregisterCampaignData](#schema-cartrequestunregistercampaigndata) * [CartRequestVetBrandData](#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](#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](#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`](#desc-608) | | `format` | Enum(`CSV`, `MLJSON`):String | [Desc. `format`](#desc-609) | | `on_done_actions` | [CreateOnDoneActions](#schema-createondoneactions) | | | `reference_id` | String(1..255) | [Desc. `reference_id`](#desc-610) | | `type` | [Enum](#enum-611):String | [Desc. `type`](#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](#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](#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](#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`](#desc-613) | | `auth_identity` | String | [Desc. `auth_identity`](#desc-614) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-615) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-616) | | `data` | String | [Desc. `data`](#desc-617) | | `filename` | String | [Desc. `filename`](#desc-618) | | `protocol` | Enum(`NONE`, `HTTP`, `SFTP`):String | [Desc. `protocol`](#desc-619) | | `reference_id` | String(0..255) | [Desc. `reference_id`](#desc-620) | | `type` | Enum(`NONE`, `NOTIFY`, `SEND`):String | [Desc. `type`](#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 ` 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](#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`](#desc-622) | | `remote_number` | String | [Desc. `remote_number`](#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](#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`](#desc-624) | | `file_hint` | Enum(`DEFAULT`, `MMS`, `LOA`):String | [Desc. `file_hint`](#desc-625) | | `filename` | String | [Desc. `filename`](#desc-626) | | `name` | String | [Desc. `name`](#desc-627) | | `notes` | String | [Desc. `notes`](#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`](#desc-629) | | `name` | String | [Desc. `name`](#desc-630) | | `notes` | String | [Desc. `notes`](#desc-631) | | `rank` | Integer(>= 0) | [Desc. `rank`](#desc-632) | | `resources` | Array:[SubObject](#type-638) | [Desc. `resources`](#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](#type-636) | | | `resource_id` | String | | | `scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](#desc-637) | #### SubObject {#type-636} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ---------------------------- | -------------------------- | | `name` | [Enum](#enum-633):String | [Desc. `name`](#desc-634) | | `value` | Enum(`true`, `false`):String | [Desc. `value`](#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](#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`](#desc-640) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-641) | | `size` | Enum(`16`, `24`, `32`, `48`, `64`):Number | [Desc. `size`](#desc-642) | | `usage` | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](#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](#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](#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](#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`](#desc-644) | | `email` | String(format:email) | [Desc. `email`](#desc-645) | | `first_name` | String | [Desc. `first_name`](#desc-646) | | `last_name` | String | [Desc. `last_name`](#desc-647) | | `password` | String | [Desc. `password`](#desc-648) | | `password_confirmation` | String | [Desc. `password_confirmation`](#desc-649) | | `title` | String | [Desc. `title`](#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](#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`](#desc-651) | | `identity` | String | [Desc. `identity`](#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`](#desc-653) | | `secret` | String | Acts as the password used for Basic auth | | `smpp_secert` | String | [Desc. `smpp_secert`](#desc-654) | | `smpp_system_id` | String | [Desc. `smpp_system_id`](#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`](#desc-656) | | `id` | String(format:uuid) | [Desc. `id`](#desc-657) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](#desc-658) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-659) | | `size` | Enum(`16`, `24`, `32`, `48`, `64`):Number | [Desc. `size`](#desc-660) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `usage` | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](#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`](#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`](#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](#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](#schema-pageinfo) | | | `results` | Array:[CspBrandResponse](#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`](#desc-664) | | `description` | String | Description of the campaign | | `embedded_link_sample` | String | | | `help_keywords` | String | | | `help_message` | String | | | `id` | String(format:ulid) | [Desc. `id`](#desc-665) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `message_flow` | String | | | `name` | String(1..255) | [Desc. `name`](#desc-666) | | `notes` | String | [Desc. `notes`](#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`](#desc-668) | | `shared` | Enum(`NO`, `OWNED`, `PARTNER`):String | [Desc. `shared`](#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`](#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](#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`](#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`](#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`](#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](#enum-674):String | [Desc. `code`](#desc-675) | | `detail` | String | [Desc. `detail`](#desc-676) | | `params` | `params` | [Desc. `params`](#desc-677) | | `sub_code` | String | [Desc. `sub_code`](#desc-678) | | `title` | String | [Desc. `title`](#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](#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`](#desc-680) | | `detail` | String | [Desc. `detail`](#desc-681) | | `params` | `params` | [Desc. `params`](#desc-682) | | `sub_code` | String | [Desc. `sub_code`](#desc-683) | | `title` | String | [Desc. `title`](#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](#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](#schema-pageinfo) | | | `results` | Array:[CspCampaignResponse](#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](#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](#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](#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](#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](#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](#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](#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`](#desc-687) | | `auth_identity` | String | The username for a BASIC auth_method | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-688) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-689) | | `destination` | String | [Desc. `destination`](#desc-690) | | `id` | String(format:uuid) | [Desc. `id`](#desc-691) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `priority` | Integer | [Desc. `priority`](#desc-692) | | `type` | [Enum](#enum-693):String | [Desc. `type`](#desc-694) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `wait_time` | Integer | [Desc. `wait_time`](#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](#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`](#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`](#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](#schema-pageinfo) | | | `results` | Array:[DestinationResponse](#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`](#desc-698) | | `detail` | String | [Desc. `detail`](#desc-699) | | `source` | `source` | | | `sub_code` | String | [Desc. `sub_code`](#desc-700) | | `title` | String | [Desc. `title`](#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](#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`](#desc-702) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-703) | | `auth_name` | String | [Desc. `auth_name`](#desc-704) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-705) | | `custom_headers` | Array:[SubObject](#type-706) | [Desc. `custom_headers`](#desc-707) | | `custom_query_params` | Array:[SubObject](#type-708) | | | `data` | String | [Desc. `data`](#desc-709) | | `enabled` | Boolean | [Desc. `enabled`](#desc-710) | | `expired_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `id` | String(format:uuid) | [Desc. `id`](#desc-711) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(..255) | [Desc. `name`](#desc-712) | | `notes` | String(..65535) | [Desc. `notes`](#desc-713) | | `protocol` | Enum(`NONE`, `HTTP`, `SMTP`, `SFTP`, `EMAIL`):String | [Desc. `protocol`](#desc-714) | | `recipient` | String | [Desc. `recipient`](#desc-715) | | `started_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `topics` | Array:[Enum](#enum-716):String | [Desc. `topics`](#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](#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](#schema-pageinfo) | | | `results` | Array:[EventSubscriptionResponse](#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`](#desc-718) | | `error_code` | Enum(`OK`):String | [Desc. `error_code`](#desc-719) | | `format` | Enum(`CSV`, `MLJSON`):String | [Desc. `format`](#desc-720) | | `id` | String(format:ulid) | [Desc. `id`](#desc-721) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `on_done_actions` | [OnDoneActions](#schema-ondoneactions) | | | `reference_id` | String(1..255) | [Desc. `reference_id`](#desc-722) | | `status` | [Enum](#enum-723):String | [Desc. `status`](#desc-724) | | `type` | [Enum](#enum-725):String | [Desc. `type`](#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](#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](#schema-pageinfo) | | | `results` | Array:[ExportTaskResponse](#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`](#desc-727) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `priority` | Integer | [Desc. `priority`](#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](#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`](#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](#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](#schema-pageinfo) | | | `results` | Array:[MessageSetResponse](#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](#schema-pageinfo) | | | `results` | Array:[MessageResponse](#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`](#desc-730) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `keywords` | Array:[SubObject](#type-736) | [Desc. `keywords`](#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`](#desc-731) | | `is_wildcard` | Boolean | [Desc. `is_wildcard`](#desc-732) | | `keyword` | String | [Desc. `keyword`](#desc-733) | | `message` | String | [Desc. `message`](#desc-734) | | `message2` | String | [Desc. `message2`](#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](#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](#schema-pageinfo) | | | `results` | Array:[MessagingAutoResponseResponse](#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`](#desc-738) | | `brand_name` | String(0..255) | [Desc. `brand_name`](#desc-739) | | `description` | String | [Desc. `description`](#desc-740) | | `forward_number` | String | [Desc. `forward_number`](#desc-741) | | `help_message` | String(0..255) | [Desc. `help_message`](#desc-742) | | `id` | String(format:uuid) | [Desc. `id`](#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`](#desc-744) | | `number` | String | [Desc. `number`](#desc-745) | | `rate_center` | String | | | `segment_overrides` | Array:[SubObject](#type-750) | [Desc. `segment_overrides`](#desc-751) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](#desc-752) | | `sms_enabled` | Boolean | [Desc. `sms_enabled`](#desc-753) | | `state` | String | | | `tier` | [Enum](#enum-754):String | [Desc. `tier`](#desc-755) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `upgrade_asset_handling` | [Enum](#enum-756):String | The asset handling flag for SMS Upgrades | | `voice_enabled` | Boolean | [Desc. `voice_enabled`](#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`](#desc-746) | | `id` | String(format:uuid) | [Desc. `id`](#desc-747) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](#desc-748) | | `target_reference_id` | String | [Desc. `target_reference_id`](#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: _ 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`](#desc-758) | | `block_messaging` | Enum(`NONE`, `SMS`, `MMS`, `ALL`):String | [Desc. `block_messaging`](#desc-759) | | `block_voip` | [Enum](#enum-760):String | [Desc. `block_voip`](#desc-761) | | `host_number` | String | [Desc. `host_number`](#desc-762) | | `id` | String(format:uuid) | [Desc. `id`](#desc-763) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `notes` | String | [Desc. `notes`](#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](#schema-numberclientsuspension) | | | `type` | String | | __associations__ | Name | Type | Description | | ---------- | ---------- | ----------------------------- | | `host_did` | `host_did` | [Desc. `host_did`](#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`](#desc-766) | | `number` | String | [Desc. `number`](#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](#schema-pageinfo) | | | `results` | Array:[NumberClientSuspensionResponse](#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`](#desc-768) | | `items` | Array:[SubObject](#type-773) | | | `search_params` | `search_params` | [Desc. `search_params`](#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`](#desc-769) | | `lata` | String | | | `npa` | String(format:npa) | [Desc. `npa`](#desc-770) | | `nxx` | String(format:nxx) | [Desc. `nxx`](#desc-771) | | `rate_center` | String | | | `state` | String | | | `type` | Enum(`TENDLC`, `TOLLFREE`):String | [Desc. `type`](#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](#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](#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](#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`](#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`](#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`](#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](#schema-pageinfo) | | | `results` | Array:[NumberResponse](#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`](#desc-779) | | `auth_identity` | String | [Desc. `auth_identity`](#desc-780) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-781) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-782) | | `data` | String | [Desc. `data`](#desc-783) | | `error_code` | Enum(`OK`):String | [Desc. `error_code`](#desc-784) | | `filename` | String | [Desc. `filename`](#desc-785) | | `protocol` | Enum(`NONE`, `HTTP`, `SFTP`):String | [Desc. `protocol`](#desc-786) | | `reference_id` | String(0..255) | [Desc. `reference_id`](#desc-787) | | `status` | Enum(`NEW`, `COMPLETED`, `ERROR`, `REJECTED`):String | [Desc. `status`](#desc-788) | | `type` | Enum(`NONE`, `NOTIFY`, `SEND`):String | [Desc. `type`](#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 ` 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](#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`](#desc-790) | | `id` | String(format:uuid) | [Desc. `id`](#desc-791) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `keyword` | String | [Desc. `keyword`](#desc-792) | | `remote_number` | String | [Desc. `remote_number`](#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](#schema-optoutitem) | | | `type` | String | | __associations__ | Name | Type | Description | | ---------- | ---------- | ----------------------------- | | `host_did` | `host_did` | [Desc. `host_did`](#desc-794) | | `sms` | `sms` | [Desc. `sms`](#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`](#desc-796) | | `number` | String | [Desc. `number`](#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`](#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](#schema-pageinfo) | | | `results` | Array:[OptoutItemResponse](#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](#schema-ordererrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-799) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](#desc-800) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-801) | | `status` | [OrderStatus](#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](#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](#schema-pageinfo) | | | `results` | Array:[OrderResponse](#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`](#desc-802) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `is_stale` | Boolean | | | `review_status` | [Enum](#enum-803):String | [Desc. `review_status`](#desc-804) | | `status` | [Enum](#enum-805):String | [Desc. `status`](#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](#schema-overwriterequest) | | | `type` | String | | __associations__ | Name | Type | Description | | ---------------- | ---------------- | ---------------------------------- | | `did` | `did` | [Desc. `did`](#desc-807) | | `new_nnid_entry` | `new_nnid_entry` | | | `reviewed_user` | `reviewed_user` | [Desc. `reviewed_user`](#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`](#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`](#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](#schema-pageinfo) | | | `results` | Array:[OverwriteRequestResponse](#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](#enum-811):String | [Desc. `code`](#desc-812) | | `detail` | String | [Desc. `detail`](#desc-813) | | `params` | `params` | [Desc. `params`](#desc-814) | | `sub_code` | String | [Desc. `sub_code`](#desc-815) | | `title` | String | [Desc. `title`](#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](#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](#schema-ordererrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-817) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..255) | | | `notes` | String | | | `status` | [OrderStatus](#schema-orderstatus) | | | `type` | [RequestType](#schema-requesttype) | | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `*` | [One-Of](#type-818) | | #### Desc. `id` {#desc-817} Another format for UUID, used primarily for tasks, requests and messages. #### One-Of {#type-818} Types * [RequestAddCampaignNumbersData](#schema-requestaddcampaignnumbersdata) * [RequestAddMessagingNumbersData](#schema-requestaddmessagingnumbersdata) * [RequestAddVoiceNumbersData](#schema-requestaddvoicenumbersdata) * [RequestNewNumbersData](#schema-requestnewnumbersdata) * [RequestRegisterBrandData](#schema-requestregisterbranddata) * [RequestRegisterCampaignData](#schema-requestregistercampaigndata) * [RequestRemoveCampaignNumbersData](#schema-requestremovecampaignnumbersdata) * [RequestRemoveMessagingNumbersData](#schema-requestremovemessagingnumbersdata) * [RequestRemoveNumbersData](#schema-requestremovenumbersdata) * [RequestRemoveVoiceNumbersData](#schema-requestremovevoicenumbersdata) * [RequestUnregisterBrandData](#schema-requestunregisterbranddata) * [RequestUnregisterCampaignData](#schema-requestunregistercampaigndata) * [RequestVetBrandData](#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`](#desc-819) | | `numbers` | Array:String | [Desc. `numbers`](#desc-820) | | `tcr_campaign_id` | String | [Desc. `tcr_campaign_id`](#desc-821) | | `tmobile_enabled` | Boolean | [Desc. `tmobile_enabled`](#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`](#desc-823) | | `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](#desc-824) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-825) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-826) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#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`](#desc-828) | | `switch_id` | String(format:uuid) | [Desc. `switch_id`](#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`](#desc-830) | | `expires_at` | String(format:date-time) | [Desc. `expires_at`](#desc-831) | | `filename` | String | [Desc. `filename`](#desc-832) | | `id` | String(format:ulid) | [Desc. `id`](#desc-833) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(1..128) | [Desc. `name`](#desc-834) | | `notes` | String | [Desc. `notes`](#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](#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](#schema-pageinfo) | | | `results` | Array:[RequestDocumentResponse](#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](#schema-addonsdata) | | | `city` | String | | | `min_quantity` | String | [Desc. `min_quantity`](#desc-836) | | `npa` | String | [Desc. `npa`](#desc-837) | | `number_type` | Enum(`NONE`, `TENDLC`, `TOLLFREE`):String | [Desc. `number_type`](#desc-838) | | `numbers` | Array:String(format:tel) | [Desc. `numbers`](#desc-839) | | `nxx` | String | [Desc. `nxx`](#desc-840) | | `quantity` | String | [Desc. `quantity`](#desc-841) | | `rate_center` | String | [Desc. `rate_center`](#desc-842) | | `state` | String | [Desc. `state`](#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](#schema-requestprovisionrecorderrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-844) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `number` | String | | | `status` | [RequestProvisionRecordStatus](#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](#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](#schema-pageinfo) | | | `results` | Array:[RequestProvisionRecordResponse](#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`](#desc-845) | | `brand_relationship` | String | | | `business_contact_email` | String(format:email) | | | `cdr_id` | String(format:uuid) | [Desc. `cdr_id`](#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`](#desc-847) | | `help_message` | String | | | `embedded_phone` | Boolean | | | `tcr_brand_id` | String | [Desc. `tcr_brand_id`](#desc-848) | | `embedded_link` | Boolean | | | `tcr_reseller_id` | String | [Desc. `tcr_reseller_id`](#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`](#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`](#desc-851) | | `subscriber_optin` | Boolean | | | `help_keywords` | String | [Desc. `help_keywords`](#desc-852) | | `expedite_tier` | Enum(`NONE`, `PRIORITY`):String | [Desc. `expedite_tier`](#desc-853) | | `affiliate_marketing` | Boolean | | | `subscriber_help` | Boolean | | | `samples` | Array:String | | | `optin_keywords` | String | [Desc. `optin_keywords`](#desc-854) | | `privacy_policy_link` | String | | | `number_pool` | Boolean | | | `terms_and_conditions` | Boolean | [Desc. `terms_and_conditions`](#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`](#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`](#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`](#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`](#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](#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`](#desc-860) | | `vetting_class` | String | [Desc. `vetting_class`](#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](#schema-pageinfo) | | | `results` | Array:[RequestResponse](#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`](#desc-862) | | `detail` | String | [Desc. `detail`](#desc-863) | | `params` | `params` | [Desc. `params`](#desc-864) | | `sub_code` | String | [Desc. `sub_code`](#desc-865) | | `title` | String | [Desc. `title`](#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`](#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](#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](#enum-868):String | [Desc. `review_status`](#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](#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`](#desc-870) | | `id` | String(format:uuid) | [Desc. `id`](#desc-871) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `level` | Enum(`GUEST`, `CLIENT`, `ADMIN`):String | [Desc. `level`](#desc-872) | | `name` | String | [Desc. `name`](#desc-873) | | `notes` | String | [Desc. `notes`](#desc-874) | | `rank` | Integer(>= 0) | [Desc. `rank`](#desc-875) | | `resources` | Array:[SubObject](#type-881) | [Desc. `resources`](#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](#type-879) | | | `resource_id` | String | | | `scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](#desc-880) | #### SubObject {#type-879} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ---------------------------- | -------------------------- | | `name` | [Enum](#enum-876):String | [Desc. `name`](#desc-877) | | `value` | Enum(`true`, `false`):String | [Desc. `value`](#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](#schema-pageinfo) | | | `results` | Array:[RolePolicyResponse](#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](#enum-883):String | [Desc. `actions`](#desc-884) | | `allowed_levels` | Array:Enum(`GUEST`, `CLIENT`, `ADMIN`):String | [Desc. `allowed_levels`](#desc-885) | | `allowed_scopes` | Array:Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `allowed_scopes`](#desc-886) | | `hint` | String | [Desc. `hint`](#desc-887) | | `label` | String | [Desc. `label`](#desc-888) | | `resource_id` | String | | | `topics` | Array:String | [Desc. `topics`](#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](#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](#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](#schema-pageinfo) | | | `results` | Array:[RoleResponse](#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`](#desc-890) | | `items` | Array:[SubObject](#type-891) | [Desc. `items`](#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](#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`](#desc-893) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `name` | String(3..255) | [Desc. `name`](#desc-894) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-895) | | `size` | Enum(`16`, `24`, `32`, `48`, `64`):Number | [Desc. `size`](#desc-896) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `usage` | Enum(`NONE`, `SIGNING`, `ENCRYPTION`):String | [Desc. `usage`](#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](#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](#schema-pageinfo) | | | `results` | Array:[SecretKeyResponse](#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`](#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`](#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](#schema-sharedresourcegroup) | | | `type` | String | | __associations__ | Name | Type | Description | | --------- | --------- | ---------------------------- | | `account` | `account` | [Desc. `account`](#desc-900) | | `donee` | `donee` | [Desc. `donee`](#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`](#desc-902) | #### Desc. `id` {#desc-902} A Universally unique identifier, which identifies the resource __donee__ | Name | Type | Description | | ---- | ------------------- | ----------------------- | | `id` | String(format:uuid) | [Desc. `id`](#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](#schema-pageinfo) | | | `results` | Array:[SharedResourceGroupResponse](#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`](#desc-904) | | `mms_signing_scheme` | [SwitchSigningScheme](#schema-switchsigningscheme) | | | `voice_data` | String | [Desc. `voice_data`](#desc-905) | | `updated_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `sms_data` | String | [Desc. `sms_data`](#desc-906) | | `sms_signing_scheme` | [SwitchSigningScheme](#schema-switchsigningscheme) | | | `voice_protocol` | [Enum](#enum-907):String | [Desc. `voice_protocol`](#desc-908) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `mms_options` | `mms_options` | [Desc. `mms_options`](#desc-909) | | `sms_message_format` | [Enum](#enum-910):String | [Desc. `sms_message_format`](#desc-911) | | `mms_message_format` | [Enum](#enum-912):String | [Desc. `mms_message_format`](#desc-913) | | `voice_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `voice_auth_method`](#desc-914) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-915) | | `name` | String | [Desc. `name`](#desc-916) | | `sms_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `sms_auth_method`](#desc-917) | | `mms_secret` | String | [Desc. `mms_secret`](#desc-918) | | `mms_identity` | String | Acts as the username in basic auth | | `sms_enabled` | Boolean | [Desc. `sms_enabled`](#desc-919) | | `mms_encryption_method` | [SwitchEncryptionMethod](#schema-switchencryptionmethod) | | | `voice_enabled` | Boolean | [Desc. `voice_enabled`](#desc-920) | | `sms_signing_hash` | [SwitchSigningHash](#schema-switchsigninghash) | | | `sms_encryption_method` | [SwitchEncryptionMethod](#schema-switchencryptionmethod) | | | `voice_identity` | String | | | `mms_name` | String | [Desc. `mms_name`](#desc-921) | | `mms_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `mms_auth_method`](#desc-922) | | `mms_protocol` | [Enum](#enum-923):String | [Desc. `mms_protocol`](#desc-924) | | `voice_name` | String | | | `voice_secret` | String | | | `sms_name` | String | Reserved for future use | | `mms_signing_hash` | [SwitchSigningHash](#schema-switchsigninghash) | | | `mms_data` | String(format:url) | [Desc. `mms_data`](#desc-925) | | `sms_protocol` | [Enum](#enum-926):String | [Desc. `sms_protocol`](#desc-927) | | `sms_identity` | String | Acts as the username in basic auth | | `sms_options` | `sms_options` | [Desc. `sms_options`](#desc-928) | | `id` | String(format:uuid) | [Desc. `id`](#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`](#desc-930) | | `forward_dlr` | Boolean | [Desc. `forward_dlr`](#desc-931) | | `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](#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`](#desc-933) | | `forward_dlr` | Boolean | [Desc. `forward_dlr`](#desc-934) | | `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](#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 <> = 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](#schema-switch) | | | `type` | String | | __associations__ | Name | Type | Description | | -------------------- | -------------------- | --------------------------------------- | | `api_key` | `api_key` | [Desc. `api_key`](#desc-936) | | `mms_encryption_key` | `mms_encryption_key` | [Desc. `mms_encryption_key`](#desc-937) | | `mms_signing_key` | `mms_signing_key` | [Desc. `mms_signing_key`](#desc-938) | | `sms_encryption_key` | `sms_encryption_key` | [Desc. `sms_encryption_key`](#desc-939) | | `sms_signing_key` | `sms_signing_key` | [Desc. `sms_signing_key`](#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](#schema-pageinfo) | | | `results` | Array:[SwitchResponse](#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`](#desc-941) | | `data` | [One-Of](#type-942) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-943) | | `inserted_at` | String(format:date-time) | [Desc. `inserted_at`](#desc-944) | | `timestamp` | String(format:date-time) | [Desc. `timestamp`](#desc-945) | | `topic` | [SystemEventTopic](#schema-systemeventtopic) | | | `type` | [SystemEventType](#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](#schema-systemeventdatacspcampaignregistered) * [SystemEventDataCspCampaignOptoutItemCreated](#schema-systemeventdatacspcampaignoptoutitemcreated) * [SystemEventDataCspCampaignOptoutItemDeleted](#schema-systemeventdatacspcampaignoptoutitemdeleted) * [SystemEventDataDidCreated](#schema-systemeventdatadidcreated) * [SystemEventDataDidDeleted](#schema-systemeventdatadiddeleted) * [SystemEventDataDidComponentCreated](#schema-systemeventdatadidcomponentcreated) * [SystemEventDataDidComponentDeleted](#schema-systemeventdatadidcomponentdeleted) * [SystemEventDataDidOptoutItemCreated](#schema-systemeventdatadidoptoutitemcreated) * [SystemEventDataDidOptoutItemDeleted](#schema-systemeventdatadidoptoutitemdeleted) * [SystemEventDataOsrOverwriteRequestPending](#schema-systemeventdataosroverwriterequestpending) * [SystemEventDataOsrOverwriteRequestCompleted](#schema-systemeventdataosroverwriterequestcompleted) * [SystemEventDataOrderCompleted](#schema-systemeventdataordercompleted) * [SystemEventDataRequestCompleted](#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](#schema-systemeventassociationprovisionrecord) | | | `requests` | Array:[SystemEventAssociationRequest](#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](#schema-requestprovisionrecorderrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-946) | | `number` | String(1..255) | [Desc. `number`](#desc-947) | | `status` | [RequestProvisionRecordStatus](#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](#schema-ordererrorcode) | | | `id` | String(format:ulid) | [Desc. `id`](#desc-948) | | `status` | [OrderStatus](#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`](#desc-949) | | `host_number` | String | [Desc. `host_number`](#desc-950) | | `keyword` | String | [Desc. `keyword`](#desc-951) | | `remote_number` | String | [Desc. `remote_number`](#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`](#desc-953) | | `host_number` | String | [Desc. `host_number`](#desc-954) | | `keyword` | String | [Desc. `keyword`](#desc-955) | | `remote_number` | String | [Desc. `remote_number`](#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`](#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](#schema-systemeventdatadidcomponent) | | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-958) | | `number` | String | [Desc. `number`](#desc-959) | | `reason` | [SystemEventDataDidCreatedReason](#schema-systemeventdatadidcreatedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#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](#schema-systemeventdatadidcomponent) | | | `did_id` | String(format:uuid) | [Desc. `did_id`](#desc-961) | | `number` | String | [Desc. `number`](#desc-962) | | `reason` | [SystemEventDataDidDeletedReason](#schema-systemeventdatadiddeletedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#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`](#desc-964) | | `number` | String | [Desc. `number`](#desc-965) | | `reason` | [SystemEventDataDidCreatedReason](#schema-systemeventdatadidcreatedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#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`](#desc-967) | | `number` | String | [Desc. `number`](#desc-968) | | `reason` | [SystemEventDataDidDeletedReason](#schema-systemeventdatadiddeletedreason) | | | `request_id` | String(format:ulid) | [Desc. `request_id`](#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`](#desc-970) | | `host_number` | String | [Desc. `host_number`](#desc-971) | | `keyword` | String | [Desc. `keyword`](#desc-972) | | `remote_number` | String | [Desc. `remote_number`](#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`](#desc-974) | | `host_number` | String | [Desc. `host_number`](#desc-975) | | `keyword` | String | [Desc. `keyword`](#desc-976) | | `remote_number` | String | [Desc. `remote_number`](#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](#schema-ordererrorcode) | | | `order_id` | String(format:ulid) | [Desc. `order_id`](#desc-978) | | `status` | [OrderStatus](#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`](#desc-979) | | `error_code` | Enum(`OK`):String | Further explanation of an error status | | `new_nnid_service_provider` | String | | | `number` | String | [Desc. `number`](#desc-980) | | `osr_overwrite_request_id` | String(format:ulid) | [Desc. `osr_overwrite_request_id`](#desc-981) | | `review_status` | [Enum](#enum-982):String | [Desc. `review_status`](#desc-983) | | `status` | [Enum](#enum-984):String | [Desc. `status`](#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`](#desc-986) | | `error_code` | Enum(`OK`):String | Further explanation of an error status | | `new_nnid_service_provider` | String | | | `number` | String | [Desc. `number`](#desc-987) | | `osr_overwrite_request_id` | String(format:ulid) | [Desc. `osr_overwrite_request_id`](#desc-988) | | `review_status` | [Enum](#enum-989):String | [Desc. `review_status`](#desc-990) | | `status` | [Enum](#enum-991):String | [Desc. `status`](#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](#type-993) | | | `error_code` | [OrderErrorCode](#schema-ordererrorcode) | | | `order_id` | String(format:ulid) | [Desc. `order_id`](#desc-994) | | `request_id` | String(format:ulid) | [Desc. `request_id`](#desc-995) | | `status` | [OrderStatus](#schema-orderstatus) | | | `type` | [RequestType](#schema-requesttype) | | #### One-Of {#type-993} Types * [SystemEventDataRequestCompletedDataRegisterBrand](#schema-systemeventdatarequestcompleteddataregisterbrand) * [SystemEventDataRequestCompletedDataRegisterCampaign](#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`](#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`](#desc-997) | | `campaign_id` | String(format:uuid) | [Desc. `campaign_id`](#desc-998) | | `reseller_id` | String(format:uuid) | [Desc. `reseller_id`](#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](#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`](#desc-1000) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-1001) | | `auth_name` | String | [Desc. `auth_name`](#desc-1002) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-1003) | | `custom_headers` | Array:[SubObject](#type-1004) | [Desc. `custom_headers`](#desc-1005) | | `custom_query_params` | Array:[SubObject](#type-1006) | [Desc. `custom_query_params`](#desc-1007) | | `data` | String | [Desc. `data`](#desc-1008) | | `name` | String(1..255) | [Desc. `name`](#desc-1009) | | `notes` | String(0..65535) | [Desc. `notes`](#desc-1010) | | `protocol` | Enum(`NONE`, `HTTP`, `SFTP`):String | [Desc. `protocol`](#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 ` 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 ` 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](#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](#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](#type-1012) | | #### One-Of {#type-1012} Types * [CartRequestAddCampaignNumbersData](#schema-cartrequestaddcampaignnumbersdata) * [CartRequestAddMessagingNumbersData](#schema-cartrequestaddmessagingnumbersdata) * [CartRequestAddVoiceNumbersData](#schema-cartrequestaddvoicenumbersdata) * [CartRequestNewNumbersData](#schema-cartrequestnewnumbersdata) * [CartRequestRegisterBrandData](#schema-cartrequestregisterbranddata) * [CartRequestRegisterCampaignData](#schema-cartrequestregistercampaigndata) * [CartRequestRemoveCampaignNumbersData](#schema-cartrequestremovecampaignnumbersdata) * [CartRequestRemoveMessagingNumbersData](#schema-cartrequestremovemessagingnumbersdata) * [CartRequestRemoveNumbersData](#schema-cartrequestremovenumbersdata) * [CartRequestRemoveVoiceNumbersData](#schema-cartrequestremovevoicenumbersdata) * [CartRequestUnregisterBrandData](#schema-cartrequestunregisterbranddata) * [CartRequestUnregisterCampaignData](#schema-cartrequestunregistercampaigndata) * [CartRequestVetBrandData](#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](#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](#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](#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](#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`](#desc-1013) | | `forward_number` | String | [Desc. `forward_number`](#desc-1014) | | `help_message` | String(0..255) | [Desc. `help_message`](#desc-1015) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-1016) | | `segment_overrides` | Array:[SubObject](#type-1021) | [Desc. `segment_overrides`](#desc-1022) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](#desc-1023) | | `upgrade_asset_handling` | [Enum](#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`](#desc-1017) | | `id` | String(format:uuid) | [Desc. `id`](#desc-1018) | | `segment_threshold` | Integer | [Desc. `segment_threshold`](#desc-1019) | | `target_reference_id` | String | [Desc. `target_reference_id`](#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: _ 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](#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`](#desc-1025) | | `notes` | String(0..65535) | [Desc. `notes`](#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](#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`](#desc-1027) | | `name` | String | [Desc. `name`](#desc-1028) | | `notes` | String | [Desc. `notes`](#desc-1029) | | `rank` | Integer(>= 0) | [Desc. `rank`](#desc-1030) | | `resources` | Array:[SubObject](#type-1036) | [Desc. `resources`](#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](#type-1034) | | | `resource_id` | String | | | `scope` | Enum(`IGNORE`, `ACCOUNT`, `USER`, `SYSTEM`):String | [Desc. `scope`](#desc-1035) | #### SubObject {#type-1034} Sub-Schema __Type__ Object | Name | Type | Description | | ------- | ---------------------------- | --------------------------- | | `name` | [Enum](#enum-1031):String | [Desc. `name`](#desc-1032) | | `value` | Enum(`true`, `false`):String | [Desc. `value`](#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](#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](#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](#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`](#desc-1038) | | `email` | String(format:email) | [Desc. `email`](#desc-1039) | | `first_name` | String | [Desc. `first_name`](#desc-1040) | | `last_name` | String | [Desc. `last_name`](#desc-1041) | | `title` | String | [Desc. `title`](#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](#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`](#desc-1043) | | `auth_identity` | String | The username for a BASIC auth_method | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-1044) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-1045) | | `destination` | String | [Desc. `destination`](#desc-1046) | | `priority` | Integer | [Desc. `priority`](#desc-1047) | | `tts_message_set_id` | String(format:uuid) | [Desc. `tts_message_set_id`](#desc-1048) | | `type` | [Enum](#enum-1049):String | [Desc. `type`](#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`](#desc-1051) | | `auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `auth_method`](#desc-1052) | | `auth_name` | String | [Desc. `auth_name`](#desc-1053) | | `auth_secret` | String | [Desc. `auth_secret`](#desc-1054) | | `custom_headers` | Array:[SubObject](#type-1055) | [Desc. `custom_headers`](#desc-1056) | | `custom_query_params` | Array:[SubObject](#type-1057) | | | `data` | String | [Desc. `data`](#desc-1058) | | `enabled` | Boolean | [Desc. `enabled`](#desc-1059) | | `name` | String(..255) | [Desc. `name`](#desc-1060) | | `notes` | String(..65535) | [Desc. `notes`](#desc-1061) | | `protocol` | Enum(`NONE`, `HTTP`, `SMTP`, `SFTP`, `EMAIL`):String | [Desc. `protocol`](#desc-1062) | | `recipient` | String | [Desc. `recipient`](#desc-1063) | | `topics` | Array:[Enum](#enum-1064):String | [Desc. `topics`](#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](#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](#type-1071) | [Desc. `keywords`](#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`](#desc-1066) | | `is_wildcard` | Boolean | [Desc. `is_wildcard`](#desc-1067) | | `keyword` | String | [Desc. `keyword`](#desc-1068) | | `message` | String | [Desc. `message`](#desc-1069) | | `message2` | String | [Desc. `message2`](#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](#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`](#desc-1073) | | `block_messaging` | Enum(`NONE`, `SMS`, `MMS`, `ALL`):String | [Desc. `block_messaging`](#desc-1074) | | `block_voip` | [Enum](#enum-1075):String | [Desc. `block_voip`](#desc-1076) | | `notes` | String | [Desc. `notes`](#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](#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`](#desc-1078) | | `mms_data` | String(format:url) | [Desc. `mms_data`](#desc-1079) | | `mms_enabled` | Boolean | [Desc. `mms_enabled`](#desc-1080) | | `mms_identity` | String | Acts as the username in basic auth | | `mms_message_format` | [Enum](#enum-1081):String | [Desc. `mms_message_format`](#desc-1082) | | `mms_name` | String | [Desc. `mms_name`](#desc-1083) | | `mms_options` | `mms_options` | [Desc. `mms_options`](#desc-1084) | | `mms_protocol` | [Enum](#enum-1085):String | [Desc. `mms_protocol`](#desc-1086) | | `mms_secret` | String | [Desc. `mms_secret`](#desc-1087) | | `name` | String | [Desc. `name`](#desc-1088) | | `notes` | String | Any notes about the switch | | `sms_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`, `HMAC_SHA256`):String | [Desc. `sms_auth_method`](#desc-1089) | | `sms_data` | String | [Desc. `sms_data`](#desc-1090) | | `sms_enabled` | Boolean | [Desc. `sms_enabled`](#desc-1091) | | `sms_identity` | String | Acts as the username in basic auth | | `sms_message_format` | [Enum](#enum-1092):String | [Desc. `sms_message_format`](#desc-1093) | | `sms_name` | String | Reserved for future use | | `sms_options` | `sms_options` | [Desc. `sms_options`](#desc-1094) | | `sms_protocol` | [Enum](#enum-1095):String | [Desc. `sms_protocol`](#desc-1096) | | `sms_secret` | String | [Desc. `sms_secret`](#desc-1097) | | `voice_auth_method` | Enum(`NONE`, `BASIC`, `BEARER`):String | [Desc. `voice_auth_method`](#desc-1098) | | `voice_data` | String | [Desc. `voice_data`](#desc-1099) | | `voice_enabled` | Boolean | [Desc. `voice_enabled`](#desc-1100) | | `voice_identity` | String | | | `voice_name` | String | | | `voice_protocol` | [Enum](#enum-1101):String | [Desc. `voice_protocol`](#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`](#desc-1103) | | `forward_dlr` | Boolean | [Desc. `forward_dlr`](#desc-1104) | | `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](#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`](#desc-1106) | | `forward_dlr` | Boolean | [Desc. `forward_dlr`](#desc-1107) | | `pad_shortcodes` | Boolean | [Desc. `pad_shortcodes`](#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`](#desc-1109) | | `email` | String(format:email) | [Desc. `email`](#desc-1110) | | `first_name` | String | [Desc. `first_name`](#desc-1111) | | `id` | String(format:uuid) | [Desc. `id`](#desc-1112) | | `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp | | `last_name` | String | [Desc. `last_name`](#desc-1113) | | `title` | String | [Desc. `title`](#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](#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](#schema-pageinfo) | | | `results` | Array:[UserResponse](#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`](#desc-1115) | | `id` | String(format:uuid) | [Desc. `id`](#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](#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](#schema-pageinfo) | | | `results` | Array:[VoiceResponse](#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](#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](#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`](#desc-1117) | | `id` | String(format:uuid) | [Desc. `id`](#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](#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](#schema-pageinfo) | | | `results` | Array:[VoipAllowedClientIpResponse](#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 ``` # End notes Some information has been omitted to keep this document brief and quick to understand, for example error handling has been omitted, the error responses are provided in the API reference. A particular error status was also not mentioned: 403 Forbidden, the client may receive a 403 if the incorrect API key is used for ordering, or if the API Key was not configured to perform the specified action. If a 403 is received and it is believed to have happened in error, then contact support with the action that was taken and the API Key that was used for the request, it should be resolved in a timely manner. # Changelog ## 2026-07-29 * Stubbed Section on `Roles`, additional developer commentary may be necessary to express full extent. * Added Secret Key section * Updated Switches to include Secret Key related changes (though this is just a side-effect of regenerating documentation naturally from the openapi) ## 2026-07-06 * Added initial Request Document APIs * Added `enhanced_country_code` and `lrn_activated_at` to Bulk Dip Task payload ## 2026-05-20 * Added `NEW_NUMBERS` request type * Added Inventory section ## 2025-09-21 * Added Campaign Optout Items section (read-only at this time) * Added Optout Item Event Subscription Events * For DID level Optout Items * For Campaign level Optout items ## 2025-04-15 * Added missing fields for the System Event Provision Record Association (as a part of the visibilty changes) * `status` * `error_code` * Added additional documentation on Provision Record statuses and Error Codes ## 2024-10-22 * Added Messaging Auto Response section ## 2024-10-04 * Added `CSP_CAMPAIGN_REGISTERED` event ## 2023-05-23 * Refactored [Cart Requests](#cart-requests) and [Requests](#requests) to match type names * Added CSP Enums section ## 2023-05-08 * Added section on Event Subscriptions and their events * Added section on DID Destinations proper ## 2023-01-26 * Add missing section on `REMOVE_NUMBERS` * Changed fonts for readability ## 2023-01-02 * Add Unshare route for CSP Campaigns `DELETE /api/v1/campaigns/{campaign_id}/shared_resource_group` * Add Shared Resource Group route for CSP Campaigns `GET /api/v1/campaigns/{campaign_id}/shared_resource_group` ## 2022-12-16 * Dropped revision numbers in favour of dates for versioning * Added Sections on DID / Number Optout Items ## 2022-10-18 * Use openapi spec to generate request/response models * Add Bulk Dip Task section ## 2022-02-24 * Document overhaul ## 2022-02-18 * Added sections on registering and unregistering TCR Brands and Campaigns ## 2021-12-31 * Refreshed structure of document * Added section on resources (will expand as needed later) ## 2021-08-24 * Added section on binding numbers to campaign via ADD_CAMPAIGN_NUMBERS ## 2021-08-18 * Fixed table formatting * Increased document margins with table formatting fixed ## Pre 2021-08-18 * Added section on MMS enablement for existing numbers * Added section on Authorization * Added section on access denied codes * First revision containing basic information on provisioning numbers