✕
Filters
Submit a TicketBranch DashboardBranch University

Events API

👍

Try It!

Try out the Events API for your Branch App via the API reference here.

Overview

Branch's Events API is a robust endpoint for tracking all of your conversions in your app. With it, you'll be able to tie in detailed metadata about your Commerce, Content, Lifecycle, and Custom Events to better understand user behavior and attribute to your ongoing campaigns.

Prerequisites

In order to access the Events API, you need to have completed the following:

  1. Created a Branch Dashboard

Authentication

Calls to the Events API require your Branch Key parameter to be passed with each request. This can be obtained through the Branch Dashboard Account Settings.

1270

Learn more about your Branch Account Profile here.

API Usage

Logging Standard Events - Commerce, Content, User Lifecycle

Endpoint

POST /v2/event/standard

Request Header Parameters

ParameterValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters

ParameterDescriptionRequired
branch_keyThe Branch key of the originating app; from your Branch Settings DashboardYes
nameThe name of the event to log. Can be one of the following depending on which type of report you are running:

Commerce:
ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS

Content:
SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE

User Lifecycle:
ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS		Yes
customer_event_aliasThe event alias as defined by you; used in addition to the event name defined above.No
user_data.osExample "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc.Yes
user_data.os_versionThe version of the operating system.No
user_data.environmentusually FULL_APP No
user_data.aaidThe Android/Google advertising ID.No
user_data.android_idAndroid hardware IDNo
user_data.idfaiOS advertising IDNo
user_data.idfviOS vendor IDNo
user_data.limit_ad_trackingtrue if the partner has opted to not be tracked by advertisersNo
user_data.user_agentThe user agent of the browser or app where the event occurred. Usually associated with a webview.No
user_data.browser_fingerprint_idBranch internal-only field for tracking browsers.No
user_data.http_originThe current page url where Web SDK logged web session start.No
user_data.http_referrerThe referral url that led to the current page where Web SDK logged web session start.No
user_data.developer_identityThe developer-specified identity for a user.No
user_data.countryThe country code of the user, usually based on device settings or user agent string.No
user_data.languageThe language code of the user, usually based on device settings or user agent string.No
user_data.ipThe ip address for the device where the event occurredYes
user_data.local_ipAndroid only : local ip of the device (e.g. "168.1.1.1")No
user_data.brandThe brand of the deviceNo
user_data.randomized_device_tokenBranch internal-only field for tracking devices.No
user_data.app_versionThe app version downloaded by the user.No
user_data.modelThe model of the device.No
user_data.screen_dpiThe screen's DPI.No
user_data.screen_heightThe screen's height.No
user_data.screen_widthThe screen's width.No
custom_dataThe key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks.No
event_data.transaction_idThe partner-specified transaction id for their internal useNo
event_data.revenueThe partner-specified reported revenue for the event.No
event_data.currencyCurrency that revenue, price, shipping, tax were originally reported in by the partnerNo
event_data.shippingShipping cost associated with the transaction.No
event_data.taxTotal tax associated with the transaction.No
event_data.couponTransaction coupon redeemed with the transaction (e.g. "SPRING2017")No
event_data.affiliationStore or affiliation from which this transaction occurred (e.g. Google Store)No
event_data.descriptionDescription associated with the event, not necessarily specific to any individual content items (see below)No
content_items[i].$content_schemaCommerce and Content Reports only
Category / Schema for a piece of content.
May be used in the future for analytics. One of:
COMMERCE_AUCTION
COMMERCE_BUSINESS
COMMERCE_OTHER
COMMERCE_PRODUCT
COMMERCE_RESTAURANT
COMMERCE_SERVICE
COMMERCE_TRAVEL_FLIGHT
COMMERCE_TRAVEL_HOTEL
COMMERCE_TRAVEL_OTHER
GAME_STATE
MEDIA_IMAGE
MEDIA_MIXED
MEDIA_MUSIC
MEDIA_OTHER
MEDIA_VIDEO
OTHER
TEXT_ARTICLE
TEXT_BLOG
TEXT_OTHER
TEXT_RECIPE
TEXT_REVIEW
TEXT_SEARCH_RESULTS
TEXT_STORY
TEXT_TECHNICAL_DOC		No
content_items[i].$og_titleCommerce and Content Reports only
The title (for the individual content item).		No
content_items[i].$og_image_urlCommerce and Content Reports only
The image URL (for the individual content item).		No
content_items[i].$canonical_identifierCommerce and Content Reports only
Used to allow Branch to unify content/messages for Content Analytics		No
content_items[i].$publicly_indexableCommerce and Content Reports only
true: content can be seen by anyone
false: cannot index for public use		No
content_items[i].$locally_indexableCommerce and Content Reports only
true: content can be indexed for local (device) use
false: cannot index for local use		No
content_items[i].$priceCommerce and Content Reports only
The price for the product/content.		No
content_items[i].$quantityCommerce and Content Reports only
The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc).		No
content_items[i].$skuCommerce and Content Reports only
The product sku or product ID.		No
content_items[i].$product_nameCommerce and Content Reports only
The product's name.		No
content_items[i].$product_brandCommerce and Content Reports only
The product's brand.		No
content_items[i].$product_categoryCommerce and Content Reports only
The product's category, if it's a product. One of:
ANIMALS_AND_PET_SUPPLIES
APPAREL_AND_ACCESSORIES
ARTS_AND_ENTERTAINMENT
BABY_AND_TODDLER
BUSINESS_AND_INDUSTRIAL
CAMERAS_AND_OPTICS
ELECTRONICS
FOOD_BEVERAGES_AND_TOBACCO
FURNITURE
HARDWARE
HEALTH_AND_BEAUTY
HOME_AND_GARDEN
LUGGAGE_AND_BAGS
MATURE
MEDIA
OFFICE_SUPPLIES
RELIGIOUS_AND_CEREMONIAL
SOFTWARE
SPORTING_GOODS
TOYS_AND_GAMES
VEHICLES_AND_PARTS		No
content_items[i].$product_variantCommerce and Content Reports only
The product's variant (e.g. XL, red).		No
content_items[i].$rating_averageCommerce and Content Reports only
The average rating of the item.		No
content_items[i].$rating_countCommerce and Content Reports only
The number of ratings for the item.		No
content_items[i].$rating_maxCommerce and Content Reports only
The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating).		No
content_items[i].$creation_timestampCommerce and Content Reports only
The time the content was created.		No
content_items[i].$exp_dateCommerce and Content Reports only
The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set.		No
content_items[i].$keywordsCommerce and Content Reports only
keywords		No
content_items[i].$address_streetCommerce and Content Reports only
The street address for a restaurant, business, room (hotel), etc.		No
content_items[i].$address_cityCommerce and Content Reports only
The street address for a restaurant, business, room (hotel), etc.		No
content_items[i].$address_regionCommerce and Content Reports only
The state or region for a restaurant, business, room (hotel), etc.		No
content_items[i].$address_countryCommerce and Content Reports only
The country code for a restaurant, business, room (hotel), etc.		No
content_items[i].$address_postal_codeCommerce and Content Reports only
The postal/zip code for a restaurant, business, room (hotel), etc.		No
content_items[i].$latitudeCommerce and Content Reports only
The latitude for a restaurant, business, room (hotel), etc.		No
content_items[i].$longitudeCommerce and Content Reports only
The longitude for a restaurant, business, room (hotel), etc.		No
content_items[i].$image_captionsCommerce and Content Reports only
The captions associated with the image.		No
content_items[i].$conditionCommerce and Content Reports only
For auctions, whether the item is new, good, acceptable, etc.

One of:
OTHER
NEW
EXCELLENT
GOOD
FAIR
POOR
USED
REFURBISHED		No
content_items[i].$custom_fieldsCommerce and Content Reports only
key-value pairs that the app developer would like attached to the content item. Attached to events that are retrieved via Exports and sent via Webhooks.		No

❗️

Required Identifiers

You must include one of the following in user_data:

  1. developer_identity
  2. browser_fingerprint_id
  3. os=iOS AND (idfa OR idfv)
  4. os=Android AND (android_id or aaid)

Example Requests

curl -vvv -d '{
  "name": "PURCHASE",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": 25,
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip":"192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "purchase_loc": "Palo Alto",
    "store_pickup": "unavailable"
  },
  "event_data": {
    "transaction_id": "tras_Id_1232343434",
    "currency": "USD",
    "revenue": 180.2,
    "shipping": 10.5,
    "tax": 13.5,
    "coupon": "promo-1234",
    "affiliation": "high_fi",
    "description": "Preferred purchase"
  },
  "content_items": [
    {
      "$content_schema": "COMMERCE_PRODUCT",
      "$og_title": "Nike Shoe",
      "$og_description": "Start loving your steps",
      "$og_image_url": "http://example.com/img1.jpg",
      "$canonical_identifier": "nike/1234",
      "$publicly_indexable": false,
      "$price": 101.2,
      "$locally_indexable": true,
      "$quantity": 1,
      "$sku": "1101123445",
      "$product_name": "Runner",
      "$product_brand": "Nike",
      "$product_category": "Sporting Goods",
      "$product_variant": "XL",
      "$rating_average": 4.2,
      "$rating_count": 5,
      "$rating_max": 2.2,
      "$creation_timestamp": 1499892854966,
      "$exp_date": 1499892854966,
      "$keywords": [
        "sneakers",
        "shoes"
      ],
      "$address_street": "230 South LaSalle Street",
      "$address_city": "Chicago",
      "$address_region": "IL",
      "$address_country": "US",
      "$address_postal_code": "60604",
      "$latitude": 12.07,
      "$longitude": -97.5,
      "$image_captions": [
        "my_img_caption1",
        "my_img_caption_2"
      ],
      "$condition": "NEW",
      "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}"
    },
    {
      "$og_title": "Nike Woolen Sox",
      "$canonical_identifier": "nike/5324",
      "$og_description": "Fine combed woolen sox for those who love your foot",
      "$publicly_indexable": false,
      "$price": 80.2,
      "$locally_indexable": true,
      "$quantity": 5,
      "$sku": "110112467",
      "$product_name": "Woolen Sox",
      "$product_brand": "Nike",
      "$product_category": "Apparel & Accessories",
      "$product_variant": "Xl",
      "$rating_average": 3.3,
      "$rating_count": 5,
      "$rating_max": 2.8,
      "$creation_timestamp": 1499892854966
    }
  ],
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api2.branch.io/v2/event/standard

curl -vvv -d '{
  "name": "VIEW_ITEMS",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": 25,
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "purchase_loc": "Palo Alto",
    "store_pickup": "unavailable"
  },
  "event_data": {
    "search_query": "red sneakers",
    "description": "Preferred purchase"
  },
  "content_items": [
    {
      "$content_schema": "COMMERCE_PRODUCT",
      "$og_title": "Nike Shoe",
      "$og_description": "Start loving your steps",
      "$og_image_url": "http://example.com/img1.jpg",
      "$canonical_identifier": "nike/1234",
      "$publicly_indexable": false,
      "$price": 101.2,
      "$locally_indexable": true,
      "$sku": "1101123445",
      "$product_name": "Runner",
      "$product_brand": "Nike",
      "$product_category": "Sporting Goods",
      "$product_variant": "XL",
      "$rating_average": 4.2,
      "$rating_count": 5,
      "$rating_max": 2.2,
      "$creation_timestamp": 1499892854966,
      "$exp_date": 1499892854966,
      "$keywords": [
        "sneakers",
        "shoes"
      ],
      "$address_street": "230 South LaSalle Street",
      "$address_city": "Chicago",
      "$address_region": "IL",
      "$address_country": "US",
      "$address_postal_code": "60604",
      "$latitude": 12.07,
      "$longitude": -97.5,
      "$image_captions": [
        "my_img_caption1",
        "my_img_caption_2"
      ],
      "$condition": "NEW",
      "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}"
    },
    {
      "$og_title": "Nike Woolen Sox",
      "$canonical_identifier": "nike/5324",
      "$og_description": "Fine combed woolen sox for those who love your foot",
      "$publicly_indexable": false,
      "$price": 80.2,
      "$locally_indexable": true,
      "$sku": "110112467",
      "$product_name": "Woolen Sox",
      "$product_brand": "Nike",
      "$product_category": "Apparel & Accessories",
      "$product_variant": "Xl",
      "$rating_average": 3.3,
      "$rating_count": 5,
      "$rating_max": 2.8,
      "$creation_timestamp": 1499892854966
    }
  ],
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api.branch.io/v2/event/standard

curl -vvv -d '{
  "name": "COMPLETE_REGISTRATION",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": 25,
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "foo": "bar"
  },
  "event_data": {
    "description": "Preferred purchase"
  },
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api.branch.io/v2/event/standard

Response Codes

Response CodeDefinition
200Success

Logging Custom Events

Endpoint

POST /v2/event/custom

Request Header Parameters

ParameterValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters

❗️

Required Identifiers

You must include one of the following in the user_data:

  1. developer_identity
  2. browser_fingerprint_id
  3. os=iOS AND (idfa OR idfv)
  4. os=Android AND (android_id or aaid)
ParameterDescriptionRequired
branch_keyThe Branch key of the originating app; from your Branch Settings DashboardYes
nameThe name of the event to log. Can be a string of custom event name. For instance "picture swiped".Yes
user_data.osExamples "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc.See Required Identifiers
user_data.os_versionThe version of the operating system.No
user_data.environmentusually FULL_APPNo
user_data.aaidThe Android/Google advertising ID.See Required Identifiers
user_data.android_idAndroid hardware IDSee Required Identifiers
user_data.idfaiOS advertising IDSee Required Identifiers
user_data.idfviOS vendor IDSee Required Identifiers
user_data.limit_ad_trackingtrue if the partner has opted to not be tracked by advertisersNo
user_data.user_agent*The user agent of the browser or app where the event occurred. Usually associated with a webview.No
user_data.browser_fingerprint_idBranch internal-only field for tracking browsers.See Required Identifiers
user_data.http_originThe current page url where Web SDK logged web session start.No
user_data.http_referrerThe referral url that led to the current page where Web SDK logged web session start.No
user_data.developer_identityThe developer-specified identity for a user.See Required Identifiers
user_data.countryThe country code of the user, usually based on device settings or user agent string.No
user_data.languageThe language code of the user, usually based on device settings or user agent string.No
user_data.ipThe ip address for the device where the event occurredNo
user_data.local_ipAndroid only : local ip of the device (e.g. "168.1.1.1")No
user_data.brandThe brand of the deviceNo
user_data.randomized_device_tokenBranch internal-only field for tracking devices.No
user_data.app_versionThe app version downloaded by the user.No
user_data.modelThe model of the device.No
user_data.screen_dpiThe screen's DPI.No
user_data.screen_heightThe screen's height.No
user_data.screen_widthThe screen's width.No
custom_dataThe key-value pairs that the app developer would like attached to the event. Attached to events that are retrieved via Exports and sent via Webhooks.No
event_data.descriptionDescription associated with the event.No

Example Request

curl -vvv -d '{
  "name": "picture swiped",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "advertising_ids": {
      "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
    },
    "os": "Android",
    "os_version": 25,
    "environment": "FULL_APP",
    "aaid": "abcdabcd-0123-0123-00f0-000000000000",
    "android_id": "a12300000000",
    "limit_ad_tracking": false,
    "developer_identity": "user123",
    "country": "US",
    "language": "en",
    "ip": "192.168.1.1",
    "local_ip": "192.168.1.2",
    "brand": "LGE",
    "app_version": "1.0.0",
    "model": "Nexus 5X",
    "screen_dpi": 420,
    "screen_height": 1794,
    "screen_width": 1080
  },
  "custom_data": {
    "foo": "bar"
  },
  "metadata": {},
  "branch_key": "key_test_hdcBLUy1xZ1JD0tKg7qrLcgirFmPPVJc"
}' https://api.branch.io/v2/event/custom

Response Codes

Response CodeDefinition
200Success

Verify Events Sent

Once you have completed tracking events via the Events API, you can verify data is being sent to Branch for attribution. To do so, you can look at the Branch Dashboard's Liveview Records.

1672

📘

Wait Period

Please be patient as data may take some time to flow through Branch's attribution systems and onto the Dashboard. If data has not appeared in the Branch Dashboard after 30 minutes of completing a test event, review your API requests to see if you may have missed something.