Programmatically generate links at scale to support all of your campaigns
Overview
Branch's Deep Linking API is a powerful tool for all things Branch Links. With the Deep Linking API, you can generate links in bulk while also tagging them appropriately based on channel
, or other analytics tags.
Benefits
With the Deep Linking API, you can both create and update Branch Deep Links in bulk. You can also read information from previously created Deep Links, as well as delete Deep Links.
Limitations
Request Type | Max Requests Per Second | Max Requests Per Minute | Max Requests Per Hour |
---|---|---|---|
PUT | 100 | 1,000 | 10,000 |
POST | 200 | 12,000 | 300,000 Please note this equates to ~83 requests per second. |
GET | 100 | 5,500 | 100,000 |
Try It!
Try out the Deep Linking API in your browser, using your Branch data:
Getting Started
Prerequisites
In order to use the Deep Linking API, you first need to:
- Be a Self-Serve Customer or an Enterprise Customer.
- Create a Branch Dashboard.
- 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.
Access
Calls to the Deep Linking API require your Branch Key.
Sometimes, your Branch Secret is also required.
Both your Branch Key and your Branch Secret can be obtained through your Branch Dashboard Account Settings.
NOTE: If you want to access the DELETE
method for this endpoint, you will need both App-Level and Sensitive Data permissions. Learn more in the Authentication section.
Learn more about your Branch Account Profile here.
Authentication
To use the DELETE
request associated with this API, you also need to pass an API key (also called Access Token). API keys are generated on a per-user basis and are permanent.
Learn more about retrieving your API key here.
Usage
Create a Deep Link URL
Request Info
Export Request
POST /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io
Request Headers
Header | Value | Required |
---|---|---|
content-type | application/json | Yes |
accept | application/json | Yes |
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. | 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/example .NOTE: If you send a POST request 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 400 error will be returned.WARNING: Non-letter characters should not be used in the alias , with the exception of forward slashes / , underscores _ , and hyphens - . The max limit for a vanity alias is 128 characters. | No |
type | Set to 0 by default, which represents standard Branch Links created via the Branch SDK. | No |
duration | Match duration in seconds. Default is set to 7200 (2 hours).This is the time that Branch allows a click to remain outstanding and be eligible to be matched with a new app session. Only set this key if you want to override the match duration for Branch Deep Link matching. | No |
Branch Analytics Parameters | Add additional parameters to tag your links with an organized structure of labels. This helps your data appear consistent and readable in your Branch Dashboard. | No |
Response Info
Response Body Parameters
Parameter | Description |
---|---|
url | The 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
Request Info
Export Request
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 our guide.
Request Headers
Header | Value | Required |
---|---|---|
content-type | application/json | Yes |
accept | application/json | Yes |
Request Path Parameters
Parameter | Description | Required |
---|---|---|
branch_key | The Branch Key of the originating app, found in the Settings tab of your Branch Dashboard. | Yes |
Request Body Parameter
Parameter | Description | Required |
---|---|---|
Branch Parameters | A JSON array of parameters associated with the Deep Links. 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 relevant Branch SDK. Learn more about configuring Branch Deep Links here. | No |
Limitations
Please note that there is a 100KB limit on request payload size for bulk Deep Link creation.
Response Info
Response Parameters
Parameter | Description |
---|---|
url | An array of Branch Deep Link URLs. |
error | Error(s) if there are invalid params. |
Example Request & Response
curl -XPOST https://api2.branch.io/v1/url/bulk/key_live_XXX -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
Request Info
Export Request
DELETE /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io
Request Headers
Header | Value | Required |
---|---|---|
Access-Token | Key that encapsulates the user's permission with regards to an organization. Obtained from the Branch Dashboard. Needed for authentication. | Yes |
accept | application/json | Yes |
content-type | application/json | Yes |
Request Body Parameters
Parameter | Description | Required |
---|---|---|
url | The Branch Deep Link URL to be deleted. | Yes |
app_id | The Branch app_id associated with the Branch Deep Link URL to be deleted. | Yes |
Limitations
Please note that this endpoint is not available in test environments.
Response Info
Response Parameters
Parameter | Description |
---|---|
url | The relevant Branch Deep Link URL. |
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
Request Info
Export Request
GET /v1/url
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io
Request Headers
Header | Value | Required |
---|---|---|
content-type | application/json | Yes |
accept | application/json | Yes |
Request Query Parameters
Parameter | Description | Required |
---|---|---|
branch_key | The Branch Key of the originating app, found in the Settings tab of your Branch Dashboard. | Yes |
url | The Branch Deep Link URL you want read. | Yes |
Response Info
Response Parameters
Parameter | Description |
---|---|
A JSON Object | A JSON object containing 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
Warnings
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/
orbnc.lt/d/
.- The following fields cannot be updated:
alias
(for example, you cannot changehttps://bnc.lt/test
tohttps://bnc.lt/test1
)identity
type
app_id
randomized_bundle_token
domain
state
creation_source
app_short_identifier
Data Object Override
Make sure to include all of the Deep Link's data when making this request, not just the data you are changing. This is because the Branch Deep Link's data object is overwritten entirely by this API call.
Request Info
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 |
accept | application/json | Yes |
Request Query Parameters
Parameter | Description | Required |
---|---|---|
url | The Branch Deep Link URL you want updated. | Yes |
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 |
branch_secret | The Branch Secret of the originating app, found in the Settings tab of your Branch Dashboard. | Yes |
data | An object containing data about the Branch Deep Link. | No |
analytics | An object containing analytics tag information related to the Branch Deep Link. | No |
Branch Deep Link keys | Define the value for a key, like channel or duration . | No |
Response Info
Response Parameters
Parameter | Description |
---|---|
data | An object containing data about the Branch Deep Link. |
type | An integer, usually 0 , that reflects the type of the Branch Deep Link. |
Branch Analytics Parameters | Additional parameters you have set for the Branch Deep Link, for example campaign or feature . |
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"
}
Example Automation Script
If you would like to update Branch Deep Links in bulk, combine the PUT
and GET
methods 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(r.url)
print(r)
ifile.close()