Documentation

Developers

API References

Data Subject Request API

Data Subject Request API Version 1 and 2

Data Subject Request API Version 3

Platform API

Platform API Overview

Accounts

Apps

Audiences

Calculated Attributes

Data Points

Feeds

Field Transformations

Services

Users

Workspaces

Warehouse Sync API

Warehouse Sync API Overview

Warehouse Sync API Tutorial

Warehouse Sync API Reference

Data Mapping

Warehouse Sync SQL Reference

Warehouse Sync Troubleshooting Guide

ComposeID

Warehouse Sync API v2 Migration

Bulk Profile Deletion API Reference

Calculated Attributes Seeding API

Custom Access Roles API

Data Planning API

Group Identity API Reference

Pixel Service

Profile API

Events API

mParticle JSON Schema Reference

IDSync

Client SDKs

AMP

AMP SDK

Android

Initialization

Configuration

Network Security Configuration

Event Tracking

User Attributes

IDSync

Screen Events

Commerce Events

Location Tracking

Media

Kits

Application State and Session Management

Data Privacy Controls

Error Tracking

Opt Out

Push Notifications

WebView Integration

Logger

Preventing Blocked HTTP Traffic with CNAME

Linting Data Plans

Troubleshooting the Android SDK

API Reference

Upgrade to Version 5

Cordova

Cordova Plugin

Identity

Flutter

Getting Started

Usage

API Reference

Direct Url Routing

Direct URL Routing FAQ

Web

Android

iOS

Initialization

Configuration

Event Tracking

User Attributes

IDSync

Screen Tracking

Commerce Events

Location Tracking

Media

Kits

Application State and Session Management

Data Privacy Controls

Error Tracking

Opt Out

Push Notifications

Webview Integration

Upload Frequency

App Extensions

Preventing Blocked HTTP Traffic with CNAME

Linting Data Plans

Troubleshooting iOS SDK

Social Networks

iOS 14 Guide

iOS 15 FAQ

iOS 16 FAQ

iOS 17 FAQ

iOS 18 FAQ

API Reference

Upgrade to Version 7

React Native

Getting Started

Identity

Roku

Getting Started

Identity

Media

Unity

Upload Frequency

Getting Started

Opt Out

Initialize the SDK

Event Tracking

Commerce Tracking

Error Tracking

Screen Tracking

Identity

Location Tracking

Session Management

Xbox

Getting Started

Identity

Web

Initialization

Configuration

Content Security Policy

Event Tracking

User Attributes

IDSync

Page View Tracking

Commerce Events

Location Tracking

Media

Kits

Application State and Session Management

Data Privacy Controls

Error Tracking

Opt Out

Custom Logger

Persistence

Native Web Views

Self-Hosting

Multiple Instances

Web SDK via Google Tag Manager

Preventing Blocked HTTP Traffic with CNAME

Facebook Instant Articles

Troubleshooting the Web SDK

Browser Compatibility

Linting Data Plans

API Reference

Upgrade to Version 2 of the SDK

Xamarin

Getting Started

Identity

Web

Alexa

Server SDKs

Node SDK

Go SDK

Python SDK

Ruby SDK

Java SDK

Quickstart

Android

Overview

Step 1. Create an input

Step 2. Verify your input

Step 3. Set up your output

Step 4. Create a connection

Step 5. Verify your connection

Step 6. Track events

Step 7. Track user data

Step 8. Create a data plan

Step 9. Test your local app

HTTP Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

iOS Quick Start

Overview

Step 1. Create an input

Step 2. Verify your input

Step 3. Set up your output

Step 4. Create a connection

Step 5. Verify your connection

Step 6. Track events

Step 7. Track user data

Step 8. Create a data plan

Java Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Node Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Python Quick Start

Step 1. Create an input

Step 2. Create an output

Step 3. Verify output

Web

Overview

Step 1. Create an input

Step 2. Verify your input

Step 3. Set up your output

Step 4. Create a connection

Step 5. Verify your connection

Step 6. Track events

Step 7. Track user data

Step 8. Create a data plan

Tools

mParticle Command Line Interface

Linting Tools

Smartype

Media SDKs

iOS

Web

Android

Guides

Partners

Introduction

Outbound Integrations

Firehose Java SDK

Inbound Integrations

Kit Integrations

Overview

Android Kit Integration

JavaScript Kit Integration

iOS Kit Integration

Compose ID

Data Hosting Locations

Glossary

Rules Developer Guide

Migrate from Segment to mParticle

Migrate from Segment to Client-side mParticle

Migrate from Segment to Server-side mParticle

Segment-to-mParticle Migration Reference

API Credential Management

The Developer's Guided Journey to mParticle

Guides

Getting Started

Create an Input

Start capturing data

Connect an Event Output

Create an Audience

Connect an Audience Output

Transform and Enhance Your Data

Platform Guide

The New mParticle Experience

The new mParticle Experience

The Overview Map

Observability

Observability Overview

Observability User Guide

Observability Span Glossary

Introduction

Data Retention

Connections

Activity

Live Stream

Data Filter

Rules

Tiered Events

mParticle Users and Roles

Analytics Free Trial

Troubleshooting mParticle

Usage metering for value-based pricing (VBP)

Analytics

Introduction

Setup

Sync and Activate Analytics User Segments in mParticle

User Segment Activation

Welcome Page Announcements

Settings

Project Settings

Roles and Teammates

Organization Settings

Global Project Filters

Portfolio Analytics

Analytics Data Manager

Analytics Data Manager Overview

Events

Event Properties

User Properties

Revenue Mapping

Export Data

UTM Guide

Query Builder

Data Dictionary

Query Builder Overview

Modify Filters With And/Or Clauses

Query-time Sampling

Query Notes

Filter Where Clauses

Event vs. User Properties

Group By Clauses

Annotations

Cross-tool Compatibility

Apply All for Filter Where Clauses

Date Range and Time Settings Overview

Understanding the Screen View Event

Analyses

Analyses Introduction

Segmentation: Basics

Getting Started

Visualization Options

For Clauses

Date Range and Time Settings

Calculator

Numerical Settings

Segmentation: Advanced

Assisted Analysis

Properties Explorer

Frequency in Segmentation

Trends in Segmentation

Did [not] Perform Clauses

Cumulative vs. Non-Cumulative Analysis in Segmentation

Total Count of vs. Users Who Performed

Save Your Segmentation Analysis

Export Results in Segmentation

Explore Users from Segmentation

Funnels: Basics

Getting Started with Funnels

Group By Settings

Conversion Window

Tracking Properties

Date Range and Time Settings

Visualization Options

Interpreting a Funnel Analysis

Funnels: Advanced

Group By

Filters

Conversion over Time

Conversion Order

Trends

Funnel Direction

Multi-path Funnels

Analyze as Cohort from Funnel

Save a Funnel Analysis

Explore Users from a Funnel

Export Results from a Funnel

Cohorts

Getting Started with Cohorts

Analysis Modes

Save a Cohort Analysis

Export Results

Explore Users

Saved Analyses

Manage Analyses in Dashboards

Journeys

Getting Started

Event Menu

Visualization

Ending Event

Save a Journey Analysis

Users

Getting Started

User Activity Timelines

Time Settings

Export Results

Save A User Analysis

Dashboards

Dashboards––Getting Started

Manage Dashboards

Dashboard Filters

Organize Dashboards

Scheduled Reports

Favorites

Time and Interval Settings in Dashboards

Query Notes in Dashboards

User Aliasing

Analytics Resources

The Demo Environment

Keyboard Shortcuts

Tutorials

Analytics for Marketers

Analytics for Product Managers

Compare Conversion Across Acquisition Sources

Analyze Product Feature Usage

Identify Points of User Friction

Time-based Subscription Analysis

Dashboard Tips and Tricks

Understand Product Stickiness

Optimize User Flow with A/B Testing

User Segments

APIs

User Segments Export API

Dashboard Filter API

IDSync

IDSync Overview

Use Cases for IDSync

Components of IDSync

Store and Organize User Data

Identify Users

Default IDSync Configuration

Profile Conversion Strategy

Profile Link Strategy

Profile Isolation Strategy

Best Match Strategy

Aliasing

Data Master

Group Identity

Overview

Create and Manage Group Definitions

Introduction

Catalog

Live Stream

Data Plans

Blocked Data Backfill Guide

Personalization

Predictive Attributes

Predictive Attributes Overview

Create Predictive Attributes

Assess and Troubleshoot Predictions

Use Predictive Attributes in Campaigns

Predictive Audiences

Predictive Audiences Overview

Using Predictive Audiences

Introduction

Profiles

Calculated Attributes

Calculated Attributes Overview

Using Calculated Attributes

Create with AI Assistance

Calculated Attributes Reference

Audiences

Audiences Overview

Real-time Audiences

Standard Audiences

Journeys

Journeys Overview

Manage Journeys

Download an audience from a journey

Audience A/B testing from a journey

Journeys 2.0

Warehouse Sync

Data Privacy Controls

Data Subject Requests

Default Service Limits

Feeds

Cross-Account Audience Sharing

Approved Sub-Processors

Import Data with CSV Files

CSV File Reference

Glossary

Video Index

Analytics (Deprecated)

Identity Providers

Single Sign-On (SSO)

Setup Examples

Settings

Debug Console

Data Warehouse Delay Alerting

Introduction

Developer Docs

Introduction

Integrations

Introduction

Rudderstack

Google Tag Manager

Segment

Data Warehouses and Data Lakes

Advanced Data Warehouse Settings

AWS Kinesis (Snowplow)

AWS Redshift (Define Your Own Schema)

AWS S3 (Snowplow Schema)

AWS S3 Integration (Define Your Own Schema)

BigQuery (Snowplow Schema)

BigQuery Firebase Schema

BigQuery (Define Your Own Schema)

GCP BigQuery Export

Snowflake (Snowplow Schema)

Snowplow Schema Overview

Snowflake (Define Your Own Schema)

APIs

REST API

Dashboard Filter API (Deprecated)

User Segments Export API (Deprecated)

SDKs

SDKs Introduction

React Native

iOS

Android

Java

JavaScript

Python

Object API

Developer Basics

Aliasing

mParticle JSON Schema Reference

The mParticle JSON schema defines the structure of all data sent to the mParticle customer data platform from the HTTP API or the platform SDKs (such as the Web, iOS, or Android SDKs).

This same JSON schema also defines the structure of data sent from mParticle to output integrations. There are some differences between the format for inbound and outbound data. For a complete list of these differences, see differences between the inbound and outbound JSON format.

The following document includes several additional explanations and examples. Use the following raw JSON schema definitions for programmatic JSON generation and validation:

See JSON schema validation for information about using these schemas to test and validate data structure.

Overall structure

{
	"events": [
		{
			"data": {},
			"event_type": "custom_event"
		}
	],
	"device_info": {},
	"source_request_id":"7fa67be4-f83a-429f-9d73-38b660c50825",
	"user_attributes": {},
	"deleted_user_attributes": [],
	"user_identities": {},
	"application_info": {},
	"schema_version": 2,
	"environment": "production",
	"context": {},
	"mpid":7346244611012968789,
	"ip": "172.217.12.142"
}

All properties are optional and support both input and output unless specified otherwise in the Description.

Property	Data Type	Description
events	array	An array of JSON objects, each representing an event. The event object consists of two nodes: `data`, and `type`. The type indicates the entity structure of the data node.
schema_version	integer	Output only. This value is used internally by mParticle account representatives. It indicates the current schema version a message batch conforms to.
device_info	object	A JSON object containing information about the device pertaining to this message batch.
application_info	object	A JSON object of information about your app.
source_request_id	string	A value to uniquely identify this request. This is used to deduplicate inbound requests. De-duplication is scoped by API key, found in Organization/Account/Workspace/Inputs, and remains in the system for enforcement anywhere from 30-60 days. Any valid string is accepted.
user_attributes	object map	String key-value pairs of demographic information about the user that generated the app events.
deleted_user_attributes	string array	An array of JSON strings describing previously provided user attributes which should be forgotten.
user_identities	object map	String key-value pairs of user ID information, such as email address and social IDs.
partner_identities	object map	String key-value pairs of partner identities.
integration_attributes	object map	String key-value pairs of integration attributes indexed by module.
environment	enum string	Default value: `production`. Must be either “production” or “development.”
context	object	Data planning and location information.
mpid	long	If known, the unique mParticle identifier for the user, calculated based on user and device identities in the batch, according to your Identity Strategy.
ip	string	Input only. The IPv4 / IPv6 address of the consumer device. The IP address is stored on user profiles and is kept updated with the most recently seen value for each user. `ip` is only forwarded to connected outputs if the `Enrich IP Address` setting is available and enabled for the connection.

`events`

The event object consists of two required nodes: data, and event_type.

{
	"data": {},
	"event_type": ""
}

The following event_type are allowed. These values are specified in the type fields within the events node.

event_type	Description
custom_event	A Custom event with a name and optional attributes.
commerce_event	A Commerce event.
session_start	Session Start event.
session_end	Session End event.
screen_view	Screen View.
uninstall	App was uninstalled.
crash_report	Crash Report.
opt_out	User Opt-Out.
push_registration	Registration of the device push token.
application_state_transition	An event fired when the application starts, exits, comes into foreground, or enters background.
push_message	A push message is received.
network_performance	An event containing network performance details on external http calls made from the application.
breadcrumb	Breadcrumbs are used for crash reporting to understand which events lead up to a crash.

The type indicates the entity structure of the data node in the event. There are also some common elements to all data nodes.

Common event data node properties

{
    "data": {
        "event_id": 6004677780660780000,
        "event_num": 0,
        "source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
        "session_id": 4957918240501247982,
        "session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
        "timestamp_unixtime_ms": 1402521613976,
        "location": {},
        "device_current_state": {},
        "custom_attributes": {},
        "custom_flags": {}
    },
    "event_type": ""
}

Property	Data Type	Required	Description
event_id	Int64	Read only	Unique ID generated by mParticle server as each event is received.
event_num	Int64	Read only, optional for S2S	Zero-based number indicating an event’s place within the current session. In a session with a single event, event_num will be 0. The iOS and Android SDKs populate event_num automatically, but for S2S connections developers should manually calculate and populate this value if desired.
source_message_id	string	suggested	Unique Id of source event. Generated by mParticle client-side SDKs for platform data. For session start events, SDKs set this value to session_uuid. If sending data via Events API it is suggested to generate a UUID for each event.
session_id	Int64	Read only	Unique Id of session.
session_uuid	string	suggested	An optional universally unique identifier for the session. The session_id will be derived from a hash of this value.
timestamp_unixtime_ms	Int64	suggested	Timestamp of event. The current server time will be used if not specified.
location	location JSON	optional	The location the event occurred in.
device_current_state	device_current_state JSON	optional	An object with a number of properties describing the state the device was in at the time the event was logged. See below for further details.
custom_attributes	JSON key value pairs	optional	A dictionary of custom attributes. If the Event API is called using Custom or Partner feed credentials, the `mParticle Source Feed` custom attribute is included which contains the name of the input feed configuration. This attribute cannot be filtered.

The details on location and device_current_state will be detailed after additional information on the event_type and the corresponding data nodes.

custom_event

{
	"data": {
		"event_name": "click",
		"custom_event_type": "navigation",
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {
			"button_name":  "home",
			"other_attribute":  "xyz"
		}
	},
	"event_type": "custom_event"
}

Property	Data Type	Required	Description
event_name	string	required	The name of the event
custom_event_type	string or enum	required	The type of custom event as detailed in the following table.
custom_flags	JSON key-value pairs	optional	A dictionary of custom flags. For more information, see Custom Flags.

The values for custom_event_type appear in the criteria builder for audiences, journeys, and the Custom Events calculated attributes drop-down. For example, custom_event_type:media appears as Media in the criteria builder for audiences and in the Select Event drop-down under Custom Events for calculated attributes.

The allowed values of “custom_event_type” are:

custom_event_type	Description
attribution	Attribution events are set of user actions (“events” or “touch points”) that contribute in some manner to a desired outcome.
location	Events that indicate where a user is located or interacting physically. Examples might include a check-in, geo fence, or GPS navigation.
media	Events for logging user media and ad content consumption and user initiated player event attributes.
navigation	Events that indicate a user click sequence or content consumption. Examples might include interface navigation, music listening, video view, menu or tab Selection, or when the back button is pressed.
search	Any event where users input criteria to find content/answers. Examples might include a keyword search, voice search, or a QR code scan.
social	Any action where users share content with others. Examples might include post, rate, tweet, share, attach, email.
transaction	Any events that are part of a transaction workflow. Examples might include selecting a product, subscribe, upgrade, or bid.
user_content	Events where users are creating content. Examples might include create task, compose, record, scan, or save.
user_preference	Any event that creates personalization for the user. This includes registration, saving/labeling content items, creating profiles, setting application preferences or permissions.
other	Use this event type to create an event that falls into no clear category.

Attribution custom events

Attribution events are sent to mParticle as custom events with:

Property	Value
event_type	`custom_event`
custom_event_type	`attribution`

The custom event_name depends on the Attribution Type:

Attribution Type	event_name	Description
Install	attribution	Install attribution events allow you to attribute the install of your app to a specific publisher and campaign. The `publisher` and `campaign` information is stored on the user’s profile and the events are available in the audience builder. Install attribution events require `campaign` and `publisher` custom attributes representing the campaign and publisher which are credited for the installation. You should also include as many device and user identifiers as you can.
Re-engagement	re-engagement	Re-engagement attribution events are typically created when a user opens an app which has already been installed as a result of clicking a deep link. Re-engagement attribution events can also accept `campaign` and `publisher` attributes. Re-engagement attribution information is not stored on the user profile.
Engagement	any	Engagement attribution events allow you to attribute actions (i.e. add to cart, purchase, etc) a user takes in the app to a specific publisher and campaign. Engagement attribution events can also accept `campaign` and `publisher` attributes. Engagement attribution information is not stored on the user profile.

commerce_event

{
	"data": {
		"product_action": {},
		"promotion_action": {},
		"product_impressions": [{}],
		"shopping_cart": {},
		"currency_code": "USD",
		"screen_name": "",
		"is_non_interactive": false,
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "commerce_event"
}

There are 3 core variations of the commerce_event.

Product-based - Used to measure data points associated with one or more products.
These have a product_action and do NOT have a promotion_action or a product_impressions
Promotion-based - Used to measure data points associated with internal promotions or campaigns.
These have a promotion_action and do NOT have a product_action or a product_impressions
Impression-based - Used to measure interactions with impressions of products and product-listings.
These have a product_impressions and do NOT have a product_action or promotion_action

Property	Data Type	Required	Description
product_action	product_action JSON	required or disallowed (see above)	Used to measure measured data points associated with one or more products
promotion_action	promotion_action JSON	required or disallowed (see above)	Used to measure data points associated with internal promotions or campaigns
product_impressions	An array of JSON product_impressions	required or disallowed (see above)	Product impressions
shopping_cart	shopping_cart JSON	optional	current shopping cart state
currency_code	string	optional	code representing the currency the transaction is conducted in
screen_name	string	optional	screen name
is_non_interactive	Boolean	optional	is non interactive

product_action

{
	"action": "add_to_cart",
	"checkout_step": 3,
	"checkout_options": "",
	"product_action_list": "",
	"product_list_source": "",
	"transaction_id": "",
	"affiliation": "",
	"total_amount": "",
	"tax_amount": "",
	"shipping_amount": "",
	"coupon_code": "",
	"products": [{}]
}

Property	Data Type	Required	Description
action	string / enum	required	The type of action the descriptions are below
checkout_step	Int32	optional	The step of the checkout process
checkout_options	string	optional	checkout options
product_action_list	string	optional	product action list
transaction_id	string	optional	transaction id
affiliation	string	optional	affiliation
total_amount	decimal	optional	total amount (mapped from revenue in the SDKs)
tax_amount	decimal	optional	tax amount (mapped from tax in the SDKs)
shipping_amount	decimal	optional	shipping amount (mapped from shipping in the SDKs)
coupon_code	string	optional	coupon code
products	An array of JSON Product	optional	products

The allowed values of “action” are:

add_to_cart
remove_from_cart
checkout
checkout_option
click
view_detail
purchase
refund
add_to_wishlist
remove_from_wish_list

promotion_action

{
	"action": "view",
	"promotions": [{}]
}

Property	Data Type	Required	Description
action	string / enum	required	Type of action. Allowed values are `view` and `click`.
promotions	An array of JSON Promotion	optional	promotions

product_impressions

{
	"product_impression_list": "",
	"products": [{}]
}

Property	Data Type	Required	Description
product_impression_list	string	optional	List of product impressions.
products	array of objects	optional	An array of JSON objects, where each object contains a product.

shopping_cart

{
	"products": [{}]
}

Property	Data Type	Required	Description
products	array of objects	optional	An array of JSON objects, where each object contains a product.

Product

{
	"id": "",
	"name": "",
	"brand": "",
	"category": "",
	"variant": "",
	"position": "",
	"price": "",
	"quantity": "",
	"coupon_code": "",
	"added_to_cart_time_ms": "",
	"total_product_amount": "",
	"custom_attributes": {}
}

Property	Data Type	Required	Description
id	string	optional	id
name	string	optional	name
brand	string	optional	brand
category	string	optional	category
variant	string	optional	variant
position	Int32	optional	position
price	decimal	optional	price
quantity	decimal	optional	quantity
coupon_code	string	optional	coupon code
added_to_cart_time_ms	Int64	optional	Added to card milliseconds since epoch
total_product_amount	decimal	optional	total product amount
custom_attributes	JSON key value pairs	optional	A dictionary of custom attributes

Promotion

{
	"id": "",
	"name": "",
	"creative": "",
	"position": ""
}

Property	Data Type	Required	Description
id	string	optional	id
name	string	optional	name
creative	string	optional	creative
position	string	optional	position

session_start

{
	"data": {			
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {}
	},
	"event_type": "session_start"
}

No additional fields are allowed in the data node.

session_end

{
	"data": {			
		"session_duration_ms": 6000,
		"custom_attributes": {
			"button_name":  "home",
			"other_attribute":  "xyz"
		},
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {}
	},
	"event_type": "session_end"
}

Property	Data Type	Required	Description
session_duration_ms	Int64	optional	The length of the session in milliseconds.
custom_attributes	JSON key value pairs	optional	A dictionary of custom attributes.

screen_view

{
	"data": {			
		"screen_name": "Home",		
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "screen_view"
}

Property	Data Type	Required	Description
screen_name	string	optional	The name of the screen

uninstall

{
	"data": {
		"event_id":6004677780660780000,
		"source_message_id":"e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id":4957918240501247982,
		"session_uuid":"91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms":1402521613976,
		"location":{},
		"device_current_state":{},
		"custom_attributes": {}
	},
	"event_type":"uninstall"
}

No additional fields are allowed in the data node.

crash_report

{
	"data": {
		"class_name": "NSInvalidArgumentException",
		"breadcrumbs": [{}],
		"severity": "fatal",
		"message": "-[MPCViewController crash]: unrecognized selector sent to instance 0x125e0d3d0",
		"stack_trace": "Example Stack Trace here",
		"exception_handled": false,
		"topmost_context": "MPCViewController",
		"pl_crash_report_file_base64": "base64 string here",
		"ios_image_base_address": 4295507968,
		"ios_image_size": 535216,
		"session_number": 25,
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "crash_report"
}

Property	Data Type	Required	Description
class_name	string	optional	Exception class name
breadcrumbs	An array of breadcrumb events	optional	An array of breadcrumb events
severity	string	optional	severity
message	string	optional	Error message
stack_trace	string	optional	Exception stack trace
exception_handled	bool	optional	Determines if the exception was handled
topmost_context	string	optional	Topmost context of the exception
pl_crash_report_file_base64	string	optional	Plausible Labs Crash Report file, as Base-64 string
ios_image_base_address	unsigned Int64	optional	iOS or tvOS image base address
ios_image_size	unsigned Int64	optional	iOS or tvOS image size
session_number	int32	optional	Session number that the crash occurred on

opt_out

{
	"data": {
		"is_opted_out": true,		
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "opt_out"
}

Property	Data Type	Required	Description
is_opted_out	bool	suggested, false by default	is the user opted out

push_registration

{
	"data": {
		"register": true,
		"registration_token": "x",
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "push_registration"
}

Property	Data Type	Required	Description
register	bool	required	Add/remove registration flag
registration_token	string	required	Registration Token

application_state_transition

{
	"data": {
		"is_first_run": false,
		"is_upgrade": false,
		"successfully_closed": true,
		"push_notification_payload": "{}",
		"application_transition_type": "application_initialized",
		"register": true,
		"registration_token": "x",
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"push_notification_payload":null,
		"launch_referral":"https://www.mparticle.com/?utm_source=adwords&utm_medium=paid-search&utm_campaign=homepage-us-key-cities&utm_term=mparticle&utm_content=growth-api-demo&gclid=EAIaIQobChMIhpjBzpSR4gIVg42zCh33nwf_EAAYASAAEgIAWfD_BwE",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "application_state_transition"
}

Property	Data Type	optional	Description
is_first_run	bool	optional	Set to true if this is on an install. Only use this field if the `application_transition_type` is `application_initialized`.
is_upgrade	bool	optional	Set to true if this is on an upgrade. Only use this field if the `application_transition_type` is `application_initialized`.
successfully_closed	bool	optional	Set to true if the previous session successfully closed
push_notification_payload	string	optional	Push notification message data in JSON format
application_transition_type	string / enum	required	Accepted values are `application_initialized`, `application_exit`, `application_background`, or `application_foreground`
launch_referral	string	optional	A string representing the referral URL that triggered the most recent app foreground and web navigation

push_message

{
	"data": {
		"push_message_token": "x",
		"push_message_type": "action",
		"message": "Message Text to consumer",
		"network": "apn",
		"push_notification_payload": "{}",
		"application_state": "foreground",
		"action_identifier": "action",
		"push_message_behavior": 2,
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "push_message"
}

Property	Data Type	Required	Description
push_message_token	string	optional	Push Message Token
push_message_type	string / enum	required	“sent”, “received”, “action”
message	string	optional	The text displayed in push message
network	string / enum	suggested	“apn” for apple push notifications, “gcm” for google cloud messaging
push_notification_payload	string	optional	push notification message data in JSON format
application_state	string / enum	optional	“not_running”, “background”, or “foreground”
action_identifier	string	optional	action identifier, 100 character limit
push_message_behavior	integer	optional	Bit mask representing the behaviors that have been so far observed for the given push message.

network_performance

{
	"data": {
		"http_verb": "GET",
		"url": "http://sample.url",
		"time_elapsed": 450,
		"bytes_in": 2048,
		"bytes_out": 2048,
		"response_code": "200",
		"data": "",
		"event_id": 6004677780660780000,
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "network_performance"
}

Property	Data Type	Required	Description
http_verb	string	optional	HTTP Verb
url	string	optional	URL
time_elapsed	Int32	optional	time elapsed during network call
bytes_in	Int32	optional	Bytes in
bytes_out	Int32	optional	Bytes out
response_code	string	optional	Http response code
data	string	optional	Base64 string

{
	"data": {
		"session_number": 45,
		"label": "label",
		"event_id": "6004677780660780000",
		"source_message_id": "e8335d31-2031-4bff-afec-17ffc1784697",
		"session_id": 4957918240501247982,
		"session_uuid": "91b86d0c-86cb-4124-a8b2-edee107de454",
		"timestamp_unixtime_ms": 1402521613976,
		"location": {},
		"device_current_state": {},
		"custom_attributes": {}
	},
	"event_type": "breadcrumb"
}

Property	Data Type	Required	Description
session_number	Int32	optional	Session number
label	string	required	Label

`location`

Note this is the location for an event, not an event batch. For information on setting event batch location, see Context.

{
	"location": {
		"latitude": 40.7142,
		"longitude": 74.0064,
		"accuracy": 195.0165104914573,
		"country_code": "US",
		"region_code": "NY",
		"city_name": "New York",
		"postal_code": "10010",
		"dma_code": 501,
		"location_source": "lat_long"
	}
}

Property	Data Type	Required	Description
latitude	double	optional	Latitude
longitude	double	optional	Longitude
accuracy	double	optional	Accuracy in meters. For example, an accuracy of `50` means the device is within 50 meters of the specified latitude and longitude.
country_code	string	optional	Two letter ISO 3166-1 country code
region_code	string	optional	Subdivision portion of the ISO 3166-2 code
city_name	string	optional	City name
postal_code	string	optional	Postal code
dma_code	Int32	optional	DMA code
location_source	string	optional	One of “unknown”, “ip_lookup”, or “lat_long”

`context`

{
	"context": {
		"data_plan": {
			"plan_id": "mobile_data_plan",
			"plan_version": 2
		},
		"location": {
			"latitude": 40.7142,
			"longitude": 74.0064,
			"accuracy": 195.0165104914573,
			"country_code": "US",
			"region_code": "NY",
			"city_name": "New York",
			"postal_code": "10010",
			"dma_code": 501,
			"location_source": "lat_long"
		}
	}
}

The context field lets you enable additional mParticle features such as Data Planning. By providing your plan’s id and version, you can start validating incoming data against your expectations. Learn more about Data Planning here.

Property	Data Type	Required	Description
plan_id	string	optional	The Id of your data plan
plan_version	Int32	optional	The version of your data plan, if omitted the latest version of the plan_id will be used.

The context field also lets you specify a location for an event batch. Location can be set automatically for some outputs if none is specified. Location is set from the first event with a valid location or IP if there are no events with valid locations.

Property	Data Type	Required	Description
latitude	double	optional	Latitude
longitude	double	optional	Longitude
accuracy	double	optional	Accuracy in meters. For example, an accuracy of `50` means the device is within 50 meters of the specified latitude and longitude.
country_code	string	optional	Two letter ISO 3166-1 country code
region_code	string	optional	Subdivision portion of the ISO 3166-2 code
city_name	string	optional	City name
postal_code	string	optional	Postal code
dma_code	Int32	optional	DMA code
location_source	string	optional	One of “unknown”, “ip_lookup”, or “lat_long”

`custom_flags`

{
	"custom_flags": {
		"Google.Category": "pageview",
		"Google.Label": "main:mktg:personal::home",
		"Google.Value": "123"
	}
}

Custom flags are:

used to trigger behaviors for predefined data-points to a specific integration.
sent to the specific integration, and to all raw data event integrations (i.e. Amazon Kinesis, Amazon S3, Amazon SNS, Amazon SQS, Apache Kafka, Google Cloud Storage, Google Pub/Sub, Microsoft Azure Blob Storage, Microsoft Azure Event Hubs, Slack, and Webhook). This differs from custom_attributes, which are will sent to all connected integrations which support generic key/value attributes.
cannot be used within an audience definition.

Reference the guide for each integration to see if you need to instrument custom flags. Custom flags are supported by the following partners:

`device_current_state`

{
	"device_current_state": {
			"cpu": "4",
			"system_memory_available_Bytes": 536903680.0,
			"system_memory_low":  false,
			"system_memory_threshold_bytes": 56590336,
			"application_memory_available_bytes": 6995328,
			"application_memory_max_bytes": 67108864,
			"application_memory_total_bytes": 17604608.0,
			"device_orientation": "undefined",
			"status_bar_orientation":  "undefined",
			"time_since_start_ms":  5515182,
			"battery_level": 0.95,
			"data_connection_type":  "wifi",
			"data_connection_type_detail":  "hdspa",
			"gps_state": true,
			"total_system_memory_usage_bytes": 2980528128,
			"disk_space_free_bytes": 29716148224,
			"external_disk_space_free_bytes":  10121
		}
}

Property	Data Type	Required	Description
cpu	string	optional	CPU utilization in integer form
system_memory_available_bytes	double	optional	Total bytes of system memory available
system_memory_low	bool	optional	Boolean to indicate whether system memory is low
system_memory_threshold_bytes	optional	double	Android only
application_memory_available_bytes	double	optional	Total bytes of application memory available
application_memory_max_bytes	double	optional	Maximum bytes of application memory used
application_memory_total_bytes	double	optional	Total bytes of memory application is currently using
device_orientation	string / enum	optional	“portrait”, “landscape”, or “square”
status_bar_orientation	string	optional	iOS only
time_since_start_ms	Int64	optional	Time in milliseconds since application was loaded
battery_level	double	optional	Integer representation of battery percentage remaining
data_connection_type	string / enum	optional	“offline”, “wifi”, or “mobile”
data_connection_type_detail	string	optional	data connection type details
gps_state	string / enum	optional	String value indicating whether GPS is enabled - Values: “unknown”, “true”, or “false”
total_system_memory_usage_bytes	Int64	optional
disk_space_free_bytes	Int64	optional	Total number of bytes of disk space available
external_disk_space_free_bytes	Int64	optional	Android only

`device_info`

{
    "device_info": {
        "brand": "iPhone6,1",
        "product": "iPhone6,1",
        "device": "John's iPhone 5s",
        "android_uuid": null,
        "device_manufacturer": "Apple",
        "platform": "iOS",
        "os_version": "7.1.1",
        "device_model": "iPhone6,1",
        "screen_height": 1136,
        "screen_width": 640,
        "screen_dpi": 160,
        "device_country": "USA",
        "locale_language": "en",
        "locale_country": "US",
        "network_country": "us",
        "network_carrier": "AT&T",
        "network_code": "410",
        "network_mobile_country_code": "310",
        "timezone_offset": -4,
        "build_identifier": "M4-rc20",
        "http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Mobile/11D167 mParticle/2.5.0",
        "ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0",
        "att_authorization_status": "authorized",
        "att_timestamp_unixtime_ms": 1614187122051,
        "push_token": "<e481f135 9629f0c3 fb634be0 82ca18b1 73ea45a2 b0b96a6e 2a00c829 bc9ff6eb>",
        "cpu_architecture": "arm64",
        "is_tablet": false,
        "push_notification_sound_enabled": true,
        "push_notification_vibrate_enabled": false,
        "radio_access_technology": "LTE",
        "supports_telephony": "",
        "has_nfc": false,
        "bluetooth_enabled": true,
        "bluetooth_version": "",
        "ios_idfv": "8c61383f-2216-4713-8c1c-1cb0a5d7a4cc",
        "android_advertising_id": "",
        "limit_ad_tracking": false,
        "is_dst": false
    }
}

Property	Data Type	Required	Description
brand	string	optional	Device Brand, e.g. Google
product	string	optional	Product
device	string	optional	Device Name
android_uuid	string	optional	legacy Android ID
device_manufacturer	string	optional	Device Manufacturer
platform	string / enum	optional	Valid values: “iOS”, “Android”, “web”, “tvOS”, “roku”, “out_of_band”, “alexa”, “smart_tv”, “fire_tv”, “xbox”
os_version	string / Version	optional	Major.Minor.Revision of OS, e.g. 7.1.1
device_model	string	optional	Name of Device Model, e.g. iPhone6,1
screen_height	Int32	optional	Screen height in pixels
screen_width	Int32	optional	Screen width in pixels
screen_dpi	Int32	optional	Android only
device_country	string	optional	Android only
locale_language	string	optional	Current language device is set to
locale_country	string	optional	Current locale device is set to
network_country	string	optional	Country name data/cellular network bound to
network_carrier	string	optional	network carrier
network_code	string	optional	This is the mobile network code
network_mobile_country_code	string	optional	Standardized country code of network bound to
timezone_offset	Int32	optional	This is the device’s timezone offset setting, in hours relative to UTC
build_identifier	string	optional	Build UUID
http_header_user_agent	string	optional	HTTP User Agent
ios_advertising_id	GUID	optional	iOS and tvOS. Synonymous with Apple Identifier for Advertisers (IDFA).
att_authorization_status	string / enum	optional	“authorized”, “denied”, “not_determined”, “restricted”
att_timestamp_unixtime_ms	Int32	optional	Specifies when the end-user first responded to the App Tracking Transparency prompt
push_token	string	optional	Push messaging registration token
cpu_architecture	string	optional	iOS and tvOS - CPU Architecture of device
is_tablet	nullable bool	optional	True/False or null whether device is a tablet
push_notification_sound_enabled	nullable bool	optional	Android only
push_notification_vibrate_enabled	nullable bool	optional	Android only
radio_access_technology	string	optional	radio access technology
supports_telephony	nullable bool	optional	Android only
has_nfc	nullable bool	optional	Android only
bluetooth_enabled	nullable bool	optional	Android only
bluetooth_version	string	optional	Android only
ios_idfv	GUID	optional	iOS and tvOS only. Apple’s Identifier for Vendors (IDFV).
android_advertising_id	GUID	optional	Android only. Synonymous with Google Advertising ID (GAID).
roku_advertising_id	GUID	optional	Roku only
roku_publisher_id	GUID	optional	Roku only
microsoft_advertising_id	GUID	optional	UWP only
microsoft_publisher_id	GUID	optional	UWP only
fire_advertising_id	GUID	optional	Amazon Fire TV only
limit_ad_tracking	nullable bool	optional	Limit Ad Tracking
is_dst	nullable bool	optional	Is Daylight Savings Time

`application_info`

{
    "application_info": {
        "application_name": "App Name",
        "application_version": "1.0.1",
        "application_build_number": "42",
        "install_referrer": "utm_campaign=my_campaign&utm_source=google&utm_medium=cpc&utm_term=my_keyword&utm_content=ad_variation1",
        "package": "com.mparticle.test",
        "apple_search_ads_attributes": {
            "Version3.1": {
                "iad-lineitem-id": "9590781",
                "iad-keyword": "foo",
                "iad-org-name": "bar",
                "iad-conversion-date": "11/04/2016 00:13:15",
                "iad-attribution": "true",
                "iad-adgroup-name": "Test Ad Group - Brand - Exact",
                "iad-campaign-id": "123456",
                "iad-adgroup-id": "654321",
                "iad-lineitem-name": "Test Ad Group - Brand - Exact",
                "iad-campaign-name": "Test Campaign - Brand",
                "iad-click-date": "11/04/2016 00:13:09",
                "iad-conversion-type": "Download",
                "iad-keyword-matchtype": "Broad"
            }
        }
    }
}

Property	Data Type	Required	Description
application_name	string	optional	Name of application
application_version	string	optional	Version of application
application_build_number	string	optional	Build of the application
install_referrer	string	optional	Android Only - Provided by Google Play Store
package	string	optional	Package name
apple_search_ads_attributes	dictionary	optional	Apple App Store Search Ads attribution arguments

`user_attributes`

The properties with the prefix ”$” are reserved attributes that drive specific behaviors in our platform. This object can also contain any number of custom user attributes that you can define from within your app. Custom attributes also allow for lists of values instead of scalar values, but in general a given attribute should not change between a scalar and a list in subsequent calls.

{
    "user_attributes": {
        "$age": "18",
        "$gender": "M",
        "$country": "USA",
        "$zip": "10016",
        "$city": "New York",
        "$state": "NY",
        "$address": "381 Park Avenue S",
        "$firstname": "John",
        "$lastname": "Doe",
        "$mobile": "123-456-7890",
        "a_custom_attribute": "some_value",
        "a_custom_list": [
          "value1",
          "value2",
          "valueN"
        ]
    }
}

`user_identities`

{
    "user_identities": {
        "customer_id": "1234",
        "email": "helpers@mparticle.com",
        "facebook": "helpers@mparticle.com",
        "twitter": "helpers@mparticle.com",
        "google": "helpers@mparticle.com",
        "microsoft": "helpers@mparticle.com",
        "other": "helpers@mparticle.com",
        "other_id_2": "helpers2@example.com",
        "other_id_3": "helpers3@example.com",
        "other_id_4": "helpers4@example.com",
        "other_id_5": "helpers5@example.com",
        "other_id_6": "helpers6@example.com",
        "other_id_7": "helpers7@example.com",
        "other_id_8": "helpers8@example.com",
        "other_id_9": "helpers9@example.com",
        "other_id_10": "helpers10@example.com",
        "mobile_number": "800-555-1111",
        "phone_number_2": "800-555-2222",
        "phone_number_3": "800-555-3333"
    }
}

`partner_identities`

Partner Identities are unique identifiers associated with a user, but specific to a partner system. They can be ingested by mParticle via Partner Feed or our S2S API, and can be sent to downstream connections associated with the given partner. A Partner Feed can only send in their registered partner identity, whereas a S2S request can include any partner identity.

{
    "partner_identities": {
        "partner_id": "1234"
    }
}

Registering a new Partner Identity

Before a partner’s unique identity can be ingested, it must be registered with mParticle. Partners can register a new identity by either:

Contacting mParticle.
Updating your Firehose module, if applicable. For more information, see Firehose — Partner Identities.

The naming convention for these identities is as follows: PartnerName_IdentityName. An example for mParticle could be: mParticle_mpid

`integration_attributes`

Integration attributes are unique values associated with a given user, for a given integration. They are generally required for the integration to function properly.

The JSON blob is indexed by Module ID, meaning each integration can have its own values:

{
    "integration_attributes": {
        "123": {
          "someIntegrationAttribute": "value"
        }
    }
}

In order to find out a given integration’s ID, you can check the corresponding URL from the mParticle Directory.

`consent_state`

Used to communicate the GDPR consent state for the user. For GDPR, you must define the purposes (shown here as location_collection and parental) in the mParticle UI. For CCPA, only the below purpose is allowed and it does not need to be defined. Pass consented: true to register a users opt-out to CCPA data sale.

{
    "consent_state": {
        "gdpr": {
            "location_collection": {
                "consented": true,
                "document": "location_collection_agreement_v4",
                "timestamp_unixtime_ms": 1523039002083,
                "location": "17 Cherry Tree Lane",
                "hardware_id": "IDFA:a5d934n0-232f-4afc-2e9a-3832d95zc702"
            },
            "parental": {
                "consented": false,
                "document": "parental_consent_agreement_v2",
                "timestamp_unixtime_ms": 1523039002083,
                "location": "17 Cherry Tree Lane",
                "hardware_id": "IDFA:a5d934n0-232f-4afc-2e9a-3832d95zc702"
            }
        },
        "ccpa": {
            "data_sale_opt_out": {
                "consented": true,
                "document": null,
                "timestamp_unixtime_ms": 1523039002083,
                "location": null,
                "hardware_id": null
            }
        }
    }
}

`source_info`

This node is populated automatically by mParticle on receiving a batch. You do not need to send source_info.

This node is available in the mParticle Rules environment, but all values are immutable.

{
    "source_info": {
        "channel": "server_to_server",
        "partner": null,
        "replay_request_id": null,
        "replay_job_id": null,
        "is_historical": true
    }
}

Property	Data Type	Description
channel	string	Source the batch was received from. Valid values: “native”, “javascript”, “pixel”, “partner”, “server_to_server”, and “unknown”.
partner	string	If the channel is `Partner`, this field is the name of the partner feed
replay_request_id	string	If data is from a replay, unique ID for the replay request
replay_job_id	string	If data is from a replay, unique ID for the replay job
is_historical	string	If true, data was received via the historical endpoint.

Master Sample

{
  "environment": "production",
  "device_info": {
	"brand": "iPhone6,1",
	"product": "iPhone6,1",
	"device": "John's iPhone 5s",
	"android_uuid": "",
	"device_manufacturer": "Apple",
	"platform": "iOS",
	"os_version": "7.1.1",
	"device_model": "iPhone6,1",
	"screen_height": 1136,
	"screen_width": 640,
	"screen_dpi": 160,
	"device_country": "USA",
	"locale_language": "en",
	"locale_country": "US",
	"network_country": "us",
	"network_carrier": "AT&T",
	"network_code": "410",
	"network_mobile_country_code": "310",
	"timezone_offset": -4,
	"build_identifier": "M4-rc20",
	"http_header_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Mobile/11D167 mParticle/2.5.0",
	"ios_advertising_id": "613ff528-afd1-4c1b-9628-e6ed25ece9c0",
	"att_authorization_status": "authorized",
	"att_timestamp_unixtime_ms": 1614187122051,
	"push_token": "<e481f135 9629f0c3 fb634be0 82ca18b1 73ea45a2 b0b96a6e 2a00c829 bc9ff6eb>",
	"cpu_architecture": "arm64",
	"is_tablet": false,
	"push_notification_sound_enabled": true,
	"push_notification_vibrate_enabled": false,
	"radio_access_technology": "LTE",
	"supports_telephony": null,
	"has_nfc": false,
	"bluetooth_enabled": true,
	"bluetooth_version": "",
	"ios_idfv": "8c61383f-2216-4713-8c1c-1cb0a5d7a4cc",
	"android_advertising_id": null,
	"limit_ad_tracking": false,
	"is_dst": false
  },
  "application_info": {
	"application_name": "App Name",
	"application_version": "1.0.1",
	"application_build_number": "42",
	"install_referrer": "utm_campaign=my_campaign&utm_source=google&utm_medium=cpc&utm_term=my_keyword&utm_content=ad_variation1",
	"package": "com.newco.myapp"
  },
  "user_attributes": {
	"$age": "18",
	"$gender": "M",
	"$country": "USA",
	"$zip": "10016",
	"$city": "New York",
	"$state": "NY",
	"$address": "381 Park Avenue S",
	"$firstname": "John",
	"$lastname": "Doe",
	"$mobile": "123-456-7890",
	"a_custom_attribute": "some_value",
	"a_custom_list": [
	  "value1",
	  "value2",
	  "valueN"
	]
  },
  "deleted_user_attributes": [
	"an_old_attribute_name",
	"another_old_attribute"
  ],
  "user_identities": {
	"customer_id": "1234",
	"email": "helpers@mparticle.com",
	"facebook": "helpers@mparticle.com",
	"twitter": "helpers@mparticle.com",
	"google": "helpers@mparticle.com",
	"microsoft": "helpers@mparticle.com",
	"alias": "helpers@mparticle.com",
	"other": "helpers@mparticle.com"
  },
  "partner_identities": {
	"partner_id": "1234"
  },
  "integration_attributes": {
	"123": {
	  "key": "value"
	}
  },
  "events": [
	{
	  "data": {
		"timestamp_unixtime_ms": 1432825980486,
		"source_message_id": "4e34bef3-d2f9-4f07-8298-4646cce292fa",
		"session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
		"session_id": 123141241343
	  },
	  "event_type": "session_start"
	},
	{
	  "data": {
		"application_transition_type": "application_background",
		"event_id": -1586912177303106600,
		"session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
		"timestamp_unixtime_ms": 1402578873533,
		"is_first_run": false,
		"is_upgrade": true,
		"successfully_closed": true,
		"push_notification_payload": null,
		"launch_referral": null,
		"location": {
		  "latitude": 40.7142,
		  "longitude": 74.0064,
		  "accuracy": 195.0165104914573
		},
		"device_current_state": {
		  "time_since_start_ms": 713485,
		  "battery_level": -1,
		  "data_connection_type": "wifi",
		  "gps_state": true,
		  "total_system_memory_usage_bytes": 2981494784,
		  "disk_space_free_bytes": 29655015424,
		  "cpu": "0",
		  "system_memory_available_bytes": 182730752,
		  "application_memory_total_bytes": 17813504,
		  "device_orientation": 6,
		  "status_bar_orientation": 1
		}
	  },
	  "event_type": "application_state_transition"
	},
	{
	  "data": {
		"class_name": "NSInvalidArgumentException",
		"severity": "fatal",
		"message": "-[MPCViewController crash]: unrecognized selector sent to instance 0x125e0d3d0",
		"stack_trace": "Example Stack Trace here",
		"topmost_context": "MPCViewController",
		"pl_crash_report_file_base64": "base64 string here",
		"ios_image_base_address": 4295507968,
		"ios_image_size": 535216,
		"event_id": 1558493756361828400,
		"timestamp_unixtime_ms": 1402579716192,
		"location": {
		  "latitude": 40.7142,
		  "longitude": 74.0064,
		  "accuracy": 195.0165104914573
		},
		"device_current_state": {
		  "time_since_start_ms": 106554,
		  "battery_level": -1,
		  "data_connection_type": "wifi",
		  "gps_state": true,
		  "total_system_memory_usage_bytes": 2995585024,
		  "disk_space_free_bytes": 29653184512,
		  "cpu": "0",
		  "system_memory_available_bytes": 300056576,
		  "application_memory_total_bytes": 18108416,
		  "device_orientation": 6,
		  "status_bar_orientation": 1
		}
	  },
	  "event_type": "crash_report"
	},
	{
	  "data": {
		"timestamp_unixtime_ms": 1432825994215,
		"session_duration_ms": 60000,
		"source_message_id": "93862b36-adf3-43e6-87d2-2fcbf3f6d903",
		"session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
		"custom_attributes": {
		  "key23": "value2"
		}
	  },
	  "event_type": "session_end"
	}
  ]
}

Differences between incoming and outgoing JSON

Described above is the format required for sending data to mParticle via the Events API. A very similar format is used to send data to event outputs that accept raw JSON, including:

For these forwarders, mParticle makes our output as complete as possible, including fields only used internally or fields that are set automatically by mParticle and not part of the inbound JSON reference. The most important difference between incoming and outgoing JSON is that the user_identities field is expanded in the outgoing JSON to include additional information. In most other cases, additional fields added in the outgoing JSON are intended for internal use or to support edge cases and should be ignored unless you have a special need for these fields.

Some notable differences include:

mParticle may add identifiers for the batch (batch_id), and each event (message_id). These are used by mParticle for internal processing tasks like de-duping.
mParticle adds a message_type field to each event, which is used for internal processing.
mParticle may add session management fields to each event: session_id, session_uuid and session_start_unixtime.
Outbound JSON will include an event_start_unixtime_ms field. In almost all cases this will be the same as the main event timestamp_unixtime_ms field. It exists to support timed event use cases.
mParticle adds a top-level batch timestamp — timestamp_unixtime_ms — representing the time the batch was received by mParticle. This field is created by mParticle and should not be set manually when sending data via the Events API.
Some fields are set automatically by one or more native SDKs. For example, the Android SDK automatically sets an activity_type of activity_started or activity_stopped on Screen View events. This field is used by some event integrations to determine how to forward the event.
The system_notifications field is currently used by mParticle to forward changes in consent state to some partners. In outbound JSON this field is present but empty unless you are instrumenting data privacy controls.
mParticle may add a top-level batch unique_id field if you enter a value for the Unique ID connection setting.

Outgoing User Identities

In outgoing JSON, the user_identities node is an array of identity objects. Each object contains the identity type, the value, and a timestamp showing when the identity was last updated. For example:

{
    "user_identities": [
        {
            "identity_type": "customer_id",
            "identity": "h.jekyll.md",
            "timestamp_unixtime_ms": 1540483995196
        },
        {
            "identity_type": "email",
            "identity": "h.jekyll.md@example.com",
            "timestamp_unixtime_ms": 1540483995196
        }
    ]
}

JSON Schema Validation

mParticle’s server-side SDKs are designed to generate correct JSON in all cases. If you are unable to use mParticle’s SDKs, you can use the mParticle Events API JSON schema documents to validate your JSON prior to upload.

Python

The following example uses the popular jsonschema library and performs the following:

Downloads the latest Event API schemas (both the single and bulk variations)
Creates an arbitrary example upload as a dictionary
Validates both the single and bulk instance objects

from jsonschema import validate, exceptions
import urllib.request, json

schema_url = "https://docs.mparticle.com/schema/mparticle.inbound.eventsapi.schema.json"
url = urllib.request.urlopen(schema_url)
schema = json.loads(url.read().decode())

bulk_schema_url = "https://docs.mparticle.com/schema/mparticle.inbound.eventsapi.bulk.schema.json"
bulk_url = urllib.request.urlopen(bulk_schema_url)
bulk_schema = json.loads(bulk_url.read().decode())

# Create a dictionary to be validated
instance = {
	"source_request_id":"769D83CB-8C60-48F9-A0C1-C38CF1B40A4F",
	"device_info": {
		"ios_advertising_id":"1cc8138f-8aaf-410a-b0b9-6465cfb2af6a",
		"ios_idfv":"0f129dcb-d5b9-450b-9003-a38a7b7e946d",
		"att_authorization_status":"authorized",
		"att_timestamp_unixtime_ms":1614187122051
	},
	"user_attributes":{ "Test attribute":"Test value" },
	"user_identities":{ "customer_id":"123456" },
	"environment":"production"
}

# You can also load an existing JSON string into a dictionary
# instance = json.loads("{}")

# If you're sending via the bulk endpoint, create an array of batches
bulk_instance = [instance]

try:
	# If your JSON is badly formed, this will throw a ValidationError
	validate(instance=instance, schema=schema)
	validate(instance=bulk_instance, schema=bulk_schema)
except exceptions.ValidationError as e:
	# Read more on ValidationError objects here:
	# https://python-jsonschema.readthedocs.io/en/stable/errors/
	print(e.message)
	print(e.path)

Additional Libraries

See the JSON Schema specification homepage for more JSON Schema validation tools.

Was this page helpful?

Last Updated: November 12, 2024