X conversions check current event payload formats.
X web conversion batches, including the documented direct API and pinned official GTM sender. Alternative event and timestamp fields are supported per conversion. Sender-profile advice does not establish receiver acceptance.
Current GTM fields and authentication alternatives are supported. IP and user-agent-only identifiers receive advice because published sources differ on acceptance.
What this pack matches
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 |
|---|---|---|---|---|
pixel_id |
required | It is the X Pixel ID, and it travels in the path. Fix: Put the Pixel ID in the path as `/12/measurement/conversions/{pixel_id}`. | vendor.x-conversions-api.param.pixel_id.missingvendor.x-conversions-api.param.pixel_id.empty |
docs |
root |
optional | Native JSON type: object. | vendor.x-conversions-api.body.root.invalid |
docs |
conversions |
required | Native JSON type: array. | vendor.x-conversions-api.body.conversions.missingvendor.x-conversions-api.body.conversions.invalid |
docs |
conversion_time |
optional | X documents the conversion time as an ISO 8601 timestamp. Body scope: conversions[]. Fix: Send an ISO 8601 timestamp, such as `2022-02-18T01:14:00.603Z`. | vendor.x-conversions-api.body.conversion_time.emptyvendor.x-conversions-api.body.conversion_time.invalid |
docs |
event_id |
optional | It is the conversion event UUID from Ads Manager, not a per-hit dedup key. Body scope: conversions[]. Fix: Send the conversion event ID from Ads Manager as `event_id`. Use `conversion_id` for dedup. | vendor.x-conversions-api.body.event_id.empty |
docs |
conversion_id |
optional | It is the per-event id used to deduplicate the pixel and the conversion API. Body scope: conversions[]. Fix: Send the same `conversion_id` the website tag fired. | vendor.x-conversions-api.body.conversion_id.empty |
docs |
identifiers[].twclid |
optional | X click identifier from the landing URL. One of the identifiers X requires, along with hashed email or hashed phone. Body scope: conversions[]. Fix: Send the `twclid` query parameter captured from the click. | vendor.x-conversions-api.body.identifiers[].twclid.empty |
docs |
identifiers[].hashed_email |
optional | Email must be trimmed, lowercased, and SHA-256 hashed before it is sent. Body scope: conversions[]. Fix: Trim and lowercase the address, hash it with SHA-256, and send the hex digest. | vendor.x-conversions-api.body.identifiers[].hashed_email.emptyvendor.x-conversions-api.body.identifiers[].hashed_email.invalid |
docs |
identifiers[].hashed_phone_number |
optional | Phone must be normalized to E.164 and SHA-256 hashed before it is sent. Body scope: conversions[]. Fix: Normalize to E.164, hash with SHA-256, and send the hex digest. | vendor.x-conversions-api.body.identifiers[].hashed_phone_number.emptyvendor.x-conversions-api.body.identifiers[].hashed_phone_number.invalid |
docs |
identifiers[].ip_address |
optional | It is the visitor IP address, sent unhashed. X documents that IP or user agent must be paired with a second identifier. Body scope: conversions[]. Fix: Send the raw IP address, and also send `twclid`, `hashed_email`, or `hashed_phone_number`. | vendor.x-conversions-api.body.identifiers[].ip_address.empty |
docs |
identifiers[].user_agent |
optional | It is the visitor user agent, sent unhashed. Body scope: conversions[]. Fix: Send the browser's user agent string, not a digest. | vendor.x-conversions-api.body.identifiers[].user_agent.empty |
docs |
price_currency |
optional | It is an ISO 4217 currency code. Body scope: conversions[]. Fix: Use the three-letter code, such as `USD`. | vendor.x-conversions-api.body.price_currency.emptyvendor.x-conversions-api.body.price_currency.invalid |
docs |
value |
optional | The direct example uses a decimal string; the official sender emits native numbers, including signed and exponent values. No nonnegative-only restriction is inferred. Body scope: conversions[]. Fix: Send `value` as a decimal string, such as `20.00`. | vendor.x-conversions-api.body.value.emptyvendor.x-conversions-api.body.value.invalid |
docs |
number_items |
optional | It is the number of items in the conversion. X documents `number_items` on the conversion object. Body scope: conversions[]. Fix: Send `number_items` as an integer, such as `3`. | vendor.x-conversions-api.body.number_items.emptyvendor.x-conversions-api.body.number_items.invalid |
docs |
description |
optional | It is a short description of the conversion. X documents `description` on the conversion object. Body scope: conversions[]. Fix: Send `description`, or drop the empty pair. | vendor.x-conversions-api.body.description.empty |
docs |
contents[].content_id |
optional | It is the product id on a contents row. X documents `content_id` on each contents object. Body scope: conversions[]. Fix: Set `contents[].content_id` to the SKU or catalog id, or drop the empty pair. | vendor.x-conversions-api.body.contents[].content_id.empty |
docs |
contents[].content_name |
optional | It is the product name on a contents row. X documents `content_name` on each contents object. Body scope: conversions[]. Fix: Set `contents[].content_name` to the product name, or drop the empty pair. | vendor.x-conversions-api.body.contents[].content_name.empty |
docs |
contents[].content_type |
optional | It is the product category on a contents row. X documents `content_type` on each contents object. Body scope: conversions[]. Fix: Set `contents[].content_type` to the category, or drop the empty pair. | vendor.x-conversions-api.body.contents[].content_type.empty |
docs |
contents[].content_price |
optional | The direct example uses a decimal string; the official sender emits native numbers, including signed and exponent values. No nonnegative-only restriction is inferred. Body scope: conversions[]. Fix: Send `contents[].content_price` as a number, such as `100.99`. Put the order total in `value`. | vendor.x-conversions-api.body.contents[].content_price.emptyvendor.x-conversions-api.body.contents[].content_price.invalid |
docs |
contents[].num_items |
optional | It is the quantity of that product. X documents `num_items` on each contents object. Body scope: conversions[]. Fix: Send `contents[].num_items` as an integer, such as `1`. | vendor.x-conversions-api.body.contents[].num_items.emptyvendor.x-conversions-api.body.contents[].num_items.invalid |
docs |
contents[].content_group_id |
optional | It is the product group id on a contents row. X documents `content_group_id` on each contents object. Body scope: conversions[]. Fix: Set `contents[].content_group_id`, or drop the empty pair. | vendor.x-conversions-api.body.contents[].content_group_id.empty |
docs |
root |
optional | Each conversions entry is an object. Body scope: conversions[]. Native JSON type: object. | vendor.x-conversions-api.body.root.invalid |
docs |
conversion_timestamp |
optional | The pinned official sender emits a native millisecond timestamp. No receiver age bound is inferred. Body scope: conversions[]. Presence diagnostic severity: warning. Native JSON type: integer. | vendor.x-conversions-api.body.conversion_timestamp.invalid |
docs |
event_name |
optional | The official sender uses gtm_ plus the incoming name when Event ID is unset. The event vocabulary stays open. Body scope: conversions[]. Presence diagnostic severity: warning. Native JSON type: string. | vendor.x-conversions-api.body.event_name.invalid |
docs |
event_source_url |
optional | The official sender forwards page_location as event_source_url. No URL-only rejection policy is inferred from this forwarded value. Body scope: conversions[]. Presence diagnostic severity: warning. Native JSON type: string. | vendor.x-conversions-api.body.event_source_url.invalid |
docs |
identifiers |
optional | Identity entries use an array in the direct API and the official sender. Body scope: conversions[]. Native JSON type: array. | vendor.x-conversions-api.body.identifiers.invalid |
docs |
identifiers[] |
optional | Each identifier entry is an object. Multiple fields may share an entry. Body scope: conversions[]. Native JSON type: object. | vendor.x-conversions-api.body.identifiers[].invalid |
docs |
identifiers[].twpid |
optional | The official sender forwards the first-party _twpid cookie unhashed. Cookie authenticity is external. Body scope: conversions[]. Presence diagnostic severity: warning. Native JSON type: string. | vendor.x-conversions-api.body.identifiers[].twpid.invalid |
docs |
contents |
optional | Optional product contents use an array. Body scope: conversions[]. Native JSON type: array. | vendor.x-conversions-api.body.contents.invalid |
docs |
contents[] |
optional | Each optional product entry is an object. Empty objects and future fields remain open. Body scope: conversions[]. Native JSON type: object. | vendor.x-conversions-api.body.contents[].invalid |
docs |
body.identifier_required |
required | The conversion has no click ID, Pixel cookie, hashed email or hashed phone. The direct guide and GTM guide differ on IP plus user-agent-only matching; that pair receives separate advice. Body scope: conversions[]. Fix: Add a `twclid`, a SHA-256 hashed email, or a SHA-256 hashed phone number. | vendor.x-conversions-api.body.identifier_required |
docs |
body.unhashed_email |
required | A field carries what looks like a raw email address. X requires email as `hashed_email`, SHA-256 hashed on the client side. Body scope: conversions[]. Fix: Trim the address, lowercase it, hash it with SHA-256, and send it as `hashed_email`. | vendor.x-conversions-api.body.unhashed_email |
docs |
body.hashed_plaintext_field |
required | This field looks like a SHA-256 digest, but X documents `ip_address` and `user_agent` as unhashed. Body scope: conversions[]. Fix: Send the raw IP address or user agent. Hashing it makes the event unmatchable. | vendor.x-conversions-api.body.hashed_plaintext_field |
docs |
body.ip_user_agent_only |
recommended | Only IP and user agent are supplied. The direct guide allows this pair but the GTM guide recommends a strong identifier; matching cannot be established locally. Body scope: conversions[]. | vendor.x-conversions-api.body.ip_user_agent_only |
docs |
conversion_time |
required | A legacy conversion needs conversion_time when the official sender timestamp is absent. Body scope: conversions[]. Applies when {"kind":"not","condition":{"kind":"exists","param":"conversion_timestamp"}}. | vendor.x-conversions-api.body.conversion_time.missing |
docs |
conversion_timestamp |
optional | Body scope: conversions[]. | docs | |
event_id |
required | A conversion needs event_id when the official sender event_name is absent. Body scope: conversions[]. Applies when {"kind":"not","condition":{"kind":"exists","param":"event_name"}}. | vendor.x-conversions-api.body.event_id.missing |
docs |
event_name |
optional | Body scope: conversions[]. | docs | |
conversion_time |
optional | Body scope: conversions[]. Presence diagnostic severity: warning. Native JSON type: string. | vendor.x-conversions-api.body.conversion_time.invalid |
docs |
event_id |
optional | Body scope: conversions[]. Presence diagnostic severity: warning. Native JSON type: string. | vendor.x-conversions-api.body.event_id.invalid |
docs |
body.conversion_time.calendar |
recommended | Check the conversion timestamp calendar, time and timezone. Prefix matching alone does not establish a valid timestamp. Body scope: conversions[]. | vendor.x-conversions-api.body.conversion_time.calendar |
docs |
path |
optional | Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. Native JSON type: string. | vendor.x-conversions-api.http.path.invalid |
docs |
method |
required | Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. | vendor.x-conversions-api.http.method.missingvendor.x-conversions-api.http.method.emptyvendor.x-conversions-api.http.method.invalid |
docs |
content_type |
recommended | Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. Presence diagnostic severity: warning. | vendor.x-conversions-api.http.content_type.missingvendor.x-conversions-api.http.content_type.emptyvendor.x-conversions-api.http.content_type.invalid |
docs |
body |
required | Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. Native JSON type: object. | vendor.x-conversions-api.http.body.missingvendor.x-conversions-api.http.body.invalid |
docs |
headers.authorization |
optional | Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. Native JSON type: string. | vendor.x-conversions-api.http.headers.authorization.invalid |
docs |
headers.x-pixel-token |
optional | Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. Native JSON type: string. | vendor.x-conversions-api.http.headers.x-pixel-token.invalid |
docs |
http.authentication |
recommended | Supply the direct API authorization header or the official GTM X-Pixel-Token. Header presence does not prove credential validity. Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/[0-9]+/measurement/conversions/[^/]+$"}. | vendor.x-conversions-api.http.authentication |
docs |
Validate a payload
pixellint validate request @request.json --rulepack vendor/x-conversions-api
Try this failing payload in the playground. An example with a validation finding.
{
"url": "https://ads-api.x.com/12/measurement/conversions/synthetic-pixel",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"X-Pixel-Token": "synthetic-token"
},
"body": "{\"conversions\":{}}"
}
cargo install pixellint
·
npm install pixellint