Customer.io Segments API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference 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: Segments
  description: Segments are groups of people, subsets of your audience. You get get information about segments and the customers contained by a segment. You can also create or delete manual segments through the API. Use the UI to create, update, or delete data-driven segments.
paths:
  /v1/segments:
    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).
    post:
      summary: Create a manual segment
      operationId: createManSegment
      security:
      - Bearer-Auth: []
      description: Create a manual segment with a name and a description. This request creates an empty segment.
      tags:
      - Segments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - segment
              properties:
                segment:
                  type: object
                  required:
                  - name
                  properties:
                    name:
                      $ref: '#/components/schemas/segment_name'
                    description:
                      $ref: '#/components/schemas/segment_description'
      responses:
        '200':
          description: Returns the segment ID and other information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment:
                    $ref: '#/components/schemas/segmentResponseObject'
        '400':
          description: The request was malformed.
        '429':
          $ref: '#/components/responses/429'
    get:
      summary: List segments
      operationId: listSegments
      security:
      - Bearer-Auth: []
      description: Retrieve a list of your segments. The list doesn't include archived segments.
      tags:
      - Segments
      responses:
        '200':
          description: Returns an array of `segments`. Each object in the response represents an individual segment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segments:
                    type: array
                    items:
                      $ref: '#/components/schemas/segmentResponseObject'
        '429':
          $ref: '#/components/responses/429'
  /v1/segments/{segment_id}:
    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/segment_id'
    get:
      summary: Get a segment
      operationId: getSegment
      security:
      - Bearer-Auth: []
      description: Return information about a segment.
      tags:
      - Segments
      responses:
        '200':
          description: Returns the information about the segment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment:
                    $ref: '#/components/schemas/segmentResponseObject'
        '404':
          description: The `segment_id` does not exist.
        '429':
          $ref: '#/components/responses/429'
    delete:
      summary: Delete a segment
      operationId: deleteManSegment
      description: Delete a manual segment. You can't delete a data-driven segment, or a manual segment that another segment, an automation, an unsent one-time send, or a SQL import uses.
      security:
      - Bearer-Auth: []
      tags:
      - Segments
      responses:
        '204':
          description: The segment is deleted.
        '404':
          description: The `segment_id` does not exist.
        '422':
          description: 'Customer.io can''t delete the segment. This may be because it''s data-driven.

            '
        '429':
          $ref: '#/components/responses/429'
  /v1/segments/{segment_id}/used_by:
    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/segment_id'
    get:
      summary: Get a segment's dependencies
      operationId: getSegmentDependencies
      security:
      - Bearer-Auth: []
      description: Use this endpoint to find out which automations and one-time sends use a segment.
      tags:
      - Segments
      responses:
        '200':
          description: Returns the IDs of items that reference the segment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  used_by:
                    type: object
                    properties:
                      segment_id:
                        $ref: '#/components/schemas/segment_id'
                      campaigns:
                        type: array
                        description: The automations that use this segment.
                        items:
                          type: integer
                      sent_newsletters:
                        type: array
                        description: The one-time sends that you've sent that use this segment.
                        items:
                          type: integer
                      draft_newsletters:
                        type: array
                        description: The one-time sends that are still in a draft state that reference this segment.
                        items:
                          type: integer
        '404':
          description: The `segment_id` does not exist.
        '429':
          $ref: '#/components/responses/429'
  /v1/segments/{segment_id}/customer_count:
    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/segment_id'
    get:
      summary: Get a segment customer count
      operationId: getSegmentCount
      security:
      - Bearer-Auth: []
      description: Returns the membership count for a segment.
      tags:
      - Segments
      responses:
        '200':
          description: Returns the customer `count` for a segment.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment_id:
                    $ref: '#/components/schemas/segment_id'
                  count:
                    type: integer
                    description: The total number of customers in the segment.
        '404':
          description: The `segment_id` does not exist.
        '429':
          $ref: '#/components/responses/429'
  /v1/segments/{segment_id}/membership:
    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/segment_id'
    - $ref: '#/components/parameters/start'
    - name: limit
      in: query
      required: false
      description: The maximum number of results you want to retrieve per page.
      schema:
        type: integer
        default: 1000
        maximum: 30000
    get:
      summary: List customers in a segment
      operationId: getSegmentMembership
      security:
      - Bearer-Auth: []
      description: 'Returns customers in a segment. This endpoint returns an array of `identifiers`; each object in the array represents a person and contains the identifier values allowed in your workspace. In general, we recommend that you use `identifiers` rather than `ids` to find people, because it provides more information.


        **If your workspace does not use email as a unique identifier** for people, `identifiers` does not contain `email` values. Go to your Workspace Settings to find out which identifiers your workspace supports.


        The `ids` array only lists ID values for people in a segment; if your workspace uses both `email` and `id` as identifiers, it''s possible that a member of your segment does not have an `id` value, resulting in an empty string in the `ids` array.'
      tags:
      - Segments
      responses:
        '200':
          description: Returns an array of customers for a segment.
          content:
            application/json:
              schema:
                oneOf:
                - title: email or id
                  type: object
                  properties:
                    segment_id:
                      $ref: '#/components/schemas/segment_id'
                    ids:
                      type: array
                      description: The customers that belong to this segment.
                      items:
                        type: string
                    identifiers:
                      description: The customers that belong to this segment.
                      type: array
                      items:
                        $ref: '#/components/schemas/customer_identifiers'
                    next:
                      $ref: '#/components/schemas/next'
                - title: id only
                  type: object
                  properties:
                    segment_id:
                      $ref: '#/components/schemas/segment_id'
                    ids:
                      type: array
                      description: The customers that belong to this segment.
                      items:
                        type: string
                    identifiers:
                      description: The customers that belong to this segment.
                      type: array
                      items:
                        type: object
                        description: 'Contains `id` and `cio_id` identifiers for a person in a workspace that doesn''t use email as an identifier.

                          '
                        required:
                        - id
                        - cio_id
                        properties:
                          id:
                            type: string
                            description: A person's unique ID. This matches a value in `ids`.
                            example: 2
                          cio_id:
                            $ref: '#/components/schemas/cio_id'
                    next:
                      $ref: '#/components/schemas/next'
        '404':
          description: The `segment_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).
    segment_name:
      x-scalar-ignore: true
      type: string
      description: The name of the segment.
      example: Manual Segment 1
    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
    segment_description:
      x-scalar-ignore: true
      type: string
      description: A description for the segment. This can help you understand the purpose of the segment when you encounter it in other requests or in the UI.
      example: My first manual segment
    customer_identifiers:
      x-scalar-ignore: true
      type: object
      description: Identifiers for the person in a response—`id`, `cio_id`, and `email`. Unset `id` or `email` values are `null`. We recommend this object over the less descriptive `customer_id`. This object doesn't include `phone`, even if your workspace uses phone numbers as an identifier; look for the person's `phone` attribute instead.
      required:
      - email
      - id
      - cio_id
      properties:
        email:
          type:
          - string
          - 'null'
          format: email
          description: A person's email address, if set.
          example: test@example.com
        id:
          type:
          - string
          - 'null'
          description: A person's unique ID, if set. This is the same as the `customer_id` if present.
          example: 2
        cio_id:
          $ref: '#/components/schemas/cio_id'
    next:
      x-scalar-ignore: true
      type: string
      description: Indicates the next page of results. Add `?start=<next_value>` to the request to get the next page of results.
    segment_id:
      x-scalar-ignore: true
      type: integer
      description: The identifier for a segment; used to target a segment in requests.
      example: 7
    updated:
      x-scalar-ignore: true
      type: integer
      format: unix timestamp
      description: The date time when the referenced ID was last updated.
      example: 1552341937
      readOnly: true
    created:
      x-scalar-ignore: true
      type: integer
      format: unix timestamp
      description: The date time when the referenced ID was created.
      example: 1552341937
      readOnly: true
    segmentResponseObject:
      x-scalar-ignore: true
      type: object
      properties:
        id:
          $ref: '#/components/schemas/segment_id'
        deduplicate_id:
          $ref: '#/components/schemas/deduplicate_id'
        name:
          $ref: '#/components/schemas/segment_name'
        description:
          $ref: '#/components/schemas/segment_description'
        state:
          type: string
          description: The segment's build state. The state is `build` while Customer.io calculates who belongs to the segment, and `finished` when membership is up to date.
          enum:
          - build
          - finished
          example: finished
        progress:
          type:
          - number
          - 'null'
          description: Customer.io returns `0` while the segment is in the `build` state and `null` when it's `finished`. This field doesn't report partial progress, so use `state` to tell whether the segment is still building.
          example: null
        type:
          type: string
          description: The type of segment.
          enum:
          - dynamic
          - manual
          example: manual
        tags:
          type:
          - array
          - 'null'
          description: The tags assigned to the segment, if any. Tags may help you sort through your segments.
          items:
            type: string
          example: null
        conditions:
          type: object
          description: The conditions that determine who belongs to the segment, as a tree of nested `and` and `or` groups. Customer.io includes this object for data-driven segments and omits it for manual segments, which don't have conditions. A profile attribute condition appears as an `attribute_change` event with a `to` filter and an inverted `from` filter, and filter values are always strings, even for numeric or boolean attributes.
          additionalProperties: true
          example:
            and:
            - event:
                filters:
                  and:
                  - field: to
                    inverse: false
                    operator: eq
                    value: premium
                  - field: from
                    inverse: true
                    operator: eq
                    value: premium
                id: 12
                name: plan
                type: attribute_change
              inverse: false
              times: 1
              within: 0
            - segment:
                id: 7
                inverse: false
        created_at:
          $ref: '#/components/schemas/created'
        updated_at:
          $ref: '#/components/schemas/updated'
    deduplicate_id:
      x-scalar-ignore: true
      type: string
      readOnly: true
      description: An identifier in the format `id:timestamp` where the id is for the object you're working with (Automations, Deliveries, Exports, Identities, One-time sends, Segments, and Templates), and the timestamp is the last time the object was updated.
      example: 15:1492548073
  parameters:
    start:
      name: start
      in: query
      required: false
      description: The token for the page of results you want to return. Responses contain a `next` property. Use this property as the `start` value to return the next page of results.
      schema:
        type: string
    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
  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'
  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