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`
`id`	String(format:uuid)	Desc. `id`
`inserted_at`	String(format:date-time)	An ISO8601 formatted timestamp
`keyword`	String	Desc. `keyword`
`remote_number`	String	Desc. `remote_number`
`updated_at`	String(format:date-time)	An ISO8601 formatted timestamp

Desc. `host_number`

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

That is the number that received the optout request.

Desc. `id`

A Universally unique identifier, which identifies the resource

Desc. `keyword`

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`

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

Example

{
  "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

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

POST /api/v1/numbers/{number_id}/optout_items HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 120

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

Response 201

application/json

HTTP/1.1 201
Content-Type: application/json
Content-Length: 484

{
  "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/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"
    }
  ]
}

Delete Optout Item

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

Path Desc. id

Optout Item ID A Universally unique identifier, which identifies the resource

Request

DELETE /api/v1/optout_items/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/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 all Optout Items

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
last	Integer	Query Desc. last
after	String	Query Desc. after
before	String	Query Desc. before

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/optout_items HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/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"
    }
  ]
}

List all Optout Items for DID / Number

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
last	Integer	Query Desc. last
after	String	Query Desc. after
before	String	Query Desc. before

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/numbers/{number_id}/optout_items HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/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 Optout Item

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

Path Desc. id

Optout Item ID A Universally unique identifier, which identifies the resource

Request

GET /api/v1/optout_items/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/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"
    }
  ]
}

DID - Optout Items

Schema

Desc. host_number

Desc. id

Desc. keyword

Desc. remote_number

Summary

API

Create Optout Item

Request application/json

Response 201

application/json

Response 403

application/json

Response 404

application/json

Delete Optout Item

Path Desc. id

Request

Response 200

application/json

Response 403

application/json

Response 404

application/json

Response 422

application/json

List all Optout Items

Query Desc. first

Query Desc. last

Query Desc. after

Query Desc. before

Request

Response 200

application/json

Response 403

application/json

List all Optout Items for DID / Number

Query Desc. first

Query Desc. last

Query Desc. after

Query Desc. before

Request

Response 200

application/json

Response 403

application/json

Get Optout Item

Path Desc. id

Request

Response 200

application/json

Response 403

application/json

Response 404

application/json

Desc. `host_number`

Desc. `id`

Desc. `keyword`

Desc. `remote_number`