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

Read More
← Atlas API & Provisioning Reference

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
inserted_at String(format:date-time) An ISO8601 formatted timestamp
name String
notes String
type RequestType
updated_at String(format:date-time) An ISO8601 formatted timestamp
* One-Of

Desc. id

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

One-Of

Types

Example

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

API

Creating A New Cart's Request

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

Path Desc. cart_id

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

Request application/json

POST /api/v1/carts/{cart_id}/requests HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 294

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

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

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

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

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

Updating An Existing Cart's Request

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
id String(format:ulid)! Path Desc. id

Path Desc. cart_id

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

Path Desc. id

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

Request application/json

PATCH /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 210

{
  "data": {
    "name": "string",
    "notes": "string",
    "*": {
      "numbers": [
        "12003004000"
      ],
      "*": {
        "tcr_campaign_id": "C000000"
      }
    }
  },
  "type": "request"
}

Response 200

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

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

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

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

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

Deleting An Existing Cart's Request

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
id String(format:ulid)! Path Desc. id

Path Desc. cart_id

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

Path Desc. id

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

Request

DELETE /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1
Accept: application/json

Response 200

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

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

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Response 422

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

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

List Existing Cart's Requests

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

Query Parameters

Name Type Description
first Integer Query Desc. first
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Path Desc. cart_id

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

Query Desc. first

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

Query Desc. last

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

Query Desc. after

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

Query Desc. before

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

Request

GET /api/v1/carts/{cart_id}/requests HTTP/1.1
Accept: application/json

Response 200

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

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

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Get Cart's Request

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
id String(format:ulid)! Path Desc. id

Path Desc. cart_id

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

Path Desc. id

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

Request

GET /api/v1/carts/{cart_id}/requests/{id} HTTP/1.1
Accept: application/json

Response 200

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

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

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

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
city String
min_quantity String Desc. min_quantity
npa String Desc. npa
number_type Enum(NONE, TENDLC, TOLLFREE):String Desc. number_type
numbers Array:String(format:tel) Desc. numbers
nxx String Desc. nxx
quantity String Desc. quantity
rate_center String Desc. rate_center
state String Desc. state

Desc. min_quantity

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

The 3 digit Area Code.

Desc. number_type

The wanted number type either TENDLC or TOLLFREE.

NONE is effectively a no-op or null.

Desc. numbers

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

The 3 digit Exchange Code.

Desc. quantity

The maximum numbers that should be requested based on the search critierias.

This pairs with min_quantity to form a range.

Desc. rate_center

The rate center code.

Desc. state

The 2 character state code, such as FL for Florida.

Example

{
  "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
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/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. numbers

A list of NANP 11-digit numbers to remove

Example

{
  "numbers": [
    "12003004000"
  ]
}

Request & Response

Request
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/json

{
  "data": {
    "name": "Remove 12003004000",
    "notes": "Some notes",
    "numbers": [
      "12003004000"
    ],
    "type": "REMOVE_NUMBERS"
  },
  "type": "request"
}
Response
HTTP/1.1 201 Created
Content-Type: application/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
message_class Enum(A2P, P2P):String Desc. message_class
mms_enabled Boolean Desc. mms_enabled
numbers Array:String(format:tel) Desc. numbers
switch_id String(format:uuid) Desc. switch_id

Desc. api_key_ids

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

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

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

Desc. message_class

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

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

Desc. mms_enabled

Should the numbers be MMS enabled?

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

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

Desc. numbers

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

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

For tollfree, additional action may be required before completion.

Desc. switch_id

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

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

Leaving this field blank will not overwrite the existing switch.

Example

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

Request & Response

Request
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/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/1.1 201 Created
Content-Type: application/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. numbers

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

Example

{
  "numbers": [
    "12003004000"
  ]
}

Request & Response

Request
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/json

{
  "data": {
    "name": "Remove messaging for 12003004000",
    "notes": "Some notes",
    "numbers": [
      "12003004000"
    ],
    "type": "REMOVE_MESSAGING_NUMBERS"
  },
  "type": "request"
}
Response
HTTP/1.1 201 Created
Content-Type: application/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

{
  "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
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/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

{
  "tcr_brand_id": "B000000"
}

Request & Response

Request
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/json

{
  "data": {
    "name": "Remove Brand B000001",
    "notes": "Some notes",
    "tcr_brand_id": "B000001",
    "type": "UNREGISTER_BRAND"
  },
  "type": "request"
}
Response
HTTP/1.1 201 Created
Content-Type: application/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
help_message String
message_flow String
mno_ids Array:String
number_pool Boolean
optin_keywords String Desc. optin_keywords
optin_message String
optout_keywords String Desc. optout_keywords
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
tcr_reseller_id String Desc. tcr_reseller_id
terms_and_conditions Boolean Desc. terms_and_conditions
terms_and_conditions_link String
use_case String

Desc. help_keywords

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

Excess spaces will be trimmed around each keyword.

Desc. optin_keywords

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

Excess spaces will be trimmed around each keyword.

Desc. optout_keywords

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

Excess spaces will be trimmed around each keyword.

Desc. tcr_brand_id

TCR issued Brand ID.

Desc. tcr_reseller_id

TCR issued Reseller ID.

Desc. terms_and_conditions

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

If false the campaign will not be accepted for registration.

Example

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

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

{
  "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
* One-Of

Desc. numbers

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

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

For example: 12003004000.

... tcr_campaign_id

Sub-Schema

Type Object

Name Type Description
tcr_campaign_id String Desc. tcr_campaign_id

Desc. tcr_campaign_id

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

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

... campaign_id

Sub-Schema

Type Object

Name Type Description
campaign_id String(format:uuid) Desc. campaign_id

Desc. campaign_id

The internal UUID of a known campaign.

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

One-Of

Types

Example

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

Request & Response

Request
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/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/1.1 201 Created
Content-Type: application/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

POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/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/1.1 201 Created
Content-Type: application/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. numbers

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

Example

{
  "numbers": [
    "12003004000"
  ]
}

Request & Response

Request
POST /api/v1/carts/01EH2Y28M6KXG14QMPM3HSP1Y0/requests HTTP/1.1
Authorization: Bearer HTTP_TOKEN
Accept: application/json
Content-Type: application/json

{
  "data": {
    "name": "Remove 12003004000 from Campaign",
    "notes": "Some notes",
    "numbers": [
      "12003004000"
    ],
    "type": "REMOVE_CAMPAIGN_NUMBERS"
  },
  "type": "request"
}
Response
HTTP/1.1 201 Created
Content-Type: application/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.

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