vendor/branch · vendor documented

Branch Events API payloads

Standard and custom events on api2.branch.io. The pack contracts the event payload Branch documents, not the deep-link redirect. Currency is a three-letter code when present. DMA consent fields are required when dma_eea is true. IP and user agent stay unhashed.

dma_eea true needs the two consent flags

Branch documents dma_ad_personalization and dma_ad_user_data as required when European regulations apply. Sending only dma_eea is not enough.

Rule: vendor.branch.body.dma_consent_required

What this pack matches

Hosts: api2.branch.io
Paths: …/v2/event/standard…, …/v2/event/custom…
Vendor docs: help.branch.io/developers-hub/reference/events-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
`branch_key`	required	It is the Branch Key for the application, and the Events API requires it. Fix: Send the Branch Key from Account settings or Configuration, Security and Access.	`vendor.branch.body.branch_key.missing` `vendor.branch.body.branch_key.empty`	docs
`name`	required	It is the event name. On `/v2/event/standard` it must be a documented Branch standard event; `/v2/event/custom` accepts any name. Fix: Set `name` to a standard event such as `PURCHASE`, or post a custom name to `/v2/event/custom`.	`vendor.branch.body.name.missing` `vendor.branch.body.name.empty`	docs
`user_data`	required	Branch requires a `user_data` object with device and identity fields. Fix: Add `user_data` with at least one documented identifier.	`vendor.branch.body.user_data.missing`	docs
`user_data.ip`	optional	It is the device IP address where the event occurred, sent unhashed. Fix: Send the device IP, not a digest.	`vendor.branch.body.user_data.ip.empty`	docs
`user_data.developer_identity`	optional	Developer-specified identity for the user. Branch requires at least one documented identifier in `user_data`.	`vendor.branch.body.user_data.developer_identity.empty`	docs
`user_data.browser_fingerprint_id`	optional	Branch browser fingerprint. One of the identifiers that can satisfy the identity requirement.	`vendor.branch.body.user_data.browser_fingerprint_id.empty`	docs
`user_data.idfa`	optional	iOS advertising ID. Branch requires it together with `os=iOS` when it is the identifier in use.	`vendor.branch.body.user_data.idfa.empty`	docs
`user_data.idfv`	optional	iOS vendor ID. Branch requires it together with `os=iOS` when it is the identifier in use.	`vendor.branch.body.user_data.idfv.empty`	docs
`user_data.android_id`	optional	Android hardware ID. Branch requires it together with `os=Android` when it is the identifier in use.	`vendor.branch.body.user_data.android_id.empty`	docs
`user_data.aaid`	optional	Android advertising ID. Branch requires it together with `os=Android` when it is the identifier in use.	`vendor.branch.body.user_data.aaid.empty`	docs
`user_data.user_agent`	optional	It is the user agent of the browser or app where the event occurred, sent unhashed.	`vendor.branch.body.user_data.user_agent.empty`	docs
`user_data.country`	optional	It is the user's country code, usually from device settings. Branch's Events API sample is a two-letter code such as `US`. Fix: Send a two-letter country code such as `US`.	`vendor.branch.body.user_data.country.empty` `vendor.branch.body.user_data.country.invalid`	docs
`user_data.limit_ad_tracking`	optional	It is whether the partner opted out of advertiser tracking. Branch documents a boolean. Fix: Send `true` or `false` in `user_data.limit_ad_tracking`.	`vendor.branch.body.user_data.limit_ad_tracking.empty` `vendor.branch.body.user_data.limit_ad_tracking.invalid`	docs
`user_data.advertising_ids.oaid`	optional	It is the OAID inside `advertising_ids`. Branch documents a UUID for non-standard IDs such as Huawei OAID. Fix: Send `user_data.advertising_ids.oaid` as a UUID.	`vendor.branch.body.user_data.advertising_ids.oaid.empty` `vendor.branch.body.user_data.advertising_ids.oaid.invalid`	docs
`user_data.dma_eea`	optional	Whether European regulations, including the DMA, apply to this user. Branch documents it as a boolean. Fix: Send `true` or `false` in `user_data.dma_eea`.	`vendor.branch.body.user_data.dma_eea.empty` `vendor.branch.body.user_data.dma_eea.invalid`	docs
`user_data.dma_ad_personalization`	optional	Whether the user granted ads personalization consent. Branch documents it as a boolean, required when `dma_eea` is true. Fix: Send `true` or `false` in `user_data.dma_ad_personalization`.	`vendor.branch.body.user_data.dma_ad_personalization.empty` `vendor.branch.body.user_data.dma_ad_personalization.invalid`	docs
`user_data.dma_ad_user_data`	optional	Whether the user granted consent for third-party transmission of user-level ads data. Branch documents it as a boolean, required when `dma_eea` is true. Fix: Send `true` or `false` in `user_data.dma_ad_user_data`.	`vendor.branch.body.user_data.dma_ad_user_data.empty` `vendor.branch.body.user_data.dma_ad_user_data.invalid`	docs
`event_data.currency`	optional	It is the ISO 4217 currency that revenue, price, shipping, and tax were reported in. Fix: Use a three-letter code such as `USD`.	`vendor.branch.body.event_data.currency.empty` `vendor.branch.body.event_data.currency.invalid`	docs
`event_data.revenue`	optional	It is the reported revenue for the event. Branch documents a number. Fix: Send a number such as `129.99`, with no currency symbol.	`vendor.branch.body.event_data.revenue.empty` `vendor.branch.body.event_data.revenue.invalid`	docs
`event_data.shipping`	optional	It is the shipping cost for the transaction. Branch documents a number. Fix: Send a number such as `10.5`, with no currency symbol.	`vendor.branch.body.event_data.shipping.empty` `vendor.branch.body.event_data.shipping.invalid`	docs
`event_data.tax`	optional	It is the total tax for the transaction. Branch documents a number. Fix: Send a number such as `13.5`, with no currency symbol.	`vendor.branch.body.event_data.tax.empty` `vendor.branch.body.event_data.tax.invalid`	docs
`content_items[].$content_schema`	optional	It is the content schema on a `content_items` row. Branch documents a closed set of COMMERCE, GAME, MEDIA, TEXT, and OTHER values. Fix: Set `content_items[].$content_schema` to a documented value such as `COMMERCE_PRODUCT`.	`vendor.branch.body.content_items[].$content_schema.empty` `vendor.branch.body.content_items[].$content_schema.invalid`	docs
`content_items[].$og_image_url`	optional	It is the image URL for the content item. Branch documents `$og_image_url` as a URL. Fix: Send an absolute image URL in `content_items[].$og_image_url`, or omit the field.	`vendor.branch.body.content_items[].$og_image_url.empty` `vendor.branch.body.content_items[].$og_image_url.invalid`	docs
`content_items[].$condition`	optional	It is the product condition on a `content_items` row, used for auctions. Branch documents a closed set. Fix: Set `content_items[].$condition` to `NEW`, `USED`, `REFURBISHED`, or another documented value.	`vendor.branch.body.content_items[].$condition.empty` `vendor.branch.body.content_items[].$condition.invalid`	docs
`body.user_needs_an_identifier`	required	`user_data` carries none of the identifiers Branch requires. At least one of `developer_identity`, `browser_fingerprint_id`, `idfa`, `idfv`, `android_id`, or `aaid` must be present. Fix: Send `user_data.developer_identity`, or a platform advertising ID such as `idfa` or `aaid`.	`vendor.branch.body.user_needs_an_identifier`	docs
`body.hashed_plaintext_field`	required	This field looks like a SHA-256 digest, but Branch documents `user_data.ip` and `user_data.user_agent` as unhashed. Fix: Send the raw IP address or user agent.	`vendor.branch.body.hashed_plaintext_field`	docs
`body.dma_consent_required`	required	`dma_eea` is true, but the event is missing `dma_ad_personalization` or `dma_ad_user_data`. Branch documents both consent signals when EU regulations apply. Fix: Send `user_data.dma_ad_personalization` and `user_data.dma_ad_user_data` as booleans.	`vendor.branch.body.dma_consent_required`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/branch

Try this failing payload in the playground. Branch event with a hashed user agent.

{"branch_key":"key_live_example","name":"PURCHASE","user_data":{"developer_identity":"user-10492","user_agent":"a85e9ca18f34935ab9b0381b25bfad2455444112b0149270fd88e3da172fe196"}}

cargo install pixellint · npm install pixellint