Overview

The Branch Attribution API offers developers a way to track INSTALL, REINSTALL, and OPEN events while also supplying a payload of attribution properties. This is something the Branch mobile SDKs do by default, but this API provides the option of sending this information server-side.

The response to a request sent to this API is deep link data.

If you choose to use this API instead of tracking these events with a Branch SDK, be aware that session management becomes your responsibility. You need to account for handling poor or no connectivity, persisting data locally, retrieving values like IP address, tracking downstream conversions, creating shareable deep links, and other possible challenges. To achieve feature parity with a Branch SDK, you would need to duplicate the code in the SDK.

For this reason, we highly recommend that all apps use a Branch SDK when possible.

Limitations

By default, Branch rate limits non-referred OPEN events (that is, app sessions not sourced by a link) to once every 4 hours per IP address.

Rate limits vary by account. See Branch pricing.

Sessions that exceed your rate limit still return deep link data in the network request, but the data does not appear in your Branch reports or exports.

Branch also returns 429 responses if your app starts sending requests for the same user in rapid succession. While this scenario does not mirror normal user behavior, you may run into it during your own testing. If this happens, wait a few minutes before resuming testing. You can also try changing the device metadata in your request.

Try it!

Try out the Attribution API in your browser, using your Branch data:

Request Open

Getting started

Before you begin

To use the Attribution API, you first need to:

1. Create a Branch account.
2. Make sure that your account has access to the v1/open API enabled.
3. Configure Branch with default link redirects, your app.link domains, a URI scheme, and Universal Links.
4. Complete the "In-app setup" section of this guide for your relevant app(s).

Authentication

For calls to the Attribution API, you need your Branch Key and Branch Secret.

Legacy Branch

To retrieve your credentials in the legacy Branch experience:

1. Navigate to the Account → Settings → Profile tab.
2. Use the copy icons to copy your Branch Key and Branch Secret.

New Branch

To retrieve your credentials in the new Branch experience:

1. Navigate to the Configuration → Security & Access → Credentials tab.
2. Use the copy icons to copy your Branch Key and Branch Secret.

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

In-app setup

iOS

Configuration

To configure your iOS app to use the Attribution API, you first need to:

1. Add your URI scheme to your info.plist file.
2. Add your Branch app.link and alternate.app.link domains to your project's Associated Domains.

Collect launch data for request

To gather the launch data you need to make a request to the Attribution API, you can:

1. Retrieve the device ID (IDFA or IDFV) if available.

2. Retrieve the device's public IP address.

3. Retrieve the device's user agent string.

4. Examine your AppDelegate's openURL() function for a URI.

   1. If a URI containing the query parameter link_click_id is present, then store that query parameter's value for use in the session's API network request.
   2. For example, if the URI example://open?link_click_id=1234 opens the app, you need to retrieve the 1234 value.

5. Examine the AppDelegate's continueUserActivity() function for a webpageURL value.

   1. The webpageURL value lives inside the NSUserActivity parameter.
   2. If you find a URL, store the entire URL value for use in the session's API network request. This is true regardless of whether it is a Branch Link.

Optional: Support Apple Search Ads

For server-to-server integrations, you need to retrieve the new attribution token and send it to Branch on install as apple_attribution_token.

To retrieve the attribution token:

1. Import the AdService.framework into your project.

2. Request the attribution token, which should be available from Apple within 50ms:

   Swift

   func appleAttributionToken() -> String? {
       if #available(iOS 14.3, *) {
           return try? AAAttribution.attributionToken()
       }
       return nil
   }

   Objective-C

   + (NSString *)appleAttributionToken {
       #if !TARGET_OS_TV
       if (@available(iOS 14.3, *)) {
           NSError *error;
           NSString *appleAttributionToken = [AAAttribution attributionTokenWithError:&error];
           if (!error) {
               return appleAttributionToken;
           }
       }
       #endif
       return nil;
   }

3. Send the token to Branch for attribution within 24 hours, as that is the TTL for the token.

For more about retrieving the attribution token, visit Apple's documentation.

To learn more about Apple Search Ads, visit our guide.

Android

Configuration

1. Add your URI scheme to your AndroidManifest.xml file.
2. Also add your Branch app.link and alternate.app.link domains to your AndroidManifest.xml file.

Collect launch data for request

To gather the launch data you need to make a request to the Attribution API, you can:

1. Retrieve the device ID (GAID or Android_ID) if available.

2. Retrieve the device's public IP address.

3. Retrieve the device's user agent string.

4. Examine the intent that opened your MainActivity for a URI.

   1. If a URI containing the query parameter link_click_id is present, then store that query parameter's value for use in the session's API network request.
   2. For example, if the URI example://open?link_click_id=1234 opens the app, you need to retrieve the 1234 value.

5. Examine the intent that opened your MainActivity for a web URL.

   1. If you find a URL, store the entire URL value for use in the session's API network request. This is true regardless of whether it is a Branch Link.

Optional: Support Google Play Install Referrer

Complete the steps below only during the INSTALL session:

1. Upon app launch, query the Google Play Install Referrer library for the referrer URL, click timestamp, and install timestamp.

2. Examine the referrer URL for a link_click_id query parameter.

   1. If present, retrieve its value for use in the request's link_identifier parameter.
   2. This value might appear in the referrer URL as &link_click_id=<> or &link_click_id-<>. In either scenario, extract only the <> part.

3. Examine the referrer URL for a google_search_install_referrer query parameter.

   1. If present, retrieve its value for use in the request's google_search_install_referrer parameter.
   2. This value might appear in the referrer URL as &google_search_install_referrer=<> or &google_search_install_referrer-<>. In either scenario, extract only the <> part.

Usage

The network request to the v1/open endpoint should occur once you've been notified that the user has successfully brought your app to the foreground.

Branch marks the beginning of an app lifecycle when your app is launched and brought to the foreground of the device. The launch can be from either a cold start or a transition from running in the background (present in the iOS or Android task manager) to the foreground.

On web, an open event is measured every time a webpage with the Branch Web SDK opens in a new tab or when a user clicks on a Branch Link and is redirected to a page with the Branch Web SDK. This is called a web_session_start.

Caution

To set the required X-IP-Override header, your app ID needs to be added to our allowlist. Reach out to support@branch.io with your Branch app ID to have it added to the allowlist.

Request info

Export request

POST /v1/open
Host: api2.branch.io
Content-Type: application/json

Request headers

Header	Description	Required?
X-IP-Override	The device's public IP address from your app user's device, not your server's IP address.	Yes
content-type	application/json	Yes
accept	application/json	Recommended

Request body parameters

Parameter	Type	Description	Required?
branch_key	String	The Branch Key of the relevant app, found in the Settings tab in Branch.	Required on iOS & Android
branch_secret	String	The Branch Secret of the relevant app, found in the Settings tab in Branch.	Required on iOS & Android
server_to_server	Bool	Always set this value to true.	Required on iOS & Android
app_version	String	The version of your app, such as "1.12.4".	Required on iOS & Android
os	String	Choose either Android or iOS.	Required on iOS & Android
os_version	String	The device's OS version, such as "14" for Android or "17.3.1" for iOS. This parameter cannot be blank, but the API accepts any string value, such as "NA".	Required on iOS & Android
user_agent	String	The user agent of the device.	Required on iOS & Android
hardware_id	String	For iOS, populate with the IDFA if available. Otherwise, fall back to IDFV. For Android, populate with the ANDROID_ID (hardware ID). Otherwise, do not include in request.	Required on iOS
hardware_id_type	String	This value confirms whether the iOS ID in the hardware_id field is an IDFA or IDFV. If hardware_id is not populated, do not include in request.	Required on iOS
ios_vendor_id	String	The IDFV, if available. Otherwise, do not include in request.	Required on iOS
google_advertising_id	String	The Google Advertising ID, if available. Otherwise, do not include in request.	Required on Android
advertising_ids	Object	The set of advertising IDs, if available. Otherwise, do not include in request. Can include identifiers like OAID.	Required on Android
is_hardware_id_real	Boolean	Set this value to false if the hardware_id property cannot be populated. Otherwise, default to true.	Required on iOS & Android
ad_tracking_enabled	Boolean	This value is used to determine whether the IDFA or GAID can be used for advertising purposes. If Limit Ad Tracking should be enabled, do not include in the request.	Required on iOS & Android
local_ip	String	This is the device's local IP address, if one is available. Optional but highly recommended for improving attribution accuracy. This is supplemental to the required X-IP-Override value in the header.	Recommended
screen_height	Int	Height of the device's screen.	Recommended
screen_width	Int	Width of the device's screen.	Recommended
link_identifier	String	When a URI opens the app, check for a link_click_id query parameter and populate the link_identifier parameter with that value. The link_click_id may also be sourced from the Google Install Referrer.	Optional
universal_link_url	String	Populate this value with the Branch or non-Branch web URL that opened the app, if available. Otherwise, do not include in request.	Optional, iOS only
android_app_link_url	String	Populate this value with the Branch or non-Branch web URL that opened the app, if available. Otherwise, do not include in request.	Optional, Android only
facebook_app_link_checked	Boolean	Set to false to ensure Branch retrieves deep links from Facebook's deferred deep linking API. This requires adding your Facebook App Secret to Branch. Learn more in our guide.	Optional
install_referrer_extras	String	Populate with the value of the full Android Play Store Install Referrer URL, if available. Only include in the app's first session.	Optional, Android only
google_search_install_referrer	String	Populate with the value of the google_search_install_referrer query parameter on the referrerUrl from the Google Install Referrer, if available. Only include in the app's first session.	Optional, Android only
clicked_referrer_ts	Long	The referrer click timestamp collected from the Play Install Referrer library, if available. Only include in the app's first session.	Optional, Android only
install_begin_ts	Long	The install begin timestamp collected from the Play Install Referrer library, if available. Only include in the app's first session.	Optional, Android only
apple_attribution_token	String	The attribution token used for Apple Search Ads. Used to call the Apple Search Ads Attribution API. This token has a 24hr TTL, so it must be sent to Branch within that same time frame to be used for attribution.	Optional, iOS only
search_ad_encoded	String	The Base64-encoded string of the entire response from the Apple Search Ads API.	Deprecated
first_session	Boolean	If this parameter is set to true, Branch checks whether we have previously seen the user download the app. If we have seen the user before, we mark it as a REINSTALL. If we have not, we mark it as an INSTALL. If this parameter is set to false, Branch counts the session as an OPEN.	Optional
server_to_server_identity	Boolean	Setting to true lets you set a randomized_bundle_token property (see below). Do not set this property in the request if you don't plan to use this feature.	Optional
randomized_bundle_token	Boolean	If server_to_server_identity is set to true, Branch returns a new identity value in any request that does not set randomized_bundle_token. After the first request, the property must be hardcoded with the randomized_bundle_token received in the first network response. Failure to return this value in subsequent requests severely limits the ability to connect different events to a user.	Optional
identity	String	If server_to_server_identity is set to true, you can use this property to associate a custom user ID with Branch's anonymous ID. You should never include personal information here, and all values should be encrypted before being passed to Branch. Learn more about PII.	Optional
tracking_disabled	Boolean	If set to true, Branch will not store any data from this app session. The network response can still return deep link data for processing, but no information will be stored afterward.	Optional
disable_ad_network_callouts	Boolean	If set to true, you can use Branch to selectively remove sessions with this flag from being sent to ad networks. Learn more about filtering ad network data.	Optional
local_url	String	Populate with a Branch web URL that is present on the Clipboard on first open, if available. Otherwise, do not include with request.	Optional, iOS only (NativeLink)
referrer_gclid	String	Populate with the value of gclid from Android Play Store Install Referrer URL. Used for tracking downstream events on Google AdWords when the user opts out on Android 12+ devices. If missing, do not include in request.	Optional, Android only
gbraid	String	Populate with the value of gbraid from the referring URL/URI for the app session. Used for tracking downstream events on Google AdWords when users are opted out of ATT. If missing, do not include in request.	Optional, iOS only
custom_param_1	String	A custom parameter slot you can attach to your OPEN, INSTALL, or other Branch Event metadata. Use it to visualize and analyze Branch aggregate data in Branch reports and exports.	No
custom_param_2	String	A custom parameter slot you can attach to your OPEN, INSTALL, or other Branch Event metadata. Use it to visualize and analyze Branch aggregate data in Branch reports and exports.	No
custom_param_3	String	A custom parameter slot you can attach to your OPEN, INSTALL, or other Branch Event metadata. Use it to visualize and analyze Branch aggregate data in Branch reports and exports.	No
dma_eea	Bool	Whether European regulations, including the DMA, apply to this user and conversion. Set to true if the user is included in European Union regulations. For example, if the user is located within the EEA, they are within the scope of the DMA. Set to false if the user is considered excluded from European Union regulations.	Required if EU regulations apply to this user Warning: Failure to include user consent signals may result in attribution or campaign performance degradation
dma_ad_personalization	Bool	Whether the end user has granted or denied ads personalization consent. Set to true if the user has granted consent for ads personalization. Set to false when the user has denied consent for ads personalization.	Required if dma_eea is set to true (that is, EU regulations apply to this user) Warning: Failure to include user consent signals may result in attribution or campaign performance degradation
dma_ad_user_data	Bool	Whether the end user has granted or denied consent for 3P transmission of user-level data for ads. Set to true if the user has granted consent for 3P transmission of user-level data for ads. Set to false if the user has denied consent for 3P transmission of user-level data for ads.	Required if dma_eea is set to true (that is, EU regulations apply to this user) Warning: Failure to include user consent signals may result in attribution or campaign performance degradation

Response info

When you make a request to the Attribution API, Branch can attribute the app session to a deep link click.

Regardless of whether the session is attributed, the API always returns a 200 response with some contextual data included in the JSON payload.

If the session was attributed to a deep link click, this payload includes the link's deep link data. You can use this data in your in-app logic and to execute your deep linking user experience.

Response body parameters

Below is a partial list of the possible values you may receive in a response:

Parameter	Description
randomized_bundle_token	If you set server_to_server_identity to true in your request, you must ensure the value returned here is used in the randomized_bundle_token property of all requests moving forward for that device.
+clicked_branch_link	This tells you if the current app session was sourced via a Branch Link. You can use this as a conditional trigger that dictates whether you use Branch-specific routing logic or other deep link routing logic. This value is nested within the data object in the response.
+non_branch_link	If a non-Branch deep link opened your app (that is, a Universal Link), you can retrieve that link from this key. This value is nested within the data object in the response.
+is_first_session	This is true if Branch has never seen this app installed on the user's device before. This value is nested within the data object in the response.
+match_guaranteed	This is true if Branch was able to match the app session to the browser click with 100% certainty. You can use this as a conditional trigger for use cases where you have zero risk threshold for a false positive. You should not use this in most instances. Not applicable to SAN-attributed installs. This value is nested within the data object in the response.
$canonical_url	This contains a web URL that you can use for deep link routing. If your app was already set up to route off Universal Links or Android App Links, you can pass this value into that pre-existing routing logic. This value is nested within the data object in the response.
$deeplink_path	This contains a URI relative path that you can use for deep link routing. If your app was already set up to route off URI schemes, you can pass this value into that pre-existing routing logic. This value is nested within the data object in the response.

Examples

Example requests

cURL (iOS)

curl -v -d '{
    "branch_key": "key_live_xxx",
    "branch_secret": "secret_live_xxx",
    "server_to_server": true,
    "app_version": "1.12.4",
    "os": "iOS",
    "os_version": "10.0",
    "model": "iPhone",
    "screen_height": 2208,
    "screen_width": 1242,
    "facebook_app_link_checked": false,
    "user_agent": "{FULL_USER_AGENT_HERE}",
    "hardware_id": "000AAAA-0A0A-000AAA-AAAA000",
    "hardware_id_type": "idfa",
    "ios_vendor_id": "000AAAA-0A0A-000AAA-AAAA000",
    "is_hardware_id_real": true,
    "ad_tracking_enabled": true,
    "custom_param_1": "Parameter 1",
    "custom_param_2": "Parameter 2",
    "custom_param_3": "Parameter 3",
    "dma_eea": true,
    "dma_ad_personalization": true,
    "dma_ad_user_data": true
}' "https://api2.branch.io/v1/open" -H "X-IP-Override: 1.2.3.4"

cURL (Android)

curl -v -d '{
    "branch_key": "key_live_xxx",
    "branch_secret": "secret_live_xxx",
    "server_to_server": true,
    "app_version": "1.12.4",
    "os": "Android",
    "os_version": 26,
    "model": "SM-G960U1",
    "screen_height": 2076,
    "screen_width": 1080,
    "facebook_app_link_checked": false,
    "user_agent": "{FULL_USER_AGENT_HERE}",
    "hardware_id": "00aa0a000a0a0",
    "google_advertising_id": "000AAAA-0A0A-000AAA-AAAA000",
    "advertising_ids": {
        "oaid": "000AAAA-0A0A-000AAA-AAAA000"
    },
    "google_search_install_referrer": "referrer_value_here",
    "clicked_referrer_ts": 1574699946,
    "install_begin_ts": 1574699955,
    "is_hardware_id_real": true,
    "ad_tracking_enabled": true,
    "custom_param_1": "Parameter 1",
    "custom_param_2": "Parameter 2",
    "custom_param_3": "Parameter 3",
    "dma_eea": true,
    "dma_ad_personalization": true,
    "dma_ad_user_data": true
}' "https://api2.branch.io/v1/open" -H "X-IP-Override: 1.2.3.4"

Example responses

Organic response:

{
  "session_id": "xxxx",
  "randomized_device_token": "xxxx",
  "link": "https://bnc.lt/j/adsf",
  "data": "{\"+clicked_branch_link\":false,\"+is_first_session\":false}"
}

Organic response with sever_to_server_identity set to true in the request:

{
  "session_id": "xxxx",
  "randomized_bundle_token": "xxxx",
  "identity": "xxxx",
  "randomized_device_token": "xxxx",
  "link": "https://bnc.lt/j/adsf",
  "data": "{\"+clicked_branch_link\":false,\"+is_first_session\":false}"
}

Response when a session was started by a non-Branch deep link:

{
  "session_id": "823602214081710808",
  "data": "{\"+non_branch_link\":\"https://branch.io/\",\"+clicked_branch_link\":false,\"+is_first_session\":false}",
  "randomized_device_token": "823601870295755491"
}

Response when a session was started by a Branch Link:

{
  "randomized_device_token": "823600311503935224",
  "link": "https://example.app.link/X7OsnWv9TF",
  "session_id": "429691081177874743",
  "data": "{
    "$canonical_url": "https://example.com/home?utm_campaign=test",
    "$desktop_url": "http://example.com/home",
    "$og_description": "My Content Description",
    "$og_image_url": "http://lorempixel.com/200/200/",
    "$og_title": "46D6D28E-0390-40E4-A856-BD74F34D24C8",
    "+click_timestamp": 1503684563,
    "+clicked_branch_link": true,
    "+is_first_session": false,
    "+match_guaranteed": true,
    "custom_param_1": "blue",
    "dma_eea": true,
    "dma_ad_personalization": true,
    "dma_ad_user_data": true,
    "~campaign": "new launch",
    "~channel": "facebook",
    "~creation_source": 3,
    "~feature": "sharing",
    "~id": 429691043152332059,
    "~referring_link": "https://example.app.link/X7OsnWv9TF",
    "~stage": "new person",
    "~tags": ["one","two"]
  }"
}

Track downstream events

Every time you call the v1/open Attribution API endpoint, the API tracks an INSTALL, REINSTALL, or OPEN event.

To track other events, you need to use the relevant API instructions for the type of event you want to track:

• Commerce Events (such as PURCHASE and ADD_TO_CART)
• Content Events (such as SEARCH and VIEW_ITEM)
• Lifecycle Events (such as SUBSCRIBE or LOGIN)
• Custom Events (all other events you want to track)

When tracking these downstream conversion events, address the following items:

1. If you make a request from the device, Branch automatically retrieves the IP address from the request. If you make the request from a server, you must set the user's IP address via the X-IP-Override header.
2. Set the device's user agent in the user_data.user_agent request body parameter.
3. For events that occur in your iOS app, populate the device ID with the IDFA (or fall back to the IDFV). For Android apps, populate the device ID with the GAID (or fall back to android_id).
4. For events that occur in your web app, retrieve a browser fingerprint via the Branch Web SDK. Include this in the event call.
5. Populate the developer_identity property whenever a persistent user ID is available. View our guide on best practices for user IDs.