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

# Events API Overview

## Overview

The Branch Events API is a robust tool for tracking events that take place in your app.

These events fall under 4 categories: **Commerce**, **Content**, **Lifecycle**, or **Custom**.

### Benefits

With the Branch Events API, you can track conversion data and include detailed metadata to help you better understand user behavior as it relates to your campaigns.

### Try it!

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

- [Logging Standard Events](https://help.branch.io/apidocs/events.md#logStandardEvents)
- [Logging Custom Events](https://help.branch.io/apidocs/events.md#logCustomEvents)

## Getting started

### Before you begin

To use the Events API, you first need to create a [Branch account](https://dashboard.branch.io/).

### Authentication

For calls to the Events API, you need your Branch Key.

**Legacy Branch**

To retrieve your credentials in the [legacy Branch experience](https://help.branch.io/marketer-hub/branch-dashboard-overview.md):

1. Navigate to the **Account → Settings → Profile** [tab](https://dashboard.branch.io/account-settings/profile).
2. Use the **copy icon** to copy your Branch Key.

**New Branch**

To retrieve your credentials in the [new Branch experience](https://help.branch.io/account-hub/credentials-new.md):

1. Navigate to the **Configuration → Security & Access → Credentials** [tab](https://branchdocs.app.link/apis-to-credentials).
2. Use the **copy icon** to copy your Branch Key.

Visit our [guide](https://help.branch.io/account-hub/credentials-new.md) to learn more about managing your Branch credentials.

### Important considerations

- **Real-time only:** You must send events in real time as they occur. Branch does not support backtracking or historical event ingestion. Events with timestamps in the past will not be backfilled into reports.
- SKAdNetwork **(SKAN)**: Your app must handle SKAN natively, not through the Branch SDK. Branch returns SKAN-relevant fields (such as `coarse_key` and `update_conversion_value`) in the API response so your app can update its conversion value accordingly. See the [SKAdNetwork guide](https://help.branch.io/marketer-hub/skadnetwork.md) for details.

## Usage

### Logging standard events

Use this endpoint to log standard Branch Events.

Standard Branch Events are limited to **Commerce**, **Content**, and **Lifecycle** events. See the "Request body parameters" [table](https://help.branch.io/apidocs/events/overview.md#request-info) in this section to see which standard Branch Events you can log with this endpoint.

#### Request info

**Export request**

```http
POST /v2/event/standard
```

**Request headers**

| Parameter | Value | Required |
| --- | --- | --- |
| `content-type` | application/json | Recommended |
| `accept` | application/json | Recommended |
| `X-IP-Override` | A public IPv4 address (for example, `198.51.100.42`) | Optional. See callout below. |

> **Caution**
>
> The `X-IP-Override` header lets you specify the IP address Branch uses for the event (for example, when forwarding events server-to-server from your own backend). You must meet two requirements for this header to function:
>
> 1. **Your app ID must be allowlisted by Branch.** The header is ignored until allowlisting is enabled. [Open a support request](https://support.branch.io/) to have your app ID allowlisted before you begin sending the header in production.
> 2. **You must also include** `user_data.ip` **in the request body** with the same IP value. Sending the header alone is not sufficient. The body field is what Branch persists for attribution.

**Top-level request body parameters**

| Top-level parameter | Type | Description | Required |
| --- | --- | --- | --- |
| `branch_key` | String | The Branch Key for the relevant application. | **Yes** |
| `name` | String | The name of the event to log. Must be one of the standard Branch Event names included below.<br><br>**Commerce event names**:<br>`ADD_TO_CART`<br>`ADD_TO_WISHLIST`<br>`CLICK_AD`<br>`VIEW_CART`<br>`INITIATE_PURCHASE`<br>`ADD_PAYMENT_INFO`<br>`PURCHASE`<br>`SPEND_CREDITS`<br><br>**Content event names**:<br>`SEARCH`<br>`VIEW_ITEM`<br>`VIEW_ITEMS`<br>`RATE`<br>`SHARE`<br><br>**Lifecycle event names**:<br>`ADD_TO_CART`<br>`ADD_TO_WISHLIST`<br>`CLICK_AD`<br>`VIEW_CART`<br>`INITIATE_PURCHASE`<br>`ADD_PAYMENT_INFO`<br>`PURCHASE`<br>`SPEND_CREDITS` | **Yes** |
| `customer_event_alias` | String | The event alias, as defined by you. Used in addition to the Branch Event name in the `name` parameter. | No |
| `user_data` | Obj | An object related to user data, containing things like device information and advertising IDs.<br><br>Also used to provide information regarding the user for Google DMA compliance.<br><br>See `user_data` [table](https://help.branch.io/apidocs/events/overview.md#request-info) for more. | **Yes** |
| `custom_data` | Obj | An object for additional custom key-value pairs that you want attached to the Branch Event. This is attached to Branch Events that are retrieved via exports and sent via webhooks. | No |
| `event_data` | Obj | An object containing additional data about the specific event, including information about things like currency and revenue.<br><br>See `event_data` [table](https://help.branch.io/apidocs/events/overview.md#request-info) for more. | No |
| `content_items` | Obj | An object **only for Commerce and Content** Branch Events. Contains additional information about specific content.<br><br>See `content_items` [table](https://help.branch.io/apidocs/events/overview.md#request-info) for more. | No |

**Parameters included in** `user_data` **object**

> **Caution: Required identifiers**
>
> You must include **at least one of the following** in `user_data`:
>
> 1. `user_data.developer_identity` or
> 2. `user_data.browser_fingerprint_id` or
> 3. `user_data.os=iOS` AND `user_data.idfa` or
> 4. `user_data.os=iOS` AND `user_data.idfv` or
> 5. `user_data.os=Android` AND `user_data.android_id` or
> 6. `user_data.os=Android` AND `user_data.aaid`

> **Note**
>
> In addition to the standard identifiers above, include any **third-party IDs** that apply to your integration so you can join events with downstream tools.  
> Common examples:
>
> - `user_data.google_analytics_id`: the Google Analytics client ID, for cross-platform stitching with GA.
> - A Snowflake user identifier (or equivalent data-warehouse key) inside `custom_data`, so you can join events with your data warehouse.
>
> Including these where applicable improves attribution coverage and downstream analytics.

| Parameters for `user_data` | Type | Description | Required |
| --- | --- | --- | --- |
| `user_data.os` | String | Examples:<br>`Android`<br>`iOS`<br>`Mac_OS`<br>`Linux`<br>`Windows` | See "Required identifiers" callout |
| `user_data.os_version` | String | The version of the operating system. | **Strongly recommended** for all paid traffic to ensure accurate attribution<br><br>**Required** for Facebook campaigns on iOS |
| `user_data.advertising_ids` | Obj | A wrapper object for advertising identifiers. Use this in addition to the flat `aaid`, `idfa`, and `idfv` fields above to future-proof your integration for non-standard IDs (for example, OAID on Huawei devices).<br><br>Example: `"advertising_ids": {"oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"}` | No (recommended for non-standard IDs like OAID) |
| `user_data.environment` | String | Usually `FULL_APP`. | No |
| `user_data.aaid` | String | The Android Advertising ID. | See "Required identifiers" callout |
| `user_data.android_id` | String | The Android hardware ID. | See "Required identifiers" callout |
| `user_data.idfa` | String | The iOS advertising ID. | See "Required identifiers" callout |
| `user_data.idfv` | String | The iOS vendor ID. | See "Required identifiers" callout |
| `user_data.anon_id` | String | The Facebook anonymous user ID. Used for measurement and attribution when running Facebook campaigns that rely on Aggregated Event Measurement (AEM). | **Required** when running Facebook campaigns using Aggregated Event Measurement (AEM) on iOS |
| `user_data.limit_ad_tracking` | Bool | Set to `true` if the partner has opted to not be tracked by advertisers. | No |
| `user_data.user_agent` | String | The user agent of the browser or app where the event occurred. Usually associated with a webview. | No |
| `user_data.browser_fingerprint_id` | String | An internal-only field for Branch to track browsers. | See "Required identifiers" callout |
| `user_data.http_origin` | String | The current page URL where the Branch Web SDK logged a web session start. | No |
| `user_data.http_referrer` | String | The referral URL that led to the current page where the Branch Web SDK logged a web session start. | No |
| `user_data.developer_identity` | String | The developer-specified identity for a user. | See "Required identifiers" callout |
| `user_data.country` | String | The country code of the user, usually based on device settings or the user agent string. | No |
| `user_data.language` | String | The language code of the user, usually based on device settings or the user agent string. | No |
| `user_data.ip` | String | The IP address for the device where the event occurred. | No |
| `user_data.local_ip` | String | **Android only**: the local IP of the device.<br><br>Example: `"168.1.1.1"` | No |
| `user_data.brand` | String | The brand of the device. | No |
| `user_data.randomized_device_token` | String | An internal-only Branch field for tracking devices. | No |
| `user_data.app_version` | String | The version of the app downloaded by the user. | No |
| `user_data.model` | String | The model of the device. | No |
| `user_data.screen_dpi` | Int | The screen's DPI. | No |
| `user_data.screen_height` | Int | The screen's height. | No |
| `user_data.screen_width` | Int | The screen's width. | No |
| `user_data.dma_eea` | Bool | Whether European regulations, including the DMA, apply to this user and conversion.<br><br>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.<br><br>Set to `false` if the user is considered **excluded** from European Union regulations. | **Required** if EU regulations apply to this user<br><br>**Warning**: Failure to include user consent signals may result in attribution or campaign performance degradation |
| `user_data.dma_ad_personalization` | Bool | Whether the end user has granted or denied ads personalization consent.<br><br>Set to `true` if the user has **granted** consent for ads personalization.<br><br>Set to `false` if the user has **denied** consent for ads personalization. | **Required** if `dma_eea` is set to `true` (that is, EU regulations apply to this user)<br><br>**Warning**: Failure to include user consent signals may result in attribution or campaign performance degradation |
| `user_data.dma_ad_user_data` | Bool | Whether the end user has granted or denied consent for 3P transmission of user-level data for ads.<br><br>Set to `true` if the user has **granted** consent for 3P transmission of user-level data for ads.<br><br>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)<br><br>**Warning**: Failure to include user consent signals may result in attribution or campaign performance degradation |

**Parameters included in** `event_data` **object**

| Parameters for `event_data` | Type | Description | Required |
| --- | --- | --- | --- |
| `event_data.transaction_id` | String | The partner-specified transaction ID for their internal use. | No |
| `event_data.revenue` | Num | The partner-specified reported revenue for the event. | No |
| `event_data.currency` | String | The currency that the revenue, price, shipping, and tax were originally reported in by the partner. | No |
| `event_data.shipping` | Num | The shipping cost associated with the transaction. | No |
| `event_data.tax` | Num | The total tax associated with the transaction. | No |
| `event_data.coupon` | String | The transaction coupon redeemed with the transaction (for example, `"SPRING2017"`). | No |
| `event_data.affiliation` | String | The store or affiliation associated with this transaction (for example, `"Google Store"`). | No |
| `event_data.description` | String | The description associated with the event, not necessarily specific to any individual content items (see the `content_items` parameter). | No |
| `event_data.search_query` | String | Additional search queries. | No |

**Parameters included in** `content_items` **object**

| Parameters for `content_items` | Type | Description | Required |
| --- | --- | --- | --- |
| `content_items[i].$content_schema` | String | The category or schema for a piece of content. May be used in the future for analytics. Must be one of the following:<br><br>`COMMERCE_AUCTION`<br>`COMMERCE_BUSINESS`<br>`COMMERCE_OTHER`<br>`COMMERCE_PRODUCT`<br>`COMMERCE_RESTAURANT`<br>`COMMERCE_SERVICE`<br>`COMMERCE_TRAVEL_FLIGHT`<br>`COMMERCE_TRAVEL_HOTEL`<br>`COMMERCE_TRAVEL_OTHER`<br>`GAME_STATE`<br>`MEDIA_IMAGE`<br>`MEDIA_MIXED`<br>`MEDIA_MUSIC`<br>`MEDIA_OTHER`<br>`MEDIA_VIDEO`<br>`OTHER`<br>`TEXT_ARTICLE`<br>`TEXT_BLOG`<br>`TEXT_OTHER`<br>`TEXT_RECIPE`<br>`TEXT_REVIEW`<br>`TEXT_SEARCH_RESULTS`<br>`TEXT_STORY`<br>`TEXT_TECHNICAL_DOC` | No |
| `content_items[i].$og_title` | String | The title for the content item. | No |
| `content_items[i].$og_image_url` | String | The image URL for the content item. | No |
| `content_items[i].$canonical_identifier` | String | Allows Branch to unify content/messages for content analytics. | No |
| `content_items[i].$publicly_indexable` | Bool | Whether content can be indexed for public use.<br><br>Use `true` for content that can be seen by anyone, and `false` for content that cannot be indexed for public use. | No |
| `content_items[i].$locally_indexable` | Bool | Use `true` for content that can be indexed for local (device) use, and `false` for content that cannot be indexed for local use. | No |
| `content_items[i].$price` | String | The price for the product or content. | No |
| `content_items[i].$quantity` | String | The quantity of the item to be ordered. | No |
| `content_items[i].$sku` | String | The product SKU or product ID. | No |
| `content_items[i].$product_name` | String | The product's name. | No |
| `content_items[i].$product_brand` | String | The product's brand. | No |
| `content_items[i].$product_category` | String | The product's category. Must be one of the following:<br><br>`ANIMALS_AND_PET_SUPPLIES`<br>`APPAREL_AND_ACCESSORIES`<br>`ARTS_AND_ENTERTAINMENT`<br>`BABY_AND_TODDLER`<br>`BUSINESS_AND_INDUSTRIAL`<br>`CAMERAS_AND_OPTICS`<br>`ELECTRONICS`<br>`FOOD_BEVERAGES_AND_TOBACCO`<br>`FURNITURE`<br>`HARDWARE`<br>`HEALTH_AND_BEAUTY`<br>`HOME_AND_GARDEN`<br>`LUGGAGE_AND_BAGS`<br>`MATURE`<br>`MEDIA`<br>`OFFICE_SUPPLIES`<br>`RELIGIOUS_AND_CEREMONIAL`<br>`SOFTWARE`<br>`SPORTING_GOODS`<br>`TOYS_AND_GAMES`<br>`VEHICLES_AND_PARTS` | No |
| `content_items[i].$product_variant` | String | The product's variant. Examples include `red` and `XL`. | No |
| `content_items[i].$rating_average` | Num | The average rating of the item. | No |
| `content_items[i].$rating_count` | Num | The number of ratings for the item. | No |
| `content_items[i].$rating_max` | Num | The maximum possible rating for the item (for example, 5.0 if 5 stars is the highest possible rating). | No |
| `content_items[i].$creation_timestamp` | Int | The time the content was created. | No |
| `content_items[i].$exp_date` | Int | The time after which this content is no longer valid. The values `null` and `0` mean no limit.<br><br>Should rarely be set. | No |
| `content_items[i].$keywords` | Array | An array of keywords (strings) related to the product. | No |
| `content_items[i].$address_street` | String | The street address for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$address_city` | String | The city for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$address_region` | String | The state or region for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$address_country` | String | The country code for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$address_postal_code` | String | The postal/zip code for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$latitude` | Num | The latitude for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$longitude` | Num | The longitude for a restaurant, business, room (hotel), etc. | No |
| `content_items[i].$image_captions` | Array | An array of captions (strings) associated with the image. | No |
| `content_items[i].$condition` | String | Relates to product condition and is generally used for auctions. Must be one of the following:<br><br>`OTHER`<br>`NEW`<br>`EXCELLENT`<br>`GOOD`<br>`FAIR`<br>`POOR`<br>`USED`<br>`REFURBISHED` | No |
| `content_items[i].$custom_fields` | Obj | An object containing key-value pairs that you want attached to the content item. Attached to events that are retrieved via exports and sent via webhooks. | No |

#### Response info

**Response codes**

| Response code | Definition |
| --- | --- |
| 200 | Success |
| 400 | Authentication failed |
| 429 | Rate limit reached |

#### Examples

**Example requests**

**Example Commerce Request (cURL)**

```curl
curl -vvv -d '{
    "name": "PURCHASE",
    "customer_event_alias": "my custom alias",
    "user_data": {
        "advertising_ids": {
            "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
        },
        "os": "Android",
        "os_version": 25,
        "anon_id": "fbanon_abc123def456",
        "environment": "FULL_APP",
        "aaid": "abcdabcd-0123-0123-00f0-000000000000",
        "android_id": "a12300000000",
        "limit_ad_tracking": false,
        "developer_identity": "user123",
        "country": "US",
        "language": "en",
        "ip":"000.000.0.0",
        "local_ip": "000.000.0.0",
        "brand": "LGE",
        "app_version": "1.0.0",
        "model": "Nexus 5X",
        "screen_dpi": 420,
        "screen_height": 1794,
        "screen_width": 1080,
        "dma_eea": true,
        "dma_ad_personalization": true,
        "dma_ad_user_data": true
    },
    "custom_data": {
        "purchase_loc": "Palo Alto",
        "store_pickup": "unavailable"
    },
    "event_data": {
        "transaction_id": "tras_Id_1232343434",
        "currency": "USD",
        "revenue": 180.2,
        "shipping": 10.5,
        "tax": 13.5,
        "coupon": "promo-1234",
        "affiliation": "high_fi",
        "description": "Preferred purchase"
    },
    "content_items": [
        {
            "$content_schema": "COMMERCE_PRODUCT",
            "$og_title": "Nike Shoe",
            "$og_description": "Start loving your steps",
            "$og_image_url": "http://example.com/img1.jpg",
            "$canonical_identifier": "nike/1234",
            "$publicly_indexable": false,
            "$price": 101.2,
            "$locally_indexable": true,
            "$quantity": 1,
            "$sku": "1101123445",
            "$product_name": "Runner",
            "$product_brand": "Nike",
            "$product_category": "Sporting Goods",
            "$product_variant": "XL",
            "$rating_average": 4.2,
            "$rating_count": 5,
            "$rating_max": 2.2,
            "$creation_timestamp": 1499892854966,
            "$exp_date": 1499892854966,
            "$keywords": [
                "sneakers",
                "shoes"
            ],
            "$address_street": "230 South LaSalle Street",
            "$address_city": "Chicago",
            "$address_region": "IL",
            "$address_country": "US",
            "$address_postal_code": "60604",
            "$latitude": 12.07,
            "$longitude": -97.5,
            "$image_captions": [
                "my_img_caption1",
                "my_img_caption_2"
            ],
            "$condition": "NEW",
            "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}"
        },
        {
            "$og_title": "Nike Woolen Sox",
            "$canonical_identifier": "nike/5324",
            "$og_description": "Fine combed woolen sox",
            "$publicly_indexable": false,
            "$price": 80.2,
            "$locally_indexable": true,
            "$quantity": 5,
            "$sku": "110112467",
            "$product_name": "Woolen Sox",
            "$product_brand": "Nike",
            "$product_category": "Apparel & Accessories",
            "$product_variant": "Xl",
            "$rating_average": 3.3,
            "$rating_count": 5,
            "$rating_max": 2.8,
            "$creation_timestamp": 1499892854966
        }
    ],
    "metadata": {},
    "branch_key": "key_test_XXX"
}' https://api2.branch.io/v2/event/standard
```

**Example Content Request (cURL)**

```curl
curl -vvv -d '{
    "name": "VIEW_ITEMS",
    "customer_event_alias": "my custom alias",
    "user_data": {
        "advertising_ids": {
            "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
        },
        "os": "Android",
        "os_version": 25,
        "anon_id": "fbanon_abc123def456",
        "environment": "FULL_APP",
        "aaid": "abcdabcd-0123-0123-00f0-000000000000",
        "android_id": "a12300000000",
        "limit_ad_tracking": false,
        "developer_identity": "user123",
        "country": "US",
        "language": "en",
        "ip": "000.000.0.0",
        "local_ip": "000.000.0.0",
        "brand": "LGE",
        "app_version": "1.0.0",
        "model": "Nexus 5X",
        "screen_dpi": 420,
        "screen_height": 1794,
        "screen_width": 1080,
        "dma_eea": true,
        "dma_ad_personalization": true,
        "dma_ad_user_data": true
    },
    "custom_data": {
        "purchase_loc": "Palo Alto",
        "store_pickup": "unavailable"
    },
    "event_data": {
        "search_query": "red sneakers",
        "description": "Preferred purchase"
    },
    "content_items": [
        {
            "$content_schema": "COMMERCE_PRODUCT",
            "$og_title": "Nike Shoe",
            "$og_description": "Start loving your steps",
            "$og_image_url": "http://example.com/img1.jpg",
            "$canonical_identifier": "nike/1234",
            "$publicly_indexable": false,
            "$price": 101.2,
            "$locally_indexable": true,
            "$sku": "1101123445",
            "$product_name": "Runner",
            "$product_brand": "Nike",
            "$product_category": "Sporting Goods",
            "$product_variant": "XL",
            "$rating_average": 4.2,
            "$rating_count": 5,
            "$rating_max": 2.2,
            "$creation_timestamp": 1499892854966,
            "$exp_date": 1499892854966,
            "$keywords": [
                "sneakers",
                "shoes"
            ],
            "$address_street": "230 South LaSalle Street",
            "$address_city": "Chicago",
            "$address_region": "IL",
            "$address_country": "US",
            "$address_postal_code": "60604",
            "$latitude": 12.07,
            "$longitude": -97.5,
            "$image_captions": [
                "my_img_caption1",
                "my_img_caption_2"
            ],
            "$condition": "NEW",
            "$custom_fields": "{\"foo1\":\"bar1\",\"foo2\":\"bar2\"}"
        },
        {
            "$og_title": "Nike Woolen Sox",
            "$canonical_identifier": "nike/5324",
            "$og_description": "Fine combed woolen sox",
            "$publicly_indexable": false,
            "$price": 80.2,
            "$locally_indexable": true,
            "$sku": "110112467",
            "$product_name": "Woolen Sox",
            "$product_brand": "Nike",
            "$product_category": "Apparel & Accessories",
            "$product_variant": "Xl",
            "$rating_average": 3.3,
            "$rating_count": 5,
            "$rating_max": 2.8,
            "$creation_timestamp": 1499892854966
        }
    ],
    "metadata": {},
    "branch_key": "key_test_XXX"
}' https://api.branch.io/v2/event/standard
```

**Example Lifecycle Request (cURL)**

```curl
curl -vvv -d '{
    "name": "COMPLETE_REGISTRATION",
    "user_data": {
        "advertising_ids": {
            "oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"
        },
        "os": "Android",
        "os_version": 25,
        "anon_id": "fbanon_abc123def456",
        "environment": "FULL_APP",
        "aaid": "abcdabcd-0123-0123-00f0-000000000000",
        "android_id": "a12300000000",
        "limit_ad_tracking": false,
        "developer_identity": "user123",
        "country": "US",
        "language": "en",
        "ip": "000.000.0.0",
        "local_ip": "000.000.0.0",
        "brand": "LGE",
        "app_version": "1.0.0",
        "model": "Nexus 5X",
        "screen_dpi": 420,
        "screen_height": 1794,
        "screen_width": 1080,
        "dma_eea": true,
        "dma_ad_personalization": true,
        "dma_ad_user_data": true
    },
    "custom_data": {
        "foo": "bar"
    },
    "event_data": {
        "description": "Preferred purchase"
    },
    "metadata": {},
    "branch_key": "key_test_XXX"
}' https://api.branch.io/v2/event/standard
```

**Example response**

```json
{
  "ascending_only": false,
  "locked": false
}
```

### Logging custom events

#### Request info

**Export request**

```http
POST /v2/event/custom
```

**Request header parameters**

| Parameter | Value | Required |
| --- | --- | --- |
| `content-type` | application/json | Recommended |
| `accept` | application/json | Recommended |
| `X-IP-Override` | A public IPv4 address (for example, `198.51.100.42`) | Optional. See callout below. |

> **Caution**
>
> The `X-IP-Override` header lets you specify the IP address Branch uses for the event (for example, when forwarding events server-to-server from your own backend). You must meet two requirements for this header to function:
>
> 1. **Your app ID must be allowlisted by Branch.** The header is ignored until allowlisting is enabled. [Open a support request](https://support.branch.io/) to have your app ID allowlisted before you begin sending the header in production.
> 2. **You must also include** `user_data.ip` **in the request body** with the same IP value. Sending the header alone is not sufficient. The body field is what Branch persists for attribution.

**Top-level request body parameters**

| Top-level parameter | Type | Description | Required |
| --- | --- | --- | --- |
| `branch_key` | String | The Branch Key for the relevant application. | **Yes** |
| `name` | String | The name of the event to log. Can be a custom event name and include spaces, for example, `"picture swapped"`. | **Yes** |
| `user_data` | Obj | An object related to user data, containing things like device information and advertising IDs.<br><br>Also used to provide information regarding the user for Google DMA compliance.<br><br>See `user_data` [table](https://help.branch.io/apidocs/events/overview.md#request-info) for more. | **Yes** |
| `custom_data` | Obj | An object for additional custom key-value pairs that you want attached to the Branch Event. This is attached to Branch Events that are retrieved via exports and sent via webhooks. | No |
| `meta_data` | Obj | An object to store further information about the Branch Event. | No |
| `event_data` | Obj | An object containing additional data about the specific event, including information about things like currency and revenue.<br><br>See `event_data` [table](https://help.branch.io/apidocs/events/overview.md#request-info) for more. | No |

**Parameters included in** `user_data` **object**

> **Caution: Required identifiers**
>
> You must include **at least one of the following** in `user_data`:
>
> 1. `user_data.developer_identity` or
> 2. `user_data.browser_fingerprint_id` or
> 3. `user_data.os=iOS` AND `user_data.idfa` or
> 4. `user_data.os=iOS` AND `user_data.idfv` or
> 5. `user_data.os=Android` AND `user_data.android_id` or
> 6. `user_data.os=Android` AND `user_data.aaid`

> **Note**
>
> In addition to the standard identifiers above, include any **third-party IDs** that apply to your integration so you can join events with downstream tools.  
> Common examples:
>
> - `user_data.google_analytics_id`: the Google Analytics client ID, for cross-platform stitching with GA.
> - A Snowflake user identifier (or equivalent data-warehouse key) inside `custom_data`, so you can join events with your data warehouse.
>
> Including these where applicable improves attribution coverage and downstream analytics.

| Parameters for `user_data` | Type | Description | Required |
| --- | --- | --- | --- |
| `user_data.os` | String | Examples:<br>`Android`<br>`iOS`<br>`Mac_OS`<br>`Linux`<br>`Windows` | See "Required identifiers" callout |
| `user_data.os_version` | String | The version of the operating system. | **Strongly recommended** for all paid traffic to ensure accurate attribution<br><br>**Required** for Facebook campaigns on iOS |
| `user_data.advertising_ids` | Obj | A wrapper object for advertising identifiers. Use this in addition to the flat `aaid`, `idfa`, and `idfv` fields above to future-proof your integration for non-standard IDs (for example, OAID on Huawei devices).<br><br>Example: `"advertising_ids": {"oaid": "00aa00a0-0000-0a00-a000-aaa0000a0aaa"}` | No (recommended for non-standard IDs like OAID) |
| `user_data.environment` | String | Usually `FULL_APP`. | No |
| `user_data.aaid` | String | The Android Advertising ID. | See "Required identifiers" callout |
| `user_data.android_id` | String | The Android hardware ID. | See "Required identifiers" callout |
| `user_data.idfa` | String | The iOS advertising ID. | See "Required identifiers" callout |
| `user_data.idfv` | String | The iOS vendor ID. | See "Required identifiers" callout |
| `user_data.anon_id` | String | The Facebook anonymous user ID. Used for measurement and attribution when running Facebook campaigns that rely on Aggregated Event Measurement (AEM). | **Required** when running Facebook campaigns using Aggregated Event Measurement (AEM) on iOS |
| `user_data.limit_ad_tracking` | Bool | Set to `true` if the partner has opted to not be tracked by advertisers. | No |
| `user_data.user_agent` | String | The user agent of the browser or app where the event occurred. Usually associated with a webview. | No |
| `user_data.browser_fingerprint_id` | String | An internal-only field for Branch to track browsers. | See "Required identifiers" callout |
| `user_data.http_origin` | String | The current page URL where the Branch Web SDK logged a web session start. | No |
| `user_data.http_referrer` | String | The referral URL that led to the current page where the Branch Web SDK logged a web session start. | No |
| `user_data.developer_identity` | String | The developer-specified identity for a user. | See "Required identifiers" callout |
| `user_data.country` | String | The country code of the user, usually based on device settings or the user agent string. | No |
| `user_data.language` | String | The language code of the user, usually based on device settings or the user agent string. | No |
| `user_data.ip` | String | The IP address for the device where the event occurred. | No |
| `user_data.local_ip` | String | **Android only**: the local IP of the device.<br><br>Example: `"168.1.1.1"` | No |
| `user_data.brand` | String | The brand of the device. | No |
| `user_data.randomized_device_token` | String | An internal-only Branch field for tracking devices. | No |
| `user_data.app_version` | String | The version of the app downloaded by the user. | No |
| `user_data.model` | String | The model of the device. | No |
| `user_data.screen_dpi` | Int | The screen's DPI. | No |
| `user_data.screen_height` | Int | The screen's height. | No |
| `user_data.screen_width` | Int | The screen's width. | No |
| `user_data.dma_eea` | Bool | Whether European regulations, including the DMA, apply to this user and conversion.<br><br>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.<br><br>Set to `false` if the user is considered **excluded** from European Union regulations. | **Required** if EU regulations apply to this user<br><br>**Warning**: Failure to include user consent signals may result in attribution or campaign performance degradation |
| `user_data.dma_ad_personalization` | Bool | Whether the end user has granted or denied ads personalization consent.<br><br>Set to `true` if the user has **granted** consent for ads personalization.<br><br>Set to `false` if the user has **denied** consent for ads personalization. | **Required** if `dma_eea` is set to `true` (that is, EU regulations apply to this user)<br><br>**Warning**: Failure to include user consent signals may result in attribution or campaign performance degradation |
| `user_data.dma_ad_user_data` | Bool | Whether the end user has granted or denied consent for 3P transmission of user-level data for ads.<br><br>Set to `true` if the user has **granted** consent for 3P transmission of user-level data for ads.<br><br>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)<br><br>**Warning**: Failure to include user consent signals may result in attribution or campaign performance degradation |

**Parameters included in** `event_data` **object**

| Parameters for `event_data` | Type | Description | Required |
| --- | --- | --- | --- |
| `event_data.transaction_id` | String | The partner-specified transaction ID for their internal use. | No |
| `event_data.revenue` | Num | The partner-specified reported revenue for the event. | No |
| `event_data.currency` | String | The currency that the revenue, price, shipping, and tax were originally reported in by the partner. | No |
| `event_data.shipping` | Num | The shipping cost associated with the transaction. | No |
| `event_data.tax` | Num | The total tax associated with the transaction. | No |
| `event_data.coupon` | String | The transaction coupon redeemed with the transaction (for example, `"SPRING2017"`). | No |
| `event_data.affiliation` | String | The store or affiliation associated with this transaction (for example, `"Google Store"`). | No |
| `event_data.description` | String | The description associated with the event, not necessarily specific to any individual content items (see the `content_items` parameter). | No |
| `event_data.search_query` | String | Additional search queries. | No |

#### Response info

**Response codes**

| Response code | Definition |
| --- | --- |
| 200 | Success |
| 400 | Authentication failed |
| 429 | Rate limit reached |

#### Example request & response

**Request (cURL)**

```curl
curl -vvv -d '{
    "name": "picture swiped",
    "user_data": {
        "advertising_ids": {
            "oaid": "02ab41d3-7886-4f29-a606-fba4372e9fdc"
        },
        "os": "Android",
        "os_version": 25,
        "anon_id": "fbanon_abc123def456",
        "environment": "FULL_APP",
        "aaid": "abcdabcd-0123-0123-00f0-000000000000",
        "android_id": "a12300000000",
        "limit_ad_tracking": false,
        "developer_identity": "user123",
        "country": "US",
        "language": "en",
        "ip": "000.000.0.0",
        "local_ip": "000.000.0.0",
        "brand": "LGE",
        "app_version": "1.0.0",
        "model": "Nexus 5X",
        "screen_dpi": 420,
        "screen_height": 1794,
        "screen_width": 1080,
        "dma_eea": true,
        "dma_ad_personalization": true,
        "dma_ad_user_data": true
    },
    "custom_data": {
        "foo": "bar"
    },
    "meta_data": {
        "foo": "bar"
    },
    "branch_key": "key_test_XXX"
}' https://api.branch.io/v2/event/custom
```

**Response (JSON)**

```json
{
  "ascending_only": false,
  "locked": false
}
```

## Verify events sent

Once you've used the Branch Events API to track a Branch Event, you can verify that it was successfully sent for attribution by using the [Liveview](https://dashboard.branch.io/liveview) screen in Branch.

**Note**: Be patient when using the Liveview screen, as it may take some time for data to flow from our attribution systems to Branch. If the data has not appeared in Liveview after 30 minutes, review your API request to see if you may have missed something.

![](https://help.branch.io/img/b4735515-555f-4053-a397-dfbe70eb4ddd.jpg "Liveview Events.JPG")