Attribution API

The Attribution API attributes app sessions and conversions to your active campaigns.

Request open

POST/open

The network request to v1/open should occur when you're successfully notified the app was brought to the foreground. Branch defines an app lifecycle as a session in which your application is launched (cold start, or if it was present in the iOS or Android task manager) and comes to the device's foreground.

Parameters

ad_tracking_enabledbooleanRequired
A value used to determine whether the IDFA or GAID can be used for advertising purposes. If Limit Ad Tracking should be enabled, don't include it in the request.
app_versionstringRequired
Your app's version.
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.
is_hardware_id_realbooleanRequired
Set to false if the hardware_id property can't be populated. Otherwise, default to true.
modelstringRequired
Model of the device.
osenumRequired
System OS. Only accepts Android or iOS.
iOSAndroid
os_versionstringRequired
The version of the device's OS (for example, “23” for Android or “9.1.2” for iOS). Accepts any value. The preferred default is “NA”. This can't be blank.
server_to_serverbooleanRequired
Must be true for server-to-server attribution requests. Required.
user_agentstringRequired
The user agent of the device.

More parameters

advertising_idsobject
android_app_link_urlstring
apple_attribution_tokenstring
clicked_referrer_tsinteger
custom_param_1string
custom_param_2string
custom_param_3string
disable_ad_network_calloutsboolean
dma_ad_personalizationboolean
dma_ad_user_databoolean
dma_eeaboolean
facebook_app_link_checkedboolean
first_sessionboolean
gbraidstring
google_advertising_idstring
google_search_install_referrerstring
hardware_idstring
hardware_id_typeenum
identitystring
install_begin_tsinteger
install_referrer_extrasstring
ios_vendor_idstring
link_identifierstring
local_ipstring
local_urlstring
randomized_bundle_tokenstring
referrer_gclidstring
screen_heightinteger
screen_widthinteger
server_to_server_identityboolean
tracking_disabledboolean
universal_link_urlstring

Returns

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

{
  "branch_key": "key_live_xxxx",
  "branch_secret": "secret_live_xxxx",
  "server_to_server": true,
  "app_version": "1.12.4",
  "model": "iPhone 14 Pro",
  "os": "iOS",
  "os_version": "16.1",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1",
  "is_hardware_id_real": true,
  "ad_tracking_enabled": true,
  "hardware_id": "XXXX-0000",
  "hardware_id_type": "idfa",
  "ios_vendor_id": "XXXX-0000",
  "google_advertising_id": "xxxx-0000",
  "local_ip": "000.000.0.000",
  "screen_height": 2556,
  "screen_width": 1179,
  "link_identifier": "00000000",
  "universal_link_url": "https://branch.app.link/example?utm_medium=test",
  "android_app_link_url": "https://branch.app.link/example?utm_medium=test",
  "install_referrer_extras": "utm_source=google&utm_medium=cpc&utm_campaign=spring_sale&gclid=EAIaIQobChMI1a2b3c4d",
  "google_search_install_referrer": "0000XXxx",
  "apple_attribution_token": "XXXX0000xxxx",
  "randomized_bundle_token": "00000000",
  "identity": "X0000000",
  "local_url": "https://branch.app.link/example?utm_medium=test",
  "referrer_gclid": "XXXX_0000_xxxx",
  "gbraid": "XXXX_0000_xxxx",
  "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
}

curl 'https://api2.branch.io/v1/open' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "branch_key": "key_live_xxxx",
    "branch_secret": "secret_live_xxxx",
    "server_to_server": true,
    "app_version": "1.12.4",
    "model": "iPhone 14 Pro",
    "os": "iOS",
    "os_version": "16.1",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1",
    "is_hardware_id_real": true,
    "ad_tracking_enabled": true,
    "hardware_id": "XXXX-0000",
    "hardware_id_type": "idfa",
    "ios_vendor_id": "XXXX-0000",
    "google_advertising_id": "xxxx-0000",
    "local_ip": "000.000.0.000",
    "screen_height": 2556,
    "screen_width": 1179,
    "link_identifier": "00000000",
    "universal_link_url": "https://branch.app.link/example?utm_medium=test",
    "android_app_link_url": "https://branch.app.link/example?utm_medium=test",
    "install_referrer_extras": "utm_source=google&utm_medium=cpc&utm_campaign=spring_sale&gclid=EAIaIQobChMI1a2b3c4d",
    "google_search_install_referrer": "0000XXxx",
    "apple_attribution_token": "XXXX0000xxxx",
    "randomized_bundle_token": "00000000",
    "identity": "X0000000",
    "local_url": "https://branch.app.link/example?utm_medium=test",
    "referrer_gclid": "XXXX_0000_xxxx",
    "gbraid": "XXXX_0000_xxxx",
    "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
  }'

Response

Success.

{
  "session_id": "",
  "data": {
    "+clicked_branch_link": false,
    "+is_first_session": true
  },
  "device_fingerprint_id": "",
  "invoke_register_app": true
}

Attribution API

Request open

Parameters

More parameters Expand all

Returns

More parameters