Skip to main content

Parameters

These parameters consist of all required event data parameters and any additional data parameters the Conversions API needs to use for ads attribution and/or ads delivery optimization.

Note : Our Conversions API now supports web, app, and offline events.

How To Use

Parameters can be used in request's root object or contained in the data array.

ParametersObject
User Datauser_data
Dynamic Adscustom_data
Dynamic Travel Adscustom_data
Server Dataroot data
LMUroot data
App Dataapp_data

Check Using The API for JSON structure and more information on sending events using the Conversions API.

User Data Parameters

ParameterDatatypeDescription
emstring or list of stringsEmail address. Trim any additional characters (such as spaces) and convert to lowercase before hashing. Hashing required.

Example:
Input: Person@Example.com
After Normalization: person@example.com
Hashed Output: 542d240129883c019e106e3b1b2d3f3cb3537c43c425364de8e951d5a3083345
phstring or list of stringsPhone number. Normalize phone numbers by including the country code, remove any double 0 in front of the country code. If the number itself begins with a 0, this should be removed. Also exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’. Hashing required.

Example:
Input: +44 844 412 4653
Normalized format: 448444124653
Hashed Output: dc008fda46e2e64002cf2f82a4906236282d431c4f75e5b60bfe79fc48546383
fnstring or list of stringsFirst name. Use lower case letters only. Make sure to remove any punctuation and if there are special characters they must be encoded using UTF-8. Hashing required.

Example:
Input: John
Normalized format: john
Hashed Output: 96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a

Input - Raphaël
Normalized format: raphaël
Hashed Output: e74bb89e718fe1e19c422a48382870399f8bf7ca8dfa008739e75b0be76627b7
lnstring or list of stringsLast name. Use lower case letters only. Make sure to remove any punctuation and if there are special characters they must be encoded using UTF-8. Hashing required

Example:
Input: Andrews
Normalized format: andrews
Hashed Output: 90aa2608758d2bc747d65079720aba7eef76ccb1b48166a3605908939aa835cd

Input: 김
Hashed UTF-8: 김
Hashed Output: a0d5f241aa6fb544e5d26431e2f40a310f0fc260803053038e5c6012ddaa6ce6
gestring or list of stringsGender Hashing required

Example:
f for female m for male

Input: f
Hashed Output: 252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111
ctstring or list of stringsCity associated with the conversion. This can come from a shipping or billing address. Use lower case letters only. Make sure to remove any punctuation, spaces and if there are special characters they must be encoded using UTF-8. Hashing required

Example:
Input: New York
Normalized format: newyork
Hashed Output: 350c754ba4d38897693aa077ef43072a859d23f613443133fecbbd90a3512ca5
ststring or list of stringsState associated with the conversion. This can come from a shipping or billing address. Hashing required

Example:
Input: CA
Normalized format: ca
Hashed Output: 6959097001d10501ac7d54c0bdb8db61420f658f2922cc26e46d536119a31126

Use the 2-character ANSI abbreviation code in lowercase. Normalize states outside the U.S. in lowercase with no punctuation, no special characters, and no spaces.
zpstring or list of stringsZip or postal code. This can come from a shipping or billing address. Use lowercase, remove any space and ‘-’ characters. For U.S addresses, use only the first 5 digits of the zipcode. In case of UK addresses, use the area, district and sector format. Hashing required

Example:
Input: 94035
Normalized format: 94035
Hashed Output: 1794327a4d443904421f5ca1f3d72d0a62ba2f0770d80755ec2220fc0efb052e
countrystring or list of stringsCountry associated with the event. Provided as a two letter ISO 3166 alpha-2 country code. US, GB, JP Hashing required

Example:
Input: US
Normalized format: us
Hashed Output: 79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621
client_ip_addressstringIP Address of the device (not server). We support both IPv4 and IPv6 for both web and app. Do not hash
external_idstringA unique ID such as a loyalty card ID, first party cookie identifier, or some other identifier. Hashing recommended
subscription_idstringThe subscription ID for the user who generated this event. Do not hash
lead_idstringThis is the identifier associated with your Snapchat Lead Ad Do not hash
anon_idstringDo not hash. This parameter is only for app events. It represents a unique application install id.
madidstringMobile advertiser id. Normalize mobile advertiser id by using all lowercase. Do not hash
download_idstringID associated with an app download event Do not hash
client_user_agentstringUser agent of the device that was used. Recommended for all web and app events when available. Do not hash

Example:
Chrome/87.0.4180.143, Safari/547.38
sc_click_idstringThe ID value stored in the landing page URL’s &ScCid= query parameter. Using this ID improves ad measurement performance. We also encourage advertisers who are using click id to pass the full url in the page_url field. Do not hash
sc_cookie1stringIf you are using the Pixel SDK, you can access a 1st party cookie by looking at the _scid value under your domain. We highly recommend you pass this, as doing so will increase your user match rate. Do not hash
idfvstringPlain text IDFV value. Highly recommended for app events. Do not hash
partner_idstringUnique identifier provided by a partner, allowlist only.

Dynamic Ads Parameters

ParameterData TypeDescription
content_categorystring or list of stringsItem or Category. Can be a single category or an array.

Example:
“shoes” or [“coats”, “shoes”, “umbrellas"]
content_idslist of stringsInternational Article Number (EAN) when applicable, or other product or category identifier. This can be a single item ID, an array, or a list of item IDs to be separated by “,” Examples: "sku001" or ["sku001”,”sku002”,”sku003"]
content_namestringThe name of the page or product associated with the event.
content_typestringThe "content_type" field indicates what the keys in “content_ids” or “contents” represent. Choose "product" for individual items or "product_group" for items that have multiple options in either size, color or any other variation.
contentslist of objectsThis field represents item purchases in the form of a list of JSON objects. Each object contains the following fields: id quantity Item_price delivery_category
currencystringThis represents the currency associated with the value provided. Subset of standard ISO 4217 code supported currencies:

USD, AED, AUD, BGN, BRL, CAD, CHF, CLP, CNY, COP,CZK, DKK, EGP, EUR, GBP, GIP, HKD, HRK, HUF, IDR, ILS, INR, JPY, KRW, KWD, KZT, LBP, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, QAR,RON, RUB, SAR, SEK, SGD, THB, TRY, TWD, TZS, UAH, VND, ZAR, ALL, BHD, DZD, GHS, IQD, ISK, JOD, KES, MAD, OMR, XOF
num_itemsstringThis indicates the total number of items
order_idstringThis is the id representative of the order
predicted_ltvfloatThis is the predicted lifetime value of a conversion event
valuefloatThis numeric value is associated with the specific event. This is required for PURCHASE event
search_stringstringThe text that was searched for

Dynamic Travel Ads Parameters

ParameterData TypeDescription
checkin_datestringThe desired hotel check-in date in the hotel's time-zone. Accepted formats are YYYYMMDD, YYYY-MM-DD, YYYY-MM-DDThh:mmTZD and YYYY-MM-DDThh:mm:ssTZD
travel_endstringEnd date of travel
travel_startstringStart date of travel
suggested_destinationsstring or list of stringsThe suggested destinations

Example:
"destination1,destination2" or ["destination1", "destination2"]
destination_airportstringThe destination airport. Make sure to use the IATA code of the airport
countrystringThe country based on the location the user intends to visit
citystringThe city based on the location the user intends to visit
regionstringThis could be the state, district, or region of interest to the user
neighborhoodstringThe neighborhood the user is interested in
departing_departure_datestringThe starting date and time for travel
departing_arrival_datestringThe arrival date and time at the destination for the travel
num_adultsintegerThe number of adults staying
origin_airportstringThe official IATA code of origin airport
returning_departure_datestringThe starting date and time of the return journey
returning_arrival_datestringThe date and time when the return journey is complete
num_childrenintegerThe number of children staying
hotel_scorestringThis represents the hotels score relative to other hotels to an advertiser
postal_codestringThe postal /zip code
num_infantsintegerThe number of infants staying
preferred_neighborhoodsstring or list of stringsAny preferred neighborhoods for the stay

Example:
"neighbor1,neighbor2" or ["neighbor1", "neighbor2"]
preferred_star_ratingsstring or list of stringsThe minimum and maximum hotel star rating supplied as a tuple. This is what the user would use for filtering hotels

Example:
"star1,star2" or ["star1", "star2"]
suggested_hotelsstring or list of stringsThe suggested hotels

Example:
"hotel1,hotel2" or ["hotel1", "hotel2"]
destination_idsstring or list of stringsThis is the id representative of the destination in the catalog

Example:
"destination1,destination2" or ["destination1", "destination2"]

Server Parameters

ParameterDatatypeDescription
event_name (required)stringEvent type required for all web and app events.

Possible Events:

PURCHASE SAVE START_CHECKOUT ADD_CART VIEW_CONTENT ADD_BILLING SIGN_UP SEARCH PAGE_VIEW SUBSCRIBE AD_CLICK AD_VIEW COMPLETE_TUTORIAL LEVEL_COMPLETE INVITE LOGIN, SHARE RESERVE ACHIEVEMENT_UNLOCKED ADD_TO_WISHLIST SPENT_CREDITS RATE START_TRIAL LIST_VIEW APP_INSTALL APP_OPEN CUSTOM_EVENT_1 CUSTOM_EVENT_2 CUSTOM_EVENT_3 CUSTOM_EVENT_4 CUSTOM_EVENT_5
event_time (required)integerThe Epoch timestamp for the conversion happening. We can handle second level or millisecond level granularity. However, we do encourage requests to provide millisecond level granularity. Required for all web and app events. Please note: The event_time cannot be more than 7 days in the past
event_source_url (required)stringThe URL of the web page where the event took place. Must include protocol (eg http, https). When website events are being shared via Conversions API, the event_source_url field is required.
event_idstringThis field represents a unique identifier chosen by the advertiser to represent an event. The event_id and event_name parameters are used for deduplication of events sent via both web, app and conversions API. We recommend that you pass this for all unique events.
Examples: Transaction id, order id can are potential identifiers which can be passed here

If using Snap Pixel, event_id must match the client_dedup_id for the matching event
action_source (required)stringWhere the event took place. Required for all web and app events. Use the appropriate value accordingly.
WEB
OFFLINE
MOBILE_APP
integrationstringThere are two types of integrations. Direct or through a partner. If you are, or using a partner integration include this parameter with the value of your partner or connector.

Example:
mparticle
data_processing_optionslist of stringCurrently-accepted values are:
LMU
DELETE

Used to indicate an OPT_IN or OPT_OUT for WEB events. For users of iOS 14.5 and above that are OPT_OUT, set this parameter’s value to a list that has a single element of the value LMU. Otherwise, do not set this parameter.
advertiser_tracking_enabledboolSet it to 1 or 0 to indicate an OPT_IN or OPT_OUT respectively for MOBILE_APP events.

For users of iOS 14.5 and above, please set this parameter to the user’s ATT Authorization Status.
test_event_codestringAny string value. Exampe "datahash"

LMU Parameters

ParameterData TypeDescription
data_processing_optionslist of stringsAccepted values are:
LMU
DELETE

Used to indicate an OPT_IN or OPT_OUT for WEB events.

For users of iOS 14.5 and above that are OPT_OUT, set this parameter’s value to a list that has a single element of the value LMU. Otherwise, do not set this parameter.
advertiser_tracking_enabledboolSet it to 1 or 0 to indicate an OPT_IN or OPT_OUT respectively for mobile events. For users of iOS 14.5 and above, please set this parameter to the user’s ATT Authorization Status.

App Data Parameters

ParameterData TypeDescription
advertiser_tracking_enabledboolSet it to 1 or 0 to indicate an OPT_IN or OPT_OUT respectively for MOBILE_APP events.

For users of iOS 14.5 and above, please set this parameter to the user’s ATT Authorization Status.
extinfoobjectRequired
Device object from app event. This parameter expects an array with comma separated values. Additional device information such as screen width and height can be supplied through this parameter. Extinfo requires all values and needs them to be in the order indexed below in the extinfo object specs. Please note that Android devices’ version must be a2 while IOS devices’ must be i2.
app_idstringThe unique ID (app_id) assigned for a given application. It should be numeric for iOS, and the human interpretable string (

example:
com.snapchat.android) for Android. Required for app events. Set Up and Manage Your Snap App ID

Example:
The app_id for Snapchat is 447188370 (iOS) and com.snapchat.android (Android)

Custom Data Parameters

The custom_data object can contain parameters for Dynamic Ads and Dynamic Travel Ads, along with any other custom parameters.

Object specs

extinfo

required for all App events.

IndexValue
0Required extinfo version String

Example:
i2
1App package name String Example : com.snapchat.sdk
2Short version String or int Example 1.0
3Long version long

Example:
1.0
4Required OS version string

Example:
10.3.1
5Device model name String

Example:
iphone14
6locale String

Example:
En_US
7timezone abbreviation String

Example:
EDT
8carrier String

Example:
AT&T
9Screen width Int64

Example:
320
10Screen height Int64

Example:
568
11Screen density String

Example:
2
12CPU cores Int64

Example:
2
13External storage size in GB Int64

Example:
15
14Free Space on external storage in GB Int64

Example:
8
15device timezone string

Example:
USA/New York
Was this page helpful?
Yes
No

AI-Powered Search