> Tychron Atlas API & Provisioning Reference — chapter 6 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/cart-requests/
> Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · 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

# 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`](https://docs.tychron.com/api-reference/cart-requests/#desc-12)         |
| `inserted_at` | String(format:date-time)           | An ISO8601 formatted timestamp |
| `name`        | String                             |                                |
| `notes`       | String                             |                                |
| `type`        | [RequestType](https://docs.tychron.com/api-reference/schemas/#schema-requesttype) |                                |
| `updated_at`  | String(format:date-time)           | An ISO8601 formatted timestamp |
| `*`           | [One-Of](https://docs.tychron.com/api-reference/cart-requests/#type-13)                 |                                |

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

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

#### One-Of {#type-13}

Types

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



__Example__

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


## 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](https://docs.tychron.com/api-reference/cart-requests/#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](https://docs.tychron.com/api-reference/cart-requests/#desc-15) |
| id      | String(format:ulid)! | [Path Desc. id](https://docs.tychron.com/api-reference/cart-requests/#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](https://docs.tychron.com/api-reference/cart-requests/#desc-17) |
| id      | String(format:ulid)! | [Path Desc. id](https://docs.tychron.com/api-reference/cart-requests/#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](https://docs.tychron.com/api-reference/cart-requests/#desc-19) |

__Query Parameters__

| Name   | Type    | Description                    |
| ------ | ------- | ------------------------------ |
| first  | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/cart-requests/#desc-20)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/cart-requests/#desc-21)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/cart-requests/#desc-22)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/cart-requests/#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](https://docs.tychron.com/api-reference/cart-requests/#desc-24) |
| id      | String(format:ulid)! | [Path Desc. id](https://docs.tychron.com/api-reference/cart-requests/#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](https://docs.tychron.com/api-reference/schemas/#schema-addonsdata)          |                                  |
| `city`         | String                                    |                                  |
| `min_quantity` | String                                    | [Desc. `min_quantity`](https://docs.tychron.com/api-reference/cart-requests/#desc-26) |
| `npa`          | String                                    | [Desc. `npa`](https://docs.tychron.com/api-reference/cart-requests/#desc-27)          |
| `number_type`  | Enum(`NONE`, `TENDLC`, `TOLLFREE`):String | [Desc. `number_type`](https://docs.tychron.com/api-reference/cart-requests/#desc-28)  |
| `numbers`      | Array:String(format:tel)                  | [Desc. `numbers`](https://docs.tychron.com/api-reference/cart-requests/#desc-29)      |
| `nxx`          | String                                    | [Desc. `nxx`](https://docs.tychron.com/api-reference/cart-requests/#desc-30)          |
| `quantity`     | String                                    | [Desc. `quantity`](https://docs.tychron.com/api-reference/cart-requests/#desc-31)     |
| `rate_center`  | String                                    | [Desc. `rate_center`](https://docs.tychron.com/api-reference/cart-requests/#desc-32)  |
| `state`        | String                                    | [Desc. `state`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#desc-35)   |
| `message_class` | Enum(`A2P`, `P2P`):String | [Desc. `message_class`](https://docs.tychron.com/api-reference/cart-requests/#desc-36) |
| `mms_enabled`   | Boolean                   | [Desc. `mms_enabled`](https://docs.tychron.com/api-reference/cart-requests/#desc-37)   |
| `numbers`       | Array:String(format:tel)  | [Desc. `numbers`](https://docs.tychron.com/api-reference/cart-requests/#desc-38)       |
| `switch_id`     | String(format:uuid)       | [Desc. `switch_id`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#desc-41)        |
| `help_message`              | String              |                                          |
| `message_flow`              | String              |                                          |
| `mno_ids`                   | Array:String        |                                          |
| `number_pool`               | Boolean             |                                          |
| `optin_keywords`            | String              | [Desc. `optin_keywords`](https://docs.tychron.com/api-reference/cart-requests/#desc-42)       |
| `optin_message`             | String              |                                          |
| `optout_keywords`           | String              | [Desc. `optout_keywords`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#desc-44)         |
| `tcr_reseller_id`           | String              | [Desc. `tcr_reseller_id`](https://docs.tychron.com/api-reference/cart-requests/#desc-45)      |
| `terms_and_conditions`      | Boolean             | [Desc. `terms_and_conditions`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#desc-47) |
| `*`       | [One-Of](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#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](https://docs.tychron.com/api-reference/cart-requests/#type-49)
* [... campaign_id](https://docs.tychron.com/api-reference/cart-requests/#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`](https://docs.tychron.com/api-reference/cart-requests/#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.

---

Previous chapter: https://docs.tychron.com/api-reference/ordering-system-reference.md  
Next chapter: https://docs.tychron.com/api-reference/cart-request-documents.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt