JSON Reference

This document details the mParticle JSON Events format. This format is used to post events to mParticle via the HTTP API, receive events via webhook, and parse files uploaded to your Amazon S3 bucket.

Swagger Schema

As a supplement to the JSON documentation below, you can download mParticle’s Swagger file and open it in the Swagger Editor to study the schema in detail.

Overall Structure

{
    "events" :
    [
        {
            "data" : {},
            "event_type" : "custom_event"
        }
    ],
    "device_info" : {},
    "user_attributes" : {},
    "deleted_user_attributes" : [],
    "user_identities" : {},
    "application_info" : {},
    "schema_version": 2,
    "environment" : "production",
    "ip" : "127.0.0.1"
}
Property Data Type Description Input/Output Required
events An array of events An array of JSON objects, each representing an app event. The event object consists of two nodes: data, and type. The type indicates the entity structure of the data node. Both optional
schema_version Int32 Indicates the current schema version that this message batch conforms to. mParticle is currently on version 2. Output optional
device_info JSON device_info A JSON object containing information about the device pertaining to this message batch. Both optional
application_info JSON application_info A JSON object of information about your app. Both optional
user_attributes JSON object of string key value pairs A JSON object of demographic information about the user that generated the app events. Both optional
deleted_user_attributes JSON object of string key value pairs An array of JSON strings describing previously provided user attributes which should be forgotten. Both optional
user_identities JSON object of string key value pairs A JSON object of user ID information, such as email address and social IDs. Both optional
environment string / enum “production” or “development” Both required
ip string The IPv4 / IPv6 address of the consumer device Input optional

events

The event object consists of two 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,
		"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 Description Required
event_id Int64 Unique ID generated by mParticle server as each event is received. Read only
source_message_id string Unique Id of source event. Generated by client-side SDKs for platform data. If sending data via server API it is suggested to generate a UUID for each event. suggested
session_id Int64 Unique Id of session. Read only
session_uuid string An optional universally unique identifier for the session. The session_id will be derived from a hash of this value. suggested
timestamp_unixtime_ms Int64 Timestamp of event. The current server time will be used if not specified. suggested
location location JSON The location the event occurred in. optional
device_current_state device_current_state JSON 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. optional
custom_attributes JSON key value pairs A dictionary of custom attributes optional
custom_flags JSON key value pairs A dictionary of custom flags. See Custom Flags for more.

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 Description Required
event_name string The name of the event required
custom_event_type string / enum The type of custom event reference the custom_event_type descriptions below required
custom_attributes JSON key value pairs A dictionary of custom attributes optional

The allowed values of “custom_event_type” are:

custom_event_type Description
attribution Attribution events are set of user actions (“events” or “touchpoints”) 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.
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

If you are sending attribution custom events, you should specify the custom event as listed below. You should also include campaign and publisher custom attributes representing the campaign and publisher which triggered the attribution event. The attribution event should include as many device and user identifiers that you have - android_advertising_id, ios_advertising_id, ios_idfv, and customer_id.

Property Value
event_type custom_event
event_name attribution
custom_event_type attribution

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.

  1. Product-based - Used to measure measured datapoints associated with one or more products.
    These have a product_action and do NOT have a promotion_action or a product_impressions

  2. Promotion-based - Used to measure datapoints associated with internal promotions or campaigns.
    These have a promotion_action and do NOT have a product_action or a product_impressions

  3. 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 Description Required
product_action product_action JSON Used to measure measured datapoints associated with one or more products required or disallowed (see above)
promotion_action promotion_action JSON Used to measure datapoints associated with internal promotions or campaigns required or disallowed (see above)
product_impressions An array of JSON product_impressions Product impressions required or disallowed (see above)
shopping_cart shopping_cart JSON current shopping cart state optional
currency_code string code representing the currency the transaction is conducted in optional
screen_name string screen name optional
is_non_interactive Boolean is non interactive optional

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 Description Required
action string / enum The type of action the descriptions are below required
checkout_step Int32 The step of the checkout process optional
checkout_options string checkout options optional
product_action_list string product action list optional
transaction_id string transaction id optional
affiliation string affiliation optional
total_amount decimal total amount optional
tax_amount decimal tax amount optional
shipping_amount decimal shipping amount optional
coupon_code string coupon code optional
products An array of JSON Product products optional

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 Description Required
action string / enum Type of action. Allowed values are view and click. required
promotions An array of JSON Promotion promotions optional

product_impressions

{
	"product_impression_list" : "",
	"products" : [{}]
}
Property Data Type Description Required
product_impression_list string product impression list optional
products array of objects products optional

shopping_cart

{
	"products" : [{}]
}
Property Data Type Description Required
products array of objects products optional

Product

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

Promotion

{
	"id" : "",
	"name" : "",
	"creative" : "",
	"position" : ""
}
Property Data Type Description Required
id string id optional
name string name optional
creative string creative optional
position string position optional

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 Description Required
session_duration_ms Int64 The length of the session in milliseconds optional
custom_attributes JSON key value pairs A dictionary of custom attributes optional

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 Description Required
screen_name string The name of the screen optional

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

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 Description Required
is_opted_out bool is the user opted out suggested, false by default

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 Description Required
register bool Add/remove registration flag required
registration_token string Registration Token required

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",
		"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 Description Required
is_first_run bool Set to true if this is on an install. Only use this field if the application_transition_type is application_initialized. optional
is_upgrade bool Set to true if this is on an upgrade. Only use this field if the application_transition_type is application_initialized. optional
successfully_closed bool Set to true if the previous session successfully closed suggested, false is assumed
push_notification_payload string Push notification message data in JSON format optional
application_transition_type string / enum Accepted values are application_initialized, application_exit, application_background, or application_foreground required

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",
		"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 Description Required
push_message_token string Push Message Token optional
push_message_type string / enum “sent”, “received”, “action” required
message string The text displayed in push message optional
network string / enum “apn” for apple push notifications, “gcm” for google cloud messaging suggested
push_notification_payload string push notification message data in JSON format optional
application_state string / enum “not_running”, “background”, or “foreground” optional
action_identifier string action identifier, 100 character limit optional

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 Description Required
http_verb string HTTP Verb optional
url string URL optional
time_elapsed Int32 time elapsed during network call optional
bytes_in Int32 Bytes in optional
bytes_out Int32 Bytes out optional
response_code string Http response code optional
data string Base64 string optional
{
	"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 Description Required
session_number Int32 Session number optional
label string Label required

location

{
	"location" :
	{
		"latitude" : 40.7142,
		"longitude" : 74.0064,
		"accuracy" : 195.0165104914573
	}
}
Property Data Type Description Required
latitude double Latitude optional
longitude double Longitude optional
accuracy double Accuracy optional

custom_flags

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

Custom flags are used to trigger specific behavior and send specific data-points to particular providers. By design, custom flags are sent only to the specific provider for which they are required. This differs from generic, custom event attributes, which mParticle will send to all of your configured services which support generic key/value event data. Custom Flags 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 Description Required
cpu string CPU utilization in integer form optional
system_memory_available_bytes double Total bytes of system memory available optional
system_memory_low bool Boolean to indicate whether system memory is low optional
system_memory_threshold_bytes double Android only optional
application_memory_available_bytes double Total bytes of application memory available optional
application_memory_max_bytes double Maximum bytes of application memory used optional
application_memory_total_bytes double Total bytes of memory application is currently using optional
device_orientation string / enum “portrait”, “landscape”, or “square” optional
status_bar_orientation string iOS only optional
time_since_start_ms Int64 Time in milliseconds since application was loaded optional
battery_level double Integer representation of battery percentage remaining optional
data_connection_type string / enum “offline”, “wifi”, or “mobile” optional
data_connection_type_detail string data connection type details optional
gps_state string / enum String value indicating whether GPS is enabled - Values: “unknown”, “true”, or “false” optional
total_system_memory_usage_bytes Int64 optional
disk_space_free_bytes Int64 Total number of bytes of disk space available optional
external_disk_space_free_bytes Int64 Android only optional

device_info

"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",   
        "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 Description Required
brand string Device Brand, e.g. Google optional
product string Product optional
device string Device Name optional
android_uuid string legacy Android ID optional
device_manufacturer string Device Manufacturer optional
platform string / enum “iOS” or “tvOS” or “Android” optional
os_version string / Version Major.Minor.Revision of OS, e.g. 7.1.1 optional
device_model string Name of Device Model, e.g. iPhone6,1 optional
screen_height Int32 Screen height in pixels optional
screen_width Int32 Screen width in pixels optional
screen_dpi Int32 Android only optional
device_country string Android only optional
locale_language string Current language device is set to optional
locale_country string Current locale device is set to optional
network_country string Country name data/cellular network bound to optional
network_carrier string network carrier optional
network_code string This is the mobile network code optional
network_mobile_country_code string Standardized country code of network bound to optional
timezone_offset Int32 This is the device’s timezone offset setting, in hours relative to UTC optional
build_identifier string Build UUID optional
http_header_user_agent string HTTP User Agent optional
ios_advertising_id GUID iOS and tvOS optional
push_token string Push messaging registration token optional
cpu_architecture string iOS and tvOS - CPU Architecture of device optional
is_tablet nullable bool True/False or null whether device is a tablet optional
push_notification_sound_enabled nullable bool Android only optional
push_notification_vibrate_enabled nullable bool Android only optional
radio_access_technology string radio access technology optional
supports_telephony nullable bool Android only optional
has_nfc nullable bool Android only optional
bluetooth_enabled nullable bool Android only optional
bluetooth_version string Android only optional
ios_idfv GUID iOS and tvOS optional
android_advertising_id GUID Android Only optional
roku_advertising_id GUID Roku only optional
roku_publisher_id GUID Roku only optional
microsoft_advertising_id GUID UWP only optional
microsoft_publisher_id GUID UWP only optional
fire_advertising_id GUID Amazon Fire TV only optional
limit_ad_tracking nullable bool Limit Ad Tracking optional
is_dst nullable bool Is Daylight Savings Time optional

application_info

"application_info":
{
    "application_name":  "App Name",
    "application_version": "1.0.1",
    "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 Description Required
application_name string Name of application optional
application_version string Version of application optional
install_referrer string Android Only - Provided by Google Play Store optional
package string Package name optional
apple_search_ads_attributes dictionary Apple App Store Search Ads attribution arguments optional

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":
{
   "customerid": "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",
   "other2": "helpers2@example.com",
   "other3": "helpers3@example.com",
   "other4": "helpers4@example.com"
}

Used to communicate the GDPR consent state for the user.

"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"     
	  }
	}  
}

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
}
Property Data Type Description
channel string Source the batch was received from. Possible values are: 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

Master Sample

{
  "schema_version": 2,
  "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",
    "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
  },
  "application_info": {
    "application_name": "App Name",
    "application_version": "1.0.1",
    "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": {
    "customerid": "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"
  },
  "events": [
    {
      "data": {
        "timestamp_unixtime_ms": 1432825980486,
        "source_message_id": "4e34bef3-d2f9-4f07-8298-4646cce292fa",
        "session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC"
      },
      "event_type": "session_start"
    },
    {
      "data": {
        "application_transition_type": "application_background",
        "event_id": -1586912177303106600,
        "session_uuid": "DDFBEA89-9A54-41C3-97F3-334FDD3B98BC",
        "timestamp_unixtime_ms": 1402578873533,
        "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 Server 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 adds the mpid field to each batch. This is the unique mParticle identifier for the user, calculated based on user and device identities in the batch, according to your Identity Strategy.
  • 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 Server 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 will be present but empty unless you are instrumenting Consent Management.

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
   }
 ],