openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Track Track V2 API
  description: "# Overview\n\nOur Track API provides ways to send real-time customer data to your Customer.io workspace including customer identification and event tracking.\n\n# Use our Postman collection\n\nWe've generated a Postman collection to help you get started with our APIs.\n\nIf you fork this collection, you might want to disable the *Watch original collection* option. We automatically update our Postman collection whenever we release changes to our documentation, even if we don't change our APIs—which happens daily! Rather than being flooded with Postman notifications, you can check out our [Release Notes](/release-notes/) for updates to our APIs.\n\n**NOTE**: Postman endpoints default to our US APIs. If you're in our European (EU) region, you'll need to add `-eu` to the server variables (`track_api_url` and `app_api_url`).\n\n[<img src=\"https://run.pstmn.io/button.svg\" alt=\"Run In Postman\" style=\"width: 128px; height: 32px;\">](https://god.gw.postman.com/run-collection/23697545-0f7ae1e8-8177-46fc-808a-2fd363dd52b9?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D23697545-0f7ae1e8-8177-46fc-808a-2fd363dd52b9%26entityType%3Dcollection%26workspaceId%3Db886877f-fc09-475f-84fe-6221a98f4d18#?env%5BCustomer.io%20API%20Environment%5D=W3sia2V5IjoidHJhY2tfYXBpX3VybCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiJ0cmFjay5jdXN0b21lci5pbyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX2FwaV91cmwiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiYXBpLmN1c3RvbWVyLmlvIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzaXRlX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpX2tleSIsInR5cGUiOiJzZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYmVhcmVyIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYnJvYWRjYXN0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaW1wb3J0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZW1haWxfYWRkcmVzcyIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN1cHByZXNzaW9uX3R5cGUiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjb2xsZWN0aW9uX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic25pcHBldF9uYW1lIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoid2ViaG9va19pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InNlbmRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImV4cG9ydF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im1lc3NhZ2VfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzZWdtZW50X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibmV3c2xldHRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvbnRlbnRfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjYW1wYWlnbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjdGlvbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImN1c3RvbWVyX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidHJhbnNhY3Rpb25hbF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRyaWdnZXJfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJmb3JtX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaWRlbnRpZmllciIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRldmljZV9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRlbGl2ZXJ5X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9XQ==)\n\n# Server addresses: US and EU\nCustomer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.\n\n| Region | Server Address |\n| :-- | :-- |\n| US | https://track.customer.io |\n| EU | https://track-eu.customer.io |\n\nNote that if your account is in the EU region and you send traffic to our US endpoints, we'll redirect it accordingly but this traffic still passes through US servers and data could be logged in the US.\n\n# Authentication \n\nYou can find all of your API authentication information in your [Account Settings](https://fly.customer.io/settings/api_credentials). Our Tracking API uses HTTP basic authorization. The App API uses bearer authorization, and you can generate tokens supporting different scopes. Each operation in this document references the authorization header it requires.\n\n# v1 vs v2 APIs\n\nMost of the time, when we talk about *The Track API*, we're talking about the v1 API because the v2 API isn't used in any of our libraries and rarely used in libraries built by third parties; it's much more common that you'd encounter the v1 API.\n\nIf you're integrating with Customer.io using one of our libraries, or a third party customer data platform (CDP) like Segment or Rudderstack, you'll be using the v1 API.\n\nThe v2 API is newer and supports two important features that the v1 API doesn't natively support: objects and batching. But, if you're integrating directly with our API, we suggest you use the [Pipelines API](/integrations/api/cdp/). The Pipelines API supports both objects, batching, *and* all of our newest integrations and libraries are based on it.\n\n# Rate Limits\n\nThe Track API has a rate limit of 1000 requests per second for both active data integrations and historical backfill scripts. This limit applies to both our v1 and v2 APIs. \n\nWhile this rate is not strictly enforced, consistently exceeding it may lead to throttling or dropped data, especially during periods of high system load. If we detect a sustained high volume that could impact other customers, we may contact you to help adjust your integration or, in rare cases, temporarily block requests.\n\n**Rate limits are subject to change. We may adjust these thresholds to ensure stable performance for all customers.**\n\nBelow are the payload size limits for the Track API. If any of these limits are too restrictive for your needs, contact support to let us know your situation as we may be able to accommodate special circumstances. \n\n## Customer limits\n\nThese limits apply to people and their attributes, often referred to as \"customers\" in our APIs.\n\n| Data Type | Limit | Description |\n| -- | -- | -- |\n| ID | 150 bytes | Max length of a person's ID value |\n| Attribute Name | 150 bytes | Max length of each attribute name |\n| Attribute Value | 1000 bytes | Max length of attribute values |\n| Unique attributes | 300 | Max number of attributes allowed per person or Identify call |\n\n## Object and relationship limits\n\nObjects (groups) and relationships between people and objects can have their own attributes. Their limits are similar to people (customers).\n\n| Data Type | Limit | Description |\n| -- | -- | -- |\n| Object ID | 150 bytes | Max length of a object's ID |\n| Attribute Names | 150 bytes | Max length of each attribute name |\n| Attribute Values | 1000 bytes | Max length of attribute values |\n| Unique attributes | 300 | Max number of attributes allowed per object or relationship |\n| Total attribute size | 100 Kilobytes | Max size of all attributes associated with an object or relationship |\n\n## Track API Event limits\n\nThese limits apply to events that you'll send with the `/v1/track` call.\n\n| Data Type | Limit | Description |\n| -- | -- | -- |\n| Event Name | 100 bytes | Max length of each event name |\n| Event Data | 100000 bytes | Max length of each event data |\n\n\n## v2 API Limits\n\nThe v2 API has two endpoints, both of which have limits on the total size of requests. \n* `/entity` is limited to requests 32kb or smaller.\n* `/batch` is limited to requests 500kb or smaller.\n  \n  Each of the requests within a batch must also be 32kb or smaller.\n"
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.
tags:
- name: track_v2
  x-displayName: Track v2 API
  description: "This version of our edge API has only two endpoints, but supports the majority of our traditional v1 track operations and then some based on the `type` and `action` keys that you set in your request. \n  \nYou can use the `/batch` call to send multiple requests at the same time. Unlike the v1 API, you can also make requests affecting objects and deliveries. Objects are a grouping mechanism for people—like an account people belong to or an online course that they enroll in. Deliveries are events based on messages sent from Customer.io.\n\nThe chart below lists the type of `action` you can perform for each `type`. Our requests below are broken out by `type`; use the `action` dropdown to see the specific payload structure for each action.\n\n| Action | Person | Object | Delivery | \n| :-- | :--: | :--: | :--: |\n| identify | &#9989; | &#9989; | |\n| delete | &#9989; | &#9989; | |\n| event | &#9989; | | &#9989; |\n| screen | &#9989; | | |\n| page | &#9989; | | |\n| add_relationships | &#9989; | &#9989; | |\n| delete_relationships | &#9989; | &#9989; | |\n| add_device | &#9989; | | | \n| delete_device | &#9989; | | |\n| merge | &#9989; | | |\n| suppress | &#9989; | | |\n| unsuppress | &#9989; | | |\n"
paths:
  /api/v2/entity:
    post:
      operationId: entity
      tags:
      - track_v2
      summary: Make a single request
      description: "This endpoint lets you create, update, or delete a single person or object—including managing relationships between objects and people. \n\nAn \"object\" is any kind of non-person entity that you want to associate with one or more people—like a company, an educational course that people signed up for, a product, etc. \n\nYour request must be smaller than 32kb. \n"
      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:
              oneOf:
              - $ref: '#/components/schemas/person_operations'
              - $ref: '#/components/schemas/object_operations'
              - $ref: '#/components/schemas/delivery_operations'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          description: The request was malformed or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    $ref: '#/components/schemas/errors'
        '401':
          $ref: '#/components/responses/401'
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"type\": \"person\",\n  \"identifiers\": {\n    \"id\": \"42\"\n  },\n  \"action\": \"identify\",\n  \"attributes\": {\n    \"first_name\": \"Jane\"\n  }\n}"
  /api/v2/batch:
    post:
      operationId: batch
      tags:
      - track_v2
      summary: Send multiple requests
      description: "This endpoint lets you batch requests for different people and objects in a single request. Each object in your array represents an individual \"entity\" operation—it represents a change for a person, an object, or a delivery. \n\nYou can mix types in this request; you are not limited to a batch containing only objects or only people. An \"object\" is a non-person entity that you want to associate with one or more people—like a company, an educational course that people enroll in, etc.\n\nYour batch request must be smaller than 500kb. Each of the requests within the batch must also be 32kb or smaller.\n"
      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
              example:
                batch:
                - type: person
                  identifiers:
                    id: '42'
                  action: identify
                  attributes:
                    first_name: Jane
                    last_name: Doe
                    plan: premium
                - type: object
                  identifiers:
                    object_type_id: '1'
                    object_id: acme
                  action: identify
                  attributes:
                    name: Acme Corp
                    plan: enterprise
                    seats: 50
                - type: object
                  identifiers:
                    object_type_id: '1'
                    object_id: acme
                  action: add_relationships
                  cio_relationships:
                  - identifiers:
                      id: '42'
                    relationship_attributes:
                      role: admin
              properties:
                batch:
                  description: A batch of requests, where each object is any individual [entity payload](##tag/v2_entity/operation/entity)—modifying a single person or object.
                  type: array
                  items:
                    anyOf:
                    - title: Person
                      anyOf:
                      - $ref: '#/components/schemas/identify_person'
                      - $ref: '#/components/schemas/person_delete'
                      - $ref: '#/components/schemas/person_event'
                      - $ref: '#/components/schemas/person_screen'
                      - $ref: '#/components/schemas/person_page'
                      - $ref: '#/components/schemas/person_add_relationships'
                      - $ref: '#/components/schemas/person_delete_relationships'
                      - $ref: '#/components/schemas/person_add_device'
                      - $ref: '#/components/schemas/person_delete_device'
                      - $ref: '#/components/schemas/person_merge'
                      - $ref: '#/components/schemas/person_suppress'
                      - $ref: '#/components/schemas/person_unsuppress'
                      discriminator:
                        propertyName: action
                    - title: Object
                      anyOf:
                      - $ref: '#/components/schemas/object_identify'
                      - $ref: '#/components/schemas/object_identify_anonymous'
                      - $ref: '#/components/schemas/object_delete'
                      - $ref: '#/components/schemas/object_add_relationships'
                      - $ref: '#/components/schemas/object_delete_relationships'
                      discriminator:
                        propertyName: action
                    - $ref: '#/components/schemas/delivery_operations'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '207':
          description: At least one object in the batch was invalid; all other requests are accepted. This response contains a list of errors for the invalid objects in the batch.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: An array of objects, where each object represents an error. The `batch_index` field for each object is the 0-indexed position of the failing object in your request.
                    items:
                      type: object
                      properties:
                        batch_index:
                          type: integer
                          description: The 0-indexed position of the failing object in your request.
                        reason:
                          type: string
                          description: The reason for the error.
                        field:
                          type: string
                          description: The field containing the error.
                        message:
                          type: string
                          description: A detailed description of the error in the offending field.
        '400':
          description: The entire request was malformed or invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    $ref: '#/components/schemas/errors'
        '401':
          $ref: '#/components/responses/401'
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"batch\": [\n    {\n      \"type\": \"person\",\n      \"identifiers\": {\n        \"id\": \"42\"\n      },\n      \"action\": \"identify\",\n      \"attributes\": {\n        \"first_name\": \"Jane\",\n        \"last_name\": \"Doe\",\n        \"plan\": \"premium\"\n      }\n    },\n    {\n      \"type\": \"object\",\n      \"identifiers\": {\n        \"object_type_id\": \"1\",\n        \"object_id\": \"acme\"\n      },\n      \"action\": \"identify\",\n      \"attributes\": {\n        \"name\": \"Acme Corp\",\n        \"plan\": \"enterprise\",\n        \"seats\": 50\n      }\n    },\n    {\n      \"type\": \"object\",\n      \"identifiers\": {\n        \"object_type_id\": \"1\",\n        \"object_id\": \"acme\"\n      },\n      \"action\": \"add_relationships\",\n      \"cio_relationships\": [\n        {\n          \"identifiers\": {\n            \"id\": \"42\"\n          },\n          \"relationship_attributes\": {\n            \"role\": \"admin\"\n          }\n        }\n      ]\n    }\n  ]\n}"
components:
  schemas:
    object_delete:
      title: 'Object: Delete'
      description: 'Delete an object. This also removes relationships from people.

        '
      example:
        type: object
        identifiers:
          object_type_id: '1'
          object_id: acme
        action: delete
      allOf:
      - $ref: '#/components/schemas/object_common'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Indicates that the operation will `delete` the the item of the specified `type`.
            enum:
            - delete
    object_delete_relationships:
      title: 'Object: Delete relationships'
      description: Delete relationships between an object and one or more people.
      example:
        type: object
        identifiers:
          object_type_id: '1'
          object_id: acme
        action: delete_relationships
        cio_relationships:
        - identifiers:
            id: '42'
      allOf:
      - $ref: '#/components/schemas/object_common'
      - type: object
        required:
        - action
        - cio_relationships
        properties:
          action:
            type: string
            description: This operation deletes an object relationship from one or more people.
            enum:
            - delete_relationships
          cio_relationships:
            $ref: '#/components/schemas/v2_cio_relationships'
    person_screen:
      title: 'Person: Screen view'
      description: A mobile "screenview" event attributed to a person. Our `screen` and `page` event types are more specific than our standard `event`, and help you track and target people based on the pages people visit in your mobile app or website.
      example:
        type: person
        identifiers:
          id: '42'
        action: screen
        name: Dashboard
        attributes:
          app_version: 2.1.0
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - name
        properties:
          action:
            type: string
            description: A mobile "screenview" event attributed to a person. Our `screen` and `page` event types are more specific than our standard `event`, and help you track and target people based on the pages people visit in your mobile app or website.
            enum:
            - screen
          id:
            type: string
            format: ULID
            description: A valid ULID used to deduplicate events. Note - our Python and Ruby libraries do not pass this id.
          name:
            type: string
            description: The name of the screen a person visited. This is how you'll find and select screen view events in Customer.io.
          timestamp:
            type: integer
            description: The Unix timestamp when the event happened.
          attributes:
            type: object
            description: Additional information that you might want to reference in a message using liquid or use to set attributes on the identified person.
            additionalProperties:
              x-additionalPropertiesName: liquid merge data
              description: Insert key-values that you want to reference in your message here.
    person_add_relationships:
      title: 'Person: Add relationships'
      description: Associate multiple objects with a person.
      example:
        type: person
        identifiers:
          id: '42'
        action: add_relationships
        cio_relationships:
        - identifiers:
            object_type_id: '1'
            object_id: acme
          relationship_attributes:
            role: admin
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - cio_relationships
        properties:
          action:
            type: string
            description: This operation associates a person with one or more objects.
            enum:
            - add_relationships
          cio_relationships:
            $ref: '#/components/schemas/object_relationships'
    object_identify_anonymous:
      title: 'Object: Identify anonymous'
      description: The `identify_anonymous` action lets you relate an object to a person who hasn't yet identified themselves by anonymous_id. When you identify the person, their anonymous relationship will carry over to the identified profile.
      example:
        type: object
        identifiers:
          object_type_id: '1'
          object_id: acme
        action: identify_anonymous
        anonymous_id: anon-abc-123
      allOf:
      - $ref: '#/components/schemas/object_common_identify'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Indicates that the operation will `identify` the item of the specified `type` and relate it to an `anonymous_id`.
            enum:
            - identify_anonymous
          attributes:
            $ref: '#/components/schemas/object_attributes'
          cio_relationships:
            type: array
            description: The anonymous people you want to associate with an object. Each object in the array contains an `anonymous_id` representing a person you haven't yet identified by `id` or `email`.
            items:
              type: object
              properties:
                identifiers:
                  type: object
                  properties:
                    anonymous_id:
                      $ref: '#/components/schemas/anonymous_id'
                relationship_attributes:
                  type: object
                  description: Coming October 2023 - The attributes associated with a relationship. Passing null or an empty string removes the attribute from the relationship.
    identify_person:
      title: 'Person: Identify'
      description: Add or update a person.
      example:
        type: person
        identifiers:
          id: '42'
        action: identify
        attributes:
          first_name: Jane
          last_name: Doe
          plan: premium
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Indicates that the operation will `identify` the the item of the specified `type`.
            enum:
            - identify
          timestamp:
            type: integer
            description: The Unix timestamp for when the attribute update occurred. This can be used to control the order of attribute updates when multiple requests are sent in rapid succession.
            example: 1772013598
          attributes:
            type: object
            description: Attributes that you want to add or update for this person. You can pass properties that aren't defined below to set custom attributes; the defined properties are reserved in the Customer.io Track API.
            properties:
              cio_subscription_preferences:
                $ref: '#/components/schemas/cio_subscription_preferences'
              _update:
                type: boolean
                default: false
                description: If `true`, update only existing people and prevent accidental profile creation. If no person matches the identifiers, the request does nothing.
            additionalProperties:
              x-additionalPropertiesName: additional attributes
              description: Custom properties that you want to set as attributes on this person.
          cio_relationships:
            $ref: '#/components/schemas/object_relationships'
    person_suppress:
      title: 'Person: Suppress'
      description: Suppress a person's identifier(s) in Customer.io, so that you can't message a person or add their identifiers back to your workspace. This is separate from suppressions performed by your email provider.
      example:
        type: person
        identifiers:
          id: '42'
        action: suppress
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Suppress a person's identifier(s) in Customer.io, so that you can't message a person or add their identifiers back to your workspace. This is separate from suppressions performed by your email provider.
            enum:
            - suppress
    errors:
      x-scalar-ignore: true
      type: array
      description: An array of errors, where each object represents a different error.
      items:
        type: object
        properties:
          reason:
            type: string
            description: The reason for the error.
          field:
            type: string
            description: The field containing the error.
          message:
            type: string
            description: A detailed description of the error in the offending field.
    delivery_operations:
      title: 'Delivery: Event'
      description: The "delivery" type lets you attribute metrics to messages that don't self-report back to Customer.io, like push and in-app notifications.
      example:
        type: delivery
        identifiers:
          id: RPIyMTM6OjEyMzQ=
        action: event
        name: opened
        attributes:
          device_token: a83b219c-e756-4c5b-a8e3-d1a5c5b2f3c1
      type: object
      required:
      - type
      - action
      - identifiers
      - name
      - attributes
      properties:
        type:
          type: string
          description: The "delivery" type lets you attribute metrics to messages that don't self-report back to Customer.io, like push and in-app notifications.
          enum:
          - delivery
        action:
          type: string
          description: An `event` action indicates a delivery event. Use the `name` to determine the specific metric that you want to attribute to this delivery.
          enum:
          - event
        identifiers:
          type: object
          description: Contains identifiers for the delivery itself.
          properties:
            id:
              type: string
              description: The `delivery_id` for the delivery that you want to attribute metrics to.
        name:
          type: string
          description: The name of the metric you want to attribute to this "delivery".
          enum:
          - opened
          - converted
          - delivered
        attributes:
          type: object
          required:
          - device_token
          description: Contains information about the delivery and the individual who received the message.
          properties:
            device_token:
              type: string
              description: The device that received the message.
    person_unsuppress:
      title: 'Person: Unsuppress'
      description: Unsuppress a person's identifier(s) in Customer.io, so that you can message a person or add their identifiers back to your workspace. This does not unsuppress addresses that were previously suppressed by your email provider.
      example:
        type: person
        identifiers:
          id: '42'
        action: unsuppress
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Unsuppress a person's identifier(s) in Customer.io, so that you can message a person or add their identifiers back to your workspace. This does not unsuppress addresses that were previously suppressed by your email provider.
            enum:
            - unsuppress
    relationship_attributes:
      x-scalar-ignore: true
      type: object
      description: 'The attributes associated with a relationship. Passing null or an empty string removes the attribute from the relationship.

        '
      additionalProperties:
        x-additionalPropertiesName: Relationship Attributes
      example:
        role: admin
    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
    person_delete:
      title: 'Person: Delete'
      description: Delete a person from your workspace.
      example:
        type: person
        identifiers:
          id: '42'
        action: delete
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Indicates that the operation will `delete` the the item of the specified `type`.
            enum:
            - delete
    cio_subscription_preferences:
      x-scalar-ignore: true
      description: A person's [subscription center](/journeys/channels/subscriptions/center/) preferences. Use JSON dot notation, such as `cio_subscription_preferences.topics.topic_<id>`, to update one topic without replacing others.
      type: object
      properties:
        topics:
          type: object
          description: Contains active topics in your workspace, named `topic_<id>`.
          additionalProperties:
            x-additionalPropertiesName: topic_<id>
            description: Boolean preference for a topic named `topic_<id>`; `true` subscribes, `false` unsubscribes, and empty or missing values use the topic default. Find topic IDs with [getTopics](#tag/subscription-center/getTopics).
            type: boolean
      example:
        topics:
          topic_1: true
          topic_2: false
          topic_3: true
    person_merge:
      title: 'Person: Merge'
      example:
        primary:
          id: '42'
        secondary:
          id: known-user-456
      type: object
      description: Merges `secondary` into `primary`, then deletes `secondary`. The operation is not reversible, and `primary` must already exist. See [merging duplicate people](/journeys/people/manage/merge-people/).
      required:
      - type
      - primary
      - secondary
      - action
      properties:
        type:
          description: The operation modifies a person in Customer.io
          type: string
          enum:
          - person
        action:
          type: string
          description: Merges `secondary` into `primary`, then deletes `secondary`. Not reversible; see [merging duplicate people](/journeys/people/manage/merge-people/).
          enum:
          - merge
        primary:
          description: The person who remains after the merge, identified by `id`, `email`, or `cio_id`. If email identifiers are disabled in [workspace settings](https://fly.customer.io/workspaces/last/settings/edit), use `id` or `cio_id`.
          oneOf:
          - title: id
            type: object
            required:
            - id
            properties:
              id:
                $ref: '#/components/schemas/not_nullable_customer_id'
          - title: email
            type: object
            required:
            - email
            properties:
              email:
                $ref: '#/components/schemas/not_nullable_email_address'
          - title: cio_id
            type: object
            required:
            - cio_id
            properties:
              cio_id:
                $ref: '#/components/schemas/cio_id'
        secondary:
          description: The person deleted after the merge, identified by `id`, `email`, or `cio_id`. If email identifiers are disabled in [workspace settings](https://fly.customer.io/workspaces/last/settings/edit), use `id` or `cio_id`.
          oneOf:
          - title: id
            type: object
            required:
            - id
            properties:
              id:
                $ref: '#/components/schemas/not_nullable_customer_id'
          - title: email
            type: object
            required:
            - email
            properties:
              email:
                $ref: '#/components/schemas/not_nullable_email_address'
          - title: cio_id
            type: object
            required:
            - cio_id
            properties:
              cio_id:
                $ref: '#/components/schemas/cio_id'
    object_identify:
      example:
        type: object
        identifiers:
          object_type_id: '1'
          object_id: acme
        action: identify
        attributes:
          name: Acme Corp
          plan: enterprise
          seats: 50
      type: object
      title: 'Object: Identify'
      description: 'The `action` determines the type of operation you want to perform with an object. If `identifiers.object_id` does not exist, we''ll create a new object; if it exists, we''ll update the object accordingly.

        '
      allOf:
      - $ref: '#/components/schemas/object_common_identify'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            description: Indicates that the operation will `identify` the the item of the specified `type`.
            enum:
            - identify
          attributes:
            $ref: '#/components/schemas/object_attributes'
          cio_relationships:
            $ref: '#/components/schemas/v2_cio_relationships'
    v2_cio_relationships:
      x-scalar-ignore: true
      type: array
      description: The people you want to associate with an object. Each object in the array represents a person.
      items:
        type: object
        properties:
          identifiers:
            oneOf:
            - title: id
              type: object
              properties:
                id:
                  $ref: '#/components/schemas/not_nullable_customer_id'
            - title: email
              type: object
              properties:
                email:
                  $ref: '#/components/schemas/not_nullable_email_address'
            - title: cio_id
              type: object
              properties:
                cio_id:
                  $ref: '#/components/schemas/cio_id'
          relationship_attributes:
            type: object
            description: 'The attributes associated with a relationship. Passing null or an empty string removes the attribute from the relationship.

              '
            additionalProperties:
              x-additionalPropertiesName: Relationship Attributes
        example:
          identifiers:
            id: '42'
          relationship_attributes:
            role: admin
            date_created: 1702480414
    object_common:
      x-scalar-ignore: true
      allOf:
      - $ref: '#/components/schemas/object_identifiers'
      - type: object
        required:
        - type
        properties:
          type:
            description: The operation modifies a single object—non person data.
            type: string
            enum:
            - object
    object_relationships:
      x-scalar-ignore: true
      type: array
      description: Each object in the array represents a relationship you want to add to, or remove from, a person.
      items:
        allOf:
        - $ref: '#/components/schemas/object_identifiers'
        - type: object
          properties:
            relationship_attributes:
              $ref: '#/components/schemas/relationship_attributes'
    person_page:
      title: 'Person: Page view'
      description: A web "pageview" event attributed to a person. Our `screen` and `page` event types are more specific than our standard `event`, and help you track and target people based on the pages people visit in your mobile app or website.
      example:
        type: person
        identifiers:
          id: '42'
        action: page
        name: /pricing
        attributes:
          referrer: https://example.com
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - name
        properties:
          action:
            type: string
            description: A web "pageview" event attributed to a person. Our `screen` and `page` event types are more specific than our standard `event`, and help you track and target people based on the pages people visit in your mobile app or website.
            enum:
            - page
          id:
            type: string
            format: ULID
            description: A valid ULID used to deduplicate events. Note - our Python and Ruby libraries do not pass this id.
          name:
            type: string
            description: The name of the page or page path that a person visited. This is how you'll find and select page view events in Customer.io.
          timestamp:
            type: integer
            description: The Unix timestamp when the event happened.
          attributes:
            type: object
            description: Additional information that you might want to reference in a message using liquid or use to set attributes on the identified person.
            properties:
              path:
                type: string
                description: The path portion of the page's URL. Equivalent to the canonical `path` which defaults to `location.pathname` from the DOM API.
              referrer:
                type: string
                description: The previous page's full URL. Equivalent to `document.referrer` from the DOM API.
              search:
                type: string
                description: The query string portion of the page's URL. Equivalent to `location.search` from the DOM API.
              title:
                type: string
                description: The page's title. Equivalent to `document.title` from the DOM API.
              url:
                type: string
                description: A page's full URL. We first look for the canonical URL. If the canonical URL is not provided, we'll use `location.href` from the DOM API.
              keywords:
                type: array
                description: Page-content keywords, typically like HTML meta keywords. Mainly for publishers with pageview tracking; not collected automatically.
                items:
                  type: string
            additionalProperties:
              x-additionalPropertiesName: liquid merge data
              description: Insert key-values that you want to reference in your message here.
    person_delete_device:
      title: 'Person: Delete device'
      description: Delete devices that belong to a person.
      example:
        type: person
        identifiers:
          id: '42'
        action: delete_device
        device:
          token: a83b219c-e756-4c5b-a8e3-d1a5c5b2f3c1
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - device
        properties:
          action:
            type: string
            description: Delete a device from a person's profile.
            enum:
            - delete_device
          device:
            description: The device you want to remove.
            type: object
            required:
            - token
            properties:
              token:
                description: The token of the device you want to remove.
                type: string
    object_operations:
      x-scalar-ignore: true
      title: Object operations
      example:
        type: object
        identifiers:
          object_type_id: '1'
          object_id: acme
        action: identify
        attributes:
          name: Acme Corp
      oneOf:
      - $ref: '#/components/schemas/object_identify'
      - $ref: '#/components/schemas/object_identify_anonymous'
      - $ref: '#/components/schemas/object_delete'
      - $ref: '#/components/schemas/object_add_relationships'
      - $ref: '#/components/schemas/object_delete_relationships'
      discriminator:
        propertyName: action
    object_attributes:
      x-scalar-ignore: true
      type: object
      description: Data that belongs to the object. Pass `null` or an empty string to remove an attribute. Some attributes have special meaning—see [reserved attributes](/journeys/objects-data/objects/create/#reserved-attributes).
    object_common_identify:
      x-scalar-ignore: true
      type: object
      required:
      - type
      - identifiers
      properties:
        identifiers:
          description: Custom object identifiers. To create, provide `object_type_id` and `object_id`; to update, use those values or `cio_object_id`.
          oneOf:
          - title: Object ID (create and update)
            type: object
            required:
            - object_type_id
            - object_id
            properties:
              object_type_id:
                $ref: '#/components/schemas/object_type_id'
              object_id:
                type: string
                description: The unique identifier for an object. If you use an `object_id` that already exists, we'll update the object accordingly.
                example: acme
          - title: CIO Object ID (updates only)
            type: object
            required:
            - cio_object_id
            properties:
              cio_object_id:
                type: string
                description: A unique value that Customer.io sets for an object when you create it. This ID is immutable.
                example: obb7fd050101
        type:
          description: The operation modifies a single object—non person data.
          type: string
          enum:
          - object
    device_object_common:
      x-scalar-ignore: true
      type: object
      description: Device information common to the v1 and v2 APIs.
      required:
      - platform
      properties:
        last_used:
          type: integer
          format: unix timestamp
          description: The `timestamp` when you last identified this device. If you don't pass a timestamp when you add or update a device, we use the time of the request itself. Our SDKs identify a device when a person launches their app.
        platform:
          type: string
          enum:
          - ios
          - android
          description: The device/messaging platform.
        attributes:
          type: object
          description: Attributes that you can reference to segment your audience—like a person's attributes, but specific to a device. These can be either the attributes defined below or custom key-value attributes.
          properties:
            device_os:
              type: string
              description: The operating system, including the version, on the device.
            device_model:
              type: string
              description: The model of the device a person uses.
            app_version:
              type: string
              description: The version of your app that a customer uses. You might target app versions to let people know when they need to update, or expose them to new features when they do.
            cio_sdk_version:
              type: string
              description: The version of the Customer.io SDK in the app.
            _last_status:
              type: string
              readOnly: true
              description: The delivery status of the last message sent to the device—sent, bounced, or suppressed. An empty string indicates that that the device hasn't received a push yet.
              enum:
              - ''
              - bounced
              - sent
              - suppressed
            device_locale:
              type: string
              description: The device's [IETF language code](/journeys/channels/localization/getting-started/#supported-languages), such as `en-MX` or `es-ES`.
            push_enabled:
              type: string
              description: If `"true"`, the device is opted-in and can receive push notifications.
              enum:
              - 'true'
              - 'false'
          additionalProperties:
            x-additionalPropertiesName: Custom Device Attributes
            description: Custom properties that you want to associate with the device.
            type: string
    anonymous_id:
      x-scalar-ignore: true
      type: string
      description: An identifier for an anonymous event, like a cookie. If set as an attribute on a person, any events bearing the same anonymous value are associated with this person. This value must be unique and is not reusable.
    object_identifiers:
      x-scalar-ignore: true
      type: object
      properties:
        identifiers:
          description: The identifiers for a particular object. You can use either the `object_type_id` and `object_id` (where `object_type_id` represents the type of object and the `object_id` is the individual identifier for the object) or the `cio_object_id`.
          oneOf:
          - title: Object ID
            type: object
            required:
            - object_type_id
            - object_id
            properties:
              object_type_id:
                $ref: '#/components/schemas/object_type_id'
              object_id:
                type: string
                description: The unique identifier for an object. If you use an `object_id` that already exists, we'll update the object accordingly.
                example: acme
          - title: CIO Object ID
            type: object
            required:
            - cio_object_id
            properties:
              cio_object_id:
                type: string
                description: A unique value that Customer.io sets for an object when you create it. This ID is immutable.
                example: obb7fd050101
    not_nullable_email_address:
      x-scalar-ignore: true
      type: string
      description: The email address of the customer.
      example: test@example.com
    not_nullable_customer_id:
      x-scalar-ignore: true
      type: string
      description: The ID of a customer profile, analogous to a "person" in the UI.
      example: '42'
    object_add_relationships:
      title: 'Object: Add relationships'
      description: Add relationships between an object and one or more people.
      example:
        type: object
        identifiers:
          object_type_id: '1'
          object_id: acme
        action: add_relationships
        cio_relationships:
        - identifiers:
            id: '42'
          relationship_attributes:
            role: admin
      allOf:
      - $ref: '#/components/schemas/object_common'
      - type: object
        required:
        - action
        - cio_relationships
        properties:
          action:
            type: string
            description: This operation associates an object with one or more people.
            enum:
            - add_relationships
          cio_relationships:
            $ref: '#/components/schemas/v2_cio_relationships'
    person_add_device:
      title: 'Person: Add device'
      description: Assign devices to a person.
      example:
        type: person
        identifiers:
          id: '42'
        action: add_device
        device:
          token: a83b219c-e756-4c5b-a8e3-d1a5c5b2f3c1
          platform: ios
          last_used: 1713484800
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - device
        properties:
          action:
            type: string
            description: Add a mobile device to a person's profile.
            enum:
            - add_device
          device:
            description: Device properties collected by [Customer.io SDKs](/integrations/sdk/) unless `autoTrackDeviceAttributes` is disabled. You can reference them outside `attributes` in segments.
            allOf:
            - type: object
              required:
              - token
              properties:
                token:
                  description: The device token.
                  type: string
            - $ref: '#/components/schemas/device_object_common'
    person_event:
      title: 'Person: Event'
      description: A custom event attributed to a person. You can use events to trigger campaigns, or reference event information using liquid in your messages.
      example:
        type: person
        identifiers:
          id: '42'
        action: event
        name: purchase
        attributes:
          product: Widget
          price: 29.99
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - name
        properties:
          action:
            type: string
            description: A custom event attributed to the specified person.
            enum:
            - event
          id:
            type: string
            format: ULID
            description: A valid ULID used to deduplicate events. Note - our Python and Ruby libraries do not pass this id.
          name:
            type: string
            description: The name of the event. This is how you'll find your event in Customer.io or select it when using events as campaign triggers.
          timestamp:
            type: integer
            description: The Unix timestamp when the event happened.
          attributes:
            type: object
            description: 'Additional information that you might want to reference in a message using liquid or use to set attributes on the identified person.

              '
            additionalProperties:
              x-additionalPropertiesName: liquid merge data
              description: Insert key-values that you want to reference in your message here.
            properties:
              recipient:
                type: string
                format: email
                description: The email address of the person associated with the event, overriding the `to` field in emails triggered by the event.
              from_address:
                type: string
                format: email
                description: The address you want to trigger messages from, overriding the `from` field in emails triggered by the event.
              reply_to:
                type: string
                format: email
                description: The address you want to receive replies to, overriding the `reply to` field for emails triggered by the event.
    object_type_id:
      x-scalar-ignore: true
      type: string
      description: The object type an object belongs to—like "Companies" or "Accounts". Object type IDs are string-formatted integers that begin at `1` and increment for each new type.
      example: '1'
    person_operations:
      x-scalar-ignore: true
      title: Person operations
      example:
        type: person
        identifiers:
          id: '42'
        action: identify
        attributes:
          first_name: Jane
      oneOf:
      - $ref: '#/components/schemas/identify_person'
      - $ref: '#/components/schemas/person_delete'
      - $ref: '#/components/schemas/person_event'
      - $ref: '#/components/schemas/person_screen'
      - $ref: '#/components/schemas/person_page'
      - $ref: '#/components/schemas/person_add_relationships'
      - $ref: '#/components/schemas/person_delete_relationships'
      - $ref: '#/components/schemas/person_add_device'
      - $ref: '#/components/schemas/person_delete_device'
      - $ref: '#/components/schemas/person_merge'
      - $ref: '#/components/schemas/person_suppress'
      - $ref: '#/components/schemas/person_unsuppress'
      discriminator:
        propertyName: action
    person_delete_relationships:
      title: 'Person: Delete relationships'
      description: Remove multiple object relationships from a person.
      example:
        type: person
        identifiers:
          id: '42'
        action: delete_relationships
        cio_relationships:
        - identifiers:
            object_type_id: '1'
            object_id: acme
      allOf:
      - $ref: '#/components/schemas/person_common'
      - type: object
        required:
        - action
        - cio_relationships
        properties:
          action:
            type: string
            description: This operation deletes an object relationship from one or more people.
            enum:
            - delete_relationships
          cio_relationships:
            $ref: '#/components/schemas/object_relationships'
    person_common:
      x-scalar-ignore: true
      type: object
      required:
      - type
      - identifiers
      properties:
        type:
          description: The operation modifies a person in Customer.io
          type: string
          enum:
          - person
        identifiers:
          description: The person you want to perform an action for—one of `id`, `email`, `phone`, or `cio_id`. You cannot pass multiple identifiers. You can use `email` and `phone` only if they're enabled as identifiers in your [workspace settings](/accounts/workspaces/overview/#migrate-workspace).
          oneOf:
          - title: id
            type: object
            required:
            - id
            properties:
              id:
                $ref: '#/components/schemas/not_nullable_customer_id'
          - title: email
            type: object
            required:
            - email
            properties:
              email:
                $ref: '#/components/schemas/not_nullable_email_address'
          - title: phone
            type: object
            required:
            - phone
            properties:
              phone:
                type: string
                description: A person's phone number, in [E.164 format](https://en.wikipedia.org/wiki/E.164) (a leading `+` followed by up to 15 digits). Available only when `phone` is enabled as an identifier in your workspace.
                example: '+14155552671'
          - title: cio_id
            type: object
            required:
            - cio_id
            properties:
              cio_id:
                $ref: '#/components/schemas/cio_id'
  responses:
    '401':
      description: Unauthorized request. Make sure that you provided the right credentials.
    '200':
      description: A successful request returns an empty object response.
  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).

        '