pixellint

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

Hosts
ads-api.twitter.com, ads-api.x.com
Paths
…/measurement/conversions/…
Vendor docs
docs.x.com/x-ads-api/measurement/web-conversions

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.missing
vendor.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.missing
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.empty
vendor.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.missing
vendor.x-conversions-api.http.method.empty
vendor.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.missing
vendor.x-conversions-api.http.content_type.empty
vendor.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.missing
vendor.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