> Tychron Atlas API & Provisioning Reference — chapter 23 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/did-optout-items/
> 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

# 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`](https://docs.tychron.com/api-reference/did-optout-items/#desc-349)   |
| `id`            | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/did-optout-items/#desc-350)            |
| `inserted_at`   | String(format:date-time) | An ISO8601 formatted timestamp     |
| `keyword`       | String                   | [Desc. `keyword`](https://docs.tychron.com/api-reference/did-optout-items/#desc-351)       |
| `remote_number` | String                   | [Desc. `remote_number`](https://docs.tychron.com/api-reference/did-optout-items/#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](https://docs.tychron.com/api-reference/did-optout-items/#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](https://docs.tychron.com/api-reference/did-optout-items/#desc-354)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/did-optout-items/#desc-355)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/did-optout-items/#desc-356)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/did-optout-items/#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](https://docs.tychron.com/api-reference/did-optout-items/#desc-358)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/did-optout-items/#desc-359)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/did-optout-items/#desc-360)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/did-optout-items/#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](https://docs.tychron.com/api-reference/did-optout-items/#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"
    }
  ]
}
```

---

Previous chapter: https://docs.tychron.com/api-reference/did-destinations.md  
Next chapter: https://docs.tychron.com/api-reference/osr-overwrite-requests.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt