Customer.io Opt Outs API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Opt Outs API
  description: Customer.io provides REST APIs to send real-time customer data, retrieve data from your account, and trigger messages.
servers:
- url: https://track.customer.io
  description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://track-eu.customer.io
  description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://api.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Opt Outs
  description: 'Programmatically manage SMS and WhatsApp opt-outs. A person opts out of a specific sender on a specific channel—for example, they can opt out of SMS from one sender number while continuing to receive messages from another. Use these endpoints to list opt-outs across your workspace or for a single person, and to opt people out of, or back in to, specific senders.


    Opt-outs are distinct from subscription preferences, which govern the separate subscription-center/unsubscribe feature.'
paths:
  /v1/optouts:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - name: from
      in: query
      required: false
      description: Filter for a specific sender on any channel. For SMS, this is a sender phone number (E.164), an alphanumeric sender ID, or a messaging-service SID; for WhatsApp, it's the sender phone number.
      schema:
        type: string
        example: '+15551234567'
    - name: start
      in: query
      required: false
      description: A pagination cursor—a base64-encoded value returned in the `next` property of the previous page. Omit this parameter to return the first page; pass the previous page's `next` value to return the following page.
      schema:
        type: string
        example: MTox
    - $ref: '#/components/parameters/limit-100-1000'
    get:
      tags:
      - Opt Outs
      summary: List opt-outs in the workspace
      operationId: getOptouts
      security:
      - Bearer-Auth: []
      description: 'Return a workspace-wide list of opt-outs across all channels. Each entry represents a person and the senders/channels (SMS or WhatsApp) they''ve opted out of.


        A person opts out of a specific sender on a specific channel—for example, a person can opt out of SMS messages from one sender number while continuing to receive messages from another. An entry''s presence in the `optouts` array means the person is opted out of that sender/channel.


        Use the `from` parameter to filter for a specific sender. Use the `start` parameter with the `next` value from the previous response to paginate through results.


        **Note**: SMS sender values are stored normalized (trimmed and lowercased). For alphanumeric SMS senders and messaging-service SIDs, the response recovers the original casing from your workspace''s Twilio sender identities. E.164 phone numbers are unaffected.'
      responses:
        '200':
          description: Returns an array of opt-out records, one per person.
          content:
            application/json:
              schema:
                type: object
                properties:
                  optouts:
                    type: array
                    description: A list of people and their opt-outs. Each object represents a person and the senders/channels they've opted out of.
                    items:
                      type: object
                      properties:
                        customer_id:
                          type: string
                          description: The person's ID.
                          example: abc123
                        cio_id:
                          $ref: '#/components/schemas/cio_id'
                        optouts:
                          $ref: '#/components/schemas/optoutChannels'
                  next:
                    type: string
                    description: The `start` value for the next page of results. Absent or empty when there are no more results.
              example:
                optouts:
                - customer_id: abc123
                  cio_id: cio_03000001
                  optouts:
                  - channel: sms
                    from: '+15551234567'
                  - channel: whatsapp
                    from: '+15559876543'
                next: MTox
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
  /v1/customers/{customer_id}/optouts:
    servers:
    - url: https://api.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    - url: https://api-eu.customer.io
      description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - $ref: '#/components/parameters/customer_id'
    - $ref: '#/components/parameters/id_type'
    get:
      tags:
      - Opt Outs
      summary: Lookup a customer's opt-outs
      operationId: getPersonOptouts
      security:
      - Bearer-Auth: []
      description: 'Return a list of the senders and channels that a person has opted out of, across all channels.


        An entry''s presence in the `optouts` array means the person is opted out of that sender/channel. Use the `PUT /v1/customers/{customer_id}/optouts` endpoint to opt a person out of, or back in to, specific senders.'
      responses:
        '200':
          description: Returns the person's opt-outs across channels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  optouts:
                    $ref: '#/components/schemas/optoutChannels'
              example:
                optouts:
                - channel: sms
                  from: '+15551234567'
                - channel: whatsapp
                  from: '+15559876543'
        '404':
          description: The `customer_id` does not exist.
        '429':
          $ref: '#/components/responses/429'
    put:
      tags:
      - Opt Outs
      summary: Update a customer's opt-outs
      operationId: updatePersonOptouts
      security:
      - Bearer-Auth: []
      description: 'Opt a person out of, or back in to, specific senders and channels. Provide one entry per sender/channel in the `optouts` array.


        Set `optout` to `true` to opt the person out of a sender, or `false` to opt them back in. The `channel` field is optional and defaults to `sms`.


        This request is processed asynchronously; it may take a moment for changes to reflect in read requests.


        Customer.io also writes a consent record for each entry, with the collection point `api`.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - optouts
              properties:
                optouts:
                  type: array
                  description: The senders and channels you want to opt the person out of, or back in to. Provide one entry per sender/channel.
                  items:
                    type: object
                    required:
                    - from
                    - optout
                    properties:
                      from:
                        type: string
                        description: The sender you want to opt the person out of, or back in to. For SMS, this is a sender phone number (E.164), an alphanumeric sender ID, or a messaging-service SID; for WhatsApp, it's the sender phone number.
                        example: '+15551234567'
                      optout:
                        type: boolean
                        description: Set to `true` to opt the person out of the sender, or `false` to opt them back in.
                        example: true
                      channel:
                        type: string
                        description: The channel for the opt-out. Defaults to `sms`.
                        enum:
                        - sms
                        - whatsapp
                        default: sms
                        example: sms
            example:
              optouts:
              - from: '+15551234567'
                optout: true
                channel: sms
      responses:
        '204':
          description: A successful request produces an empty response.
        '400':
          description: The request is malformed—for example, it references an unknown `channel`.
        '404':
          description: The `customer_id` does not exist.
        '429':
          $ref: '#/components/responses/429'
components:
  schemas:
    appApiError:
      x-scalar-ignore: true
      type: object
      description: An array/list of failures where each entry is a separate failure reason.
      required:
      - errors
      properties:
        errors:
          type: array
          description: One entry for each reason the request failed.
          items:
            type: object
            required:
            - detail
            - status
            properties:
              detail:
                type: string
                description: What went wrong, in plain text. Most messages end with a support reference you can use if you need to contact support.
                example: bad request (reference a1b2c3)
              status:
                type: string
                description: The HTTP status code as a string.
                example: '400'
              code:
                type: string
                description: A stable identifier for the failure, on the errors that carry one. Use this rather than the text in `detail` if you need to identify the error programmatically.
                example: invalid_credentials
              source:
                type: object
                description: The part of the request that the error refers to.
                properties:
                  pointer:
                    type: string
                    description: A JSON pointer to the part of the request body that the error refers to.
                    example: /data/attributes/email
              meta:
                type: object
                additionalProperties: true
                description: Extra context (if available).
    cio_id:
      x-scalar-ignore: true
      type: string
      description: A unique identifier set by Customer.io, used to reference a person if you want to update their identifiers.
      example: a3000001
    optoutChannels:
      x-scalar-ignore: true
      type: array
      description: The senders and channels that the person is opted out of. An entry's presence means the person is opted out of that sender on that channel.
      items:
        type: object
        properties:
          channel:
            type: string
            description: The channel that the person is opted out of.
            enum:
            - sms
            - whatsapp
            example: sms
          from:
            type: string
            description: The sender that the person is opted out of. For SMS, this is a sender phone number (E.164), an alphanumeric sender ID, or a messaging-service SID; for WhatsApp, it's the sender phone number.
            example: '+15551234567'
  headers:
    Retry-After:
      description: How many seconds you must wait before you send another request. This header is present when you are rate limited by a per-second limit. If you hit a daily quota, this header is not set.
      schema:
        type: integer
        minimum: 1
        example: 1
  parameters:
    limit-100-1000:
      name: limit
      in: query
      required: false
      description: The maximum number of results you want to retrieve per page.
      schema:
        type: integer
        default: 100
        maximum: 1000
    id_type:
      name: id_type
      required: false
      in: query
      description: The type of `customer_id` you want to use to reference a person. If you don't provide this parameter, we assume that the `customer_id` in your request is a person's `id`. You can use `email` and `phone` only if they're enabled as identifiers in your [workspace settings](/accounts/workspaces/overview/#migrate-workspace); otherwise the request returns `400`. Reference `phone` values in [E.164 format](https://en.wikipedia.org/wiki/E.164), like `+14155552671`, and URL-encode the leading `+` as `%2B`.
      schema:
        type: string
        enum:
        - id
        - email
        - phone
        - cio_id
    customer_id:
      name: customer_id
      required: true
      in: path
      description: The ID of the customer you want to perform an operation against.
      schema:
        type: string
        example: 12345
  responses:
    '429':
      description: Your request is over the 10-per-second limit. `Retry-After` tells you how many seconds you must wait before you send the next request.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/appApiError'
          example:
            errors:
            - detail: rate limited to 10 requests per 1s (reference a1b2c3)
              status: '429'
    '401':
      description: Unauthorized request. Make sure that you provided the right credentials.
  securitySchemes:
    Tracking-API-Key:
      type: http
      scheme: basic
      description: 'The Track API uses a basic authentication scheme. Your credentials are your **Site ID** and your **API key**, **Base-64 encoded** in the format `site_id:api_key`.


        You can find your Site ID and API key on the [Track API Keys page](https://fly.customer.io/settings/api_credentials).

        '
    Bearer-Auth:
      type: http
      scheme: bearer
      description: 'The App API uses a bearer authentication scheme.


        You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).

        '
    ServiceAccount-Auth:
      x-scalar-ignore: true
      type: http
      scheme: bearer
      bearerFormat: sa_live_
      description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/whatsapp`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.


        Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.


        Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token.
x-tagGroups:
- name: Track API v2
  tags:
  - track_v2
  - Object Schemas
  - Person Schemas
  - Deliveries
- name: Track API
  tags:
  - trackOverview
  - trackJsOrBackend
  - trackLimit
  - trackRegion
  - Track Customers
  - Track Events
  - Forms
  - Track Segments
  - Track v1 Overview
- name: App API
  tags:
  - appOverview
  - appLimit
  - appAuth
  - Activities
  - Automations
  - Broadcasts
  - Collections
  - Customers
  - Data Index
  - ESP Suppression
  - Exports
  - Imports
  - Info
  - Live Notifications
  - Messages
  - Newsletters
  - Opt-outs
  - Reporting Webhooks
  - Segments
  - Sender Identities
  - Snippets
  - Subscription Center
  - Transactional
  - Workspaces
  - Send Messages
  - Objects
  - Newsletter Variants
  - Newsletter Metrics
  - Assets
- name: Design Studio API
  tags:
  - Folders
  - Components
  - Emails
  - Email link and publish
  - Email testing
  - SMS
  - SMS link and publish
x-provenance:
  method: harvested
  publisher: Customer.io
  source: https://docs.customer.io/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)