Mobile Tracking API Reference

CustomerLabs Mobile Tracking enables you to collect, unify, and activate user behavioural data from your mobile application. By integrating with the CustomerLabs API, you can track anonymous and identified users across sessions, stitch identities across platforms using advertising IDs and external identifiers, and send structured events to any downstream destination.

Fields to Collect

Before sending data to CustomerLabs, your mobile app must collect the following fields. These are passed across the three core API endpoints.

Required Fields

Field	Type	Description
app_id	string	CustomerLabs application identifier
aaid / idfa	string	Advertising ID — AAID on Android, IDFA on iOS
limitAdTracking	boolean	User’s ad tracking permission (true = limited, false = allowed)
sessionId	string	Session identifier, generated as CL- + UUIDv4 for each new session. Stored in mobile local storage.
user_id	string	User identifier, generated as app_id + UUIDv4 on first visit. Stored in mobile local storage.
appPackageName	string	Application package name / bundle ID
app_version_name	string	App version name
carrier	string	Mobile carrier name
deviceModelName	string	Device model identifier
deviceTimeZone	string	Device timezone (e.g., Asia/Kolkata)
extInfoVersion	string	Platform identifier — i2 for iOS, a2 for Android
externalStorageSize	string	Total external storage in GB
fingerprint	string	Device build fingerprint
freeSpaceExternalStorage	string	Free external storage in GB
locale	string	Device locale (e.g., en-US)
longVersion	string	App long version string
osVersion	string	OS version number
screenDensity	string	Screen pixel density
screenHeight	string	Screen height in dp
screenWidth	string	Screen width in dp
shortVersion	string	App short version string
user_agent	string	WebView user agent string

Optional Fields

Field	Type	Description
fcmToken	string	Firebase Cloud Messaging token
google_analytics__app_instance_id	string	Google Analytics app instance identifier
google_analytics__app_session_id	string	Google Analytics session identifier

---

API Endpoints

Common Headers

All endpoints require the following headers:

Header	Value
Content-Type	application/json
CL-User-Agent	<user_agent>

---

1. External IDs Endpoint

URL: https://io.v2.customerlabs.co/app/externalIds Method: POST

Call this endpoint at the start of every session — for both new and returning users. It registers the device’s advertising IDs, device metadata, and UTM parameters with CustomerLabs to enable cross-platform identity stitching.

Request Body

JSON

{
  "id": "app_id",
  "uid": "user_id",
  "sid": "session_id",
  "external_ids": {
    "idfa": "idfa_value",
    "aaid": "aaid_value",
    "google_analytics__app_instance_id": "ga_app_instance_id",
    "google_analytics__app_session_id": "ga_session_id",
    "customerlabs_user_id": "user_id"
  },
  "additional_info": {
    "limitAdTracking": "limitAdTracking_value",
    "fcmToken": "fcmToken_value",
    "user_agent": "user_agent_value",
    "appPackageName": "appPackageName_value",
    "app_version_name": "app_version_name_value",
    "carrier": "carrier_value",
    "deviceModelName": "deviceModelName_value",
    "deviceTimeZone": "deviceTimeZone_value",
    "extInfoVersion": "extInfoVersion_value",
    "externalStorageSize": "externalStorageSize_value",
    "fingerprint": "fingerprint_value",
    "freeSpaceExternalStorage": "freeSpaceExternalStorage_value",
    "locale": "locale_value",
    "longVersion": "longVersion_value",
    "osVersion": "osVersion_value",
    "screenDensity": "screenDensity_value",
    "screenHeight": "screenHeight_value",
    "screenWidth": "screenWidth_value",
    "shortVersion": "shortVersion_value",
    "fbclid": "fbclid_value",
    "gclid": "gclid_value",
    "msclkid": "msclkid_value",
    "wbraid": "wbraid_value"
  },
  "utm_params": {
    "utm_source": "utm_source_value",
    "utm_medium": "utm_medium_value",
    "utm_campaign": "utm_campaign_value",
    "utm_content": "utm_content_value",
    "utm_term": "utm_term_value"
  }
}

Request Body Parameters

Field	Type	Required	Description
id	string	Yes	CustomerLabs application identifier (app_id) used to route data to the correct account
uid	string	Yes	Unique user identifier (app_id + UUIDv4), persisted in mobile local storage to track the user across sessions
sid	string	Yes	Session identifier (CL- + UUIDv4), regenerated for each new app session to group events within a single visit
external_ids	object	Yes	Map of third-party identifiers (IDFA, AAID, GA app instance ID, GA session ID, CustomerLabs user ID) used to stitch user identity across platforms
additional_info	object	Yes	Device metadata, ad click IDs, and app details used for audience segmentation and ad platform matching
utm_params	object	No	UTM campaign parameters captured from the deep link or referral URL that initiated the app session

Response

Status	Description
200 OK	Success
400 Bad Request	Validation error
500 Internal Server Error	Server error

200 OK

{
  "user_id": "user_id",
  "external_ids": { "...": "..." },
  "additional_info": { "...": "..." }
}

400 / 500 Error

{
  "error": "error_message"
}

---

2. Profile Identify Endpoint

URL: https://io.v2.customerlabs.co/app/identify Method: POST

Call this endpoint when a user logs in or when you have identifiable user information (email, phone). This links the anonymous device identity to a known user profile and enriches the profile with user traits.

Request Body

JSON

{
  "id": "app_id",
  "uid": "user_id",
  "sid": "sessionId",
  "event_source": "mobile_app",
  "added_at": "2026-03-12T05:45:15Z",
  "identify_by": {
    "identify_by_email": "[email protected]",
    "identify_by_phone": "+918424032105"
  },
  "traits": {
    "first_name": "Nelson",
    "last_name": "Jaffery",
    "email": "[email protected]",
    "phone": "+918424032105",
    "gender": "male",
    "age": 25,
    "country": "India",
    "state": "Maharashtra",
    "city": "Thane",
    "zip": "400601",
    "address1": "Line 1",
    "address2": "Line 2",
    "address3": "Line 3"
  },
  "external_ids": {
    "idfa": "idfa_value",
    "aaid": "aaid_value",
    "google_analytics__app_instance_id": "ga_app_instance_id",
    "google_analytics__app_session_id": "ga_session_id",
    "customerlabs_user_id": "user_id"
  }
}

Request Body Parameters

Field	Type	Required	Description
id	string	Yes	CustomerLabs application identifier (app_id)
uid	string	Yes	Unique user identifier (app_id + UUIDv4), persisted in mobile local storage
sid	string	Yes	Session identifier (CL- + UUIDv4), regenerated for each new app session
event_source	string	Yes	Event source — set to mobile_app for mobile app events
added_at	string	Yes	Event timestamp in ISO 8601 format (e.g., 2026-03-12T05:45:15Z)
identify_by	object	Yes	Used to search for and match the user. Accepts identify_by_email and/or identify_by_phone. All traits in the request will be assigned to the matched user profile.
traits	object	Yes	Map of user profile attributes: first_name, last_name, email, phone, gender, age, country, state, city, zip, address1, address2, address3
external_ids	object	Yes	Map of third-party identifiers used to stitch user identity across platforms

Response

Status	Description
200 OK	Success
400 Bad Request	Validation error
500 Internal Server Error	Server error

200 OK

{
  "user_id": "user_id",
  "external_ids": { "...": "..." },
  "additional_info": { "...": "..." },
  "user_traits": { "...": "..." }
}

400 / 500 Error

{
  "error": "error_message"
}

---

3. Events Tracking Endpoint

URL: Your Webhook URL from CustomerLabs Source Configuration Method: POST

Call this endpoint to track user actions and behavioural events (e.g., View Item, Add to Cart, Purchase, Search). The Webhook URL is unique per CustomerLabs source — retrieve it from your CustomerLabs dashboard under Sources → [Your Mobile Source] → Source Configuration.

Request Body

JSON

{
  "id": "app_id",
  "uid": "user_id",
  "sid": "sessionId",
  "event_name": "Purchase",
  "event_source": "mobile_app",
  "added_at": "2026-03-12T05:45:15Z",
  "identify_by": {
    "identify_by_email": "[email protected]",
    "identify_by_phone": "+918424032105"
  },
  "properties": {
    "value": 100,
    "currency": "USD",
    "transaction_id": "TXN-12345",
    "shipping": 10,
    "tax": 10,
    "discount": 10,
    "coupon": "SAVE10",
    "affiliation": "affiliation_value",
    "search_string": "running shoes",
    "description": "description_value"
  },
  "products": [
    {
      "product_id": "SKU-001",
      "product_name": "Running Shoes",
      "product_price": 100,
      "product_quantity": 1
    }
  ],
  "utm_params": {
    "utm_source": "utm_source_value",
    "utm_medium": "utm_medium_value",
    "utm_campaign": "utm_campaign_value",
    "utm_content": "utm_content_value",
    "utm_term": "utm_term_value"
  }
}

Request Body Parameters

Field	Type	Required	Description
id	string	Yes	CustomerLabs application identifier (app_id)
uid	string	Yes	Unique user identifier (app_id + UUIDv4), persisted in mobile local storage
sid	string	Yes	Session identifier (CL- + UUIDv4), regenerated for each new app session
event_name	string	Yes	Name of the event (e.g., View Item, Add to Cart, Purchase, Search)
event_source	string	Yes	Event source — set to mobile_app for mobile app events
added_at	string	Yes	Event timestamp in ISO 8601 format (e.g., 2026-03-12T05:45:15Z)
identify_by	object	Yes	Used to match the event to a known user profile. Accepts identify_by_email and/or identify_by_phone.
properties	object	Yes	Map of event properties: value, currency, transaction_id, shipping, tax, discount, coupon, affiliation, search_string, description
products	array	No	Array of product objects for e-commerce events. Each object supports: product_id, product_name, product_price, product_quantity
utm_params	object	No	UTM campaign parameters from the deep link or referral URL that initiated the app session

Response

Status	Description
200 OK	Success — header only, no response body
400 Bad Request	Validation error
500 Internal Server Error	Server error

400 Bad Request

{
  "validation_error": {
    "error_message": "error_message"
  }
}

500 Internal Server Error

{
  "error": "error_message"
}

---

Key Implementation Notes

User & Session ID Generation

• user_id — Generated once on first app install as app_id + UUIDv4. Persisted in mobile local storage and reused across all subsequent sessions.
• session_id — Generated as CL- + UUIDv4 at the start of every new app session. Stored in mobile local storage for the duration of the session.

Identity Stitching

• Use external_ids (AAID/IDFA, GA IDs) to stitch anonymous mobile users with ad platform identities.
• Use identify_by_email or identify_by_phone in the identify_by object to link events and traits to a known user profile.
• Once a user is identified via /app/identify, all subsequent events carrying the same identify_by value will be attributed to that profile.

Platform Identifiers

Set extInfoVersion based on the platform:

Platform	Value
iOS	i2
Android	a2

Ad Tracking Consent

Always collect and pass limitAdTracking:

Value	Meaning
false	User has allowed ad tracking — AAID/IDFA available
true	User has restricted ad tracking — AAID/IDFA may be zeroed out

Timestamps

All added_at values must be in ISO 8601 format with UTC timezone.

Note

Example: 2026-03-12T05:45:15Z

Webhook URL

The Events Tracking endpoint URL is unique per CustomerLabs source. Retrieve your Webhook URL from:

CustomerLabs Dashboard → Sources → [Your Mobile Source] → Source Configuration

---

Next Steps

• Set up Mobile App Tracking
• Javascript API Reference
• Connect other data sources