Track events

Server

US region

Client Libraries

Shell Curl

Track events

Send an event associated with a person. The track call is how you record the things that people do on your website or in your app.

While this endpoint takes any event name you want to send, Customer.io also supports "semantic events." These are specific event names (like User Deleted or Device Created or Updated) that perform special operations in Customer.io like deleting people, adding mobile devices to profiles, and so on. See the Customer.io Semantic Events documentation for complete schemas and examples.

When you use our libraries, you'll typically only provide an event, an ID for the person, and properties. The libraries fill in the rest of the payload automatically.

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. Learn more
values
- 1

Body

application/json

event
Type: string
required

The name of the event

userId
Type: string
required

The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources and destinations.

context

A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.

integrations
Type: object

Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set "All": false to reverse this behavior.

messageId
Type: string

A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io

originalTimestamp
Type: stringFormat: date-time

In general, you can use timestamp rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.

properties
Type: object

Additional properties for your event.

sentAt
Type: stringFormat: date-time

The ISO-8601 timestamp when a library sends an event to Data Pipelines.

timestamp
Type: stringFormat: date-time

The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.

Responses

200

A successful request returns an empty object response.

post/track

curl https://cdp.customer.io/v1/track \
  --request POST \
  --header 'X-Strict-Mode: 1' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "anonymousId": "23adfd82-aa0f-45a7-a756-24f2a7a4c895",
  "context": {
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    },
    "page": {
      "path": "/",
      "referrer": "https://www.google.com/",
      "search": "?q=analytics",
      "title": "Customer.io Docs",
      "url": "https://docs.customer.io"
    },
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML like Gecko) Chrome/46.0.2490.86 Safari/537.36",
    "ip": "108.0.78.21"
  },
  "event": "Course Started",
  "integrations": null,
  "messageId": "ajs-f8ca1e4de5024d9430b3928bd8ac6b96",
  "properties": {
    "title": "Intro to Customer.io"
  },
  "receivedAt": "2015-12-12T19:11:01.266Z",
  "sentAt": "2015-12-12T19:11:01.169Z",
  "timestamp": "2015-12-12T19:11:01.249Z",
  "type": "track",
  "userId": "AiUGstSDIg",
  "originalTimestamp": "2015-12-12T19:11:01.152Z"
}'

No Body

A successful request returns an empty object response.

Track events

Authentication

Track events