Events API

The Events API tracks conversions in your app. Attach metadata for Commerce, Content, Lifecycle, and Custom events to measure user behavior and attribute it to your campaigns.

Important considerations

Real-time only: You must send events in real time as they occur. Branch doesn't support backtracking or historical event ingestion. Events with timestamps in the past won't be backfilled into reports.
SKAdNetwork (SKAN): Your app must handle SKAN natively, not via the Branch SDK. Branch returns SKAN-relevant fields (such as coarse_key and update_conversion_value) in the API response so your app can update its conversion value accordingly. See the SKAdNetwork guide for details.

Rate limits

The Events API enforces rate limits on a per-app basis. If you exceed the limit, the API returns a 429 Rate Limit Reached error. Back off and retry with exponential delay.

Rate limits are enforced per app. Contact your Branch account manager for your app's specific limits.

Read the Events API overview

Log custom events

POST/event/custom

Use this endpoint to log custom events.

Important considerations

Real-time only: You must send events in real time as they occur. Branch doesn't support backtracking or historical event ingestion. Events with timestamps in the past won't be backfilled into reports.
SKAdNetwork (SKAN): Your app must handle SKAN natively, not via the Branch SDK. Branch returns SKAN-relevant fields (such as coarse_key and update_conversion_value) in the API response so your app can update its conversion value accordingly. See the SKAdNetwork guide for details.

Parameters

branch_keystringRequired
The Branch Key of the originating app obtained in your Account Settings.
namestringRequired
The name of the event to log. Can be a custom event name string, for example, "picture swiped".
Acceptstringheader
Recommended. The media type the client expects in the response. Should be application/json.
Content-Typestringheader
Recommended. The media type of the request body. Should be application/json.
custom_dataobjectExpandable
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.
event_dataobjectExpandable
meta_dataobjectExpandable
Additional metadata for the event.
user_dataobjectExpandable
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, or
- browser_fingerprint_id, or
- os=iOS AND idfa, or
- os=iOS AND idfv, or
- os=Android AND android_id, or
- os=Android AND aaid
X-IP-Overridestringheader
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:
- Branch must allowlist your app ID. 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.ip in the request body with the same IP value. Sending the header alone isn't sufficient—the body field is what Branch persists for attribution.

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

Content-TypeAcceptX-IP-Override

{
  "branch_key": "key_live_xxxx",
  "name": "CustomEventTest",
  "user_data": {
    "os": "Android",
    "os_version": "12.4.0",
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "idfa": "00000000-0000-0000-0000-000000000001",
    "idfv": "00000000-0000-0000-0000-000000000002",
    "anon_id": "fbanon_abc123def456",
    "advertising_ids": {
      "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
    },
    "google_analytics_id": "GA1.2.123456789.1234567890",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)",
    "browser_fingerprint_id": "857675855146829999",
    "http_origin": "https://example.com/landing",
    "http_referrer": "https://referrer.example.com/path",
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "198.51.100.42",
    "local_ip": "192.0.2.1",
    "brand": "LGE",
    "randomized_device_token": "857675855146829998",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080,
    "dma_eea": true,
    "dma_ad_personalization": true,
    "dma_ad_user_data": true
  },
  "event_data": {
    "revenue": 1.5,
    "currency": "USD",
    "shipping": 10.2,
    "tax": 12.3,
    "coupon": "coupon",
    "affiliation": "test_affiliation",
    "description": "Event_description",
    "search_query": "Test Search query"
  }
}

curl 'https://api2.branch.io/v2/event/custom' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_key": "key_live_xxxx",
    "name": "CustomEventTest",
    "user_data": {
      "os": "Android",
      "os_version": "12.4.0",
      "environment": "FULL_APP",
      "aaid": "abcdabcd-0123-0123-00f0-000000000000",
      "android_id": "a12300000000",
      "idfa": "00000000-0000-0000-0000-000000000001",
      "idfv": "00000000-0000-0000-0000-000000000002",
      "anon_id": "fbanon_abc123def456",
      "advertising_ids": {
        "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
      },
      "google_analytics_id": "GA1.2.123456789.1234567890",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)",
      "browser_fingerprint_id": "857675855146829999",
      "http_origin": "https://example.com/landing",
      "http_referrer": "https://referrer.example.com/path",
      "developer_identity": "user123",
      "country": "US",
      "language": "en",
      "ip": "198.51.100.42",
      "local_ip": "192.0.2.1",
      "brand": "LGE",
      "randomized_device_token": "857675855146829998",
      "app_version": "1.0.0",
      "model": "Nexus 5X",
      "screen_dpi": 420,
      "screen_height": 1794,
      "screen_width": 1080,
      "dma_eea": true,
      "dma_ad_personalization": true,
      "dma_ad_user_data": true
    },
    "event_data": {
      "revenue": 1.5,
      "currency": "USD",
      "shipping": 10.2,
      "tax": 12.3,
      "coupon": "coupon",
      "affiliation": "test_affiliation",
      "description": "Event_description",
      "search_query": "Test Search query"
    }
  }'

Response

Success.

{
  "ascending_only": false,
  "coarse_key": "high",
  "locked": false,
  "update_conversion_value": 3
}

Log standard events

POST/event/standard

Use this endpoint to log standard events, that is, Commerce, Content, and User Lifecycle events.

Important considerations

Real-time only: You must send events in real time as they occur. Branch doesn't support backtracking or historical event ingestion. Events with timestamps in the past won't be backfilled into reports.
SKAdNetwork (SKAN): Your app must handle SKAN natively, not via the Branch SDK. Branch returns SKAN-relevant fields (such as coarse_key and update_conversion_value) in the API response so your app can update its conversion value accordingly. See the SKAdNetwork guide for details.

Parameters

branch_keystringRequired
The Branch Key of the originating app obtained in your Account Settings.
nameenumRequired
The name of the event to log. Must be one of the following standard Branch Event names:
- Commerce:
- ADD_TO_CART
- ADD_TO_WISHLIST
- VIEW_CART
- INITIATE_PURCHASE
- ADD_PAYMENT_INFO
- CLICK_AD
- PURCHASE
- SPEND_CREDITS
- VIEW_AD
- Content:
- SEARCH
- VIEW_ITEM
- VIEW_ITEMS
- RATE
- SHARE
- INITIATE_STREAM
- COMPLETE_STREAM
- User Lifecycle:
- COMPLETE_REGISTRATION
- COMPLETE_TUTORIAL
- ACHIEVE_LEVEL
- UNLOCK_ACHIEVEMENT
- INVITE
- LOGIN
- START_TRIAL
- SUBSCRIBE
ADD_TO_CARTADD_TO_WISHLISTVIEW_CARTINITIATE_PURCHASEADD_PAYMENT_INFOCLICK_ADPURCHASESPEND_CREDITSVIEW_ADSEARCHVIEW_ITEMVIEW_ITEMS
user_dataobjectRequiredExpandable
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, or
- browser_fingerprint_id, or
- os=iOS AND idfa, or
- os=iOS AND idfv, or
- os=Android AND android_id, or
- os=Android AND aaid
Acceptstringheader
Recommended. The media type the client expects in the response. Should be application/json.
content_itemsarray of objectExpandable
Content-Typestringheader
Recommended. The media type of the request body. Should be application/json.
custom_dataobjectExpandable
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.
customer_event_aliasstring
The event alias that you define, used in addition to the event name defined above.
event_dataobjectExpandable
X-IP-Overridestringheader
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:
- Branch must allowlist your app ID. 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.ip in the request body with the same IP value. Sending the header alone isn't sufficient—the body field is what Branch persists for attribution.

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

Content-TypeAcceptX-IP-Override

{
  "branch_key": "key_live_xxxx",
  "name": "PURCHASE",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "os": "Android",
    "os_version": "12.4.0",
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "idfa": "00000000-0000-0000-0000-000000000001",
    "idfv": "00000000-0000-0000-0000-000000000002",
    "anon_id": "fbanon_abc123def456",
    "advertising_ids": {
      "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
    },
    "google_analytics_id": "GA1.2.123456789.1234567890",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)",
    "browser_fingerprint_id": "857675855146829999",
    "http_origin": "https://example.com/landing",
    "http_referrer": "https://referrer.example.com/path",
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "198.51.100.42",
    "local_ip": "192.0.2.1",
    "brand": "LGE",
    "randomized_device_token": "857675855146829998",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080,
    "dma_eea": true,
    "dma_ad_personalization": true,
    "dma_ad_user_data": true
  },
  "event_data": {
    "revenue": 1.5,
    "currency": "USD",
    "shipping": 10.2,
    "tax": 12.3,
    "coupon": "coupon",
    "affiliation": "test_affiliation",
    "description": "Event_description",
    "search_query": "Test Search query"
  },
  "content_items": [
    {
      "$content_schema": "COMMERCE_PRODUCT",
      "$og_title": "My Content Title",
      "$og_image_url": "valid URL",
      "$canonical_identifier": "item12345",
      "$locally_indexable": true,
      "$price": 23.2,
      "$quantity": 2,
      "$sku": "1994320302",
      "$product_name": "my_product_name1",
      "$product_brand": "my_prod_Brand1",
      "$product_category": "BABY_AND_TODDLER",
      "$product_variant": "3T",
      "$rating_average": 4.2,
      "$rating_count": 5,
      "$rating_max": 5,
      "$creation_timestamp": 1499892854966,
      "$keywords": [
        "sneakers",
        "shoes"
      ],
      "$address_street": "Street_name1",
      "$address_city": "city1",
      "$address_region": "Region1",
      "$address_country": "Country1",
      "$address_postal_code": "postal_code",
      "$latitude": 12.07,
      "$longitude": -97.5,
      "$image_captions": [
        "my_img_caption1"
      ],
      "$condition": "OTHER"
    }
  ]
}

curl 'https://api2.branch.io/v2/event/standard' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_key": "key_live_xxxx",
    "name": "PURCHASE",
    "customer_event_alias": "my custom alias",
    "user_data": {
      "os": "Android",
      "os_version": "12.4.0",
      "environment": "FULL_APP",
      "aaid": "abcdabcd-0123-0123-00f0-000000000000",
      "android_id": "a12300000000",
      "idfa": "00000000-0000-0000-0000-000000000001",
      "idfv": "00000000-0000-0000-0000-000000000002",
      "anon_id": "fbanon_abc123def456",
      "advertising_ids": {
        "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
      },
      "google_analytics_id": "GA1.2.123456789.1234567890",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)",
      "browser_fingerprint_id": "857675855146829999",
      "http_origin": "https://example.com/landing",
      "http_referrer": "https://referrer.example.com/path",
      "developer_identity": "user123",
      "country": "US",
      "language": "en",
      "ip": "198.51.100.42",
      "local_ip": "192.0.2.1",
      "brand": "LGE",
      "randomized_device_token": "857675855146829998",
      "app_version": "1.0.0",
      "model": "Nexus 5X",
      "screen_dpi": 420,
      "screen_height": 1794,
      "screen_width": 1080,
      "dma_eea": true,
      "dma_ad_personalization": true,
      "dma_ad_user_data": true
    },
    "event_data": {
      "revenue": 1.5,
      "currency": "USD",
      "shipping": 10.2,
      "tax": 12.3,
      "coupon": "coupon",
      "affiliation": "test_affiliation",
      "description": "Event_description",
      "search_query": "Test Search query"
    },
    "content_items": [
      {
        "$content_schema": "COMMERCE_PRODUCT",
        "$og_title": "My Content Title",
        "$og_image_url": "valid URL",
        "$canonical_identifier": "item12345",
        "$locally_indexable": true,
        "$price": 23.2,
        "$quantity": 2,
        "$sku": "1994320302",
        "$product_name": "my_product_name1",
        "$product_brand": "my_prod_Brand1",
        "$product_category": "BABY_AND_TODDLER",
        "$product_variant": "3T",
        "$rating_average": 4.2,
        "$rating_count": 5,
        "$rating_max": 5,
        "$creation_timestamp": 1499892854966,
        "$keywords": [
          "sneakers",
          "shoes"
        ],
        "$address_street": "Street_name1",
        "$address_city": "city1",
        "$address_region": "Region1",
        "$address_country": "Country1",
        "$address_postal_code": "postal_code",
        "$latitude": 12.07,
        "$longitude": -97.5,
        "$image_captions": [
          "my_img_caption1"
        ],
        "$condition": "OTHER"
      }
    ]
  }'

Response

Success.

{
  "ascending_only": false,
  "coarse_key": "high",
  "locked": false,
  "update_conversion_value": 3
}