Customer.io
v1.0.0
OpenAPI 3.1.0

Pipelines API - Mobile App Events

Mobile App Semantic Events

This document describes semantic events for mobile applications in the Customer.io Pipelines API.

Semantic events are special track events that follow a standard structure across different integrations. When you send a mobile app event with a specific name (like Application Installed or Application Opened), 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 mobile app events.

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 Mobile App Events

​

Send mobile app lifecycle events such as Application Installed, Application Opened, Application Backgrounded, Application Foregrounded, Application Updated, Application Uninstalled, Application Crashed, or Geofence Transition.

These are semantic events that follow a standard structure for mobile app tracking 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
required
application/json
      • event
        enum
        const:  
        Application Installed
        required

        A person installed your app.

        values
        • Application Installed
      • 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 · 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 · Integrations

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

      • properties
        Type: object

        Properties that describe the app installation.

      • 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
{
  "event": "Application Installed",
  "type": "track",
  "userId": "user_12345",
  "context": {
    "additionalProperty": "anything"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  },
  "properties": {
    "build": "421",
    "version": "2.1.0",
    "additionalProperty": null
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{}

A successful request returns an empty object response.

Models