Filters

Track specific events for deep linking and session attribution.

Overview

The Branch Attribution API offers developers a way 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 will be deep link data.

If you choose to use this API instead of tracking these events with a Branch SDK, please be aware that session management becomes the responsibility of the developer. You will 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, one would need to duplicate the code in the SDK.

For this reason, it is highly recommended that all apps use a Branch SDK when possible.

Limitations

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

Contact your Branch Account Manager to confirm the exact limit for your account.

Sessions exceeding your rate limit will still return deep link data in the network request, but the data will not appear in your Branch Dashboard reports or exports.

Branch will also return 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, please 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

Prerequisites

In order to use the Attribution API, you first need to:

  1. Create a Branch Dashboard.
  2. Make sure that your account has access to the v1/open API enabled. This access is restricted to Enterprise accounts. See the "Access" section for more.
  3. Configure your Branch Dashboard 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).

Access

Access to the Attribution API is restricted to Enterprise accounts. Please contact your Branch Account Manager to confirm if your account is eligible for enablement.

Authentication

Calls to the Attribution API require your Branch Key and Branch Secret. Both can be found in your Branch Dashboard Account Settings.

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. An example: If the URI example://open?link_click_id=1234 opens the app, you will need to retrieve the 1234 value.
  5. Examine the AppDelegate's continueUserActivity() function for a webpageURL value.
    1. The webpageURL value will live 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 Deep Link.

Optional: Support Apple Search Ads

For server-to-server integrations, you will 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:
    func appleAttributionToken() -> String? {
            if #available(iOS 14.3, *) {
                return try? AAAttribution.attributionToken()
            }
            return nil
        }
    
    + (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. An example: If the URI example://open?link_click_id=1234 opens the app, you will 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 Deep 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=<value> or &link_click_id-<value>. In either scenario, extract only the <value> part.
  3. Examine the referrer URL for a google_search_install_referrer query parameter.
    1. If present, retrieve its value for use in the requests's google_search_install_referrer parameter.
    2. This value might appear in the referrer URL as &google_search_install_referrer=<value> or &google_search_install_referrer-<value>. In either scenario, extract only the <value> 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 as when your app is launched and brought to the foreground of the device. The launch can either be from a cold start, or a transition from running in the background (present in the iOS or Android task manager) to the foreground.

Request Open

Request Info

Export Request

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

Request Headers

HeaderDescriptionRequired?
X-IP-OverrideThe device's public IP address from your app user's device, not your server's IP address.Yes
content-typeapplication/jsonYes
acceptapplication/jsonRecommended

Request Body Parameters

ParameterTypeDescriptionRequired?
branch_keyStringThe Branch Key of the relevant app, found in the Settings tab of your Branch Dashboard.Required on iOS & Android
branch_secretStringThe Branch Secret of the relevant app, found in the Settings tab of your Branch Dashboard.Required on iOS & Android
server_to_serverBoolAlways set this value to true.Required on iOS & Android
app_versionStringThe version of your app, such as "1.12.4".Required on iOS & Android
osStringChoose either Android or iOS.Required on iOS & Android
os_versionStringThe device's OS version, such as "14" for Android or "17.3.1" for iOS.

This parameter cannot be blank but the API will accept any string value, such as "NA".
Required on iOS & Android
user_agentStringThe user agent of the device.Required on iOS & Android
hardware_idStringFor iOS, populate with the IDFA if available. Otherwise, fallback to IDFV.

For Android, populate with the ANDROID_ID (hardware ID). Otherwise, do not include in request.
Required on iOS
hardware_id_typeStringThis 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_idStringThe IDFV, if available.

Otherwise, do not include in request.
Required on iOS
google_advertising_idStringThe Google Advertising ID, if available.

Otherwise, do not include in request.
Required on Android
advertising_idsObjectThe set of advertising IDs, if available.

Otherwise, do not include in request.

Can include identifiers like OAID.
Required on Android
is_hardware_id_realBooleanSet this value to false if the hardware_id property cannot be populated.

Otherwise, default to true.
Required on iOS & Android
ad_tracking_enabledBooleanThis 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_ipStringThis is the device's local IP address, if one is available. Optional but highly recommended for improving attribution accuracy.

The is supplemental to the required X-IP-Override value in the header.
Recommended
screen_heightIntHeight of the device’s screen.Recommended
screen_widthIntWidth of the device’s screen.Recommended
link_identifierStringWhen 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 by the Google Install Referrer.
Optional
universal_link_urlStringPopulate 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_urlStringPopulate 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_checkedBooleanSet to false to ensure Branch retrieves deep links from Facebook's deferred deep linking API.

This requires adding your Facebook App Secret to the Branch Dashboard. Learn more in our guide.
Optional
install_referrer_extrasStringPopulate with the value of the full Android PlayStore Install Referrer URL, if available.

Only include in the app's first session.
Optional, Android only
google_search_install_referrerStringPopulate 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_tsLongThe 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_tsLongThe 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_tokenStringThe 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 in order to be used for attribution.
Optional, iOS only
search_ad_encodedStringThe Base64 encoded string of the entire response from the Apple Search Ads API.Deprecated
first_sessionBooleanIf this param is set to true, Branch will check if we have previously seen the user download the app. If we have seen the user before, we will mark it as a REINSTALL. If we have not, we will mark it as an INSTALL.

If this param is set to false, Branch will count the session as an OPEN.
Optional
server_to_server_identityBooleanSetting to true enables the ability to 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_tokenBooleanIf server_to_server_identity is set to true, then Branch will return 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
identityStringIf server_to_server_identity is set to true, this property can be used 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 here.
Optional
tracking_disabledBooleanIf 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_calloutsBooleanIf set to true, you can use the Branch Dashboard to selectively remove sessions with this flag from being sent to ad networks. Learn more about filtering ad network data here.Optional
local_urlStringPopulate 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_gclidStringPopulate with the value of gclid from Android PlayStore Install Referrer URL.

Utilized for tracking downstream events on Google Adwords when user opts out on Android 12+ devices.

If missing, do not include in request.
Optional, Android only
gbraidStringPopulate with the value of gbraid from the referring URL/URI for the app session.

Utilized 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_1StringA custom parameter slot you can attach to your OPEN, INSTALL, or other Branch Event metadata.

To be used for visualizing/analyzing Branch aggregate data in Branch Dashboard reports and exports.
No
custom_param_2StringA custom parameter slot you can attach to your OPEN, INSTALL, or other Branch Event metadata.

To be used for visualizing/analyzing Branch aggregate data in Branch Dashboard reports and exports.
No
custom_param_3StringA custom parameter slot you can attach to your OPEN, INSTALL, or other Branch Event metadata.

To be used for visualizing/analyzing Branch aggregate data in Branch Dashboard reports and exports.
No
dma_eeaBoolWhether European regulations, including the DMA, apply to this user and conversion.

Set to true if user is included in European Union regulations. For example, if the user is located within the EEA, they are within the scope of DMA.

Set to false if 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_personalizationBoolWhether end user has granted or denied ads personalization consent.

Set to true if user has granted consent for ads personalization.

Set to false when user has denied consent for ads personalization.
Required if dma_eea is set to true (i.e., EU regulations apply to this user)

Warning: Failure to include user consent signals may result in attribution or campaign performance degradation
dma_ad_user_dataBoolWhether end user has granted or denied consent for 3P transmission of user level data for ads.

Set to true if user has granted consent for 3P transmission of user-level data for ads.

Set to false if user has denied consent for 3P transmission of user-level data for ads.
Required if dma_eea is set to true (i.e., EU regulations apply to this user)

Warning: Failure to include user consent signals may result in attribution or campaign performance degradation

Response Info

When a request is made to the Attribution API, the app session can be attributed to a deep link click.

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

If the session was attributed to a deep link click, this payload will include 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:

ParameterDescription
randomized_bundle_tokenIf 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_linkThis will tell you if the current app session was sourced via a Branch Deep Link.

This can be used 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_linkIf a non-Branch deep link opened your app (i.e., a Universal Link), you can retrieve that link from this key.

This value is nested within the data object in the response.
+is_first_sessionThis will be 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_guaranteedThis will be true if Branch was able to match the app session to the browser click with 100% certainty.

This can be used as a conditional trigger for use cases where you have zero risk threshold for a false positive. This should not be used in most instances.

Not applicable to SAN-attributed installs.

This value is nested within the data object in the response.
$canonical_urlThis will contain a web url that you can use for deep link routing. If your app was already setup 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_pathThis will contain a URI relative path that you can use for deep link routing. If your app was already setup 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 -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 -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 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 session was started by a Branch Deep 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 the v1/open Attribution API endpoint is called, the API will track an INSTALL, REINSTALL, or OPEN event.

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

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

  1. If a request is made from the device, Branch will automatically retrieve the IP address from the request. If the request is made from a server, the user's IP address must be set 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 fallback to the IDFV). For Android apps, populate the device ID with the GAID (or fallback 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. Please view our guide on best practices for user IDs.