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

# Deep Linking API Overview

> Use Branch's Deep Linking API to create, update, and manage Branch Links in bulk.

## 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 and tag them appropriately based on `channel` or other analytics tags.

### Benefits

With the Deep Linking API, you can create and update Branch Links in bulk. You can also read information from previously created Branch Links and delete them.

### Limitations

#### Request limits

| 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<br><br>This equates to about 83 requests per second. |
| GET | 100 | 5,500 | 100,000 |

#### Link expiration

Sending a read (`GET`) request for a Short Link resets its expiration window. Short Links created on or after March 11, 2024, expire 380 days after creation, and that window resets each time the link is clicked or read via this endpoint. See [Expiration behavior](https://help.branch.io/marketer-hub/deep-link-reference.md#expiration-behavior) in the Deep Linking Full Reference for expiration behavior by link type.

## Getting started

### Before you begin

To use the Deep Linking API, you first need to:

1. Create a [Branch account](https://dashboard.branch.io/).
2. Set appropriate user permissions in your Branch account. To access the `DELETE` method for this endpoint, you need both App-Level and Sensitive Data [permissions](https://help.branch.io/account-hub/add-manage-users.md).

### Access

Availability varies by Branch plan. See [Branch pricing](https://www.branch.io/pricing/).

### Authentication

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

**Important**: To access the `DELETE` method for this endpoint, you need both App-Level and Sensitive Data [permissions](https://help.branch.io/account-hub/add-manage-users.md).

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

## Usage

### Create a deep link URL

#### Request info

**Export request**

```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** |
| `accept` | 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](https://help.branch.io/marketer-hub/deep-link-reference.md#link-data). You can also use it for additional [link data keys](https://help.branch.io/apidocs/deep-linking/overview.md#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`. The top-level parameter setting takes precedence. | 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.<br>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`.<br>**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, Branch returns the original link to you. If it clashes and you don't specify a match, Branch returns an HTTP 400 error.<br>**Warning**: Non-letter characters should not be used in the `alias`, except for forward slashes `/`, underscores `_`, and hyphens `-`. The maximum length of 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. The 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 Link matching. | No |
| `domain` | The domain that your link uses. The domain (for example, `branch.io`) must be [set up in Branch](https://help.branch.io/account-hub/basic-link-configuration.md). If you don't specify a domain, the link uses your default domain set in Branch. This parameter is only available if you have Branch Activation. | No |

#### Response info

**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 '{
                    "domain":"mydomain.custom.com",
                    "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" }
                    }
                    }'
```

**Example Response (JSON)**

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

### Bulk create deep link URLs

#### Request info

**Export request**

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

**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](https://dashboard.branch.io/account-settings/app) tab of Branch. | **Yes** |

**Request body parameter**

| Parameter | Description | Required |
| --- | --- | --- |
| [Branch Parameters](https://help.branch.io/marketer-hub/deep-link-reference.md#configure-deep-links) | A JSON array of objects. Each object represents a Branch Link (see [Create a Deep Link URL](https://help.branch.io/apidocs/deep-linking/overview.md#create-a-deep-link-url) for structure).<br>Learn more about [configuring Branch Links](https://help.branch.io/marketer-hub/deep-link-reference.md#configure-deep-links). | No |

**Limitations**

There is a 100KB limit on request payload size for bulk Branch Link creation.

#### Response info

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

**Example Response (JSON)**

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

### Delete existing deep link

#### Request info

**Export request**

```http
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 regard to an organization. Obtained from Branch. Needed for [authentication](https://help.branch.io/apidocs/deep-linking/overview.md#authentication). | **Yes** |
| `accept` | application/json | **Yes** |
| `content-type` | application/json | **Yes** |

**Request body parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| `url` | The Branch Link URL to delete. | **Yes** |
| `app_id` | The Branch `app_id` associated with the Branch Link URL to delete. | **Yes** |

**Limitations**

This endpoint is not available in test environments.

#### Response info

**Response parameters**

| Parameter | Description |
| --- | --- |
| `url` | The relevant Branch Link URL. |
| `deleted` | Returns `true` if the URL has been successfully deleted, `false` if not. |

#### Example request & response

**cURL**

```curl
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"
```

**Example Response (JSON)**

```json
{
  "url": "https://example.app.link/ABCD",
  "deleted": true
}
```

### Read existing deep link

#### Request info

**Export request**

```http
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](https://dashboard.branch.io/account-settings/app) tab of Branch. | **Yes** |
| `url` | The Branch Link URL you want to read. | **Yes** |

#### Response info

**Response parameters**

| Parameter | Description |
| --- | --- |
| A JSON object | A JSON object containing Branch Link [properties](https://help.branch.io/marketer-hub/deep-link-reference.md#data-structure). |

#### Example request & response

**Example Request (cURL)**

```curl
curl -XGET 'https://api2.branch.io/v1/url?url=https://example.app.link/WgiqvsepqF&branch_key=key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt'
```

**Example Response (JSON)**

```json
{
  "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**

```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** |
| `accept` | application/json | **Yes** |

**Request query parameters**

| Parameter | Description | Required |
| --- | --- | --- |
| url | The Branch Link URL you want to update. | **Yes** |

**Request body parameters**

> **Caution**
>
> **Data object override**
>
> Make sure to include all of the Branch Link's data when making this request, not just the data you're changing. This is because this API call **overwrites the Branch Link's data object entirely**.

| 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** |
| `data` | The dictionary to embed with the link. Accessed as session or install parameters from the SDK.<br>Use the `data` dictionary for all [link control parameters](https://help.branch.io/marketer-hub/deep-link-reference.md#link-data).<br>You can also use it for additional [link data keys](https://help.branch.io/apidocs/deep-linking/overview.md#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`. The top-level parameter setting takes precedence. | 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.<br>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.<br>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.<br>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`.<br>**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, Branch returns the original link to you. If it clashes and you don't specify a match, Branch returns an HTTP 400 error.<br>**Warning**: Non-letter characters should not be used in the `alias`, except for forward slashes `/`, underscores `_`, and hyphens `-`. The maximum length of 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. The default is set to `7200` (2 hours).<br>This is the time that Branch allows a click to remain outstanding and be eligible to be matched with a new app session.<br>Only set this key if you want to override the match duration for Branch Link matching. | No |

#### Response info

**Response parameters**

| Parameter | Description |
| --- | --- |
| `data` | An object containing data about the Branch Link. |
| `type` | An integer, usually `0`, that reflects the type of the Branch Link. |

#### 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_000000000",
                    "branch_secret": "secret_live_00000000000",
                    "channel": "twitter",
                    "data":{
                    "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"
}
```

## 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 Link was created, represented by a number (passed as a `string`).<br>`"0"` = API<br>`"1"` = Branch Quick Link<br>`"2"` = SDK<br>`"3"` = iOS SDK<br>`"4"` = Android SDK<br>`"5"` = Web SDK<br>`"6"` = Dynamic<br>`"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.<br>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.<br>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.<br>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](https://help.branch.io/account-hub/agency-profile.md). |
| `~quick_link_template_id` | The ID of the [Branch Quick Link template](https://help.branch.io/marketer-hub/link-templates.md#overview) you're using. |
| `~ad_link_template_id` | The ID of the [ad link template](https://help.branch.io/marketer-hub/testing-ads-campaign-setup.md#_2-create-a-branch-link) you're 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 where the ad appears in 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:<br>`"Cross-Platform Display"`<br>`"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

To update Branch 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:

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

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