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.
Parameters | Object |
---|---|
User Data | user_data |
Dynamic Ads | custom_data |
Dynamic Travel Ads | custom_data |
Server Data | root data |
LMU | root data |
App Data | app_data |
Check Using The API for JSON structure and more information on sending events using the Conversions API.
User Data Parameters
Parameter | Datatype | Description | ||
---|---|---|---|---|
em | string or list of strings | Email 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 | ||
ph | string or list of strings | Phone 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 | ||
fn | string or list of strings | First 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 | ||
ln | string or list of strings | Last 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 | ||
ge | string or list of strings | Gender Hashing required Example: f for female m for male Input: f Hashed Output: 252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111 | ||
ct | string or list of strings | City 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 | ||
st | string or list of strings | State 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. | ||
zp | string or list of strings | Zip 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 | ||
country | string or list of strings | Country 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_address | string | IP Address of the device (not server). We support both IPv4 and IPv6 for both web and app. Do not hash | ||
external_id | string | A unique ID such as a loyalty card ID, first party cookie identifier, or some other identifier. Hashing recommended | ||
subscription_id | string | The subscription ID for the user who generated this event. Do not hash | ||
lead_id | string | This is the identifier associated with your Snapchat Lead Ad Do not hash | ||
anon_id | string | Do not hash. This parameter is only for app events. It represents a unique application install id. | ||
madid | string | Mobile advertiser id. Normalize mobile advertiser id by using all lowercase. Do not hash | ||
download_id | string | ID associated with an app download event Do not hash | ||
client_user_agent | string | User 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_id | string | The 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_cookie1 | string | If 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 | ||
idfv | string | Plain text IDFV value. Highly recommended for app events. Do not hash | ||
partner_id | string | Unique identifier provided by a partner, allowlist only. |
Dynamic Ads Parameters
Parameter | Data Type | Description | ||
---|---|---|---|---|
content_category | string or list of strings | Item or Category. Can be a single category or an array. Example: “shoes” or [“coats”, “shoes”, “umbrellas"] | ||
content_ids | list of strings | International 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_name | string | The name of the page or product associated with the event. | ||
content_type | string | The "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. | ||
contents | list of objects | This 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 | ||
currency | string | This 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_items | string | This indicates the total number of items | ||
order_id | string | This is the id representative of the order | ||
predicted_ltv | float | This is the predicted lifetime value of a conversion event | ||
value | float | This numeric value is associated with the specific event. This is required for PURCHASE event | ||
search_string | string | The text that was searched for |
Dynamic Travel Ads Parameters
Parameter | Data Type | Description | ||
---|---|---|---|---|
checkin_date | string | The 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_end | string | End date of travel | ||
travel_start | string | Start date of travel | ||
suggested_destinations | string or list of strings | The suggested destinations Example: "destination1,destination2" or ["destination1", "destination2"] | ||
destination_airport | string | The destination airport. Make sure to use the IATA code of the airport | ||
country | string | The country based on the location the user intends to visit | ||
city | string | The city based on the location the user intends to visit | ||
region | string | This could be the state, district, or region of interest to the user | ||
neighborhood | string | The neighborhood the user is interested in | ||
departing_departure_date | string | The starting date and time for travel | ||
departing_arrival_date | string | The arrival date and time at the destination for the travel | ||
num_adults | integer | The number of adults staying | ||
origin_airport | string | The official IATA code of origin airport | ||
returning_departure_date | string | The starting date and time of the return journey | ||
returning_arrival_date | string | The date and time when the return journey is complete | ||
num_children | integer | The number of children staying | ||
hotel_score | string | This represents the hotels score relative to other hotels to an advertiser | ||
postal_code | string | The postal /zip code | ||
num_infants | integer | The number of infants staying | ||
preferred_neighborhoods | string or list of strings | Any preferred neighborhoods for the stay Example: "neighbor1,neighbor2" or ["neighbor1", "neighbor2"] | ||
preferred_star_ratings | string or list of strings | The 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_hotels | string or list of strings | The suggested hotels Example: "hotel1,hotel2" or ["hotel1", "hotel2"] | ||
destination_ids | string or list of strings | This is the id representative of the destination in the catalog Example: "destination1,destination2" or ["destination1", "destination2"] |
Server Parameters
Parameter | Datatype | Description | ||
---|---|---|---|---|
event_name (required) | string | Event 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) | integer | The 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) | string | The 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_id | string | This 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) | string | Where the event took place. Required for all web and app events. Use the appropriate value accordingly. WEB OFFLINE MOBILE_APP | ||
integration | string | There 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_options | list of string | Currently-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_enabled | bool | Set 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_code | string | Any string value. Exampe "datahash" |
LMU Parameters
Parameter | Data Type | Description | ||
---|---|---|---|---|
data_processing_options | list of strings | 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_enabled | bool | Set 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
Parameter | Data Type | Description | ||
---|---|---|---|---|
advertiser_tracking_enabled | bool | Set 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. | ||
extinfo | object | Required 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_id | string | The 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.
Index | Value | |||
---|---|---|---|---|
0 | Required extinfo version String Example: i2 | |||
1 | App package name String Example : com.snapchat.sdk | |||
2 | Short version String or int Example 1.0 | |||
3 | Long version long Example: 1.0 | |||
4 | Required OS version string Example: 10.3.1 | |||
5 | Device model name String Example: iphone14 | |||
6 | locale String Example: En_US | |||
7 | timezone abbreviation String Example: EDT | |||
8 | carrier String Example: AT&T | |||
9 | Screen width Int64 Example: 320 | |||
10 | Screen height Int64 Example: 568 | |||
11 | Screen density String Example: 2 | |||
12 | CPU cores Int64 Example: 2 | |||
13 | External storage size in GB Int64 Example: 15 | |||
14 | Free Space on external storage in GB Int64 Example: 8 | |||
15 | device timezone string Example: USA/New York |
Was this page helpful?