vendor/pinterest-conversions-api · vendor documented

Pinterest CAPI events need seconds and event_id

conversions API Pinterest is Pinterest CAPI. The ad account ID lives in the path. The event payload is contracted as Pinterest documents it.

conversions API Pinterest

conversions API Pinterest is Pinterest CAPI. Seconds clock, event_id required, action_source web. Pinterest standard events stay lowercase on both pipes.

What this pack matches

Hosts: api.pinterest.com
Paths: …/ad_accounts/…, …/events…
Vendor docs: developers.pinterest.com/docs/track-conversions/track-conversions-in-the-api/

Rules

Codes are stable. A finding in CI, MCP, or the playground lands on the same id.

Field	Required	What it checks	Rule ids	Source
`ad_account_id`	required	It is the Pinterest ad account ID, and it travels in the path. Fix: Put the ad account ID in the path as `/v5/ad_accounts/{ad_account_id}/events`.	`vendor.pinterest-conversions-api.param.ad_account_id.missing` `vendor.pinterest-conversions-api.param.ad_account_id.empty`	docs
`event_name`	required	It is the conversion event name. Pinterest documents a set of standard names and also allows a custom name of up to 100 characters. Fix: Send a documented name such as `checkout`, or a custom name mapped to a standard event in Ads Manager.	`vendor.pinterest-conversions-api.body.event_name.missing` `vendor.pinterest-conversions-api.body.event_name.empty`	docs
`action_source`	required	It is the platform the event was ingested from. Pinterest documents `web`, `app_android`, `app_ios`, and `offline`. Fix: Send `web`, `app_android`, `app_ios`, or `offline`. Pinterest spells `web` in lower case, unlike Snap.	`vendor.pinterest-conversions-api.body.action_source.missing` `vendor.pinterest-conversions-api.body.action_source.empty` `vendor.pinterest-conversions-api.body.action_source.invalid`	docs
`event_id`	required	It identifies the event for deduplication against the Pinterest tag. Fix: Send a stable id per conversion, such as an order number.	`vendor.pinterest-conversions-api.body.event_id.missing` `vendor.pinterest-conversions-api.body.event_id.empty`	docs
`event_time`	required	Pinterest documents a Unix timestamp in seconds. A 13-digit value is milliseconds. Fix: Send seconds, not milliseconds: divide a JavaScript `Date.now()` by 1000 and floor it.	`vendor.pinterest-conversions-api.body.event_time.missing` `vendor.pinterest-conversions-api.body.event_time.empty` `vendor.pinterest-conversions-api.body.event_time.invalid`	docs
`user_data`	required	Pinterest requires a `user_data` object, and it must include at least one of `em`, `hashed_maids`, or an IP and user agent pair. Fix: Add `user_data` with a hashed email, hashed MAIDs, or `client_ip_address` and `client_user_agent`.	`vendor.pinterest-conversions-api.body.user_data.missing`	docs
`user_data.em`	optional	Email must be lowercased and SHA-256 hashed before it is sent. Fix: Lowercase the address, hash it with SHA-256, and send the hex digest.	`vendor.pinterest-conversions-api.body.user_data.em.empty` `vendor.pinterest-conversions-api.body.user_data.em.invalid`	docs
`user_data.em[]`	optional	Every email in the list must be lowercased and SHA-256 hashed. Fix: Hash each address with SHA-256 and send the hex digest.	`vendor.pinterest-conversions-api.body.user_data.em[].empty` `vendor.pinterest-conversions-api.body.user_data.em[].invalid`	docs
`user_data.ph`	optional	Phone must be digits-only with country code, then SHA-256 hashed. Fix: Strip symbols, keep the country code, hash with SHA-256, and send the hex digest.	`vendor.pinterest-conversions-api.body.user_data.ph.empty` `vendor.pinterest-conversions-api.body.user_data.ph.invalid`	docs
`user_data.external_id`	optional	External IDs must be SHA-256 hashed. Fix: Hash the customer id with SHA-256 and send the hex digest.	`vendor.pinterest-conversions-api.body.user_data.external_id.empty` `vendor.pinterest-conversions-api.body.user_data.external_id.invalid`	docs
`user_data.client_ip_address`	optional	It is the visitor IP address, sent unhashed. Fix: Send the browser's public IP, not a digest.	`vendor.pinterest-conversions-api.body.user_data.client_ip_address.empty`	docs
`user_data.client_user_agent`	optional	It is the visitor user agent, sent unhashed. Fix: Send the browser's user agent string, not a digest.	`vendor.pinterest-conversions-api.body.user_data.client_user_agent.empty`	docs
`user_data.hashed_maids`	optional	Hashed GAID or IDFA. Pinterest documents SHA-256. Fix: Hash the MAID with SHA-256 and send the hex digest.	`vendor.pinterest-conversions-api.body.user_data.hashed_maids.empty` `vendor.pinterest-conversions-api.body.user_data.hashed_maids.invalid`	docs
`user_data.hashed_maids[]`	optional	Every MAID in the list must be SHA-256 hashed. Fix: Hash each MAID with SHA-256 and send the hex digest.	`vendor.pinterest-conversions-api.body.user_data.hashed_maids[].empty` `vendor.pinterest-conversions-api.body.user_data.hashed_maids[].invalid`	docs
`custom_data.currency`	optional	It is an ISO 4217 currency code. Fix: Use the three-letter code, such as `USD`.	`vendor.pinterest-conversions-api.body.custom_data.currency.empty` `vendor.pinterest-conversions-api.body.custom_data.currency.invalid`	docs
`custom_data.value`	optional	It is the total monetary value of purchased items. Pinterest documents a string parsed as a double, with no negatives, and currency whenever it is sent. Fix: Send the pre-tax, pre-shipping total in `custom_data.value` as a number, such as `66.95`.	`vendor.pinterest-conversions-api.body.custom_data.value.empty` `vendor.pinterest-conversions-api.body.custom_data.value.invalid`	docs
`custom_data.content_ids`	optional	It is a product ID related to the event. Pinterest documents an array of IDs that also appear on `custom_data.contents`. Fix: Send catalog IDs in `custom_data.content_ids`, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.content_ids.empty`	docs
`custom_data.content_ids[]`	optional	Every listed ID is a product ID related to the event. Fix: Send catalog IDs in `custom_data.content_ids`, or drop empty entries.	`vendor.pinterest-conversions-api.body.custom_data.content_ids[].empty`	docs
`custom_data.content_name`	optional	It is the name of the page or product associated with the event. Fix: Send the page or product name in `custom_data.content_name`, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.content_name.empty`	docs
`custom_data.content_category`	optional	It is the type of merchandise. Pinterest documents `content_category` on the product event table. Fix: Send the merchandise type in `custom_data.content_category`, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.content_category.empty`	docs
`custom_data.content_brand`	optional	It is the brand of merchandise. Pinterest documents `content_brand` on the product event table. Fix: Send the brand in `custom_data.content_brand`, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.content_brand.empty`	docs
`custom_data.num_items`	optional	It is the total number of products involved, for example items purchased in a checkout. Fix: Send a whole number in `custom_data.num_items`, such as `2`.	`vendor.pinterest-conversions-api.body.custom_data.num_items.empty` `vendor.pinterest-conversions-api.body.custom_data.num_items.invalid`	docs
`custom_data.order_id`	optional	It identifies the order in a purchase-related event. Fix: Send the order id in `custom_data.order_id`, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.order_id.empty`	docs
`custom_data.search_string`	optional	It is the string entered in a search event. Fix: Send the query in `custom_data.search_string`, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.search_string.empty`	docs
`custom_data.opt_out_type`	optional	It is the privacy opt-out type. Pinterest documents `ldp` as the only accepted value for limited data processing. Fix: Set `custom_data.opt_out_type` to `ldp`, or drop the pair.	`vendor.pinterest-conversions-api.body.custom_data.opt_out_type.empty` `vendor.pinterest-conversions-api.body.custom_data.opt_out_type.invalid`	docs
`custom_data.contents[].id`	optional	It is the product ID of an individual merchandise item. Fix: Set `custom_data.contents[].id` to the catalog item ID, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.contents[].id.empty`	docs
`custom_data.contents[].item_name`	optional	It is the product name of an individual merchandise item. Fix: Set `custom_data.contents[].item_name` to the product name, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.contents[].item_name.empty`	docs
`custom_data.contents[].item_category`	optional	It is the product category of an individual merchandise item. Fix: Set `custom_data.contents[].item_category` to the category, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.contents[].item_category.empty`	docs
`custom_data.contents[].item_brand`	optional	It is the brand of an individual merchandise item. Fix: Set `custom_data.contents[].item_brand` to the brand, or drop the empty pair.	`vendor.pinterest-conversions-api.body.custom_data.contents[].item_brand.empty`	docs
`custom_data.contents[].item_price`	optional	It is the price of one merchandise item (single quantity). Pinterest documents it as a string parsed as a number. Fix: Send `custom_data.contents[].item_price` as a number, such as `19.99`. Put the order total in `custom_data.value`.	`vendor.pinterest-conversions-api.body.custom_data.contents[].item_price.empty` `vendor.pinterest-conversions-api.body.custom_data.contents[].item_price.invalid`	docs
`custom_data.contents[].quantity`	optional	It is the quantity of that merchandise item selected by the user. Fix: Send a whole number in `custom_data.contents[].quantity`, such as `2`.	`vendor.pinterest-conversions-api.body.custom_data.contents[].quantity.empty` `vendor.pinterest-conversions-api.body.custom_data.contents[].quantity.invalid`	docs
`body.checkout_requires_value_and_currency`	recommended	A `checkout` event is missing `custom_data.value` or `custom_data.currency`. Pinterest documents both as recommended for checkout. Fix: Send the checkout total and a three-letter currency code.	`vendor.pinterest-conversions-api.body.checkout_requires_value_and_currency`	docs
`body.value_requires_currency`	recommended	The event carries `custom_data.value` with no `custom_data.currency`. Pinterest documents currency as required whenever value is sent. Fix: Add `custom_data.currency` as a three-letter code alongside the value.	`vendor.pinterest-conversions-api.body.value_requires_currency`	docs
`body.user_needs_an_identifier`	required	`user_data` carries none of the identifiers Pinterest requires. Send `em`, `hashed_maids`, or `client_ip_address` with `client_user_agent`. Fix: Add a hashed email, hashed MAIDs, or the IP and user agent pair.	`vendor.pinterest-conversions-api.body.user_needs_an_identifier`	docs
`body.unhashed_email`	required	A field carries what looks like a raw email address. Pinterest requires `user_data.em` to be a SHA-256 hex digest. Fix: Lowercase the address, hash it with SHA-256, and send the hex digest.	`vendor.pinterest-conversions-api.body.unhashed_email`	docs
`body.hashed_plaintext_field`	required	This field looks like a SHA-256 digest, but Pinterest documents `client_ip_address` and `client_user_agent` as unhashed. Fix: Send the raw IP address or user agent. Hashing it makes the event unmatchable.	`vendor.pinterest-conversions-api.body.hashed_plaintext_field`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/pinterest-conversions-api

Try this failing payload in the playground. Pinterest CAPI missing event_id.

{"data":[{"event_name":"checkout","action_source":"web","event_time":1770000000,"event_source_url":"https://shop.example/thanks","user_data":{}}]}

cargo install pixellint · npm install pixellint