Quick Links (Short Links) API Overview

Overview

Branch's Quick Links API is a useful tool for programmatically generating Branch Links that surface in Branch. You can create Branch Links at scale to support all of your campaigns while tagging the links appropriately based on channel and other analytics tags.

The API also supports QR code customization during link creation, allowing you to programmatically apply branding and design settings to the QR codes associated with your Short Links. This streamlines the workflow for creating branded assets at scale. You can generate deep links and their corresponding branded QR codes in a single API call, removing the need to manually customize QR codes in Branch after link creation.

Note

URLs created via this API will not automatically show up in Branch. To make sure a URL appears in Branch, set "$marketing_title": "mytitle" ($marketing_title is part of the data object) and type: 2 in your request. Both parameters need to be properly filled out to see the link in Branch.

Link creation with type: 2 is not enabled for all accounts. If your request returns the error "You don't have access to this type", your account does not have access to this feature. Availability varies by Branch plan. See Branch pricing.

Limits

Limitation	Details
Rate limits	100 requests per second 5,500 requests per minute 300,000 requests per hour Note that 300,000 requests per hour equates to 83 requests per second.

Get started

Before you begin

To access the Quick Links API, you first need to:

Join Branch.
Set appropriate user permissions in your Branch account.

Access

Availability varies by Branch plan. See Branch pricing.

Authentication

For calls to the Quick Links API, you need your Branch Key. For some operations, you also need your Branch Secret and Access Token.

Legacy Branch

To retrieve your credentials in the legacy Branch experience:

Navigate to the Account → Settings → Profile tab.
Use the copy icons to copy your Branch Key and Branch Secret.
From the tabs at the top of the page, select the User tab.
If you have not yet generated an Access Token, select the Generate token button.
Use the copy icon to copy your Access Token.

New Branch

To retrieve your credentials in the new Branch experience:

Navigate to the Configuration → Security & Access → Credentials tab.
If you have not yet generated an Access Token, select the Generate token button.
Use the copy icons to copy your Branch Key, Branch Secret, and Access Token.

Visit our guide to learn more about managing your Branch credentials.

Use the API

Create a Quick Link

Endpoint

http

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, found in the Settings tab of Branch.	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. The key `$marketing_title` is part of the `data` object and must be set to see the link in Branch. The `type` parameter (not part of the `data` object) must also be set to 2 for this to happen.	Yes
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 send a POST request to this endpoint with the same alias and a matching set of other POST parameters as an existing aliased link, Branch returns the original link. This deduplication applies for 7 days after the link is created. After 7 days, a POST request using an existing alias returns an HTTP 400 error for the alias conflict, even if the rest of the parameters match. If the alias clashes and the other parameters don't match, the request returns an HTTP 400 error.	No
type	Set `type` to 2 if you want to see the URL in Branch. You must also set `$marketing_title` (which is part of the `data` object) to a string value. Note: `type: 2` is also required to customize a QR code using `qr_code_settings`.	Yes
duration	In seconds. Only set this key if you want to override the match duration for Branch 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 set to 7200 (2 hours) by default.	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 Branch.	No
qr_code_settings	QR code customization settings. When included, both the Short Link and its customized QR code are generated instantly and appear in Branch. This object accepts the same styling parameters as the QR Code API. Requires `type: 2` to be set. See the QR Code Customization section below for available options.	No

Response body parameters

Parameter	Description
url	The URL created by this endpoint.

Example request/response

Example Request (cURL)Example Response (JSON)

curl

curl -XPOST https://api2.branch.io/v1/url -H "Content-Type: application/json" \
                    -d '{
                    "branch_key": "key_live_XyZ",
                    "channel": "facebook",
                    "feature": "onboarding",
                    "campaign": "new product",
                    "stage": "new user",
                    "tags": ["one", "two", "three"],
                    "type": 2,
                    "data": {
                    "$marketing_title": "mytitle",
                    "$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" }
                    }
                    }'

json

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

QR code customization

You can include the qr_code_settings object in your request to customize the QR code associated with your Short Link. When you create a Short Link with qr_code_settings, both the Short Link and its customized QR code are generated instantly and appear in Branch.

Note

You must set type: 2 in your API request to customize a QR code.

qr_code_settings parameters

Parameter	Description
image_format	The output image format. Valid values: `png`, `jpeg`, `jpg`
center_logo_url	URL to the image you want as a center logo.
width	Output size of the QR code image in pixels. Min: 300, Max: 2000. Only applicable to JPEG/PNG.
margin	The number of pixels for the margin. Min: 1, Max: 20.
code_color	Hex color value of the QR code itself (for example, `#000000`).
background_color	Hex color value of the background (for example, `#FFFFFF`).
code_pattern	QR code pattern style. Valid values: `1` (standard), `2` (squares), `3` (circles), `4` (triangles), `5` (diamonds), `6` (hexagons), `7` (octagons). Default: `1`
finder_pattern	The finder pattern shape (corners of the QR code). Valid values: `1` (square), `2` (rounded rectangle), `3` (circle). Default: `1`
finder_pattern_color	Hex color value of the finder pattern (for example, `#00A3D8`).
finder_eye_color	Hex color value of the finder eye (for example, `#00A3D8`).
background_image_url	URL to an image to use as the background behind the QR code.
code_pattern_url	Direct link to an image to use as the code pattern itself on the QR code.
code_shape	Shape of the QR code modules.

Example request with QR code customization

curl

curl -XPOST https://api2.branch.io/v1/url -H "Content-Type: application/json" \
-d '{
    "branch_key": "key_live_XyZ",
    "channel": "facebook",
    "feature": "onboarding",
    "campaign": "new product",
    "type": 2,
    "data": {
        "$marketing_title": "My QR Code via API",
        "$desktop_url": "http://www.example.com"
    },
    "qr_code_settings": {
        "code_pattern": 1,
        "finder_pattern": 2,
        "finder_pattern_color": "#D94280",
        "code_color": "#D94280",
        "background_color": "#FFFFFF",
        "width": 500
    }
}'

Availability

All users with access can view and download the customized QR codes in Branch.

The ability to edit QR codes created via the API depends on your Branch interface:

New Branch: Users can edit the QR code design directly within Branch after creation.
Legacy Branch: The QR code design is read-only in legacy Branch. To edit the design, you must update the link via the API or delete and recreate it.

Bulk create Quick Links

Endpoint

http

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 Links, see the Branch 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, found in the Settings tab of Branch.	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. The Branch SDK you're using passes these parameters to your app. The key `$marketing_title` is part of the `data` object and must be set to see the link in Branch. The `type` parameter (not part of the `data` object) must also be set to 2 for this to happen.	No

Note

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

Response parameters

Parameter	Description
url	An array of Branch Link URLs.
error	Error(s) if there are invalid parameters.

Example request/response

Example Request (cURL)Example Response (JSON)

curl

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"],
                    "type": 2,
                    "data": {
                    "$marketing_title": "mytitle",
                    "$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"],
                    "type": 2,
                    "data": {
                    "$marketing_title": "mysecondtitle",
                    "$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"
                    }
                    }
                    ]'

json

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

Update existing Quick Link

Tip

This API call overwrites a Branch Link's data object entirely, so make sure to include all of the Branch Link's data when updating it and not just the data you're changing.
To update Branch 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 need to do it outside of the API Reference.
You can update the QR code design on an existing link by including qr_code_settings in your update request.

Caution

There are certain restrictions when attempting to update Branch 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
  - This means if you want to see Branch Links in Branch, you need to have set type to 2 during creation.
- app_id
- randomized_bundle_token
- domain
- state
- creation_source
- app_short_identifier

Endpoint

http

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, found in the Settings tab of Branch.	Yes
branch_secret	The Branch Secret of the originating app, found in the Settings tab of Branch.	Yes
url	The Branch Quick Link URL you want to update.	Yes
qr_code_settings	QR code customization settings for updating the QR code design on an existing link. See the QR Code Customization section for available options.	No

Example request/response

Example Request (cURL)Example Response (JSON)

curl

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_XyZ",
                    "branch_secret": "secret_live_XyZ",
                    "channel": "twitter",
                    "type": 2,
                    "data": {
                    "$marketing_title": "mynewtitle",
                    "name": "alex",
                    "user_id": "12346"
                    }
                    }'

json

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

python

import requests
import csv
import sys
import urllib
import json

def BranchUpdateModule(KeyV, SecretV, UpdateV, File):
    # Insert API key & App Secret from Branch, 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

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

Quick Links (Short Links) API Overview

Overview ​

Limits ​

Get started ​

Before you begin ​

Access ​

Authentication ​

Use the API ​

Create a Quick Link ​

Endpoint ​

Request headers ​

Request body parameters: ​

Response body parameters ​

Example request/response ​

QR code customization ​

qr_code_settings parameters ​

Example request with QR code customization ​

Availability ​

Bulk create Quick Links ​

Endpoint ​

Request headers ​

Request body parameters ​

Response parameters ​

Example request/response ​

Update existing Quick Link ​

Endpoint ​

Request headers ​

Request body parameters ​

Example request/response ​

Overview

Limits

Get started

Before you begin

Access

Authentication

Use the API

Create a Quick Link

Endpoint

Request headers

Request body parameters:

Response body parameters

Example request/response

QR code customization

qr_code_settings parameters

Example request with QR code customization

Availability

Bulk create Quick Links

Endpoint

Request headers

Request body parameters

Response parameters

Example request/response

Update existing Quick Link

Endpoint

Request headers

Request body parameters

Example request/response