Loading API documentation...
v1.0.0
OAS 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

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

The base URL for all Data Pipelines calls in our United States (US) region.

No authentication selected
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, or Application Crashed.

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
      • userId
        Type: string
        required

        The unique identifier for the user.

      • type
        enum
        const:  
        track
        required

        The event type. Must be track for event calls.

        values
        • track
      • event
        enum
        const:  
        Application Installed
        required

        A person installed your app.

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

      • properties
        Type: object

        Properties that describe the app installation.

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

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

{}

A successful request returns an empty object response.

Models