> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Attribution API

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

[Read the Attribution API overview](https://help.branch.io/apidocs/attribution/overview.md)

## Request open

`POST https://api2.branch.io/v1/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_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, don't include it in the request.
- `app_version` (string, required) — Your app's version.
- `branch_key` (string, required) — The Branch Key of the originating app obtained in your [Account Settings](https://help.branch.io/account-hub/profile-settings.md).
- `branch_secret` (string, required) — The Branch Secret of the originating app obtained in your [Account Settings](https://help.branch.io/account-hub/profile-settings.md).
- `is_hardware_id_real` (boolean, required) — Set to false if the hardware_id property can't be populated. Otherwise, default to true.
- `model` (string, required) — Model of the device.
- `os` (enum, required) — System OS. Only accepts Android or iOS. One of `iOS`, `Android`.
- `os_version` (string, required) — 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_server` (boolean, required) — Must be `true` for server-to-server attribution requests. Required.
- `user_agent` (string, required) — The user agent of the device.
- `advertising_ids` (object) — Valid for Android only. The set of Advertising IDs if it's available. Otherwise, don't include it in the request. Can include identifiers like OAID.
- `advertising_ids.<key>` (string) — Any additional key. Values are passed through as provided.
- `android_app_link_url` (string) — Populate with a Branch or non-Branch web URL that opened the app (if missing, don't include it in the request).
- `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 it to Branch within that time to use it for attribution.
- `clicked_referrer_ts` (integer) — Valid for Android only. The referrer click timestamp collected from the Play Install Referrer library. Only include it in the app's first session, if it's available.
- `custom_param_1` (string) — A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing and analyzing Branch aggregate data in both Branch reports and exports.
- `custom_param_2` (string) — A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing and analyzing Branch aggregate data in both Branch reports and exports.
- `custom_param_3` (string) — A customized parameter attached to your OPEN, INSTALL, or Event metadata to be used for visualizing and analyzing Branch aggregate data in both Branch reports and exports.
- `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](https://help.branch.io/developer-hub/filtering-ad-network-data.md#set-event-flag).
- `dma_ad_personalization` (boolean) — Whether the end user has granted or denied ads personalization consent. Required if `dma_eea` is set to `true` (that is, EU regulations apply to this user).
- `dma_ad_user_data` (boolean) — Whether the end user has granted or 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).
- `dma_eea` (boolean) — Whether European regulations, including the DMA, apply to this user and conversion. Required if EU regulations apply to this user.
- `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 in [Branch](https://help.branch.io/marketer-hub/meta-app-install-ads.md#setup)).
- `first_session` (boolean) — Identifies whether this is the first time the user opened the app. If true, Branch checks whether we saw the user download the app before, and marks the session as a reinstall if yes and an install if no. If this value is set to false, Branch counts the session as an open.
- `gbraid` (string) — Valid for iOS only. (Optional, for Google AdWords campaigns) Extract 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, don't include it in the request).
- `google_advertising_id` (string) — Valid for Android only. The Google Advertising ID if it's available. Otherwise, don't include it in the request.
- `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 it in the app's first session, if it's available.
- `hardware_id` (string) — In iOS, populate with the IDFA if it's available. Otherwise, fall back to IDFV. On Android, populate with the ANDROID_ID (hardware ID). If no device ID is available, don't include it in the request.
- `hardware_id_type` (enum) — Valid for iOS only. Value confirms whether the iOS ID in the hardware_id property is an "idfa" or "vendor_id" (don't include it in the request if hardware_id isn't populated). One of `idfa`, `vendor_id`.
- `identity` (string) — If server_to_server_identity is true, you can use this property 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/account-hub/best-practices-to-minimize-data-sent-to-branch.md#developer-identity)
- `install_begin_ts` (integer) — Valid for Android only. The install begin timestamp collected from the Play Install Referrer library. Only include it in the app's first session, if it's available.
- `install_referrer_extras` (string) — Valid for Android only. Populate it with the value of the full Android Play Store Install Referrer URL. Only include it in the app's first session, if it's available.
- `ios_vendor_id` (string) — Valid for iOS only. The IDFV if it's available. Otherwise, don't include it in the request.
- `link_identifier` (string) — When a URI opens the app, check for a link_click_id query and populate with that value (if missing, don't include it in the request). The link_click_id may also be sourced by the [Google Install Referrer](https://help.branch.io/apidocs/attribution/overview.md#optional-support-google-play-install-referrer).
- `local_ip` (string) — This is the device's local IP address, if one is available. This is incremental to the required IP header. Optional but highly recommended metadata that improves attribution accuracy.
- `local_url` (string) — (Optional, for NativeLink) Populate with a Branch web URL that's present on the clipboard on the very first open (if missing, don't include it in the request).
- `randomized_bundle_token` (string) — If server_to_server_identity is true, Branch returns a new identity value in any request that doesn't 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.
- `referrer_gclid` (string) — Valid for Android only. (Optional, for Google AdWords campaigns) Extract the value of gclid from the 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, don't include it in the request).
- `screen_height` (integer) — Height of the device's screen. Optional but useful metadata that improves attribution accuracy.
- `screen_width` (integer) — Width of the device's screen. Optional but useful metadata that improves attribution accuracy.
- `server_to_server_identity` (boolean) — Setting it to true lets you set a randomized_bundle_token property in v1/open requests and returns a value in the response. Don't set this property in the request if you won't use this feature.
- `tracking_disabled` (boolean) — If set to true, Branch won't 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.
- `universal_link_url` (string) — Populate with a Branch or non-Branch web URL that opened the app (if missing, don't include it in the request).

### Responses

- `200` — Success.
- `400` — Bad request—typically an invalid or missing credential or parameter.
- `429` — Rate limit exceeded—reduce request frequency and retry.

### Returns

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

### Example request

```bash
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
  }'
```

### Example responses

`200`

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

`400`

```json
{
  "error": {
    "message": "Authentication failed.",
    "code": 400
  }
}
```

`429`

```json
{
  "error": {
    "code": 429,
    "message": "Rate limit reached."
  }
}
```