Customer.io Track Segments API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Track Segments 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: Track Segments
  x-displayName: Segments
  description: 'Manual segments are lists of people that you incorporate using the API or by uploading CSVs. You can add people to, or remove people from, manual segments with these endpoints. These endpoints do _not_ let you modify data-driven segments.


    **NOTE**: These endpoints do not yet support workspaces that use both `email` and `id` as identifiers.


    A segment must exist before you can add people to it. You can create manual segments using the App API `/segments` endpoints.'
paths:
  /api/v1/segments/{segment_id}/add_customers:
    parameters:
    - $ref: '#/components/parameters/segment_id'
    - $ref: '#/components/parameters/id_type_segment'
    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.
    post:
      tags:
      - Track Segments
      operationId: add_to_segment
      summary: Add people to a manual segment
      description: 'Add people to a manual segment by ID. You are limited to 1000 customer IDs per request.


        This endpoint lets you add people to manual segments, but a segment must exist before you can add people to it. You can create and find manual segments using the App API.


        When you call this API, you can pass an `id_type` query parameter determining the type of identifier you want to use, `id`, `email`, or `cio_id`; If you don''t pass this parameter, it defaults to `id`. The request body always uses `ids`, even though it''ll accept either IDs, emails, or `cio_id`s depending on the query parameter. Everybody in the payload must use the same kind of identifier; we''ll ignore values in the `ids` array that don''t match the `id_type` parameter.


        **NOTE**: You cannot add people to data-driven segments using the API. See our documentation on segments for more information about segments.'
      servers:
      - url: https://track.customer.io
        description: This endpoint is a part of the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
      security:
      - Tracking-API-Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: The IDs of people you want to add to the segment.
              required:
              - ids
              properties:
                ids:
                  type: array
                  description: The customer IDs you want to add to the segment. The type of value you pass in the array corresponds to the `id_type` query parameter—`id`, `email`, or `cio_id`. Entries in the array that don't match the `id_type` are ignored.
                  maxItems: 1000
                  minItems: 1
                  items:
                    description: The customer IDs you want to add to the segment.
                    type: string
            example:
              ids:
              - customer_id1
              - customer_id2
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
  /api/v1/segments/{segment_id}/remove_customers:
    parameters:
    - $ref: '#/components/parameters/segment_id'
    - $ref: '#/components/parameters/id_type_segment'
    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.
    post:
      tags:
      - Track Segments
      operationId: remove_from_segment
      summary: Remove people from a manual segment
      description: 'You can remove users from a manual segment by ID. You are limited to 1000 customer IDs per request.


        This endpoint requires people to have `id` attributes. If your workspace does not use `id` as an identifier, or you have not assigned people `id` values, you cannot remove people from manual segments using the API. Our user interface does not have this limitation. You can remove people from manual segments through the UI as a part of an automation workflow.


        **NOTE**: You cannot remove people from data-driven segments using the API. See our documentation on segments for more information about segments.'
      servers:
      - url: https://track.customer.io
        description: This endpoint is a part of the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
      security:
      - Tracking-API-Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: The IDs of people you want to remove from the segment.
              required:
              - ids
              properties:
                ids:
                  type: array
                  description: The customer IDs you want to remove from the segment.
                  maxItems: 1000
                  minItems: 1
                  items:
                    description: The customer IDs you want to remove from the segment.
                    type: string
            example:
              ids:
              - customer_id1
              - customer_id2
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
components:
  responses:
    '401':
      description: Unauthorized request. Make sure that you provided the right credentials.
    '400':
      description: Invalid or malformed request.
      content:
        application/json:
          schema:
            type: object
            properties:
              meta:
                type: object
                properties:
                  errors:
                    type: array
                    description: An array of errors.
                    items:
                      type: string
                      description: Error descriptions.
    '200':
      description: A successful request returns an empty object response.
  parameters:
    id_type_segment:
      name: id_type
      required: false
      in: query
      description: The type of `ids` you want to use. All of the values in the `ids` array must be of this type. If you don't provide this parameter, we assume that the `ids` array contains `id` values.
      schema:
        type: string
        enum:
        - id
        - email
        - cio_id
        default: id
    segment_id:
      name: segment_id
      in: path
      required: true
      description: The identifier for a segment. You can find your segment's ID on its page in the dashboard—go to *Segments*, select your segment, and find the ID under *Usage*. Or you can find your segment using the [App API](/integrations/api/app/tag/segments/).
      schema:
        type: integer
        format: int32
  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/files/journeys-track.json
  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)