> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# 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](https://www.branch.io/pricing/).

### Limits

| Limitation | Details |
| --- | --- |
| Rate limits | 100 requests per second<br>5,500 requests per minute<br>300,000 requests per hour<br><br>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:

1. Join [Branch](https://dashboard.branch.io/).
2. Set appropriate user permissions in your Branch account.

### Access

Availability varies by Branch plan. See [Branch pricing](https://www.branch.io/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](https://help.branch.io/marketer-hub/branch-dashboard-overview.md):

1. Navigate to the **Account → Settings → Profile** [tab](https://dashboard.branch.io/account-settings/profile).
2. Use the **copy icons** to copy your Branch Key and Branch Secret.
3. From the tabs at the top of the page, select the **User** [tab](https://dashboard.branch.io/account-settings/user).
4. If you have not yet generated an Access Token, select the **Generate token** button.
5. Use the **copy icon** to copy your Access Token.

**New Branch**

To retrieve your credentials in the [new Branch experience](https://help.branch.io/account-hub/credentials-new.md):

1. Navigate to the **Configuration → Security & Access → Credentials** [tab](https://branchdocs.app.link/apis-to-credentials).
2. If you have not yet generated an Access Token, select the **Generate token** button.
3. Use the **copy icons** to copy your Branch Key, Branch Secret, and Access Token.

Visit our [guide](https://help.branch.io/account-hub/credentials-new.md) 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](https://dashboard.branch.io/account-settings/app) 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.**](https://help.branch.io/marketer-hub/deep-link-reference.md#link-data) 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](https://help.branch.io/marketer-hub/deep-link-reference.md#attribution-and-analytics-control) | 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](https://help.branch.io/apidocs/qr-code/overview.md). Requires `type: 2` to be set. See the [QR Code Customization](#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)**

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

**Example Response (JSON)**

```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](https://help.branch.io/marketer-hub/deep-link-reference.md).

#### Request headers

| Header | Value | Required |
| --- | --- | --- |
| Content-Type | application/json | **Yes** |

#### Request body parameters

A JSON array of parameters from [Creating a Deep Linking URL](https://help.branch.io/marketer-hub/deep-link-reference.md#configure-deep-links).

| Parameter | Description | Required |
| --- | --- | --- |
| branch_key | The Branch Key of the originating app, found in the [Settings](https://dashboard.branch.io/account-settings/app) tab of Branch. | **Yes** |
| [Branch Parameters](https://help.branch.io/marketer-hub/deep-link-reference.md#configure-deep-links) | A JSON array of parameters from [Creating a Deep Linking URL.](https://help.branch.io/marketer-hub/deep-link-reference.md#configure-deep-links)<br>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.<br><br>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)**

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

**Example Response (JSON)**

```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](https://dashboard.branch.io/account-settings/app) tab of Branch. | **Yes** |
| branch_secret | The Branch Secret of the originating app, found in the [Settings](https://dashboard.branch.io/account-settings/app) 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](#qr-code-customization) section for available options. | No |

#### Example request/response

**Example Request (cURL)**

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

**Example Response (JSON)**

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