Custom Exports API

👍

Try it!

Try out the Custom Exports API using your Branch data via the API reference here

Overview

Benefits of Custom Exports API

• The Branch Custom Exports find and queue log records that match your search criteria for export. You can do so either via the Custom Exports section in your Branch Dashboard or via the API (this page).

API Limitations

You will get the following response once you've hit the rate limit:

{
    "errors": [
        {
            "message": "Limit is exceeded for org-525983469347282987, retry after 3418 seconds",
            "error_code": 7
        }
    ]
}

Prerequisites & API Access

In order to use the Custom Exports API, you need to have completed the following:

1. Created a Branch Dashboard
2. Implemented the Branch SDK into your mobile app (iOS | Android)
   • Track events.
3. Opt into sharing device data through Apple's AppTrackingTransparency framework. When an install is attributed to paid ads, a 2nd install event will fire post user opt-in.

🚧

Data Changes Post iOS

Opt-ins will affect your final install count. We recommend using a different identifier (ex. IDFV) to de-dupe install events on your internal systems.

For additional information on changes post iOS 14.5, visit our FAQ Pages

4. Logged into the Branch Dashboard with the Sensitive Data and Export Access Permission enabled.

Providing Agencies API Access

Any user with access to an account’s API keys will be able to access Branch’s Custom Export API (and thus unfiltered, log-level data). As a result, we would recommend against providing third parties with the permissions required to view API keys during the invitation process.

🚧

Data Purge

• Branch will purge last-attributed data after 60 days.

If you work with an agency that runs your advertising campaigns and want to give them access to export the subsequent data, you can provide them with access to the Custom Export API.

To provide an agency team member with access to the Custom Export API:

1. In the left-hand navigation, under Configure, click on Account Settings.
2. On the Account Settings page, click on the Agencies tab.
3. Expand the agency in question, find the agency team member you want to give access to, hover on the button in the Actions column and click Edit.
4. In the Edit Agency Team Member modal:
   1. Under Access Level, check the Export box.
   2. Under Permissions, check the Sensitive Data box.
5. Optional: add data filters
   1. Under Data Filters, toggle any necessary data filters on/blue. Exported data will be filtered accordingly.
6. Click Save.

🚧

Agency-Tagged Data

If you do not enable the Only Show Agency-Tagged Data data filter, the Agency Team Member will be able to export sensitive data associated with all of your campaigns, regardless if they are associated with them or not.

Authentication

Calls to the Custom Export API require an access token parameter to be passed with each request. Access tokens are generated on a per-user basis and are permanent.

Learn how to retrieve your Access Token (a.k.a. an API Key).

API Usage

Create Export Request

POST /v2/logs?organization_id=ORG_ID
POST /v2/logs?app_id=APP_ID
Headers:
Access-Token: API_KEY
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

Request Body Parameters

Response Body Parameters

Example Request/Response

curl -X POST 'https://api2.branch.io/v2/logs?app_id=123456700098765432'
	-H "Content-Type: application/json"
	-H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
	-d '{"report_type": "eo_open",
			"limit": 100,
			"fields": ["timestamp","name"],
			"start_date": "2019-12-09T00:00:00Z",
			"end_date": "2019-12-09T01:59:59Z",
			"filter": ["gt","last_attributed_touch_timestamp", 1604015756]
			}'

{"handle":"1612dbb3-85ef-49f8-b1c5-5818c163600c","export_job_status_url":"https://api2.branch.io/v2/logs/1612dbb3-85ef-49f8-b1c5-5818c163600c?app_id=123456700098765432"}

Response Codes

Get Export Request

GET /v2/logs/JOB_ID
Headers:
Access-Token: API_KEY
Host: api2.branch.io

Request Headers

Response Path Parameters

Request Query Parameters

Response Body Parameters

Example Request/Response

curl -X GET https://api2.branch.io/v2/logs/<YOUR_HANDLE>\?app_id\=<YOUR_BRANCH_APP_ID>
  -H "Content-Type: application/json" 
  -H "Access-Token:<YOUR_ACCESS_TOKEN>"

{"code":200,"lines_exported":2000000,"status":"complete","response_url":"https://branch-exports-web.s3.amazonaws.com/732662944269095814-eo_open-2019-12-10-2019-12-10-1612dbb3-85ef-49f8-b1c5-5818c163600c-bUlN2lwyTE10qIVH.csv?Signature=YOUR_ACCESS_TOKEN_HERE&AWSAccessKeyId=YOUR_ACCESS_TOKEN_HERE&Expires=1577305615"}

Response Codes

Status Values

Check Data Readiness

POST /v2/data/ready
Headers:
Access-Token: YOUR_API_KEY_HERE
Content-Type: application/json
Body: JSON parameters
Host: api2.branch.io

Request Headers

Request Body Parameters

Response Body Parameters

Examples

Successful Request/Response:

curl -X POST 'http://api2.branch.io/v2/data/ready'
	-H 'Content-Type: application/json' 
	-H 'Accept: application/json'
	-H 'Access-Token: <YOUR_API_KEY_HERE>'
	-d '{"date":"2024-01-05 17:00:00",
		"warehouse_meta_type":"EVENT",
		"topic":"eo_click",
		"app_id":"<YOUR_APP_ID_HERE>"}'

{ "data_ready": true, "date": "2024-01-05 17:00:00" }

Invalid Request/Response:

curl -X POST 'http://api2.branch.io/v2/data/ready'
	-H 'Content-Type: application/json' 
	-H 'Accept: application/json'
	-H 'Access-Token: <YOUR_API_KEY_HERE>'
	-d '{"date":"2024-01-06 17:00:00",
		"warehouse_meta_type":"EVENT",
		"topic":"eo",
		"app_id":"<YOUR_APP_ID_HERE>"}'

{"errors":[{"message":"Report type eo is invalid. It has to be one of: [eo_branch_cta_view, eo_click, eo_commerce_event, eo_content_event, eo_custom_event, eo_impression, eo_install, eo_open, eo_pageview, eo_reinstall, eo_user_lifecycle_event, eo_web_session_start, eo_web_to_app_auto_redirect, eo_dismissal, eo_san_touch, webhook2, skadnetwork_invalid_messages, skadnetwork_valid_messages, eo_branch_cta_view_blocked, eo_click_blocked, eo_commerce_event_blocked, eo_content_event_blocked, eo_custom_event_blocked, eo_impression_blocked, eo_install_blocked, eo_open_blocked, eo_pageview_blocked, eo_reinstall_blocked, eo_user_lifecycle_event_blocked, eo_web_session_start_blocked]","error_code":7}]}

Response Codes

Appendix

Available EO Fields

Available SKAdNetwork Message Fields

🚧

IP Discrepancies

Geographic data, such as country and city, may not be available for a very small percentage of events where the IP cannot be resolved to a location.

Available Topics

🚧

Blocked Topics

Branch allows the export of blocked topics for up to 60 days from the time of the request.

Cthulhu Filter Specification

Cthulhu is a prefix notation syntax written in JSON for specifying filters on records (usually column-based records).

Purpose
Easily parses into an abstract syntax tree.

Glossary
any - any valid json basic value (number, string)
... - previous item in a list can repeat as many times as necessary

Additional Examples