Quick Links (Short Links) API Overview

Overview

Branch's Quick Links API is a useful tool for programmatically generating Branch Deep Links that surface on the Branch Dashboard. You can create Deep 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 the Branch Dashboard. To make sure a URL appears in the Branch Dashboard, 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 Deep Link in the Dashboard.

Limits

Getting Started

Prerequisites

In order to access the Quick Links API, you first need to:

1. Create a Branch Dashboard.

2. Set appropriate user permissions in your Branch account.

Access

Access to the Quick Links API requires a premium plan. Please contact our Sales team to learn more about pricing and availability.

QR code customization via the API is available to customers with Engagement Pro, or those with access to both the Quick Links API and QR Codes API.

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.

API Usage

Create a Quick Link URL

Endpoint

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

Request Headers

Request Body Parameters:

Response Body Parameters

Example Request/Response

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

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

Example Request with QR Code Customization

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

QR code customization via the API is available to customers with Engagement Pro, or those with access to both the Quick Links API and QR Codes API. 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:

• Activation Essentials or 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 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

Request Body Parameters

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

Note

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

Response Parameters

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

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

Update Existing Quick 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.

• You can update the QR code design on an existing link by including qr_code_settings in your update request.

Link Update Restrictions

There are certain restrictions when attempting to update Deep 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 Deep Links in the Dashboard, you need to have set type to 2 during creation.

  • 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

Request Body Parameters

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_XyZ",
                    "branch_secret": "secret_live_XyZ",
                    "channel": "twitter",
                    "type": 2,
                    "data": {
                    "$marketing_title": "mynewtitle",
                    "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()