Customer.io
v1.0.0
OpenAPI 3.1.0

Pipelines API - A/B Test Events

A/B Test Semantic Events

This document describes semantic events for A/B testing in the Customer.io Pipelines API.

Semantic events are special payloads for our track endpoint based on the event name. When you send an A/B test event with a specific name (like Experiment Viewed), Customer.io and downstream integrations recognize it and handle it appropriately.

With semantic events, you can set up your events and they'll work with any of our destinations that support A/B testing.

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

The Data Pipelines API uses basic authentication with your API key as the username and a blank password.

US region

Client Libraries
Shell Curl

Track Experiment Viewed

​

Send an Experiment Viewed event when a person views an A/B test experiment.

This is a semantic event that follows a standard structure for A/B testing across different analytics and optimization platforms.

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·Experiment Viewed Event
required
application/json

  • Track when a person views an A/B test experiment

    Track when a person views an A/B test experiment

    • event
      enum
      const:  
      Experiment Viewed
      required

      The event name. Must be Experiment Viewed for this semantic event.

      values
      • Experiment Viewed
    • properties
      Type: object
      required

      Properties that describe the A/B test experiment.

    • type
      enum
      const:  
      track
      required

      The event type. Must be track for event calls.

      values
      • track
    • userId
      Type: string
      required

      The unique identifier for the user.

    • context
      Type: object · Event Context

      Additional context about the event, such as device information, IP address, user agent, etc. Most of our libraries collect this automatically.

    • integrations
      Type: object · Integration Control

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

    • timestamp
      Type: stringFormat: 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
curl https://cdp.customer.io/track \
  --request POST \
  --header 'X-Strict-Mode: 1' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic username:password' \
  --data '{
  "userId": "user_12345",
  "type": "track",
  "event": "Experiment Viewed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "properties": {
    "experiment_id": "exp_summer_promo_2024",
    "experiment_name": "Summer Promo Button Color",
    "variation_id": "var_blue_button",
    "variation_name": "Blue Button",
    "additionalProperty": null
  },
  "context": {
    "additionalProperty": "anything"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  }
}'

{}

A successful request returns an empty object response.

Models