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.
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 |
|---|---|---|---|---|
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.missingvendor.branch.body.branch_key.emptyvendor.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.missingvendor.branch.body.name.emptyvendor.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.missingvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.emptyvendor.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.missingvendor.branch.http.method.emptyvendor.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.missingvendor.branch.http.path.emptyvendor.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.missingvendor.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.missingvendor.branch.http.content_type.emptyvendor.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.missingvendor.branch.http.headers.accept.emptyvendor.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.emptyvendor.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.emptyvendor.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.missingvendor.branch.http.url.emptyvendor.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.missingvendor.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