Branch-Public-API

A public API to tie into for fancy integrations. All endpoints are appended to https://api2.branch.io

API Reference

URL Management
Logging Events
Branch App Settings Management
Custom Events (deprecated)
- Create a custom events
- Create a custom commerce events

Creating a Deep Linking URL

Endpoint

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

Parameters

branch_key required : The Branch key of the originating app.

Functional

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 (max 128 characters) : Instead of our standard encoded short url, you can specify the alias of the link bnc.lt/devonaustin. Aliases are enforced to be unique per domain (bnc.lt, yourapp.com, etc). Be careful, link aliases are unique, immutable objects that cannot be deleted.

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

Set type to 1, to make the URL a one-time use URL. It won't deep link after 1 successful deep link.
default is set to 0, which is the standard Branch links created via our SDK.git

duration optional : ADVANCED: 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)

Tracking

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 (max 127 characters) : The identity used to identify the user. If the link is not tied to an identity, there's no need to specify an identity.

Returns

  {
    'url': 'http://bnc.lt/l/deeplink-randomID'
  }

Example

Here's an example cURL that you can paste into the terminal

curl -X POST \
\
-H "Content-Type: application/json" \
\
-d '{"branch_key":"key_live_feebgAAhbH9Tv85H5wLQhpdaefiZv5Dv", "campaign":"new_product_annoucement", "channel":"email", "tags":["monday", "test123"], "data":"{\"name\": \"devon\", \"email\": \"devon@branch.io\", \"user_id\": \"12346\", \"$deeplink_path\": \"article/jan/123\", \"$desktop_url\": \"https://branch.io\"}"}' \
\
https://api2.branch.io/v1/url

Bulk creating Deep Linking URLs

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

Endpoint

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

Parameters

A json array of pramameters from Creating a Deep Linking URL. (Note: there is a 100KB limit on the request payload size)

[
   { "channel": "branch" },
   { "channel": "fb", "data": "{ \"$og_title\": \"deep linking\" }" }
]

Returns

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

  [
   { 'url': 'http://bnc.lt/l/deeplink-randomID' },
   { 'error': 'error message' }  // in case of error
  ]

Modifying Existing Deep Linking URLs

We've exposed an endpoint to update a certain category of Branch links through our API. Simply issue a PUT to our v1/url endpoint. Certain links may not be updated, which are /c/ and /d/ links.

Endpoint

    PUT /v1/url?url=<url>
    Content-Type: application/json

Parameters

branch_key required : The Branch key of the originating app. Found in the Branch Dashboard under Settings.

branch_secret required : The paired Branch Secret to the Branch Key making the request. Found in the Branch Dashboard under Settings.

url required : The URL you want to modify, including the host and domain, ex: https://bnc.lt/m/abcd1234, this is included on the URL to request itself:

PUT https://api2.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Ftest

analytics/tracking parameters optional

: Branch analytics parameters. Use these keys inside the body of the PUT (NOT inside the 'data' key) to modify data such as channel, campaign, tags, and more.

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.

Example

If you have a link with a URL of https://bnc.lt/test-link, a channel of 'facebook', and data of { "photo_id" : "50", "valid": "true" } and want to update the channel, add an extra value to the dictionary, and add a campaign, here's how that would look:

PUT https://api2.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Ftest-link

{
    "branch_key" : "key_live_xxxx",
    "branch_secret": "secret_live_xxxx",
    "channel": "twitter",
    "campaign": "twitter-november-campaign",
    "data": {
        "photo_id": "51",
        "photo_name": "John Smith",
        "$og_image_url": "https://imgur.com/abcd"
    }
}

Returns

The new link returns existing data of the link plus the newly added data of the link. Following the example above, this is what would return.

{
   "channel": "twitter",
   "campaign": "twitter-november-campaign",
   "feature": "share-button",
   "data": {
       "photo_id": "51",
       "valid": "true",
       "photo_name": "John Smith",
       "$og_image_url": "https://imgur.com/abcd",
       "~id": "123456789",
       "url": "https://bnc.lt/test-link"
   },
   "alias": "test-link",
   "type": 0
}

Note, some of this data is existing link data, and some is updated data, but the response will return all data.

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

Viewing State of Existing Deep Linking URLs

We've exposed an endpoint to view the contents of Branch links through our API. Simply issue a GET to our v1/url endpoint with the URL you'd like to view.

Endpoint

    GET /v1/url?url=<url>&branch_key=<branch key>

Parameters

branch_key required : The Branch key of the originating app. Found in the Branch Dashboard under Settings.

url required : The URL you want to modify, including the host and domain, ex: https://bnc.lt/m/abcd1234, this is included on the URL to request itself:

Example

If you have a link with a URL of https://bnc.lt/m/7IhbRIjjmp with Branch key of key_live_lceUuShIL0u4VHJv8BwEQmaitBfAXqCZ:

GET https://api2.branch.io/v1/url?url=https%3A%2F%2Fbnc.lt%2Fm%2F7IhbRIjjmp&branch_key=key_live_lceUuShIL0u4VHJv8BwEQmaitBfAXqCZ

Returns

The new link returns existing data of the link. Following the example above, this is what would return.

{
   "channel": "twitter",
   "campaign": "twitter-november-campaign",
   "feature": "share-button",
   "data": {
       "photo_id": "51",
       "valid": "true",
       "photo_name": "John Smith",
       "$og_image_url": "https://imgur.com/abcd",
       "~id": "123456789",
       "url": "https://bnc.lt/test-link"
   },
   "alias": "test-link",
   "type": 0
}

Structuring a 'dynamic' deep link for app.link domains

This should be used for situations where the longer link is okay and you want to create links quickly without a POST to the API. Here's a list of instructions on how to build a deep link:

Start with your Branch domain, http://yourapp.app.link.
[optional] Append the start of query params '?'
[optional] Append the Branch analytics tag to keep your data organized in the dashboard. (list here) channel=email&tags[]=drip1&tags[]=welcome
[optional] Append any custom deep link parameters &user_id=4562&name=devon&article_id=456
[optional] Append your Branch control parameters - see a full list of them here

Endpoint

  GET https://yourapp.app.link?AnyOptionalQueryParamsBelow

Example: https://branch.app.link?$deeplink_path=article%2Fjan%2F123&$fallback_url=https%3A%2F%2Fgoogle.com&channel=facebook&feature=affiliate

Parameters

For consistency, all parameters are kept in one spot since they are used for everything. Please find them in the Link Configuration guide

Structuring a 'dynamic' deep link for bnc.lt and custom domains

This should be used for situations where the longer link is okay and you want to create links quickly without a POST to the API. Here's a list of instructions on how to build a deep link:

Start with your Branch domain, http://bnc.lt (or your white labeled one).
Append /a/your_Branch_key.
[optional] Append the start of query params '?'
[optional] Append the Branch analytics tag to keep your data organized in the dashboard. (list here) channel=email&tags[]=drip1&tags[]=welcome
[optional] Append any custom deep link parameters &user_id=4562&name=devon&article_id=456
[optional] Append your Branch control parameters - see a full list of them here

Endpoint

  GET https://bnc.lt/a/<branch_key>?AnyOptionalQueryParamsBelow

Example: https://bnc.lt/a/key_live_jbgnjxvlhSb6PGH23BhO4hiflcp3y7ky?$deeplink_path=article%2Fjan%2F123&$fallback_url=https%3A%2F%2Fgoogle.com&channel=facebook&feature=affiliate

Parameters

For consistency, all parameters are kept in one spot since they are used for everything. Please find them in the Link Configuration guide

Logging Commerce Events

Endpoint

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

Parameters

Note about required identifiers. You must send up (in user_data):

developer_identity OR
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

branch_key required : the app's branch_key

name required : one of ADD_TO_CART, ADD_TO_WISHLIST, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS

user_data.os required : one of "Android", "iOS"

user_data.os_version : version of the operating system. Specific to Android and iOS.

user_data.environment : usually FULL_APP.

user_data.aaid : Android/Google advertising id

user_data.android_id : Android hardware id

user_data.idfa : iOS advertising id

user_data.idfv : iOS vendor id

user_data.limit_ad_tracking : true if the partner has opted to not be tracked by advertisers

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

user_data.browser_fingerprint_id : Branch internal-only field for tracking browsers

user_data.http_origin : current page url where Web SDK logged web session start

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

user_data.developer_identity : developer-specified identity for a user

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

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

user_data.local_ip Android only : local ip of the device

user_data.brand : brand of the device

user_data.device_fingerprint_id : Branch internal-only field for tracking devices

user_data.app_version : app version downloaded by the user

user_data.model : model of the device

user_data.screen_dpi : screen's DPI

user_data.screen_height : screen's height

user_data.screen_width : screen's width

custom_data : 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 : partner-specified transaction id for their internal use

event_data.revenue : partner-specified reported revenue for the event

event_data.currency : Currency that revenue, price, shipping, tax were orginally reported in by the partner

event_data.shipping : Shipping cost associated with the transaction

event_data.tax : Total tax associated with the transaction

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

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

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

content_items[i].$content_schema : 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 : title (for the individual content item)

content_items[i].$og_description : description (for individual content item)

content_items[i].$og_image_url : image URL (for the individual content item)

content_items[i].$canonical_identifier : used to allow Branch to unify content/messages for Content Analytics

content_items[i].$publicly_indexable : true: content can be seen by anyone | false: cannot index for public use

content_items[i].$locally_indexable : true: content can be indexed for local (device) use | false: cannot index for local use

content_items[i].$price : price for the product/content

content_items[i].$quantity : quantity of the item to be ordered (for PURCHASE, ADD_TO_CART, etc)

content_items[i].$sku : product sku or product id

content_items[i].$product_name : product's name

content_items[i].$product_brand : product's brand

content_items[i].$product_category : 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 : product's variant (e.g. XL, red)

content_items[i].$rating_average : average rating of the item

content_items[i].$rating_count : number of ratings for the item

content_items[i].$rating_max : maximum possible rating for the item (e.g. 5.0 if 5 stars is highest possible rating)

content_items[i].$creation_timestamp : time the content was created

content_items[i].$exp_date : the last time afterwhich this content is no longer valid. null / 0 mean no limit. Should rarely be set.

content_items[i].$keywords : keywords

content_items[i].$address_street : street address for a restaurant, business, room (hotel), etc

content_items[i].$address_city : street address for a restaurant, business, room (hotel), etc

content_items[i].$address_region : state or region for a restaurant, business, room (hotel), etc

content_items[i].$address_country : country code for a restaurant, business, room (hotel), etc

content_items[i].$address_postal_code : postal/zip code for a restaurant, business, room (hotel), etc

content_items[i].$latitude : latitude for a restaurant, business, room (hotel), etc

content_items[i].$longitude : longitude for a restaurant, business, room (hotel), etc

content_items[i].$image_captions : captions associated with the image

content_items[i].$condition : 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 : 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.

metadata : internal use only

Request

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

Response

{ "branch_view_enabled": true/false }

Logging Content Events

Endpoint

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

Parameters

Note about required identifiers. You must send up (in user_data):

developer_identity OR
browser_fingerprint_id OR
os=iOS AND (idfa OR idfv) OR
os=Android AND (android_id or aaid)

branch_key required : the app's branch_key

name required : one of SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE