Customer.io Segments API

openapi: 3.1.0
info:
  title: Customer.io App Activities Segments API
  description: The Customer.io App API enables developers to manage workspace resources and send messages programmatically. It provides endpoints for sending transactional messages, triggering broadcasts, managing customers and segments, retrieving campaign and newsletter data, and exporting customer information. The API uses bearer token authentication with an App API key and is designed for operations that go beyond data ingestion, such as retrieving metrics, managing message templates, and automating outbound communications from Customer.io.
  version: 1.0.0
  contact:
    name: Customer.io Support
    url: https://customer.io/contact
  termsOfService: https://customer.io/legal/terms-of-service
servers:
- url: https://api.customer.io/v1
  description: US Production Server
- url: https://api-eu.customer.io/v1
  description: EU Production Server
security:
- bearerAuth: []
tags:
- name: Segments
  description: Create and manage manual segments, and retrieve segment membership information.
paths:
  /segments:
    get:
      operationId: listSegments
      summary: List segments
      description: Returns a list of segments in your workspace.
      tags:
      - Segments
      responses:
        '200':
          description: A list of segments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Segment'
        '401':
          description: Unauthorized. Invalid App API key.
    post:
      operationId: createSegment
      summary: Create a manual segment
      description: Creates a new manual segment. Manual segments allow you to group customers by explicitly adding or removing them rather than using automatic filter criteria.
      tags:
      - Segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentRequest'
      responses:
        '200':
          description: Segment created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment:
                    $ref: '#/components/schemas/Segment'
        '400':
          description: Bad request. Invalid segment data.
        '401':
          description: Unauthorized. Invalid App API key.
  /segments/{segment_id}:
    get:
      operationId: getSegment
      summary: Get a segment
      description: Returns detailed information about a specific segment including its type and customer count.
      tags:
      - Segments
      parameters:
      - $ref: '#/components/parameters/SegmentId'
      responses:
        '200':
          description: Segment details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  segment:
                    $ref: '#/components/schemas/Segment'
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Segment not found.
  /segments/{segment_id}/membership:
    get:
      operationId: getSegmentMembership
      summary: Get segment membership
      description: Returns customer identifiers that are members of a specific segment.
      tags:
      - Segments
      parameters:
      - $ref: '#/components/parameters/SegmentId'
      responses:
        '200':
          description: Segment membership list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ids:
                    type: array
                    items:
                      type: string
                    description: An array of customer identifiers in the segment.
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Segment not found.
components:
  schemas:
    Segment:
      type: object
      description: A customer segment in Customer.io.
      properties:
        id:
          type: integer
          description: The unique segment identifier.
        name:
          type: string
          description: The segment name.
        description:
          type: string
          description: A description of the segment.
        type:
          type: string
          description: The segment type (manual or data-driven).
          enum:
          - manual
          - data_driven
        state:
          type: string
          description: The current state of the segment.
    CreateSegmentRequest:
      type: object
      required:
      - segment
      description: A request to create a manual segment.
      properties:
        segment:
          type: object
          required:
          - name
          properties:
            name:
              type: string
              description: The segment name.
            description:
              type: string
              description: A description of the segment.
  parameters:
    SegmentId:
      name: segment_id
      in: path
      required: true
      description: The unique identifier for the segment.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your App API key. Pass the key in the Authorization header as Bearer {app_api_key}.
externalDocs:
  description: App API Documentation
  url: https://docs.customer.io/integrations/api/app/