pixellint

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, api.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. Native JSON type: string. 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
vendor.branch.body.branch_key.invalid
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. Native JSON type: string. 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
vendor.branch.body.name.invalid
docs
user_data required Branch requires a `user_data` object with device and identity fields. Native JSON type: object. Fix: Add `user_data` with at least one documented identifier. vendor.branch.body.user_data.missing
vendor.branch.body.user_data.invalid
docs
user_data.ip optional It is the device IP address where the event occurred, sent unhashed. Native JSON type: string. Fix: Send the device IP, not a digest. vendor.branch.body.user_data.ip.empty
vendor.branch.body.user_data.ip.invalid
docs
user_data.developer_identity optional Developer-specified identity for the user. Branch requires at least one documented identifier in `user_data`. Native JSON type: string. vendor.branch.body.user_data.developer_identity.empty
vendor.branch.body.user_data.developer_identity.invalid
docs
user_data.browser_fingerprint_id optional Branch browser fingerprint. One of the identifiers that can satisfy the identity requirement. Native JSON type: string. vendor.branch.body.user_data.browser_fingerprint_id.empty
vendor.branch.body.user_data.browser_fingerprint_id.invalid
docs
user_data.idfa optional iOS advertising ID. Branch requires it together with `os=iOS` when it is the identifier in use. Native JSON type: string. vendor.branch.body.user_data.idfa.empty
vendor.branch.body.user_data.idfa.invalid
docs
user_data.idfv optional iOS vendor ID. Branch requires it together with `os=iOS` when it is the identifier in use. Native JSON type: string. vendor.branch.body.user_data.idfv.empty
vendor.branch.body.user_data.idfv.invalid
docs
user_data.android_id optional Android hardware ID. Branch requires it together with `os=Android` when it is the identifier in use. Native JSON type: string. vendor.branch.body.user_data.android_id.empty
vendor.branch.body.user_data.android_id.invalid
docs
user_data.aaid optional Android advertising ID. Branch requires it together with `os=Android` when it is the identifier in use. Native JSON type: string. vendor.branch.body.user_data.aaid.empty
vendor.branch.body.user_data.aaid.invalid
docs
user_data.user_agent optional It is the user agent of the browser or app where the event occurred, sent unhashed. Native JSON type: string. vendor.branch.body.user_data.user_agent.empty
vendor.branch.body.user_data.user_agent.invalid
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. Native JSON type: 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. Native JSON type: string. 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. Native JSON type: 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. Native JSON type: boolean. 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. Native JSON type: boolean. 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. Native JSON type: number. Fix: Send a number such as `129.99`, with no currency symbol. vendor.branch.body.event_data.revenue.invalid docs
event_data.shipping optional It is the shipping cost for the transaction. Branch documents a number. Native JSON type: number. Fix: Send a number such as `10.5`, with no currency symbol. vendor.branch.body.event_data.shipping.invalid docs
event_data.tax optional It is the total tax for the transaction. Branch documents a number. Native JSON type: number. Fix: Send a number such as `13.5`, with no currency symbol. 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. Native JSON type: string. 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. Native JSON type: string. 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. Native JSON type: string. 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
root optional Each event is a JSON object, rather than a scalar or list. Native JSON type: object. vendor.branch.body.root.invalid docs
event_data optional The vendor documents the JSON shape or value type of this field. Native JSON type: object. vendor.branch.body.event_data.invalid docs
custom_data optional The vendor documents the JSON shape or value type of this field. Native JSON type: object. vendor.branch.body.custom_data.invalid docs
user_data.advertising_ids optional The vendor documents the JSON shape or value type of this field. Native JSON type: object. vendor.branch.body.user_data.advertising_ids.invalid docs
content_items optional The vendor documents the JSON shape or value type of this field. Native JSON type: array. vendor.branch.body.content_items.invalid docs
content_items[] optional The vendor documents the JSON shape or value type of this field. Native JSON type: object. vendor.branch.body.content_items[].invalid docs
customer_event_alias optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.customer_event_alias.invalid docs
user_data.os optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.os.invalid docs
user_data.os_version optional Branch's parameter table calls this a string. The published commerce example sends the Android API level as a number, so a string or a number is accepted. Native JSON type: string or number. vendor.branch.body.user_data.os_version.invalid docs
user_data.language optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.language.invalid docs
user_data.local_ip optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.local_ip.empty
vendor.branch.body.user_data.local_ip.invalid
docs
user_data.brand optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.brand.invalid docs
user_data.app_version optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.app_version.invalid docs
user_data.model optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.model.invalid docs
user_data.environment optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.environment.invalid docs
user_data.google_analytics_id optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.user_data.google_analytics_id.invalid docs
event_data.transaction_id optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.event_data.transaction_id.invalid docs
event_data.coupon optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.event_data.coupon.invalid docs
event_data.affiliation optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.event_data.affiliation.invalid docs
event_data.description optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.event_data.description.invalid docs
event_data.search_query optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.event_data.search_query.invalid docs
user_data.screen_dpi optional The vendor documents the JSON shape or value type of this field. Native JSON type: integer. vendor.branch.body.user_data.screen_dpi.invalid docs
user_data.screen_height optional The vendor documents the JSON shape or value type of this field. Native JSON type: integer. vendor.branch.body.user_data.screen_height.invalid docs
user_data.screen_width optional The vendor documents the JSON shape or value type of this field. Native JSON type: integer. vendor.branch.body.user_data.screen_width.invalid docs
content_items[].$publicly_indexable optional The vendor documents the JSON shape or value type of this field. Native JSON type: boolean. vendor.branch.body.content_items[].$publicly_indexable.invalid docs
content_items[].$locally_indexable optional The vendor documents the JSON shape or value type of this field. Native JSON type: boolean. vendor.branch.body.content_items[].$locally_indexable.invalid docs
content_items[].$rating_average optional The vendor documents the JSON shape or value type of this field. Native JSON type: number. vendor.branch.body.content_items[].$rating_average.invalid docs
content_items[].$rating_count optional The vendor documents the JSON shape or value type of this field. Native JSON type: number. vendor.branch.body.content_items[].$rating_count.invalid docs
content_items[].$rating_max optional The vendor documents the JSON shape or value type of this field. Native JSON type: number. vendor.branch.body.content_items[].$rating_max.invalid docs
content_items[].$latitude optional The vendor documents the JSON shape or value type of this field. Native JSON type: number. vendor.branch.body.content_items[].$latitude.invalid docs
content_items[].$longitude optional The vendor documents the JSON shape or value type of this field. Native JSON type: number. vendor.branch.body.content_items[].$longitude.invalid docs
content_items[].$creation_timestamp optional The vendor documents the JSON shape or value type of this field. Native JSON type: integer. vendor.branch.body.content_items[].$creation_timestamp.invalid docs
content_items[].$exp_date optional The vendor documents the JSON shape or value type of this field. Native JSON type: integer or null. vendor.branch.body.content_items[].$exp_date.invalid docs
content_items[].$og_title optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$og_title.invalid docs
content_items[].$canonical_identifier optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$canonical_identifier.invalid docs
content_items[].$price optional The content item table and official example document this property. Native JSON type: string or number. vendor.branch.body.content_items[].$price.invalid docs
content_items[].$quantity optional The content item table and official example document this property. Native JSON type: string or number. vendor.branch.body.content_items[].$quantity.invalid docs
content_items[].$sku optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$sku.invalid docs
content_items[].$product_name optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$product_name.invalid docs
content_items[].$product_brand optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$product_brand.invalid docs
content_items[].$product_variant optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$product_variant.invalid docs
content_items[].$address_street optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$address_street.invalid docs
content_items[].$address_city optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$address_city.invalid docs
content_items[].$address_region optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$address_region.invalid docs
content_items[].$address_country optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$address_country.invalid docs
content_items[].$address_postal_code optional The content item table and official example document this property. Native JSON type: string. vendor.branch.body.content_items[].$address_postal_code.invalid docs
content_items[].$keywords optional The vendor documents the JSON shape or value type of this field. Native JSON type: array. vendor.branch.body.content_items[].$keywords.invalid docs
content_items[].$keywords[] optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.content_items[].$keywords[].invalid docs
content_items[].$image_captions optional The vendor documents the JSON shape or value type of this field. Native JSON type: array. vendor.branch.body.content_items[].$image_captions.invalid docs
content_items[].$image_captions[] optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.content_items[].$image_captions[].invalid docs
content_items[].$custom_fields optional The vendor documents the JSON shape or value type of this field. Native JSON type: object. vendor.branch.body.content_items[].$custom_fields.invalid docs
content_items[].$product_category optional The vendor documents the JSON shape or value type of this field. Native JSON type: string. vendor.branch.body.content_items[].$product_category.empty
vendor.branch.body.content_items[].$product_category.invalid
docs
user_data.anon_id optional The current official vendor reference documents this field. Native JSON type: string. vendor.branch.body.user_data.anon_id.invalid docs
user_data.http_origin optional The current official vendor reference documents this field. Native JSON type: string. vendor.branch.body.user_data.http_origin.invalid docs
user_data.http_referrer optional The current official vendor reference documents this field. Native JSON type: string. vendor.branch.body.user_data.http_referrer.invalid docs
user_data.randomized_device_token optional The current official vendor reference documents this field. Native JSON type: string. vendor.branch.body.user_data.randomized_device_token.invalid docs
meta_data optional The published current endpoint schema declares an optional metadata object. Its custom member values may be any JSON type. Native JSON type: object. vendor.branch.body.meta_data.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
body.idfa_requires_os required The device identifier requires the operating system documented for that identifier. vendor.branch.body.idfa_requires_os docs
body.idfv_requires_os required The device identifier requires the operating system documented for that identifier. vendor.branch.body.idfv_requires_os docs
body.android_id_requires_os required The device identifier requires the operating system documented for that identifier. vendor.branch.body.android_id_requires_os docs
body.aaid_requires_os required The device identifier requires the operating system documented for that identifier. vendor.branch.body.aaid_requires_os docs
body.os_forbids_idfa required The device identifier belongs to a different operating system. vendor.branch.body.os_forbids_idfa docs
body.os_forbids_idfv required The device identifier belongs to a different operating system. vendor.branch.body.os_forbids_idfv docs
body.os_forbids_android_id required The device identifier belongs to a different operating system. vendor.branch.body.os_forbids_android_id docs
body.os_forbids_aaid required The device identifier belongs to a different operating system. vendor.branch.body.os_forbids_aaid docs
method required The event endpoints document POST. Complete HTTP capture contract. Native JSON type: string. vendor.branch.http.method.missing
vendor.branch.http.method.empty
vendor.branch.http.method.invalid
docs
path required Use a Branch standard or custom event endpoint. Complete HTTP capture contract. Native JSON type: string. vendor.branch.http.path.missing
vendor.branch.http.path.empty
vendor.branch.http.path.invalid
docs
body_encoding required Branch events are JSON encoded. Complete HTTP capture contract. Native JSON type: string. vendor.branch.http.body_encoding.missing
vendor.branch.http.body_encoding.invalid
docs
content_type recommended Branch recommends application/json for this header. Complete HTTP capture contract. Presence diagnostic severity: warning. Value diagnostic severity: warning. Native JSON type: string. vendor.branch.http.content_type.missing
vendor.branch.http.content_type.empty
vendor.branch.http.content_type.invalid
docs
headers.accept recommended Branch recommends application/json for this header. Complete HTTP capture contract. Presence diagnostic severity: warning. Value diagnostic severity: warning. Native JSON type: string. vendor.branch.http.headers.accept.missing
vendor.branch.http.headers.accept.empty
vendor.branch.http.headers.accept.invalid
docs
headers.x-ip-override optional The override header accepts IPv4 and requires the same user_data.ip. Complete HTTP capture contract. Native JSON type: string. vendor.branch.http.headers.x-ip-override.empty
vendor.branch.http.headers.x-ip-override.invalid
docs
body.user_data.ip optional The user_data IP must repeat a submitted X-IP-Override. Complete HTTP capture contract. Native JSON type: string. vendor.branch.http.body.user_data.ip.invalid docs
body.name optional The standard endpoint accepts only the published standard event names; custom endpoint names remain open. Complete HTTP capture contract. Applies when {"kind":"value_pattern","param":"path","pattern":"^/v2/event/standard/?$"}. Native JSON type: string. vendor.branch.http.body.name.empty
vendor.branch.http.body.name.invalid
docs
body.content_items optional Content items belong to Commerce and Content standard events. Complete HTTP capture contract. docs
url required The published request endpoint uses HTTPS. Complete HTTP capture contract. Native JSON type: string. vendor.branch.http.url.missing
vendor.branch.http.url.empty
vendor.branch.http.url.invalid
docs
body required Branch event requests carry a JSON object, including when JSON headers are omitted. Complete HTTP capture contract. Native JSON type: object. vendor.branch.http.body.missing
vendor.branch.http.body.invalid
docs
http.ip_override_requires_body_ip required X-IP-Override requires the same IP in user_data.ip. Complete HTTP capture contract. vendor.branch.http.ip_override_requires_body_ip docs
http.ip_override_matches_body required X-IP-Override and user_data.ip must carry the same IP. Complete HTTP capture contract. vendor.branch.http.ip_override_matches_body docs
http.lifecycle_content_items recommended content_items is documented for Commerce and Content events; this is a Lifecycle event. Complete HTTP capture contract. vendor.branch.http.lifecycle_content_items 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