Deep Linking API

The Deep Linking API creates and manages Branch Links programmatically—generate links at scale and tag them by channel and campaign for analytics.

Read the Deep Linking API overview

Read deep link

GET/url

This endpoint retrieves the deep link URL details based on the parameter you provide.

Parameters

branch_keystringqueryRequired
The Branch Key of the originating app, from your Branch Settings.
urlstringqueryRequired
The deep link URL against which the details are to be fetched.

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

url*branch_key*

curl 'https://api2.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2FabCdEf123&branch_key=key_live_xxxx' \
  --request GET

Response

Success.

{
  "channel": "facebook",
  "feature": "onboarding",
  "campaign": "new product",
  "stage": "new user",
  "tags": [
    "one"
  ],
  "data": {
    "~channel": "facebook",
    "url": "https://branch-demo.app.link/abCdEf123",
    "$one_time_use": false,
    "+url": "https://branch-demo.app.link/abCdEf123",
    "~creation_source": 0,
    "$match_duration": 7200,
    "$fallback_url": "",
    "$identity_id": "00000000",
    "$id": "00000000",
    "$fallback_url_xx": "",
    "$desktop_url": "",
    "$ios_url": "",
    "$ios_url_xx": "",
    "$ipad_url": "",
    "$android_url": "",
    "$android_url_xx": "",
    "$samsung_url": "",
    "$huawei_url": "",
    "$windows_phone_url": "",
    "$blackberry_url": "",
    "$fire_url": "",
    "$ios_wechat_url": "",
    "$android_wechat_url": "",
    "$web_only": false,
    "$desktop_web_only": false,
    "$mobile_web_only": false,
    "$after_click_url": "",
    "$afterclick_desktop_url": false,
    "$canonical_url": "http://www.example.com/content/123",
    "$deeplink_path": "radio/station/456",
    "$og_title": "Deep Link title.",
    "$og_description": "Deep Link description.",
    "$og_image_url": "https://cdn.branch.io/example/og-image.png"
  },
  "alias": "",
  "type": 0,
  "duration": 7200
}

Create deep link

POST/url

This endpoint generates a deep link URL based on the parameters you provide.

Parameters

branch_keystringRequired
The Branch Key of the originating app obtained in your Account Settings.
aliasstring
Instead of our standard encoded short URL, you can specify the vanity alias. For example, instead of a random string of characters/integers, you can set the vanity alias as .app.link/spring-launch.
campaignstring
Campaign name.
channelstring
Deep link channel.
dataobjectExpandable
domainstring
Link domain.
durationinteger
In seconds. Only set this key if you want to override the match duration for deep 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. The default is 7200 (2 hours).
featurestring
Deep link feature set.

More parameters

stagestring
tagsarray of string
typeinteger

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

{
  "branch_key": "key_live_xxxx",
  "channel": "facebook",
  "feature": "onboarding",
  "campaign": "new product",
  "stage": "new user",
  "tags": [
    "one"
  ],
  "domain": "mydomain.custom.com",
  "data": {
    "$canonical_url": "http://www.example.com/content/123",
    "$deeplink_path": "radio/station/456",
    "$og_title": "Deep Link title.",
    "$og_description": "Deep Link description.",
    "$og_image_url": "https://cdn.branch.io/example/og-image.png",
    "~id": "00000001",
    "~creation_source": "1",
    "~tags": [
      "tag_one"
    ],
    "~campaign": "fall_feature_launch",
    "~campaign_id": "data_campaign_0000",
    "~channel": "LinkedIn",
    "~feature": "referral",
    "~stage": "level 5",
    "~link_type": "Quick",
    "~agency_id": "1111",
    "~quick_link_template_id": "1010",
    "~ad_link_template_id": "0101",
    "~advertising_partner_name": "Facebook",
    "~creative_name": "fall_feature_facebook",
    "~customer_placement": "company_ios_app",
    "~ad_set_name": "ad_group_name",
    "~ad_set_id": "ad_group_id",
    "~branch_ad_format": "Cross-Platform Display",
    "~secondary_ad_format": "App Only"
  },
  "duration": 7200
}

curl 'https://api2.branch.io/v1/url' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_key": "key_live_xxxx",
    "channel": "facebook",
    "feature": "onboarding",
    "campaign": "new product",
    "stage": "new user",
    "tags": [
      "one"
    ],
    "domain": "mydomain.custom.com",
    "data": {
      "$canonical_url": "http://www.example.com/content/123",
      "$deeplink_path": "radio/station/456",
      "$og_title": "Deep Link title.",
      "$og_description": "Deep Link description.",
      "$og_image_url": "https://cdn.branch.io/example/og-image.png",
      "~id": "00000001",
      "~creation_source": "1",
      "~tags": [
        "tag_one"
      ],
      "~campaign": "fall_feature_launch",
      "~campaign_id": "data_campaign_0000",
      "~channel": "LinkedIn",
      "~feature": "referral",
      "~stage": "level 5",
      "~link_type": "Quick",
      "~agency_id": "1111",
      "~quick_link_template_id": "1010",
      "~ad_link_template_id": "0101",
      "~advertising_partner_name": "Facebook",
      "~creative_name": "fall_feature_facebook",
      "~customer_placement": "company_ios_app",
      "~ad_set_name": "ad_group_name",
      "~ad_set_id": "ad_group_id",
      "~branch_ad_format": "Cross-Platform Display",
      "~secondary_ad_format": "App Only"
    },
    "duration": 7200
  }'

Response

Success.

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

Create deep links in bulk

POST/url/bulk/{branch_key}

This endpoint generates a deep link URL based on the parameters you provide.

Parameters

branch_keystringpathRequired
The Branch Key of the originating app, from your Branch Settings.
aliasstring
Instead of our standard encoded short URL, you can specify the vanity alias. For example, instead of a random string of characters/integers, you can set the vanity alias as .app.link/spring-launch.
campaignstring
Campaign name.
channelstring
Deep link channel.
dataobjectExpandable
durationinteger
In seconds. Only set this key if you want to override the match duration for deep 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. The default is 7200 (2 hours).
featurestring
Deep link feature set.
stagestring
tagsarray of string
Social media tags.
typeinteger
Set type to 1 to make the URL a one-time-use URL. It won't deep link after 1 successful deep link. Default is 0, the standard Branch Link behavior used by our SDKs.

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

branch_key*

[
  {
    "channel": "facebook",
    "feature": "onboarding",
    "campaign": "new product",
    "stage": "new user",
    "tags": [
      "one"
    ],
    "data": {
      "$canonical_url": "http://www.example.com/content/123",
      "$deeplink_path": "radio/station/456",
      "$og_title": "Deep Link title.",
      "$og_description": "Deep Link description.",
      "$og_image_url": "https://cdn.branch.io/example/og-image.png",
      "~id": "00000001",
      "~creation_source": "1",
      "~tags": [
        "tag_one"
      ],
      "~campaign": "fall_feature_launch",
      "~campaign_id": "data_campaign_0000",
      "~channel": "LinkedIn",
      "~feature": "referral",
      "~stage": "level 5",
      "~link_type": "Quick",
      "~agency_id": "1111",
      "~quick_link_template_id": "1010",
      "~ad_link_template_id": "0101",
      "~advertising_partner_name": "Facebook",
      "~creative_name": "fall_feature_facebook",
      "~customer_placement": "company_ios_app",
      "~ad_set_name": "ad_group_name",
      "~ad_set_id": "ad_group_id",
      "~branch_ad_format": "Cross-Platform Display",
      "~secondary_ad_format": "App Only"
    },
    "duration": 7200
  }
]

curl 'https://api2.branch.io/v1/url/bulk/key_live_xxxx' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "channel": "facebook",
      "feature": "onboarding",
      "campaign": "new product",
      "stage": "new user",
      "tags": [
        "one"
      ],
      "data": {
        "$canonical_url": "http://www.example.com/content/123",
        "$deeplink_path": "radio/station/456",
        "$og_title": "Deep Link title.",
        "$og_description": "Deep Link description.",
        "$og_image_url": "https://cdn.branch.io/example/og-image.png",
        "~id": "00000001",
        "~creation_source": "1",
        "~tags": [
          "tag_one"
        ],
        "~campaign": "fall_feature_launch",
        "~campaign_id": "data_campaign_0000",
        "~channel": "LinkedIn",
        "~feature": "referral",
        "~stage": "level 5",
        "~link_type": "Quick",
        "~agency_id": "1111",
        "~quick_link_template_id": "1010",
        "~ad_link_template_id": "0101",
        "~advertising_partner_name": "Facebook",
        "~creative_name": "fall_feature_facebook",
        "~customer_placement": "company_ios_app",
        "~ad_set_name": "ad_group_name",
        "~ad_set_id": "ad_group_id",
        "~branch_ad_format": "Cross-Platform Display",
        "~secondary_ad_format": "App Only"
      },
      "duration": 7200
    }
  ]'

Response

Success.

[
  {
    "url": "https://example.app.link/abCdEf123"
  }
]

Update deep link

PUT/url

Updates an existing Branch Link.

Parameters

branch_keystringRequired
The Branch Key of the originating app obtained in your Account Settings.
branch_secretstringRequired
The Branch Secret of the originating app obtained in your Account Settings.
urlstringqueryRequired
The full URL of the deep link to update.
campaignstring
The name of the campaign associated with your link.
channelstring
The route that your link reaches your users by.
dataobjectExpandable
durationinteger
In seconds. Only set this key if you want to override the match duration for deep 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. The default is 7200 (2 hours).
featurestring
The feature of your app associated with the link.

Returns

Deep link updated successfully. Returns 400 and 429 on failure — see the response panel for the error shape.

url*

{
  "branch_key": "key_live_xxxx",
  "branch_secret": "secret_live_xxxx",
  "data": {
    "$canonical_url": "http://www.example.com/content/123",
    "$deeplink_path": "radio/station/456",
    "$og_title": "Deep Link title.",
    "$og_description": "Deep Link description.",
    "$og_image_url": "https://cdn.branch.io/example/og-image.png",
    "~id": "00000001",
    "~creation_source": "1",
    "~tags": [
      "tag_one"
    ],
    "~campaign": "fall_feature_launch",
    "~campaign_id": "data_campaign_0000",
    "~channel": "LinkedIn",
    "~feature": "referral",
    "~stage": "level 5",
    "~link_type": "Quick",
    "~agency_id": "1111",
    "~quick_link_template_id": "1010",
    "~ad_link_template_id": "0101",
    "~advertising_partner_name": "Facebook",
    "~creative_name": "fall_feature_facebook",
    "~customer_placement": "company_ios_app",
    "~ad_set_name": "ad_group_name",
    "~ad_set_id": "ad_group_id",
    "~branch_ad_format": "Cross-Platform Display",
    "~secondary_ad_format": "App Only"
  },
  "channel": "Facebook",
  "feature": "Onboarding",
  "campaign": "New Product",
  "duration": 7200
}

curl 'https://api2.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2FabCdEf123' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_key": "key_live_xxxx",
    "branch_secret": "secret_live_xxxx",
    "data": {
      "$canonical_url": "http://www.example.com/content/123",
      "$deeplink_path": "radio/station/456",
      "$og_title": "Deep Link title.",
      "$og_description": "Deep Link description.",
      "$og_image_url": "https://cdn.branch.io/example/og-image.png",
      "~id": "00000001",
      "~creation_source": "1",
      "~tags": [
        "tag_one"
      ],
      "~campaign": "fall_feature_launch",
      "~campaign_id": "data_campaign_0000",
      "~channel": "LinkedIn",
      "~feature": "referral",
      "~stage": "level 5",
      "~link_type": "Quick",
      "~agency_id": "1111",
      "~quick_link_template_id": "1010",
      "~ad_link_template_id": "0101",
      "~advertising_partner_name": "Facebook",
      "~creative_name": "fall_feature_facebook",
      "~customer_placement": "company_ios_app",
      "~ad_set_name": "ad_group_name",
      "~ad_set_id": "ad_group_id",
      "~branch_ad_format": "Cross-Platform Display",
      "~secondary_ad_format": "App Only"
    },
    "channel": "Facebook",
    "feature": "Onboarding",
    "campaign": "New Product",
    "duration": 7200
  }'

Response

Deep link updated successfully.

{
  "url": "https://example.app.link/abCdEf123",
  "updated": true
}

Delete deep link

DELETE/url

This endpoint deletes an existing deep link.

Note: This endpoint requires both App-Level and Sensitive Data permissions. You must pass an Access Token (API key) to use the DELETE method. Otherwise, you may see an Unauthorized User error. See the Deep Linking API Overview's Authentication section for details.

Parameters

Access-TokenstringheaderRequired
The Branch Access Token of the originating app obtained in your Account Settings.
app_idstringqueryRequired
The Branch app_id against the associated deep link URL.
urlstringqueryRequired
The deep link URL against which the details are to be fetched.

Returns

Success. Returns 400 and 429 on failure — see the response panel for the error shape.

Access-Token*url*app_id*

curl 'https://api2.branch.io/v1/url?url=https%3A%2F%2Fexample.app.link%2FabCdEf123&app_id=123456789012345680' \
  --request DELETE \
  --header 'Access-Token: api_app_xxxx'

Response

Success.

{
  "url": "https://example.app.link/abCdEf123",
  "deleted": true
}

Deep Linking API

Read deep link

Parameters

Returns

Create deep link

Parameters

More parameters Expand all

Returns

Create deep links in bulk

Parameters

Returns

Update deep link

Parameters

Returns

Delete deep link

Parameters

Returns

More parameters