Events API

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.

12701270

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:

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

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.

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

Description associated with the event.

No

❗️

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)

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.

16721672

📘

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.


Did this page help you?