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.
API Limitations
Limitation | Details |
---|---|
Rate Limits |
|
Prerequisites & API Access
In order to access the Deep Linking API, you need to have completed the following:
- Created a Branch Dashboard
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
Header | 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 |
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 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. | No |
type | Set to 0 by default, which represents standard Branch links created via the Branch SDK. | No |
duration | 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). | No |
Branch analytics parameters | 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. | No |
identity | 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 | No |
Response Body Parameters
Parameter | Description |
---|---|
url | The deep link 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 links, see the Branch link creation guide
Request Headers
Header | Value | Required |
---|---|---|
Content-Type | application/json | Yes |
Request Body Parameters
A json array of parameters from Creating a Deep Linking URL.
Parameter | Description | Required |
---|---|---|
branch_key | The Branch key of the originating app; from your Branch Settings Dashboard | Yes |
Branch Parameters | A 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 link. These parameters will be passed to your app via the Branch SDK. | No |
Note
There is a 100KB limit on the request payload size.
Response Parameters
Parameter | Description |
---|---|
url[] | An array of deep linking URLs. |
error | error(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
Header | Value | Required |
---|---|---|
Content-Type | application/json | Yes |
Request Body Parameters
Parameter | Description | Required |
---|---|---|
access_key | Your API Key / Access Token; Learn how to retrieve your API key (a.k.a. Access Token) | Yes |
url | The Deep Link URL to be deleted | Yes |
Response Parameters
Parameter | Description |
---|---|
url | The Deep Link URL to be deleted |
deleted | Returns 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
Header | 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 |
url | The deep link url you want read. | Yes |
Response Parameters
Parameter | Description |
---|---|
array of properties | Returns Android SDK deep link properties](/using-branch/docs/creating-a-deep-link#section-read-deep-links). |
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 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.
- If you want to add custom key/value pairs to the
data
object, you will need to do it outside of the API Reference.
Endpoint
PUT /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io
Request Headers
Header | 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 |
branch_secret | The Branch secret if the originating app; from your Branch Settings Dashboard | Yes |
url | The 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"
}
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
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("\n \n")
print(r.url)
print(r)
# print
ifile.close()
Link Update Restrictions
There are certain restrictions when attempting to update links:
- Not all links are updateable, namely links with the structure of
bnc.lt/c/
orbnc.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
randomized_bundle_token
domain
state
creation_source
app_short_identifier