This endpoint is used to log custom events.
Important considerations
- Real-time only: Events must be sent in real time as they occur. Branch does not support backtracking or historical event ingestion. Events with timestamps in the past will not be backfilled into reports.
- SKAdNetwork (SKAN): SKAN must be handled natively by your app, not via the Branch SDK. Branch returns SKAN-relevant fields (such as
coarse_keyandupdate_conversion_value) in the API response so your app can update its conversion value accordingly. See the SKAdNetwork guide for details.
Recommended. The media type of the request body. Should be application/json.
Recommended. The media type the client expects in the response. Should be application/json.
Optional. Override the IP address Branch uses for the event (for example, when forwarding events server-to-server from your own backend).
Two requirements must be met for this header to function:
- Your app ID must be allowlisted by Branch. The header is ignored until allowlisting is enabled. Open a support request to have your app ID allowlisted before sending this header in production.
- You must also include
user_data.ipin the request body with the same IP value. Sending the header alone is not sufficient — the body field is what Branch persists for attribution.
The Branch Key of the originating app obtained in your Account Settings
The name of the event to log. Can be a string of custom event name. For instance "picture swiped".
Information about the user and the device the event occurred on.
Required identifiers: You must include at least one of the following in user_data:
developer_identity, orbrowser_fingerprint_id, oros=iOSANDidfa, oros=iOSANDidfv, oros=AndroidANDandroid_id, oros=AndroidANDaaid
One of the following operating system e.g. Android, iOS,MAC_OS,LINUX,WINDOWS etc.
The version of the operating system. Strongly recommended for all paid traffic to ensure accurate attribution. Required for Facebook campaigns on iOS.
usually FULL_APP
The Android/Google advertising ID.
Android hardware ID
iOS advertising ID
iOS vendor ID
The Facebook anonymous user ID. Required when running Facebook campaigns using Aggregated Event Measurement (AEM) on iOS.
Wrapper object for advertising identifiers. Use this in addition to the flat aaid, idfa, and idfv fields above to future-proof your integration for non-standard IDs (for example, OAID on Huawei devices). Additional advertising ID keys may be supported as new platforms emerge — contact Branch Support if you need to send an identifier that is not listed here.
Open Advertising ID, used on Huawei devices and other Android devices without Google Play Services.
The Google Analytics client ID, useful for cross-platform stitching with Google Analytics. Include where applicable to improve attribution coverage and downstream analytics.
true if the partner has opted to not be tracked by advertisers
The user agent of the browser or app where the event occurred. Usually associated with a webview.
Branch internal-only field for tracking browsers.
The current page url where Web SDK logged web session start.
The referral url that led to the current page where Web SDK logged web session start.
The developer-specified identity for a user.
The country code of the user, usually based on device settings or user agent string.
The language code of the user, usually based on device settings or user agent string.
The IP address for the device where the event occurred. Required if using the X-IP-Override request header.
Android only - local ip of the device
The brand of the device
Branch internal-only field for tracking devices.
The app version downloaded by the user.
The model of the device.
The screen's DPI.
The screen's height.
The screen's width.
Whether European regulations, including the DMA, apply to this user and conversion. Required if EU regulations apply to this user. Failure to include user consent signals may result in attribution or campaign performance degradation.
Whether end user has granted or denied ads personalization consent. Required if dma_eea is set to true (i.e., EU regulations apply to this user). Failure to include user consent signals may result in attribution or campaign performance degradation.
Whether end user has granted or denied consent for 3P transmission of user level data for ads. Required if dma_eea is set to true (i.e., EU regulations apply to this user). Failure to include user consent signals may result in attribution or campaign performance degradation.
Additional custom key-value pairs that you want attached to the event. Values may be of any JSON type. Attached to events retrieved via Exports and sent via Webhooks.
Additional metadata for the event.
The partner-specified transaction id for their internal use
The partner-specified reported revenue for the event.
Currency that revenue, price, shipping, tax were originally reported in by the partner
Shipping cost associated with the transaction.
Total tax associated with the transaction.
Transaction coupon redeemed with the transaction (e.g. "SPRING2017")
Store or affiliation from which this transaction occurred (e.g. Google Store)
Description associated with the event, not necessarily specific to any individual content items (see below)
Additional search queries.
Ok
Successful event ingestion. The response carries SKAdNetwork-relevant fields that the app can use to update its native SKAN conversion value.
Authentication Failed
"{\n \"error\": {\n \"message\": \"Authentication failed !\",\n \"code\": 400\n }\n}"Rate Limit Reached
"{\n \"error\": {\n \"code\": 429,\n \"message\": \"Rate limit reached.\"\n }\n}"