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:

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.

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

Parameter	Value	Required
Content-Type	application/json	Yes

Request Body Parameters

Parameter	Description	Required
branch_key	The Branch key of the originating app; from your Branch Settings Dashboard	Yes
name	The 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_alias	The event alias as defined by you; used in addition to the event name defined above.	No
user_data.os	Example "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc.	Yes
user_data.os_version	The version of the operating system.	No
user_data.environment	usually FULL_APP	No
user_data.aaid	The Android/Google advertising ID.	No
user_data.android_id	Android hardware ID	No
user_data.idfa	iOS advertising ID	No
user_data.idfv	iOS vendor ID	No
user_data.limit_ad_tracking	true if the partner has opted to not be tracked by advertisers	No
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_id	Branch internal-only field for tracking browsers.	No
user_data.http_origin	The current page url where Web SDK logged web session start.	No
user_data.http_referrer	The referral url that led to the current page where Web SDK logged web session start.	No
user_data.developer_identity	The developer-specified identity for a user.	No
user_data.country	The country code of the user, usually based on device settings or user agent string.	No
user_data.language	The language code of the user, usually based on device settings or user agent string.	No
user_data.ip	The ip address for the device where the event occurred	Yes
user_data.local_ip	Android only : local ip of the device (e.g. "168.1.1.1")	No
user_data.brand	The brand of the device	No
user_data.randomized_device_token	Branch internal-only field for tracking devices.	No
user_data.app_version	The app version downloaded by the user.	No
user_data.model	The model of the device.	No
user_data.screen_dpi	The screen's DPI.	No
user_data.screen_height	The screen's height.	No
user_data.screen_width	The screen's width.	No
custom_data	The 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_id	The partner-specified transaction id for their internal use	No
event_data.revenue	The partner-specified reported revenue for the event.	No
event_data.currency	Currency that revenue, price, shipping, tax were originally reported in by the partner	No
event_data.shipping	Shipping cost associated with the transaction.	No
event_data.tax	Total tax associated with the transaction.	No
event_data.coupon	Transaction coupon redeemed with the transaction (e.g. "SPRING2017")	No
event_data.affiliation	Store or affiliation from which this transaction occurred (e.g. Google Store)	No
event_data.description	Description associated with the event, not necessarily specific to any individual content items (see below)	No
content_items[i].$content_schema	*Commerce 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_title	*Commerce and Content Reports only* The title (for the individual content item).	No
content_items[i].$og_image_url	*Commerce and Content Reports only* The image URL (for the individual content item).	No
content_items[i].$canonical_identifier	*Commerce and Content Reports only* Used to allow Branch to unify content/messages for Content Analytics	No
content_items[i].$publicly_indexable	*Commerce and Content Reports only* `true`: content can be seen by anyone `false`: cannot index for public use	No
content_items[i].$locally_indexable	*Commerce and Content Reports only* `true`: content can be indexed for local (device) use `false`: cannot index for local use	No
content_items[i].$price	*Commerce and Content Reports only* The price for the product/content.	No
content_items[i].$quantity	*Commerce and Content Reports only* The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc).	No
content_items[i].$sku	*Commerce and Content Reports only* The product sku or product ID.	No
content_items[i].$product_name	*Commerce and Content Reports only* The product's name.	No
content_items[i].$product_brand	*Commerce and Content Reports only* The product's brand.	No
content_items[i].$product_category	*Commerce 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_variant	*Commerce and Content Reports only* The product's variant (e.g. XL, red).	No
content_items[i].$rating_average	*Commerce and Content Reports only* The average rating of the item.	No
content_items[i].$rating_count	*Commerce and Content Reports only* The number of ratings for the item.	No
content_items[i].$rating_max	*Commerce 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_timestamp	*Commerce and Content Reports only* The time the content was created.	No
content_items[i].$exp_date	*Commerce 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].$keywords	*Commerce and Content Reports only* keywords	No
content_items[i].$address_street	*Commerce and Content Reports only* The street address for a restaurant, business, room (hotel), etc.	No
content_items[i].$address_city	*Commerce and Content Reports only* The street address for a restaurant, business, room (hotel), etc.	No
content_items[i].$address_region	*Commerce and Content Reports only* The state or region for a restaurant, business, room (hotel), etc.	No
content_items[i].$address_country	*Commerce and Content Reports only* The country code for a restaurant, business, room (hotel), etc.	No
content_items[i].$address_postal_code	*Commerce and Content Reports only* The postal/zip code for a restaurant, business, room (hotel), etc.	No
content_items[i].$latitude	*Commerce and Content Reports only* The latitude for a restaurant, business, room (hotel), etc.	No
content_items[i].$longitude	*Commerce and Content Reports only* The longitude for a restaurant, business, room (hotel), etc.	No
content_items[i].$image_captions	*Commerce and Content Reports only* The captions associated with the image.	No
content_items[i].$condition	*Commerce 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_fields	*Commerce 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:

developer_identity

browser_fingerprint_id

os=iOS AND (idfa OR idfv)

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 Code	Definition
200	Success

Logging Custom Events

Endpoint

POST /v2/event/custom

Request Header Parameters

Parameter	Value	Required
Content-Type	application/json	Yes

Request Body Parameters

❗️
Required Identifiers
You must include one of the following in the user_data:

developer_identity

browser_fingerprint_id

os=iOS AND (idfa OR idfv)

os=Android AND (android_id or aaid)

Parameter	Description	Required
branch_key	The Branch key of the originating app; from your Branch Settings Dashboard	Yes
name	The name of the event to log. Can be a string of custom event name. For instance "picture swiped".	Yes
user_data.os	Examples "Android", "iOS","MAC_OS","LINUX","WINDOWS" etc.	See Required Identifiers
user_data.os_version	The version of the operating system.	No
user_data.environment	usually FULL_APP	No
user_data.aaid	The Android/Google advertising ID.	See Required Identifiers
user_data.android_id	Android hardware ID	See Required Identifiers
user_data.idfa	iOS advertising ID	See Required Identifiers
user_data.idfv	iOS vendor ID	See Required Identifiers
user_data.limit_ad_tracking	`true` if the partner has opted to not be tracked by advertisers	No
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_id	Branch internal-only field for tracking browsers.	See Required Identifiers
user_data.http_origin	The current page url where Web SDK logged web session start.	No
user_data.http_referrer	The referral url that led to the current page where Web SDK logged web session start.	No
user_data.developer_identity	The developer-specified identity for a user.	See Required Identifiers
user_data.country	The country code of the user, usually based on device settings or user agent string.	No
user_data.language	The language code of the user, usually based on device settings or user agent string.	No
user_data.ip	The ip address for the device where the event occurred	No
user_data.local_ip	Android only : local ip of the device (e.g. "168.1.1.1")	No
user_data.brand	The brand of the device	No
user_data.randomized_device_token	Branch internal-only field for tracking devices.	No
user_data.app_version	The app version downloaded by the user.	No
user_data.model	The model of the device.	No
user_data.screen_dpi	The screen's DPI.	No
user_data.screen_height	The screen's height.	No
user_data.screen_width	The screen's width.	No
custom_data	The 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.description	Description 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 Code	Definition
200	Success

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.

📘
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.

Filters

Overview

Prerequisites

Authentication

API Usage

Logging Standard Events - Commerce, Content, User Lifecycle

Endpoint

Request Header Parameters

Request Body Parameters

Example Requests

Response Codes

Logging Custom Events

Endpoint

Request Header Parameters

Request Body Parameters

Example Request

Response Codes

Verify Events Sent