Request Open

Post
/open

The network request to v1/open should occur when you are successfully notified the app was brought to the foreground. Branch defines an app lifecycle as a session of when 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.

Body parameters
Expand All
object
branch_key
string Required

The Branch Key of the originating app obtained in your Account Settings

Examplekey_live_xxxx
branch_secret
string Required

The Branch secret of the originating app obtained in your Account Settings

Examplesecret_live_xxxx
server_to_server
boolean Required

REQUIRED Always set to true

Valid values[ "True" ]
Defaulttrue
ExampleTrue
app_version
string Required

Your app's version

Example1.12.4
model
string Required

Model of the device.

ExampleiPhone 14 Pro
os
string Required

System OS. Only accepts Android or iOS

Valid values[ "iOS", "Android" ]
ExampleiOS
os_version
string Required

The version of the device's OS (e.g. “23” for Android or “9.1.2” for iOS respectively. Will accept any value, preferred default to “NA”. This cannot be blank.)

Example16.1
user_agent
string Required

The user agent of the device

ExampleMozilla/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
boolean Required

Set to false if the hardware_id property cannot be populated, otherwise default to true

Defaulttrue
ExampleTrue
ad_tracking_enabled
boolean Required

A value 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.

ExampleTrue
hardware_id
string

In iOS, populate with the IDFA if it's available, otherwise fallback to IDFV. On Android, populate with the ANDROID_ID (hardware id). If no device ID is available, do not include in request.

ExampleXXXX-0000
hardware_id_type
string

Valid for iOS ONLY. Value confirms whether the iOS ID in the hardware_id property is an "idfa" or "vendor_id" (do not include in request, if hardware_id is not populated)

Valid values[ "idfa", "vendor_id" ]
Exampleidfa
ios_vendor_id
string

iOS ONLY The IDFV if it's available, otherwise do not include in request.

ExampleXXXX-0000
google_advertising_id
string

Valid for ANDROID ONLY. The Google Advertising ID if it's available, otherwise do not include in request

Examplexxxx-0000
advertising_ids
object

ANDROID ONLY The set of Advertising IDs if it's available, otherwise do not include in request. Can include identifiers like OAID

property*
string additionalProperties
local_ip
string

This is the device's local IP address, if one is available. This is incremental to the falserequired IP header. An optional but highly recommended data metadata that improves attribution accuracy.

Example000.000.0.000
screen_height
integer

Height of the device’s screen. An optional but useful data metadata that improves attribution accuracy.

Example2556
screen_width
integer

Width of the device’s screen. An optional but useful data metadata that improves attribution accuracy.

Example1179
link_identifier
string

a URI opens the app, check for a link_click_id query, and populate with that value (if missing, do not include in request) link_click_id may also be sourced by the Google Install Referrer

Example00000000
universal_link_url
string

Populate with a Branch or non-Branch web url that opened the app (if missing, do not include in request)

Examplehttps://branch.app.link/example?utm_medium=test
android_app_link_url
string

Populate with a Branch or non-Branch web url that opened the app (if missing, do not include in request)

Examplehttps://branch.app.link/example?utm_medium=test
facebook_app_link_checked
boolean

Set to false to ensure we retrieve deep links from Facebook's deferred deep linking API (requires adding your Facebook App Secret to the Branch Dashboard)

ExampleFalse
install_referrer_extras
string

Valid for ANDROID ONLY Populate it with the value of the full Android PlayStore Install Referrer URL. Only include in the app's first session, if it's available.

Exampleutm_source=some_source&utm_medium=preload&utm_campaign=null&gclid=Cj0KCQiA7IDiBRCLARIsABIPohhqdEU00f-Obte_OIVTbjPo-iLDBjkhj8ov=
google_search_install_referrer
string

Valid for ANDROID ONLY The value of the google_search_install_referrer query parameter on the referrerUrl from the Google Install Referrer. Only include in the app's first session, if it's available.

Example0000XXxx
clicked_referrer_ts
integer

Valid for ANDROID ONLY The referrer click timestamp collected from the Play Install Referrer library. Only include in the app's first session, if it's available.

Example0
install_begin_ts
integer

Valid for ANDROID ONLY The install begin timestamp collected from the Play Install Referrer library. Only include in the app's first session, if it's available.

Example0
apple_attribution_token
string

Valid for iOS ONLY Attribution Token used for Apple Search Ads . used to call the Apple Search Ads Attribution API. The token has a 24 hr TTL, so send to Branch within that time in order to use it for attribution.

ExampleXXXX0000xxxx
first_session
boolean

Identifies if this is the first time the user opened the app. If true, Branch will check if we saw the user download the app before, and mark the session as a reinstall if yes, and an install if no. If this value was set to false, Branch will count the session as an open.

ExampleFalse
server_to_server_identity
boolean

Setting to true enables the ability to set an randomized_bundle_token property in v1/open requests and returns a value in the response. Do not set this property in the request, if this feature will not be used.

ExampleFalse
randomized_bundle_token
string

If server_to_server_identity is true, Branch returns a new identity value in any request that does not set randomized_bundle_token. After the first request, this 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 for that user.

Example00000000
identity
string

If server_to_server_identity is true, this property can be used to associate a custom user ID with Branch's anonymous identity. (You should never use personal user information here, and all values should be encrypted before being passed to Branch.)[https://help.branch.io/using-branch/docs/best-practices-to-avoid-sending-pii-to-branch#section-developer-identity}

ExampleX0000000
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 afterwards.

ExampleFalse
disable_ad_network_callouts
boolean

If set to true, you can use the Branch Dashboard to selectively remove sessions with this flag (from being sent to ad networks)[https://help.branch.io/developers-hub/docs/filtering-ad-network-data#setting-the-event-flag-in-the-branch-sdk}

ExampleFalse
local_url
string

(Optional, for NativeLink) Populate with a Branch web url that is present on the clipboard on the very first open (if missing, do not include in request)

Examplehttps://branch.app.link/example?utm_medium=test
referrer_gclid
string

Valid for ANDROID ONLY (Optional, for Google AdWord Campaigns) Extract 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)

ExampleXXXX_0000_xxxx
gbraid
string

Valid for IOS ONLY (Optional, for Google AdWord Campaigns) Extract 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)

ExampleXXXX_0000_xxxx
custom_param_1
string

A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.

ExamplePARAMETER 1
custom_param_2
string

A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.

ExamplePARAMETER 2
custom_param_3
string

A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing/analyzing Branch aggregate data in both the Branch Dashboard reports and exports.

ExamplePARAMETER 3
dma_eea
boolean

Whether European regulations, including the DMA, apply to this user and conversion. Required if EU regulations apply to this user.

ExampleTrue
dma_ad_personalization
boolean

Whether end user has granted or denied ads personalization consent. Required if dma_eea is set to true (i.e., EU regulations apply to this user).

ExampleTrue
dma_ad_user_data
boolean

Whether end user has granted or 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).

ExampleTrue
Responses
200

Ok

object
session_id
string

The generated session id assigned against the API Setup. This is the primary response the developer must look into.

Example00000000
data
string

The setup data in JSON format set against the API.

Example{"+clicked_branch_link":false,"+is_first_session":true}
device_fingerprint_id
string

Device unique fingerprint identity used for transactional reference.

Example00000000
invoke_register_app
boolean

N/A

ExampleTrue
400

Authentication Failed

Result
"{\n    \"error\": {\n        \"message\": \"Authentication failed !\",\n        \"code\": 400\n    }\n}"
Expand All
object
error
object (inline_response_400_error)
message
string
ExampleAuthentication failed !
code
integer
Example400
429

Rate Limit Reached

Result
"{\n    \"error\": {\n        \"code\": 429,\n        \"message\": \"Rate limit reached.\"\n    }\n}"
Expand All
object
error
object (inline_response_400_error)
message
string
ExampleAuthentication failed !
code
integer
Example400