Developers Hub

Deep Linking API

Suggest Edits

Creating a Deep Linking URL

Endpoint - Create

POST /v1/url
Content-Type: application/json

Parameters - Create

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

data | Optional

The dictionary to embed with the link. Accessed as session or install parameters from the SDK. Use the data dictionary for all link control parameters that you'll find here.

alias | Optional

Instead of our standard encoded short url, you can specify the vanity alias. For example, instead of a random string of characters/integers, you can set the vanity alias as *.app.link/devonaustin. Aliases are enforced to be unique** and immutable per domain, and per link - they cannot be reused unless deleted.

Max 128 characters

NOTE: If you POST to the this endpoint with the same alias, and a matching set of other POST parameters to an existing aliased link, the original will be returned to you. If it clashes and you don't specify a match, will return a HTTP 409 error.

type | Optional

  • Set type to 1, to make the URL a one-time use URL. It won't deep link after 1 successful deep link.

  • Set type to 2 to make a Marketing URL. These are URLs that are displayed under the Marketing tab on the dashboard (to also set the marketing title of the link, which shows up in the Marketing tab, set the $marketing_title field in the data dictionary to the value that you would like).

  • default is set to 0, which is the standard Branch links created via our SDK.git

duration | Optional

In seconds. Only set this key if you want to override the match duration for deep link matching. This is the time that Branch allows a click to remain outstanding and be eligible to be matched with a new app session. This is default set to 7200 (2 hours)

Branch analytics parameters | Optional

It's important to tag your links with an organized structure of analytics labels so that the data appears consistent and readable in the dashboard.

identity | Optional

The identity used to identify the user. If the link is not tied to an identity, there's no need to specify an identity.

Max 127 characters

Sample Request - Create

curl -XPOST https://api2.branch.io/v1/url -H "Content-Type: application/json" \
  -d '{
  "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
  "channel": "facebook",
  "feature": "onboarding",
  "campaign": "new product",
  "stage": "new user",
  "tags": ["one", "two", "three"],
  "data": {
    "$canonical_identifier": "content/123",
    "$og_title": "Title from Deep Link",
    "$og_description": "Description from Deep Link",
    "$og_image_url": "http://www.lorempixel.com/400/400/",
    "$desktop_url": "http://www.example.com",
    "custom_boolean": true,
    "custom_integer": 1243,
    "custom_string": "everything",
    "custom_array": [1,2,3,4,5,6],
    "custom_object": { "random": "dictionary" }
  }
}'

Sample Response - Create

{
  "url": "https://example.app.link/WgiqvsepqF"
}

Bulk creating Deep Linking URLs

For more details on how to create links, see the Branch link creation guide

Endpoint - Bulk Create

POST /v1/url/bulk/:branch_key
Content-Type: application/json

Parameters - Bulk Create

A json array of parameters from Creating a Deep Linking URL.

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

Branch Parameters | Optional

You're free to add any of your own key-value parameters to a Branch link. These parameters will be passed to your app via the Branch SDK

Note: there is a 100KB limit on the request payload size

Sample Request - Bulk Create

curl -XPOST https://api2.branch.io/v1/url/bulk/key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt -H "Content-Type: application/json" \
  -d '[
    {
      "channel": "facebook",
      "feature": "onboarding",
      "campaign": "new product",
      "stage": "new user",
      "tags": ["one", "two", "three"],
      "data": {
        "$canonical_identifier": "content/123",
        "$og_title": "Title from Deep Link",
        "$og_description": "Description from Deep Link",
        "$og_image_url": "http://www.lorempixel.com/400/400/",
        "$desktop_url": "http://www.example.com",
        "custom_boolean": true,
        "custom_integer": 1243,
        "custom_string": "everything",
        "custom_array": [1,2,3,4,5,6],
        "custom_object": { "random": "dictionary" }
      }
    },
    {
      "channel": "facebook",
      "feature": "onboarding",
      "campaign": "new product",
      "stage": "new user",
      "tags": ["one", "two", "three"],
      "data": {
        "$canonical_identifier": "content/123",
        "$og_title": "Title from Deep Link",
        "$og_description": "Description from Deep Link",
        "$og_image_url": "http://www.lorempixel.com/400/400/",
        "$desktop_url": "http://www.example.com"
      }
    }
  ]'

Sample Response - Bulk Create

An array of deep linking urls and/or errors in case invalid params.

[
  {
    "url": "https://example.app.link/0AjuiLcpqF"
  },
  {
    "url": "https://example.app.link/5IULiLcpqF"
  },
  { 
    'error': 'error message'
  }
]

Deleting Existing Links

📘

Not Available in Testing Environment

Endpoint - Delete

DELETE /v1/url
Content-Type: application/json

Parameters - Delete

Parameters

[access_key | REQUIRED

Your API Key / Access Token; Learn how to retrieve your API key (a.k.a. Access Token)

Sample Request - Delete

curl -X DELETE \
'https://api2.branch.io/v1/url?url=https://example.app.link/ABCD&app_id=YOUR_APP_ID' \
  -H "Access-Token: YOUR_ACCESS_TOKEN"

Sample Response - Delete

{
  "url": "https://example.app.link/ABCD",
  "deleted": true
}

Reading Existing Deep Links

Returns deep link properties.

Endpoint - Read

GET /v1/url
Content-Type: application/json

Parameters - Read

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

url | REQUIRED

The deep link url you want read.

Sample Request - Read

curl -XGET 'https://api2.branch.io/v1/url?url=https://example.app.link/WgiqvsepqF&branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt'

Sample Response - Read

{
  "campaign": "new product",
  "channel": "facebook",
  "feature": "onboarding",
  "stage": "new user",
  "tags": [
    "one",
    "two",
    "three"
  ],
  "data": {
    "$canonical_identifier": "content/123",
    "$desktop_url": "http://www.example.com",
    "$og_description": "Description from Deep Link",
    "$og_image_url": "http://www.lorempixel.com/400/400/",
    "$og_title": "Title from Deep Link",
    "$one_time_use": false,
    "custom_array": [
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "custom_boolean": true,
    "custom_integer": 1243,
    "custom_object": {
      "random": "dictionary"
    },
    "custom_string": "everything",
    "~campaign": "new product",
    "~channel": "facebook",
    "~creation_source": 0,
    "~feature": "onboarding",
    "~id": "423196192848102356",
    "~stage": "new user",
    "~tags": [
      "one",
      "two",
      "three"
    ],
    "url": "https://example.app.link/WgiqvsepqF"
  },
  "type": 0,
  "alias": null
}

Updating Existing Deep Links

Endpoint - Update

PUT /v1/url
Content-Type: application/json

Parameters - Update

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

branch_secret | REQUIRED

The Branch secret if the originating app; from your Branch Settings Dashboard

url | REQUIRED

The deep link url you want updated.

Sample Request - Update

curl -XPUT 'https://api2.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2F5IULiLcpqF' -H "Content-Type: application/json" \
  -d '{
  "branch_key": "key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt",
  "branch_secret": "secret_live_RrrsLqpzVcoVWf5t4ncQVpzlg2pRpGH9",
  "channel": "twitter",
  "data":{
    "name":"alex",
    "user_id":"12346"
  }
}'

Sample Response - Update

{
  "campaign": "new product",
  "channel": "twitter",
  "feature": "onboarding",
  "stage": "new user",
  "tags": [
    "one",
    "two",
    "three"
  ],
  "data": {
    "$one_time_use": false,
    "name": "alex",
    "user_id": "12346",
    "~campaign": "new product",
    "~channel": "twitter",
    "~creation_source": 0,
    "~feature": "onboarding",
    "~id": "423196096467215333",
    "~stage": "new user",
    "~tags": [
      "one",
      "two",
      "three"
    ],
    "url": "https://example.app.link/5IULiLcpqF"
  },
  "type": 0,
  "alias": null
}

Link Update Tips

A link's data object is overwritten entirely by the Link update API, so make sure to include all of the link's data when updating it (not just the data you're changing)

To update links in bulk, combine the Link update and Link read APIs when creating a script. The sample Python script below reads a 2-column CSV file, and updates a key specified in the script for all links listed in column A, with the values in column B:

import requests
import csv
import sys
import urllib
import json

#Insert API key & App Secret from the Branch dashboard, and the Link data key you want to change in each link **
branch_key = "[API_KEY]"
branch_secret = "[APP_SECRET]"
key_to_update = "[DATA_KEY_TO_UPDATE]"

#Insert filename for CSV containing links to update in first column, and values to add in second column **
ifile = open('[INSERT_FILENAME].csv', "rb")

#Constants
branchendpoint = "https://api2.branch.io/v1/url?url="
reader = csv.reader(ifile, delimiter=',')

#Uncomment the next line if you want the script to skip the first line of the CSV
#next(reader)

#Loop through CSV
for row in reader:

  #Retrieve link data for link being updated
  url = urllib.quote_plus(row[0])
  getrequest = branchendpoint + url + "&branch_key=" + branch_key
  linkdata = requests.get(getrequest)
  jsonData = json.loads(linkdata.text)

  #Set credentials for update API
  jsonData["branch_key"] = branch_key
  jsonData["branch_secret"] = branch_secret

  #Update specified data key
  newValue = row[1]
  if key_to_update in jsonData:
    jsonData[key_to_update] = newValue
  if key_to_update in jsonData["data"]:
    jsonData["data"][key_to_update] = newValue

  #PUT request to update link
  payload = json.dumps(jsonData)
  putrequest = branchendpoint + url
  r = requests.put(putrequest, json=jsonData)
  print(r.url)
  print(r)
  print
ifile.close()

Restrictions

There are certain restrictions when attempting to update links:

  • Not all links are updateable, namely links with the structure of bnc.lt/c/ or bnc.lt/d/
  • The alias of a link cannot be updated, e.g. 'https://bnc.lt/test' -> 'https://bnc.lt/test1'
  • The identity associated with a Branch link cannot be updated
  • The type of a link cannot be changed, e.g. a marketing link is type 2, and a standard link generated by our Branch SDK is type 0
  • The following additional fields cannot be updated:
    • app_id
    • identity_id
    • domain
    • state
    • creation_source
    • app_short_identifier

Logging Commerce Events

Endpoint - Commerce

POST /v2/event/standard
Content-Type: application/json

Parameters - Commerce

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

name | REQUIRED

The name of the event to log. Can be one of the following: ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS

customer_event_alias | Optional

The event alias as defined by you; used in addition to the event name defined above.

user_data.os | REQUIRED

one of "Android", "iOS"

user_data.os_version | Optional

The version of the operating system. Specific to Android and iOS.

user_data.environment | Optional

usually FULL_APP

user_data.aaid | Optional

The Android/Google advertising ID.

user_data.android_id | Optional

Android hardware ID

user_data.idfa | Optional

iOS advertising ID

user_data.idfv | Optional

iOS vendor ID

user_data.limit_ad_tracking | Optional

true if the partner has opted to not be tracked by advertisers

user_data.user_agent | Optional

The user agent of the browser or app where the event occurred. Usually associated with a webview.

user_data.browser_fingerprint_id | Optional

Branch internal-only field for tracking browsers.

user_data.http_origin | Optional

The current page url where Web SDK logged web session start.

user_data.http_referrer | Optional

The referral url that led to the current page where Web SDK logged web session start.

user_data.developer_identity | Optional

The developer-specified identity for a user.

user_data.country | Optional

The country code of the user, usually based on device settings or user agent string.

user_data.language | Optional

The language code of the user, usually based on device settings or user agent string.

user_data.ip | REQUIRED

The ip address for the device where the event occurred

user_data.local_ip | Optional

Android only : local ip of the device (e.g. "168.1.1.1")

user_data.brand | Optional

The brand of the device

user_data.device_fingerprint_id | Optional

Branch internal-only field for tracking devices.

user_data.app_version | Optional

The app version downloaded by the user.

user_data.model | Optional

The model of the device.

user_data.screen_dpi | Optional

The screen's DPI.

user_data.screen_heighti | Optional

The screen's height.

user_data.screen_width | Optional

The screen's width.

custom_data | Optional

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.

event_data.transaction_id | Optional

The partner-specified transaction id for their internal use

event_data.revenue | Optional

The partner-specified reported revenue for the event.

event_data.currency | Optional

Currency that revenue, price, shipping, tax were originally reported in by the partner

event_data.shipping | Optional

Shipping cost associated with the transaction.

event_data.tax | Optional

Total tax associated with the transaction.

event_data.coupon | Optional

Transaction coupon redeemed with the transaction (e.g. "SPRING2017")

event_data.affiliation | Optional

Store or affiliation from which this transaction occurred (e.g. Google Store)

event_data.description | Optional

Description associated with the event, not necessarily specific to any individual content items (see below)

content_items[i].$content_schema | Optional

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

content_items[i].$og_title | Optional

The title (for the individual content item).

content_items[i].$og_image_url | Optional

The image URL (for the individual content item).

content_items[i].$canonical_identifier | Optional

used to allow Branch to unify content/messages for Content Analytics

content_items[i].$publicly_indexable | Optional

true: content can be seen by anyone | false`: cannot index for public use

content_items[i].$locally_indexable | Optional

true: content can be indexed for local (device) use | false: cannot index for local use

content_items[i].$price | Optional

The price for the product/content.

content_items[i].$quantity | Optional

The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc).

content_items[i].$sku | Optional

The product sku or product ID.

content_items[i].$product_name | Optional

The product's name.

content_items[i].$product_brand | Optional

The product's brand.

content_items[i].$product_category | Optional

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

content_items[i].$product_variant | Optional

The product's variant (e.g. XL, red).

content_items[i].$rating_average | Optional

The average rating of the item.

content_items[i].$rating_count | Optional

The number of ratings for the item.

content_items[i].$rating_max | Optional

The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating).

content_items[i].$creation_timestamp | Optional

The time the content was created.

content_items[i].$exp_date | Optional

The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set.

content_items[i].$keywords | Optional

keywords

content_items[i].$address_street | Optional

The street address for a restaurant, business, room (hotel), etc.

content_items[i].$address_city | Optional

The street address for a restaurant, business, room (hotel), etc.

content_items[i].$address_region | Optional

The state or region for a restaurant, business, room (hotel), etc.

content_items[i].$address_country | Optional

The country code for a restaurant, business, room (hotel), etc.

content_items[i].$address_postal_code | Optional

The postal/zip code for a restaurant, business, room (hotel), etc.

content_items[i].$latitude | Optional

The latitude for a restaurant, business, room (hotel), etc.

content_items[i].$longitude | Optional

The longitude for a restaurant, business, room (hotel), etc.

content_items[i].$image_captions | Optional

The captions associated with the image.

content_items[i].$condition | Optional

For auctions, whether the item is new, good, acceptable, etc.

One of:
OTHER
NEW
EXCELLENT
GOOD
FAIR
POOR
USED
REFURBISHED

content_items[i].$custom_fields | Optional

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

🚧

Note about required identifiers

You must send up (in user_data):

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

Sample Request - Commerce

curl -vvv -d '{
  "name": "PURCHASE",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "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

Sample Response - Commerce

{ "branch_view_enabled": true/false }

Logging Content Events

Endpoint - Content

POST /v2/event/standard
Content-Type: application/json

Parameters - Content

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

name | REQUIRED

The name of the event to log. Can be one of the following: SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE

customer_event_alias | Optional

The event alias as defined by you; used in addition to the event name defined above

user_data.os | REQUIRED

one of "Android", "iOS"

user_data.os_version | Optional

The version of the operating system. Specific to Android and iOS.

user_data.environment | Optional

usually FULL_APP

user_data.aaid | Optional

The Android/Google advertising ID.

user_data.android_id | Optional

Android hardware ID

user_data.idfad | Optional

iOS advertising ID

user_data.idfv | Optional

iOS vendor ID

user_data.limit_ad_tracking | Optional

true if the partner has opted to not be tracked by advertisers

user_data.user_agent | Optional

The user agent of the browser or app where the event occurred. Usually associated with a webview.

user_data.browser_fingerprint_id | Optional

Branch internal-only field for tracking browsers.

user_data.http_origin | Optional

The current page url where Web SDK logged web session start.

user_data.http_referrer | Optional

The referral url that led to the current page where Web SDK logged web session start.

user_data.developer_identity | Optional

The developer-specified identity for a user.

user_data.country | Optional

The country code of the user, usually based on device settings or user agent string.

user_data.language | Optional

The language code of the user, usually based on device settings or user agent string.

user_data.ip | YES

The ip address for the device where the event occurred

user_data.local_ip | Optional

Android only : local ip of the device (e.g. "168.1.1.1")

user_data.brand | Optional

The brand of the device

user_data.device_fingerprint_id | Optional

Branch internal-only field for tracking devices.

user_data.app_version | Optional

The app version downloaded by the user.

user_data.model | Optional

The model of the device.

user_data.screen_dpi | Optional

The screen's DPI.

user_data.screen_height | Optional

The screen's height.

user_data.screen_width | Optional

The screen's width.

custom_data | Optional

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.

event_data.transaction_id | Optional

The partner-specified transaction id for their internal use

event_data.revenue | Optional

The partner-specified reported revenue for the event.

event_data.currency | Optional

Currency that revenue, price, shipping, tax were originally reported in by the partner

event_data.shipping | Optional

Shipping cost associated with the transaction.

event_data.tax | Optional

Total tax associated with the transaction.

event_data.coupon | Optional

Transaction coupon redeemed with the transaction (e.g. "SPRING2017")

event_data.affiliation | Optional

Store or affiliation from which this transaction occurred (e.g. Google Store)

event_data.description | Optional

Description associated with the event, not necessarily specific to any individual content items (see below)

content_items[i].$content_schema | Optional

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

content_items[i].$og_title | Optional

The title (for the individual content item).

content_items[i].$og_description | Optional

The description (for individual content item).

content_items[i].$og_image_url | Optional

The image URL (for the individual content item).

content_items[i].$canonical_identifier | Optional

used to allow Branch to unify content/messages for Content Analytics

content_items[i].$publicly_indexable | Optional

true: content can be seen by anyone | false: cannot index for public use

content_items[i].$locally_indexable | Optional

true: content can be indexed for local (device) use | false: cannot index for local use

content_items[i].$price | Optional

The price for the product/content.

content_items[i].$quantity | Optional

The quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc).

content_items[i].$sku | Optional

The product sku or product ID.

content_items[i].$product_name | Optional

The product's name.

content_items[i].$product_brand | Optional

The product's brand.

ccontent_items[i].$product_category | Optional

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

content_items[i].$product_variant | Optional

The product's variant (e.g. XL, red).

content_items[i].$rating_average | Optional

The average rating of the item.

content_items[i].$rating_count | Optional

The number of ratings for the item.

content_items[i].$rating_max | Optional

The maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating).

content_items[i].$creation_timestamp | Optional

The time the content was created.

content_items[i].$exp_date | Optional

The last time after which this content is no longer valid. null / 0 mean no limit. Should rarely be set.

content_items[i].$keywords | Optional

keywords

content_items[i].$address_street | Optional

The street address for a restaurant, business, room (hotel), etc.

content_items[i].$address_city | Optional

The street address for a restaurant, business, room (hotel), etc.

content_items[i].$address_region | Optional

The state or region for a restaurant, business, room (hotel), etc.

content_items[i].$address_country | Optional

The country code for a restaurant, business, room (hotel), etc.

content_items[i].$address_postal_code | Optional

The postal/zip code for a restaurant, business, room (hotel), etc.

content_items[i].$latitude | Optional

The latitude for a restaurant, business, room (hotel), etc.

content_items[i].$longitude | Optional

The longitude for a restaurant, business, room (hotel), etc.

content_items[i].$image_captions | Optional

The captions associated with the image.

content_items[i].$condition | Optional

For auctions, whether the item is new, good, acceptable, etc.

One of:
OTHER
NEW
EXCELLENT
GOOD
FAIR
POOR
USED
REFURBISHED

content_items[i].$custom_fields | Optional

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.

🚧

Note about required identifiers

You must send up (in user_data):

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

Sample Request - Content

curl -vvv -d '{
  "name": "VIEW_ITEMS",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "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

Sample Response - Content

{ "branch_view_enabled": true/false }

Logging User Lifecycle Events

Endpoint - Lifecycle

POST /v2/event/standard
 Content-Type: application/json

Parameters - Lifecycle

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

name | REQUIRED

The name of the event to log. Can be one of the following: ADD_TO_CART, ADD_TO_WISHLIST, CLICK_AD, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS

user_data.os | REQUIRED

one of "Android", "iOS"

user_data.os_version | Optional

The version of the operating system. Specific to Android and iOS.

user_data.environment | Optional

usually FULL_APP

user_data.aaid | Optional

The Android/Google advertising ID.

user_data.android_id | Optional

Android hardware ID

user_data.idfa | Optional

iOS advertising ID

user_data.idfv | Optional

iOS vendor ID

user_data.limit_ad_tracking | Optional

true if the partner has opted to not be tracked by advertisers

user_data.user_agent | Optional

The user agent of the browser or app where the event occurred. Usually associated with a webview.

user_data.browser_fingerprint_id | Optional

Branch internal-only field for tracking browsers.

user_data.http_origin | Optional

The current page url where Web SDK logged web session start.

user_data.http_referrer | Optional

The referral url that led to the current page where Web SDK logged web session start.

user_data.developer_identity | Optional

The developer-specified identity for a user.

user_data.country | Optional

The country code of the user, usually based on device settings or user agent string.

user_data.language | Optional

The language code of the user, usually based on device settings or user agent string.

user_data.ip | REQUIRED

The ip address for the device where the event occurred

user_data.local_ip | Optional

Android only : local ip of the device (e.g. "168.1.1.1")

user_data.brand | Optional

The brand of the device

user_data.device_fingerprint_id | Optional

Branch internal-only field for tracking devices.

user_data.app_version | Optional

The app version downloaded by the user.

user_data.model | Optional

The model of the device.

user_data.screen_dpi | Optional

The screen's DPI.

user_data.screen_height | Optional

The screen's height.

user_data.screen_width | Optional

The screen's width.

custom_data | Optional

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.

event_data.description | Optional

Description associated with the event.

🚧

Note about required identifiers

You must send up (in user_data):

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

Sample Request - Lifecycle

curl -vvv -d '{
  "name": "COMPLETE_REGISTRATION",
  "user_data": {
    "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

Sample Response - Lifecycle

{ "branch_view_enabled": true/false }

Logging Custom Events

Endpoint - Custom

POST /v2/event/custom
Content-Type: application/json

Parameters - Custom

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

name | REQUIRED

The name of the event to log. Can be a string of custom event name. For instance "picture swiped".

user_data.os | REQUIRED

one of "Android", "iOS"

user_data.os_version | Optional

The version of the operating system. Specific to Android and iOS.

user_data.environment | Optional

usually FULL_APP

user_data.aaid | Optional

The Android/Google advertising ID.

user_data.android_id | Optional

Android hardware ID

user_data.idfa | Optional

iOS advertising ID

user_data.idfv | Optional

iOS vendor ID

user_data.limit_ad_tracking | Optional

true if the partner has opted to not be tracked by advertisers

user_data.user_agent | Optional

The user agent of the browser or app where the event occurred. Usually associated with a webview.

user_data.browser_fingerprint_id | Optional

Branch internal-only field for tracking browsers.

user_data.http_origin | Optional

The current page url where Web SDK logged web session start.

user_data.http_referrer | Optional

The referral url that led to the current page where Web SDK logged web session start.

user_data.developer_identity | Optional

The developer-specified identity for a user.

user_data.country | Optional

The country code of the user, usually based on device settings or user agent string.

user_data.language | Optional

The language code of the user, usually based on device settings or user agent string.

user_data.ip | REQUIRED

The ip address for the device where the event occurred

user_data.local_ip | Optional

Android only : local ip of the device (e.g. "168.1.1.1")

user_data.brand | Optional

The brand of the device

user_data.device_fingerprint_id | Optional

Branch internal-only field for tracking devices.

user_data.app_version | Optional

The app version downloaded by the user.

user_data.model | Optional

The model of the device.

user_data.screen_dpi | Optional

The screen's DPI.

user_data.screen_height | Optional

The screen's height.

user_data.screen_width | Optional

The screen's width.

custom_data | Optional

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.

event_data.description | **

Description associated with the event.

🚧

Note about required identifiers

You must send up (in user_data):

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

Sample Request - Custom

curl -vvv -d '{
  "name": "picture swiped",
  "customer_event_alias": "my custom alias",
  "user_data": {
    "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

Sample Response - Custom

{ }

Getting Current Branch App Config

Endpoint - Get App Config

GET /v1/app/[branch key]?branch_secret=[branch secret]

Parameters - Get App Config

Parameters

branch_key | REQUIRED

The Branch key of the originating app; from your Branch Settings Dashboard

branch_secret | REQUIRED

The Branch secret if the originating app; from your Branch Settings Dashboard

Returns - Get App Config

{
    branch_key: "the app key",
    branch_secret: "the app secret",
    creation_date : "date app was created",

    app_name: "name of the app",

    dev_name: "main contact name",
    dev_email: "main contact email",
    dev_phone_number: "main contact phone",

    android_app: "whether an Android app is enabled",
    android_url: "url of Android store, or namespace (com.android.myapp)",
    android_uri_scheme: "the Android URI scheme",
    android_package_name: "the Android package name",
    sha256_cert_fingerprints: "the SHA256 fingerprints for App Links",
    android_app_links_enabled: "whether App Links are enabled",

    ios_app: "whether an iOS app is enabled",
    ios_url: "url of iOS store, or app id (id512451233)",
    ios_uri_scheme:  "the iOS URI scheme",
    ios_store_country: "the country code of the app, default to US",
    ios_bundle_id: "the iOS bundle ID",
    ios_team_id: "the iOS Team ID",
    universal_linking_enabled: "whether Universal Links are enabled",

    fire_url: "the redirect on Fire phones",
    windows_phone_url: "the redirect on Windows phones",
    blackberry_url: "The redirect on Blackberry phones",
    web_url: "backup website if URLs are null",
    default_desktop_url: "the default desktop redirect, or null if set to hosted SMS",

    short_url_domain: "white labeled domain for short links",

    text_message: "text message to use, {{ link }} will be replaced with short link",

    og_app_id: "optional default Open Graph (OG) app id",
    og_title: "optional default OG title",
    og_image_url: "optional default OG image URL",
    og_description: "optional default OG description",
    
    deepview_desktop: "the current deepview selected for the desktop platform",
    deepview_ios: "the current deepview selected for the iOS platform",
    deepview_android: "the current deepview selected for the Android platform",
  }

Updating a Branch App Config

Endpoint - Update App Config

PUT /v1/app/:branch_key
Content-Type: application/json

Parameters - Update App Config

Parameters

branch_secret | REQUIRED

The Branch secret if the originating app; from your Branch Settings Dashboard

app_name | Optional

The name of the app (max 255 characters).

dev_name | Optional

The main contact developer name (max 255 characters).

dev_email | Optional

The main contact developer email (max 255 characters).

android_url | Optional

The url of the Android store, or package name (com.android.myapp). Note that to set a fallback URL for Android instead, you must also set android_app to 2.

android_uri_scheme | Optional

The Android URI scheme.

ios_url | Optional

The url of iOS store, or app id (id512451233)

ios_uri_scheme | Optional

The iOS URI scheme.

ios_store_country | Optional

The country code of the app, default to US (max 255 characters).

web_url | Optional

Backup website if URLs are null.

text_message | Optional

The text message to use for text-me feature, {{ link }} will be replaced with short link (max 255 characters).

og_app_id | Optional

Default Open Graph (OG) app id (max 255 characters).

og_title | Optional

Default OG title to be used with links (max 255 characters).

og_description | Optional

Default OG description to be used with links (max 255 characters).

og_image_url | Optional

Default OG image URL to be used with links (max 255 characters).

Returns - Update App Config

{
    branch_key: "the app key",
    branch_secret: "the app secret",
    creation_date : "date app was created",

    app_name: "name of the app",

    dev_name: "main contact name",
    dev_email: "main contact email",
    dev_phone_number: "main contact phone",

    android_url: "url of Android store, or namespace (com.android.myapp)",
    android_uri_scheme: "the Android URI scheme",

    ios_url: "url of iOS store, or app id (id512451233)",
    ios_uri_scheme:  "the iOS URI scheme",
    ios_store_country: "the country code of the app, default to US",

    web_url: "backup website if URLs are null",

    short_url_domain: "white labeled domain for short links",

    text_message: "text message to use, {{ link }} will be replaced with short link",

    og_app_id: "optional default Open Graph (OG) app id",
    og_title: "optional default OG title",
    og_image_url: "optional default OG image URL",
    og_description: "optional default OG description"
  }

Updated 6 months ago

Deep Linking API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.