{"openapi":"3.0.0","info":{"version":"1.0.0","title":"Pipelines API - Customer.io Semantic Events","description":"# Customer.io Semantic Events\n\nThis document describes semantic events that perform actions in Customer.io Journeys via the Pipelines API.\n\nThese are special track events that trigger specific actions in your Customer.io workspace, such as:\n- Managing devices (creating, updating, or deleting mobile device tokens)\n- Deleting people or objects\n- Suppressing or unsuppressing people for compliance\n- Removing relationships between people and objects\n- Reporting delivery events for in-app messages\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://cdp.customer.io |\n| EU | https://cdp-eu.customer.io |\n\nIf you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.\n\n# Authentication\n\nThe Data Pipelines API uses basic authentication with your API key as the username and a blank password.\n"},"servers":[{"url":"https://cdp.customer.io/v1","description":"The base URL for all Data Pipelines calls in our United States (US) region."},{"url":"https://cdp-eu.customer.io/v1","description":"The base URL for all Data Pipelines calls in our European Union (EU) region."}],"paths":{"/track":{"post":{"operationId":"track_customerio_events","summary":"Track Customer.io Events","description":"Send Customer.io semantic events to perform actions in your workspace.\n\nThese events follow standard structures and trigger specific actions in Customer.io Journeys, such as managing devices, deleting people or objects, and reporting delivery events.\n","security":[{"Basic-Auth":[]}],"parameters":[{"name":"X-Strict-Mode","in":"header","description":"When set to `1`, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200.\n","required":false,"schema":{"type":"string","enum":["1"]},"example":"1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/device_created_or_updated_event"},{"$ref":"#/components/schemas/device_deleted_event"},{"$ref":"#/components/schemas/user_deleted_event"},{"$ref":"#/components/schemas/user_suppressed_event"},{"$ref":"#/components/schemas/user_unsuppressed_event"},{"$ref":"#/components/schemas/relationship_deleted_event"},{"$ref":"#/components/schemas/object_deleted_event"},{"$ref":"#/components/schemas/report_delivery_event"}]}}}},"responses":{"200":{"$ref":"#/components/responses/200"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"}}}}},"components":{"schemas":{"device_created_or_updated_event":{"title":"Device Created or Updated","description":"Add or update a device. If a device (represented by `device.token`) does not exist, we'll create it. If the device token already exists, we'll update it.\n","type":"object","required":["userId","event","type","context"],"properties":{"userId":{"type":"string","description":"The user's unique identifier.","example":"42"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Device Created or Updated"],"description":"The event name. Must be `Device Created or Updated` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"context":{"type":"object","required":["device"],"description":"Information about the device performing the event. Our SDKs typically collect these properties automatically.","properties":{"device":{"type":"object","required":["token"],"description":"Device information.","properties":{"token":{"type":"string","description":"The device token."},"type":{"type":"string","description":"The device type.","enum":["ios","android"]}}}},"additionalProperties":true},"integrations":{"$ref":"#/components/schemas/integrations"}}},"device_deleted_event":{"title":"Device Deleted","description":"Delete a device.","type":"object","required":["userId","event","type","context"],"properties":{"userId":{"type":"string","description":"The user's unique identifier.","example":"42"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Device Deleted"],"description":"The event name. Must be `Device Deleted` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"context":{"type":"object","required":["device"],"description":"Information about the device performing the event. Our SDKs typically collect these properties automatically.","properties":{"device":{"type":"object","required":["token"],"description":"Device information.","properties":{"token":{"type":"string","description":"The device token."},"type":{"type":"string","description":"The device type.","enum":["ios","android"]}}}},"additionalProperties":true},"integrations":{"$ref":"#/components/schemas/integrations"}}},"user_deleted_event":{"title":"User Deleted","description":"Remove a person from your Customer.io environment. You might do this when someone cancels their subscription with you or otherwise leaves your service. While this event can have properties, you don't typically need to include them because the purpose of the event is to delete the person from your workspace.\n","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The user's unique identifier or their email address. If you provide an email address, we'll look up the person by their email address and delete them.","example":"42"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["User Deleted"],"description":"The event name. Must be `User Deleted` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"properties":{"type":"object","description":"Properties for the event. These aren't typically useful in Customer.io when deleting people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).","additionalProperties":true},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},"user_suppressed_event":{"title":"User Suppressed","description":"Remove a person from your Customer.io workspace _and_ prevent them from being added back to your workspace using the same identifier. In general you should **only send this event for compliance reasons**, like when someone invokes their right to be forgotten in accordance with GDPR or CAN-SPAM regulations.\n","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The user's unique identifier.","example":"42"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["User Suppressed"],"description":"The event name. Must be `User Suppressed` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"properties":{"type":"object","description":"Properties for the event. These aren't typically useful in Customer.io when suppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).","additionalProperties":true},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},"user_unsuppressed_event":{"title":"User Unsuppressed","description":"Allow a userId to be added back to your Customer.io workspace. This does not restore information from a person you previously suppressed. It only allows you to add a person back to your workspace using the same identifier.\n","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The user's unique identifier.","example":"42"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["User Unsuppressed"],"description":"The event name. Must be `User Unsuppressed` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"properties":{"type":"object","description":"Properties for the event. These aren't typically useful in Customer.io when unsuppressing people, but you might use them in other places—like an analytics tool (e.g. Mixpanel).","additionalProperties":true},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},"relationship_deleted_event":{"title":"Relationship Deleted","description":"Remove a relationship between a person and an object in Customer.io. This is basically the opposite of a `group` operation. Where objects represent things like accounts, companies, or online classes, you might delete a relationship when a person is no longer on an account, leaves a company, or drops a class.\n\nThis event requires a `objectId` and an `objectTypeId`. If you don't provide an `objectTypeId`, we'll assume it's `1`. If the `objectId` with the associated objectTypeId` (defaulting to 1) does not exist, the event won't do anything.\n","type":"object","required":["userId","event","type","properties"],"properties":{"userId":{"type":"string","description":"The user's unique identifier or their email address. If you provide an email address, we'll look up the person by their email address.","example":"1"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Relationship Deleted"],"description":"The event name. Must be `Relationship Deleted` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"properties":{"type":"object","required":["objectId"],"description":"Properties for the event. In this case, you'll need to provide the `objectId`. You should also provide the `objectTypeId` if you have more than 1 object type; if you don't include it, we'll assume it's `1`.","properties":{"objectId":{"type":"string","description":"A person is related to a group/object. This is the group/object you want to remove the person from.","example":"acme"},"objectTypeId":{"type":"integer","description":"The type of group/object the `objectId` represents. In Customer.io, each type of group/object has an integer value, starting at 1 and incrementing. For example, if you have two types of groups/objects, you might have `1` represent accounts and `2` might represent companies.\n\nIf you leave this value blank, we'll assume it's `1`.\n","default":1,"example":1}},"additionalProperties":true},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},"object_deleted_event":{"title":"Object Deleted","description":"Remove a group (also called an \"object\") from Customer.io Journeys. Groups/objects represent things like accounts, companies, and online classes—non-people entities that people can be related to. You might delete a group when an account is closed, a company is acquired, or you stop offering a class.\n\nThis event requires a `objectId` and an `objectTypeId`. If you don't provide an `objectTypeId`, we'll assume it's `1`. If the `objectId` with the associated objectTypeId` (defaulting to 1) does not exist, the event won't do anything.\n","type":"object","required":["anonymousId","event","type","properties"],"properties":{"anonymousId":{"type":"string","description":"While you must set a value, it can be anything; we don't use it. Customer.io requires events to be performed by people, but the \"performer\" is irrelevant to this event.","example":"value-not-used"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Object Deleted"],"description":"The event name. Must be `Object Deleted` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"properties":{"type":"object","required":["objectId"],"description":"Properties for the event. In this case, you'll need to provide the `objectId`. You should also provide the `objectTypeId` if you have more than 1 object type; if you don't include it, we'll assume it's `1`.","properties":{"objectId":{"type":"string","description":"This is the group/object you want to remove.","example":"acme"},"objectTypeId":{"type":"integer","description":"The type of group/object the `objectId` represents. In Customer.io, each type of group/object has an integer value, starting at 1 and incrementing. For example, if you have two types of groups/objects, you might have `1` represent accounts and `2` might represent companies.\n\nIf you leave this value blank, we'll assume it's `1`.\n","default":1,"example":1}},"additionalProperties":true},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},"report_delivery_event":{"title":"Report Delivery Event","description":"Reports delivery events for messages. In general, we use this event with our JavaScript snippet to report delivery events for in-app messages back to your Customer.io workspace.\n\nWhile Customer.io knows about messages that are sent, we use this event to determine when an in-app message is delivered, clicked, and so on. Each message contains a unique `deliveryId` that we trace back to the person, campaign/broadcast, and other items in your Customer.io workspace.\n","type":"object","required":["event","type","properties"],"properties":{"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Report Delivery Event"],"description":"The event name. Must be `Report Delivery Event` for this semantic event."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2021-07-14T19:10:25.000Z"},"properties":{"type":"object","required":["deliveryId","metric"],"description":"Properties for the event that describe the delivery event being reported.","properties":{"deliveryId":{"type":"string","description":"The ID of the message delivery.","example":"42"},"metric":{"type":"string","enum":["delivered","clicked","converted","opened"],"description":"The metric you're reporting. Remember, these are metrics that occur outside of Customer.io—after the message is sent. Because this event typically tracks in-app messages, you'll generally see metrics like delivered, opened, clicked, etc.","example":"clicked"},"recipient":{"type":"string","description":"The recipient of the message. This field changes depending on the type of message. For in-app messages, this is the person's `deviceId`; for SMS it's the recipient's phone number; for push notifications, it's their device token.","example":"device_token"},"reason":{"type":"string","description":"If the message failed for some reason, this field contains the reason why."},"actionValue":{"type":"string","description":"For in-app messages that are `clicked`, this value represents the value of the action the recipient clicked.","example":"enable_push"},"href":{"type":"string","description":"For in-app messages that are `clicked`, this value represents the URL/link the recipient clicked.","example":"myapp://settings/enable_push"}},"additionalProperties":true},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},"context":{"x-scalar-ignore":true,"title":"Context","type":"object","description":"Additional context about the event, such as device information, IP address, user agent, etc. Most of our libraries collect this automatically.","additionalProperties":true},"integrations":{"x-scalar-ignore":true,"title":"Integrations","type":"object","description":"Control which integrations receive this event. By default, all enabled integrations receive events.","additionalProperties":true,"example":{"All":false,"Mixpanel":true,"Segment":true}}},"securitySchemes":{"Basic-Auth":{"type":"http","scheme":"basic","description":"The Data Pipelines API uses a basic authentication scheme with your API key. Use the API Key as the username and leave the password blank.\n"}},"responses":{"200":{"description":"A successful request returns an empty object response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or malformed request.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"errors":{"type":"array","description":"An array of errors.","items":{"type":"string","description":"Error descriptions."}}}}}}}}},"401":{"description":"Unauthorized request. Make sure that you provided the right credentials."}}}}