✕
Filters
Submit a TicketBranch DashboardBranch University

Deep Linking API

Overview

Branch's Deep Linking API is a powerful tool for all things Branch Links. You can programmatically generate links at scale to support all of your campaigns while tagging the links appropriately based on channel and other analytics tags.

📘

Account Requirements

In order to create Branch Links via the Deep Linking API, you need to be a Self-Serve Customer or an Enterprise Customer.

API Limitations

Limitation

Details

Rate Limits

100 requests per second
5,500 requests per minute
300,000 requests per hour

Please note that 300,000 requests per hour equates to 83 requests per second.

Prerequisites & API Access

In order to access the Deep Linking API, you first need to:

  1. Create a Branch Dashboard.
  2. Set appropriate user permissions in your Branch account. If you want to access the DELETE method for this endpoint, you will need both App-Level and Sensitive Data permissions.

Authentication

Calls to the Deep Linking API require both your Branch Key and (sometimes) Branch Secret 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.

For some calls, you will also need your Branch Access Token. This can be obtained from your Branch Dashboard User Settings.

Learn more on retrieving your Access Token here.

API Usage

Create a Deep Link URL

Endpoint

POST /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters:

Parameter

Description

Required

branch_key

The Branch Key of the originating app, found in the Settings tab of your Branch Dashboard.

Yes

data

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.

No

alias

Instead of Branch's standard encoded short URL, you can specify a 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 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, a HTTP 409 error will be returned.


Warning: Non-letter characters should not be used in the alias, with the exception of forward slashes /, underscores _, and hyphens -. Doing so will result in a broken Deep Link.

No

type

Set to 0 by default, which represents standard Branch links created via the Branch SDK.

No
durationIn seconds. Only set this key if you want to override the match duration for Branch 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).No
Branch analytics parametersIt's important to tag your links with an organized structure of analytics labels so that the data appears consistent and readable in the dashboard.No

Response Body Parameters

ParameterDescription
urlThe URL created by this endpoint.

Example Request/Response

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" }
  }
}'

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

Bulk Create Deep Link URLs

Endpoint

POST /v1/url/bulk/{branch_key}
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

For more details on how to create Branch Deep Links, see the Branch guide for creating Deep Links.

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters

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

ParameterDescriptionRequired
branch_keyThe Branch Key of the originating app, found in the Settings tab of your Branch Dashboard.Yes
Branch ParametersA JSON array of parameters from Creating a Deep Linking URL.
You're free to add any of your own key-value parameters to a Branch Deep Link. These parameters will be passed to your app via the Branch SDK you are using.		No

📘

Note

There is a 100KB limit on the request payload size.

Response Parameters

ParameterDescription
urlAn array of Branch Deep Link URLs.
errorError(s) if there are invalid params.

Example Request/Response

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"
      }
    }
  ]'

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

Delete Existing Deep Link

Endpoint

DELETE /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

📘

Not Available in Testing Environment

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters

ParameterDescriptionRequired
access_keyYour API Key (also called Access Token). Learn how to retrieve your API key here.Yes
urlThe Branch Deep Link URL to be deleted.Yes

Response Parameters

ParameterDescription
urlThe Branch Deep Link URL to be deleted.
deletedReturns true if the URL has been successfully deleted, false if not.

Example Request/Response

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"

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

Read Existing Deep Link

Endpoint

GET /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters

ParameterDescriptionRequired
branch_keyThe Branch Key of the originating app, found in the Settings tab of your Branch Dashboard.Yes
urlThe Branch Deep Link URL you want read.Yes

Response Parameters

ParameterDescription
array of propertiesReturns Deep Link properties.

Example Request/Response

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

{
  "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
}

Update Existing Deep Link

📘

Link Update Tips

  • A Branch Deep Link's data object is overwritten entirely by this API call, so make sure to include all of the Branch Deep Link's data when updating it and not just the data you're changing.
  • To update Branch Deep Links in bulk, combine the update and read methods when creating a script.
  • If you want to add custom key/value pairs to the data object, you will need to do it outside of the API Reference.

🚧

Link Update Restrictions

There are certain restrictions when attempting to update links:

  • Not all links can be updated, namely links with the structure of bnc.lt/c/ or bnc.lt/d/.
  • The following fields cannot be updated:
    • alias (for example, you cannot change https://bnc.lt/test to https://bnc.lt/test1)
    • identity
    • type
    • app_id
    • randomized_bundle_token
    • domain
    • state
    • creation_source
    • app_short_identifier

Endpoint

PUT /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

HeaderValueRequired
Content-Typeapplication/jsonYes

Request Body Parameters:

ParameterDescriptionRequired
branch_keyThe Branch Key of the originating app, found in the Settings tab of your Branch Dashboard.Yes
branch_secretThe Branch Secret of the originating app, found in the Settings tab of your Branch Dashboard.Yes
urlThe Branch Deep Link URL you want updated.Yes

Example Request/Response

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"
  }
}'

{
  "data": {
    "+url": "https://example.app.link/5IULiLcpqF",
    "~creation_source": 0,
    "user_id": "12346",
    "$one_time_use": false,
    "~id": "423196096467215333",
    "name": "alex",
    "~campaign": "new product",
    "~channel": "twitter",
    "$identity_id": "755468067194863158",
    "~stage": "new user",
    "~feature": "onboarding",
    "url": "https://example.app.link/5IULiLcpqF"
  },
  "type": 0,
  "campaign": "new product",
  "feature": "onboarding",
  "channel": "twitter",
  "stage": "new user"
}

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

def BranchUpdateModule(KeyV, SecretV, UpdateV, File):
    # Insert API key & App Secret from the Branch dashboard, and the Link data key you want to change in each link **
    branch_key = KeyV
    branch_secret = SecretV
    key_to_update = UpdateV


    # Insert filename for CSV containing links to update in first column, and values to add in second column **
    ifile = open(File, "r", encoding="utf-8")

    # 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.parse.quote_plus(row[0])
        getrequest = branchendpoint + url + "&branch_key=" + branch_key
        linkdata = requests.get(getrequest)
        jsonData = json.loads(linkdata.text)

        if linkdata.status_code != 200:
            print('Failed: {}'.format( getrequest))
            continue

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

        #TODO for editing new value
        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

        if jsonData.get('type', None) is not None:
            del jsonData['type']
        if jsonData.get('alias', None):
            del jsonData['alias']
        payload = json.dumps(jsonData)
        print("\n \n payload")
        print(payload)
        putrequest = branchendpoint + url

        print(putrequest)
        r = requests.put(putrequest, json=jsonData)
        print(r.url)
        print(r)
        
    ifile.close()