openapi: 3.0.1
info:
  title: Customer.io API
  description: >-
    Specification of the Customer.io APIs for customer messaging and marketing
    automation. Covers the Track API (track.customer.io - people, events,
    devices, manual segments, plus the v2 entity/batch endpoints), the App /
    Transactional API (api.customer.io - transactional send, API-triggered
    broadcasts, customers, segments, campaigns, newsletters, messages, exports,
    collections, snippets, sender identities, imports), and the Pipelines / Data
    Pipelines CDP API (cdp.customer.io - identify, track, page, screen, group,
    alias, batch). Authentication differs per surface - the Track API uses HTTP
    Basic auth with site_id:api_key, the App and Pipelines APIs use a Bearer
    token.
  termsOfService: https://customer.io/legal/terms-of-service/
  contact:
    name: Customer.io Support
    email: win@customer.io
  version: '1.0'
servers:
  - url: https://track.customer.io
    description: Track API (US region)
  - url: https://track-eu.customer.io
    description: Track API (EU region)
  - url: https://api.customer.io
    description: App / Transactional API (US region)
  - url: https://api-eu.customer.io
    description: App / Transactional API (EU region)
  - url: https://cdp.customer.io
    description: Pipelines / Data Pipelines CDP API (US region)
  - url: https://cdp-eu.customer.io
    description: Pipelines / Data Pipelines CDP API (EU region)
security:
  - basicAuth: []
  - bearerAuth: []
tags:
  - name: People
    description: Track API - add, update, suppress, or delete people (customers).
  - name: Events
    description: Track API - send customer or anonymous behavioral events.
  - name: Devices
    description: Track API - register and remove customer device tokens.
  - name: Segments
    description: Manual segment membership management.
  - name: Track v2
    description: Track API v2 entity and batch endpoints.
  - name: Transactional
    description: App API - send transactional email, push, SMS, and in-app messages.
  - name: Broadcasts
    description: App API - trigger API-driven broadcasts.
  - name: Customers
    description: App API - look up people, their attributes, segments, and messages.
  - name: Campaigns
    description: App API - read campaigns, their metrics, and actions.
  - name: Messages
    description: App API - read sent messages and their metadata.
  - name: Exports
    description: App API - export customers and deliveries.
  - name: Collections
    description: App API - manage reusable data collections.
  - name: Pipelines
    description: Pipelines / CDP API - identify, track, page, screen, group, alias, batch.
paths:
  /api/v1/customers/{identifier}:
    put:
      operationId: identifyCustomer
      tags:
        - People
      summary: Create or update a person
      description: >-
        Create or update a person (customer) and set their attributes. Uses
        HTTP Basic auth with site_id:api_key.
      parameters:
        - name: identifier
          in: path
          required: true
          description: The customer's unique identifier (id or email, per workspace settings).
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      responses:
        '200':
          description: Person created or updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
    delete:
      operationId: deleteCustomer
      tags:
        - People
      summary: Delete a person
      description: Delete a person from the workspace.
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Person deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v1/events:
    post:
      operationId: trackAnonymousEvent
      tags:
        - Events
      summary: Track an anonymous event
      description: >-
        Send an event that is not yet attributed to a known person. Anonymous
        events can later be associated with a person when they are identified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Event accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v1/customers/{identifier}/events:
    post:
      operationId: trackCustomerEvent
      tags:
        - Events
      summary: Track a customer event
      description: Send an event attributed to a known person to trigger campaigns or update segments.
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Event accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v1/customers/{identifier}/devices:
    put:
      operationId: addDevice
      tags:
        - Devices
      summary: Add or update a device
      description: Register or update a device token for push notifications for a person.
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceRequest'
      responses:
        '200':
          description: Device added or updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v1/customers/{identifier}/devices/{device_id}:
    delete:
      operationId: deleteDevice
      tags:
        - Devices
      summary: Delete a device
      description: Remove a device token from a person.
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            type: string
        - name: device_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Device removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v1/segments/{segment_id}/add_customers:
    post:
      operationId: addCustomersToSegment
      tags:
        - Segments
      summary: Add people to a manual segment
      parameters:
        - name: segment_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentMembership'
      responses:
        '200':
          description: People added to segment.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v1/segments/{segment_id}/remove_customers:
    post:
      operationId: removeCustomersFromSegment
      tags:
        - Segments
      summary: Remove people from a manual segment
      parameters:
        - name: segment_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentMembership'
      responses:
        '200':
          description: People removed from segment.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v2/entity:
    post:
      operationId: trackEntityV2
      tags:
        - Track v2
      summary: Create, update, or delete an entity (v2)
      description: >-
        Track API v2 single-payload endpoint for people and objects. The type
        field selects the entity (person or object) and action selects the
        operation (identify, delete, add_relationships, etc.).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityV2'
      responses:
        '200':
          description: Entity processed.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /api/v2/batch:
    post:
      operationId: trackBatchV2
      tags:
        - Track v2
      summary: Batch entity operations (v2)
      description: Submit up to 32 KB worth of mixed person/object/event operations in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchV2'
      responses:
        '200':
          description: Batch accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /v1/send/email:
    post:
      operationId: sendTransactionalEmail
      tags:
        - Transactional
      summary: Send a transactional email
      description: >-
        Send a single transactional email using a transactional message
        template or inline body. App API Bearer token required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
      responses:
        '200':
          description: Message accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/send/push:
    post:
      operationId: sendTransactionalPush
      tags:
        - Transactional
      summary: Send a transactional push notification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendPushRequest'
      responses:
        '200':
          description: Push accepted for delivery.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/send/sms:
    post:
      operationId: sendTransactionalSms
      tags:
        - Transactional
      summary: Send a transactional SMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transactional_message_id:
                  oneOf:
                    - type: string
                    - type: integer
                to:
                  type: string
                identifiers:
                  $ref: '#/components/schemas/Identifiers'
                message_data:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: SMS accepted for delivery.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/send/broadcast:
    post:
      operationId: triggerBroadcast
      tags:
        - Broadcasts
      summary: Trigger an API-driven broadcast
      description: >-
        Trigger a broadcast and optionally provide data for liquid placeholders
        and per-recipient data via per_user_data. Limited to one request every
        10 seconds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BroadcastTrigger'
      responses:
        '200':
          description: Broadcast triggered.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/customers:
    post:
      operationId: searchCustomers
      tags:
        - Customers
      summary: Search for people
      description: Search for people by attributes, segment membership, and other filters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerSearch'
      responses:
        '200':
          description: A list of matching people.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/customers/{customer_id}/attributes:
    get:
      operationId: getCustomerAttributes
      tags:
        - Customers
      summary: Get a person's attributes
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The person's attributes.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/customers/{customer_id}/segments:
    get:
      operationId: getCustomerSegments
      tags:
        - Customers
      summary: Get the segments a person belongs to
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The person's segment memberships.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/customers/{customer_id}/messages:
    get:
      operationId: getCustomerMessages
      tags:
        - Customers
      summary: Get messages sent to a person
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Messages delivered to the person.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/segments:
    get:
      operationId: listSegments
      tags:
        - Segments
      summary: List segments
      responses:
        '200':
          description: A list of segments.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
    post:
      operationId: createSegment
      tags:
        - Segments
      summary: Create a manual segment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                segment:
                  type: object
                  properties:
                    name:
                      type: string
                    description:
                      type: string
      responses:
        '200':
          description: Segment created.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/campaigns:
    get:
      operationId: listCampaigns
      tags:
        - Campaigns
      summary: List campaigns
      responses:
        '200':
          description: A list of campaigns.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/campaigns/{campaign_id}:
    get:
      operationId: getCampaign
      tags:
        - Campaigns
      summary: Get a campaign
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The campaign.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/campaigns/{campaign_id}/metrics:
    get:
      operationId: getCampaignMetrics
      tags:
        - Campaigns
      summary: Get campaign metrics
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign metrics.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/messages:
    get:
      operationId: listMessages
      tags:
        - Messages
      summary: List sent messages
      responses:
        '200':
          description: A list of messages.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/exports/customers:
    post:
      operationId: exportCustomers
      tags:
        - Exports
      summary: Export people
      description: Begin an export of people matching a filter.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Export started.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/exports:
    get:
      operationId: listExports
      tags:
        - Exports
      summary: List exports
      responses:
        '200':
          description: A list of exports.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/collections:
    get:
      operationId: listCollections
      tags:
        - Collections
      summary: List collections
      responses:
        '200':
          description: A list of collections.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
    post:
      operationId: createCollection
      tags:
        - Collections
      summary: Create a collection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                data:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '200':
          description: Collection created.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/identify:
    post:
      operationId: pipelinesIdentify
      tags:
        - Pipelines
      summary: Identify a user (Pipelines)
      description: >-
        Pipelines / CDP identify call. Requires at least one of userId or
        anonymousId. Bearer auth with a source write key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelinesIdentify'
      responses:
        '200':
          description: Call accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/track:
    post:
      operationId: pipelinesTrack
      tags:
        - Pipelines
      summary: Track an event (Pipelines)
      description: Pipelines / CDP track call. Requires an event name and one of userId or anonymousId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipelinesTrack'
      responses:
        '200':
          description: Call accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/page:
    post:
      operationId: pipelinesPage
      tags:
        - Pipelines
      summary: Record a page view (Pipelines)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Call accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/screen:
    post:
      operationId: pipelinesScreen
      tags:
        - Pipelines
      summary: Record a screen view (Pipelines)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Call accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/group:
    post:
      operationId: pipelinesGroup
      tags:
        - Pipelines
      summary: Associate a user with a group (Pipelines)
      description: Requires a groupId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Call accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/alias:
    post:
      operationId: pipelinesAlias
      tags:
        - Pipelines
      summary: Alias two identities (Pipelines)
      description: Requires a previousId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Call accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
  /v1/batch:
    post:
      operationId: pipelinesBatch
      tags:
        - Pipelines
      summary: Batch Pipelines calls
      description: Submit multiple identify/track/page/screen/group/alias calls (1 MB limit).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                batch:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '200':
          description: Batch accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Track API auth. Base-64 encode site_id:api_key and pass it in the
        Authorization header (Basic ...).
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        App API and Pipelines API auth. Pass the App API key (or Pipelines
        source write key) as a Bearer token in the Authorization header.
  responses:
    Unauthorized:
      description: Authentication failed or credentials missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Person:
      type: object
      description: A person (customer) and their attributes.
      properties:
        email:
          type: string
        created_at:
          type: integer
          description: Unix timestamp when the person was created.
        _update:
          type: boolean
      additionalProperties: true
    Event:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The event name.
        type:
          type: string
          description: Set to "page" for page-view events.
        timestamp:
          type: integer
        data:
          type: object
          additionalProperties: true
    DeviceRequest:
      type: object
      required:
        - device
      properties:
        device:
          type: object
          required:
            - id
            - platform
          properties:
            id:
              type: string
              description: The device token.
            platform:
              type: string
              enum:
                - ios
                - android
            last_used:
              type: integer
    SegmentMembership:
      type: object
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
          description: Customer identifiers to add to or remove from the manual segment.
    EntityV2:
      type: object
      required:
        - type
        - identifiers
        - action
      properties:
        type:
          type: string
          enum:
            - person
            - object
        action:
          type: string
          enum:
            - identify
            - delete
            - add_relationships
            - delete_relationships
        identifiers:
          $ref: '#/components/schemas/Identifiers'
        attributes:
          type: object
          additionalProperties: true
    BatchV2:
      type: object
      required:
        - batch
      properties:
        batch:
          type: array
          items:
            $ref: '#/components/schemas/EntityV2'
    Identifiers:
      type: object
      description: One or more identifiers locating a person (id, email, or cio_id).
      properties:
        id:
          type: string
        email:
          type: string
        cio_id:
          type: string
    SendEmailRequest:
      type: object
      properties:
        transactional_message_id:
          oneOf:
            - type: string
            - type: integer
          description: ID or trigger name of a transactional message template.
        to:
          type: string
        identifiers:
          $ref: '#/components/schemas/Identifiers'
        from:
          type: string
        subject:
          type: string
        body:
          type: string
        message_data:
          type: object
          additionalProperties: true
        attachments:
          type: object
          additionalProperties:
            type: string
        disable_message_retention:
          type: boolean
        send_to_unsubscribed:
          type: boolean
    SendPushRequest:
      type: object
      properties:
        transactional_message_id:
          oneOf:
            - type: string
            - type: integer
        to:
          type: string
        identifiers:
          $ref: '#/components/schemas/Identifiers'
        title:
          type: string
        message:
          type: string
        message_data:
          type: object
          additionalProperties: true
    SendResponse:
      type: object
      properties:
        delivery_id:
          type: string
        queued_at:
          type: integer
        recipient:
          type: object
          additionalProperties: true
    BroadcastTrigger:
      type: object
      properties:
        id:
          type: integer
          description: The broadcast/campaign ID to trigger.
        data:
          type: object
          additionalProperties: true
        recipients:
          type: object
          additionalProperties: true
        per_user_data:
          type: array
          items:
            type: object
            additionalProperties: true
        email_add_duplicates:
          type: boolean
    CustomerSearch:
      type: object
      properties:
        filter:
          type: object
          additionalProperties: true
    PipelinesIdentify:
      type: object
      properties:
        userId:
          type: string
        anonymousId:
          type: string
        traits:
          type: object
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
    PipelinesTrack:
      type: object
      required:
        - event
      properties:
        event:
          type: string
        userId:
          type: string
        anonymousId:
          type: string
        properties:
          type: object
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        meta:
          type: object
          properties:
            error:
              type: string
            errors:
              type: array
              items:
                type: string