Supported Keys for Pinterest API for Conversions

See what events and data can be passed to Pinterest API for Conversions once the integration has been set up. Use API Reference page to fill out the required and recommended data parameter fields and see how your payload should be structured.

🚧
The list of supported keys is in this article is subject to change. For the most up-to-date list of supported keys, see Pinterest’s documentation.

Event Keys

Property	Description
`event_name` string Required	The type of the user event. Please use the right event_name otherwise the event won’t be accepted and show up correctly in reports. - `add_to_cart` - `checkout` - `custom` - `lead` - `page_visit` - `search` - `signup` - `view_category` - `watch_video`
`event_id` string Required	A unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking. Without this, event's data is likely to be double counted and will cause report metric inflation. Third-party vendors make sure this field is updated on both Pinterest tag and Conversions API side before rolling out template for Conversions API.
`event_time` string Required	The time when the event happened. Unix timestamp in seconds.
`event_source_url` string Required	URL of the web conversion event.
`user_data` {} Required	See list of user data keys.
`custom_data` {}	See list of custom data keys.
`app_id` string	The app store app ID.
`app_name` string	Name of the app.
`app_version` string	Version of the app.
`device_brand` string	Brand of the user device.
`device_carrier` string	User device's mobile carrier.
`device_model` string	Model of the user device.
`device_type` string	Type of the user device.
`os_version` string	Version of the device operating system.
`wifi` boolean	Whether the event occurred when the user device was connected to wifi.
`language` string	Two-character ISO-639-1 language code indicating the user's language.

User Data Keys

Property	Description	Example
`partner_id` string Required	ATS Envelope value.	`'BVOBHAIrEaLRRbGFusikzEyEOEGKVZ0kNPCgRDSoujeTtkmK2OQEGwW7F1lkkQebcPAgAKK58m5A35'`
`ct` array of strings	Plaintext or sha256 hashes of user's city, in lowercase, and without spaces or punctuation. User residency city (mostly billing).	`'london'`
`st` array of strings	Plaintext or sha256 hashes of user's state, given as a two-letter code in lowercase. User residency state (mostly billing).	`'ca'`
`country` array of strings	Plaintext or SHA-256 hashes of two-character ISO-3166 country code indicating the user's country.	`'US'`
`click_id` string	The unique identifier stored in `\_epik` cookie on your domain or `&epik=` query parameter in the URL. We highly recommend this on at least checkout events. It may improve reporting performance such as ROAS/CPA.

Custom Data Keys

You can send additional data by passing the parameters below under custom_data.

Property	Description	Example
`currency` string	The ISO-4217 currency code. If not provided, we will default to the advertiser's currency set during account creation. Your campaign performance needs this field to report right ROAS/CPA. Required when using `checkout` events	`'USD'`
`value` string	Total value of the event. Accepted as a string in the request; it will be parsed into a double. For example, if there are two items in a checkout event, the value should be the total price. We recommend to use pre-tax, pre-shipping final value. Required when using `checkout` events	`'142.54'`
`content_ids` array of strings	List of products IDs. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For more details, see "Install the Pinterest tag" section here.	`['ABC123', XYZ789']`
`content_name` string	The name of the page or product associated with the event.	'`lettuce'`
`content_category` string	The category of the content associated with the event.	`'grocery'`
`content_brand` string	The brand of the content associated with the event.	`'brand'`
`contents` array of objects	A list of objects containing information about products, such as price and quantity. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For more details, see "Install the Pinterest tag" section here. Supported objects are: - `id` - string The id of a product. Example: `'red-pinterest-shirt-logo-1'` - `item_price` - string The price of a product. Accepted as a string in the request; it will be parsed into a double. This is the original item value before any discount. Example: `'1325.12'` - `quantity` - integer The amount of a product Example: `5`	`[]`
`num_items` integer	Total number of products of the event. For example, the total number of items purchased in a checkout event. We recommend using this if you are a merchant for AddToCart and Checkouts. For more details, see "Install the Pinterest tag" section here.	`2`
`order_id` string	The order ID. We recommend sending order_id to help us deduplicate events when necessary. This also helps to run other measurement products at Pinterest.	`'order1234'`
`search_string` string	The search string related to the user conversion event.	`'lettuce'`