Deep Linking API Overview

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

Getting Started

Prerequisites

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

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

Access to the Deep Linking API requires our Engagement product.

Learn more on our packaging page.

Authentication

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.

Delete Functionality

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. You can also use it for additional link data keys. Note that you can set `campaign`, `tags`, `channel`, `feature`, and `stage` as top level parameters, or you can set them inside the `data` object using the `~prefix`. Preference is given to the top level parameter setting.	No
`campaign`	The name of the campaign associated with your link.	No
`tags`	A free form entry with unlimited values of type `string`. Use it to organize your link data with labels that don't fit under other keys.	No
`channel`	The route that your link reaches your users by. For example, tag links with `"Facebook"` or `"LinkedIn"` to help track clicks and installs through those paths separately.	No
`feature`	The feature of your app associated with the link. For example, if you built a referral program, you would label links with the feature `"referral"`.	No
`stage`	The progress or category of a user when the link was generated. For example, if you had an invite system accessible on `"level 1"`, `"level 3"`, and `"level 5"`, you could differentiate links generated at each level with this parameter.	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

Response Info

Response Body Parameters

Parameter	Description
`url`	The URL created by this endpoint.

Example Request & Response

Example Request (cURL)

Example Response (JSON)

curl -XPOST https://api2.branch.io/v1/url -H "Content-Type: application/json" \
  -d '{
  "branch_key": "key_live_00000000000000",
  "channel": "top_level_channel",
  "data": {
    "~creative_id": "data_creative_0000",
    "~campaign": "winter_product_launch",
		"$canonical_url": "https://www.example.com",
		"$og_title": "Title from Deep Link",
		"$og_description": "Description from Deep Link",
		"$og_image_url": "https://www.lorempixel.com/400/400/",
		"$desktop_url": "https://www.desktop-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 objects. Each object represents a Branch Deep Link (see Create a Deep Link URL for structure). 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

Example Request (cURL)

Example Response (JSON)

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_url": "https://www.example.com",
    "$og_title": "Title from Deep Link",
    "$og_description": "Description from Deep Link",
    "$og_image_url": "https://www.lorempixel.com/400/400/",
    "$desktop_url": "https://www.desktop-example.com",
    "custom_boolean": true,
    "custom_integer": 1243,
    "custom_string": "everything",
    "custom_array": [1,2,3,4,5,6],
    "custom_object": { "random": "dictionary" }
    }
  },
  {
    "channel": "linkedin",
    "data": {
    "~creative_id": "data_creative_0001",
    "~campaign": "fall_feature_launch",
    "$canonical_url": "https://www.example.com",
    "$og_title": "Title from Deep Link",
    "$og_description": "Description from Deep Link",
    "$og_image_url": "https://www.lorempixel.com/400/400/",
    "$desktop_url": "https://www.desktop-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/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

Example Response (JSON)

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

Example Request (cURL)

Example Response (JSON)

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

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

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.

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`	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. You can also use it for additional link data keys. Note that you can set `campaign`, `tags`, `channel`, `feature`, and `stage` as top level parameters, or you can set them inside the `data` object using the `~prefix`. Preference is given to the top level parameter setting.	No
`campaign`	The name of the campaign associated with your link.	No
`tags`	A free form entry with unlimited values of type `string`. Use it to organize your link data with labels that don't fit under other keys.	No
`channel`	The route that your link reaches your users by. For example, tag links with `"Facebook"` or `"LinkedIn"` to help track clicks and installs through those paths separately.	No
`feature`	The feature of your app associated with the link. For example, if you built a referral program, you would label links with the feature `"referral"`.	No
`stage`	The progress or category of a user when the link was generated. For example, if you had an invite system accessible on `"level 1"`, `"level 3"`, and `"level 5"`, you could differentiate links generated at each level with this parameter.	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

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.

Example Request & Response

Example Request (cURL)

Example Response (JSON)

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_000000000",
  "branch_secret": "secret_live_00000000000",
  "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"
}

Appendix

Link Data Keys

You can include these keys as part of the data object in your API requests.

Key	Usage
`~id`	The unique ID for the link.
`~creation_source`	The source where the Branch Deep Link was created, represented by a number (passed as a `string`). `"0"` = API `"1"` = Branch Quick Link `"2"` = SDK `"3"` = iOS SDK `"4"` = Android SDK `"5"` = Web SDK `"6"` = Dynamic `"7"` = Third party
`~tags`	A free form entry with unlimited values of type `string`. Use it to organize your link data with labels that don't fit under other keys.
`~campaign`	The name of the campaign associated with your link.
`~campaign_id`	The ID for the campaign associated with your link.
`~channel`	The route that your link reaches your users by. For example, tag links with `"Facebook"` or `"LinkedIn"` to help track clicks and installs through those paths separately.
`~feature`	The feature of your app associated with the link. For example, if you built a referral program, you would label links with the feature `"referral"`.
`~stage`	The progress or category of a user when the link was generated. For example, if you had an invite system accessible on `"level 1"`, `"level 3"`, and `"level 5"`, you could differentiate links generated at each level with this parameter.
`~marketing`	Pass `"true"` to indicate this is a Quick Link.
`~link_type`	The Branch link type (Deep, Quick, or Ad).
`~agency_id`	The ID of the relevant agency.
`~quick_link_template_id`	The ID of the Branch Quick Link template you are using.
`~ad_link_template_id`	The ID of the ad link template you are using.
`~advertising_partner_name`	The name of the relevant advertising partner, such as `"Facebook"`.
`~creative_name`	The creative name specified for the last attributed touch.
`~customer_placement`	The customer specified placement of the last touch. This is the actual app or website that the ad appears on display campaigns.
`~ad_set_name`	The ad set name specified for the last attributed touch.
`~ad_set_id`	The ad set ID specified for the last attributed touch.
`~branch_ad_format`	Possible values: `"Cross-Platform Display"` `"App Only"`
`~secondary_ad_format`	Specify an ad format to help organize your analytics and make it faster to set up web fallbacks for your link.

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()

Deep Linking API Overview

Overview

Benefits

Limitations

Getting Started

Prerequisites

Access

Authentication

Delete Functionality

Usage

Create a Deep Link URL

Request Info

Response Info

Example Request & Response

Bulk Create Deep Link URLs

Request Info

Response Info

Example Request & Response

Delete Existing Deep Link

Request Info

Response Info

Example Request & Response

Read Existing Deep Link

Request Info

Response Info

Example Request & Response

Update Existing Deep Link

Request Info

Response Info

Example Request & Response

Appendix

Link Data Keys

Example Automation Script

Shortcuts

Company

Resources