Customer.io Subscription Center API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Subscription Center 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: Subscription Center
  description: A subscription center differentiates the types of messages available for your product. Your audience sets subscription preferences by name, but we record subscription preferences by topic ID. You can use these endpoints to get a list of topics and names, helping you understand your audience's subscription preferences.
paths:
  /v1/subscription_topics:
    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).
    get:
      summary: List subscription topics
      operationId: getTopics
      security:
      - Bearer-Auth: []
      description: Returns a list of subscription topics in your workspace. If there are no topics, it returns an empty array.
      tags:
      - Subscription Center
      responses:
        '200':
          description: Returns an array of `topics`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  topics:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The name of the subscription topic.
                          example: Product Updates
                        description:
                          type: string
                          description: A description of the topic that you provided when you created the topic in the UI.
                          example: For people who want updates on product releases.
                        subscribed_by_default:
                          type: boolean
                          description: If false, a person is opted-out by default. If true, a person is opted-in by default.
                          example: false
                        id:
                          type: integer
                          description: The system-generated id for the subscription topic. Also located on the subscription center landing page. These increment up by 1, starting with 1.
                          example: 4
                        identifier:
                          type: string
                          description: The key associated with the subscription topic. The format is `topic_<id>`.
                          example: topic_4
        '429':
          $ref: '#/components/responses/429'
  /v1/subscription_center/{customer_id}/token:
    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).
    get:
      summary: Generate a subscription center token
      operationId: getSubscriptionCenterToken
      security:
      - Bearer-Auth: []
      description: 'Generates a signed token and URL for a person''s standalone subscription center page. The token is valid for 24 hours.


        Use the returned `url` to link people to a hosted subscription center page where they can manage their subscription preferences outside of a message. This is useful when you want to provide a direct link to the subscription center—for example, in your app''s account settings or in a custom email.


        The `customer_id` path parameter is the person''s identifier (e.g. an email address or customer ID) as it appears in Customer.io. The identifier must match an existing person in your workspace.'
      tags:
      - Subscription Center
      parameters:
      - name: customer_id
        in: path
        required: true
        description: The identifier for a person in your workspace—the same value you'd use as an `id` or `email` to identify a person in Customer.io.
        schema:
          type: string
          example: person@example.com
      responses:
        '200':
          description: Returns a signed `token` and a subscription center `url` for the person.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: 'A signed token representing the person''s subscription center session. The token expires after 24 hours.


                      If you want to use a custom link tracking domain, you can point your customers to `https://<your-tracking-domain>/u/i/<your-token>/<language-code (optional)>`.

                      '
                  url:
                    type: string
                    description: A full URL to the person's standalone subscription center page. You can use this URL directly as a link.
                    example: https://track.customer.io/u/i/<your-token>/
        '400':
          description: The `customer_id` is invalid or does not match a known person in your workspace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        detail:
                          type: string
                          example: bad request
                        status:
                          type: string
                          example: '400'
  /v1/subscription_channels:
    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).
    get:
      summary: List subscription channels
      operationId: getChannels
      security:
      - Bearer-Auth: []
      description: Returns a list of subscription channels available in your workspace. Channels represent the delivery methods that people can subscribe to or unsubscribe from—email, SMS, push, etc. If you haven't set up channel options in your subscription center, this endpoint returns an empty array.
      tags:
      - Subscription Center
      responses:
        '200':
          description: Returns an array of `channels`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  channels:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The system-generated ID for the subscription channel.
                          example: 1
                        type:
                          type: string
                          description: The type of delivery channel.
                          enum:
                          - email
                          - twilio
                          - urban_airship
                          - slack
                          - push
                          - in_app
                          - line
                          - inbox
                          - whatsapp
                          example: email
                        name:
                          type: string
                          description: The display name of the subscription channel.
                          example: Email
                        description:
                          type: string
                          description: A description of the channel.
                          example: Email messages
                        subscribed_by_default:
                          type: boolean
                          description: If false, a person is opted-out by default. If true, a person is opted-in by default.
                          example: true
        '429':
          $ref: '#/components/responses/429'
components:
  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'
  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).
  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
  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)