Customer.io
v1.0.0
OpenAPI 3.1.0

Pipelines API - Customer.io Semantic Events

Customer.io Semantic Events

This document describes semantic events that perform actions in Customer.io Journeys via the Pipelines API.

These are special track events that trigger specific actions in your Customer.io workspace, such as:

  • Managing devices (creating, updating, or deleting mobile device tokens)
  • Deleting people or objects
  • Suppressing or unsuppressing people for compliance
  • Removing relationships between people and objects
  • Reporting delivery events for in-app messages

Server addresses: US and EU

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Region Server Address
US https://cdp.customer.io
EU https://cdp-eu.customer.io

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.

Authentication

Use a private key (sk_) as a bearer token: Authorization: Bearer sk_us_.... To get one, set up the Customer.io API integration. In a browser or mobile app, use a public key (pk_). Learn more about public and private keys.

Legacy credentials: If you already have a Customer.io API integration with a write key, you can keep using it with Basic authentication: the key is the Username, and the Password is blank.

US region

Client Libraries
Shell Curl

Track Customer.io Events

​

Send Customer.io semantic events to perform actions in your workspace.

These events follow standard structures and trigger specific actions in Customer.io Journeys, such as managing devices, deleting people or objects, and reporting delivery events.

Headers
  • X-Strict-Mode
    enum
    const:  
    1

    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.

    values
    • 1
Body
required
application/json

  • 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.

    • context
      Type: object
      required

      Information about the device performing the event. Our SDKs typically collect these properties automatically.

    • event
      enum
      const:  
      Device Created or Updated
      required

      The event name. Must be Device Created or Updated for this semantic event.

      values
      • Device Created or Updated
    • type
      enum
      const:  
      track
      required

      The event type. Must be track for event calls.

      values
      • track
    • userId
      Type: string
      required

      The user's unique identifier.

    • integrations
      Type: object · Integrations

      Control which integrations receive this event. By default, all enabled integrations receive events.

    • timestamp
      Type: string Format: date-time

      The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

Request Example for post/track
{
  "context": {
    "device": {
      "token": "",
      "type": "ios"
    },
    "additionalProperty": "anything"
  },
  "event": "Device Created or Updated",
  "type": "track",
  "userId": "42",
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  },
  "timestamp": "2021-07-14T19:10:25.000Z"
}

{}

A successful request returns an empty object response.

Models