Data Subject Request API Overview

  • Published on Mar 20, 2025

The Branch Data Subject Request API supports our customers with two key components of data protection laws like the General Data Protection Regulation 2016/679 (GDPR) and the California Consumer Privacy Act (CCPA) - the right to access personal data and the right to request deletion of personal data (also known as the right be forgotten).

With this API, Branch customers can programmatically:

  • Access end user personal data stored by Branch.

  • Erase end user personal data from Branch.

This API is for Branch customers only.

If you are a user of an app or website that uses Branch, you need to make your request directly with the respective app or website to access your personal data (who are the controllers of your personal data under the GDPR), to ask for your personal data to be deleted from Branch, or for other data subject requests. Those apps and websites that use Branch will then pass on that request to us. We are fully committed to working with our app and website partners to address your rights under applicable data protection laws.

By Request Only

Access to the Data Subject Request API is by request only. Please contact our support team to gain access to this feature.

Not Available in Testing Environment

Please note that the Data Subject Request API is not available in test environments.

Calls to the Data Subject Request API require an api_key query string parameter to be passed with each request. API Keys are generated on a per-user basis and are permanent.

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

In order to access the Data Subject Request API, a user will need to have Sensitive Data access as well as App Level read/edit access.

For more details on how to give a user the required access, please read Default Access Levels, Users Roles & Permissions.

Due to the unique purpose of the Data Subject Request API, third parties such as Agencies will not be allowed access to this API. This includes agencies that have the required access levels mentioned above.

The Data Subject Request API includes the following limits:

  • 1000 Identity Objects limit per request

  • 5 requests per second

  • 10 requests per minute

  • 100 requests per hour API Access

POST https://api2.branch.io/v1/gdpr?app_id=<App-ID>
Content-type: application/json
Host: api2.branch.io
HTTP

Access any personal data associated with known given identities from Branch Metrics.

HTTP Header Parameters

api_key / access token | REQUIRED | StringYour API Key / Access Token.

Query Parameters

app_id | REQUIRED | LongThe App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

Body Parameters

Body Parameters

subject_request_type | REQUIRED | StringThe type of post request being sent. In this case “access”The App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

subject_identities | REQUIRED | StringThis is an array containing the device ID in the below JSON format.

identity_type | REQUIRED | StringThe type of identity being sent. It can be “BROWSER_ID”, “DEVICE_ID”, “USER_ID”, or “DEVELOPER_ID”.

BROWSER_ID | Either of one identity_type mandatory | StringThe browser user identifier such as browser_fingerprint_id.

DEVICE_ID | Either of one identity_type mandatory | StringThe device user identifier such as IDFA, IDFV, Google_advertising_id.

USER_ID | Either of one identity_type mandatory | StringThe app scoped user-id.

identity_value | REQUIRED | StringThe value as per the identity_type, IDFA, Google_advertising_id, etc.

identity_format | NOT REQUIRED | StringTo be sent as “raw”. Branch currently only supports “raw”.

curl -X POST 'https://api2.branch.io/v1/gdpr?app_id=<YOUR _APP_ID_HERE>'
	-H "Content-Type: application/json"
	-H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
	-d '{ "subject_request_type": "access",
                  "subject_identities": [
                      {
                           "identity_type": "BROWSER_ID",
                           "identity_value": "123",
                           "identity_format": "raw"
                       }
                       {
                            "identity_type": "BROWSER_ID",
                            "identity_value": "123",
                            "identity_format": "raw"
                       }
                    ]
                 }
Curl

Response Code: 200

Successful register of the Access request

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "PENDING"
}
JSON

Response Parameters

request_id

String

The UUID generated for the request made. This can be used to check the status of the request at a later time.

request_status

String

This is the status of your request. Possible values:

  • “SUCCESS”: The request has been fulfilled.

  • “PENDING”: A correct request has been received and is currently in the queue

  • “IN_PROGRESS”: The request is currently being acted on.

POST https://api2.branch.io/v1/gdpr/status
Content-type: application/json
Host: api2.branch.io
HTTP

Erase any personal data associated with known given identities from Branch Metrics.

HTTP Header Parameters

iapi_key / access token | REQUIRED | StringYour API Key / Access Token.

Query Parameters

iapp_id | REQUIRED | LongThe App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

Body Parameters

Body Parameters

subject_request_type | REQUIRED | StringThe type of post request being sent. In this case “erasure”

subject_identities | REQUIRED | StringThis is an array containing the device ID in the below JSON format.

identity_type | REQUIRED | StringThe type of identity being sent. It can be “BROWSER_ID”, “DEVICE_ID”, “USER_ID”, or “DEVELOPER_ID”.

BROWSER_ID | Either of one identity_type mandatory | StringThe browser user identifier such as browser_fingerprint_id.

DEVICE_ID | Either of one identity_type mandatory | StringThe device user identifier such as IDFA, IDFV, Google_advertising_id.

USER_ID | Either of one identity_type mandatory | StringThe app scoped user-id.

identity_value | REQUIRED | StringThe value as per the identity_type, IDFA, Google_advertising_id, etc.

identity_format | NOT REQUIRED | StringTo be sent as “raw”. Branch currently only supports “raw”.

curl -X POST 'https://api2.branch.io/v1/gdpr?app_id=<YOUR _APP_ID_HERE>'
	-H "Content-Type: application/json"
	-H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
	-d '{ "subject_request_type": "erasure",
                   "subject_identities": [
                      {
                           "identity_type": "BROWSER_ID",
                           "identity_value": "123",
                           "identity_format": "raw"
                       }
                       {
                             "identity_type": "USER_ID",
                             "identity_value": "ABC123",
                             "identity_format": "raw"
                       }
                    ]
                 }
Curl

Response Code: 200
Successful register of the Erasure request

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "PENDING"
}
JSON

Response Parameters

request_id | StringThe UUID generated for the request made. This can be used to check the status of the request at a later time.

request_status | StringThis is the status of your request. It can be
“SUCCESS”: The request has been fulfilled.
“PENDING”: A correct request has been received and is currently in the queue
“IN_PROGRESS”: The request is currently being acted on.

Gets the current status of the request for the given request_id generated from the Access/Erasure POST request.

HTTP Header Parameters

api_key / access token | REQUIRED | StringYour API Key / Access Token.

Query Parameters

app_id | REQUIRED | LongThe App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

Body Parameters

Body Parameters

request_id | StringThe UUID generated for the request made. This can be used to check the status of the request at a later time.

curl -X POST 'https://api2.branch.io/v1/gdpr/status?app_id=<YOUR _APP_ID_HERE>'
-H "Content-Type: application/json"
-H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
-d '{"request_id": "<ID>"}'
Curl

Response Code: 200
Successful register of the Status request

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "SUCCESS"
}
JSON

Response Parameters

request_id | StringThe UUID generated for the request made. This can be used to check the status of the request at a later time.

request_status | StringThis is the status of your request. It can be
“SUCCESS”: The request has been fulfilled.
“PENDING”: A correct request has been received and is currently in the queue
“IN_PROGRESS”: The request is currently being acted on.

Response Code: 200
Successful register of the Status request

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "COMPLETED",
  "export_url": "presigned_s3_link"
}
JSON

Response Parameters

request_id | StringThe UUID generated for the request made. This can be used to check the status of the request at a later time.

request_status | StringThis is the status of your request. It can be
“SUCCESS”: The request has been fulfilled.
“PENDING”: A correct request has been received and is currently in the queue
“IN_PROGRESS”: The request is currently being acted on.

export_url | StringThe pre-assigned s3 URL link to download the CSV file containing the identity objects requested.

  • Missing or invalid Branch key:

{
    "error": {
        "message": "Invalid or missing app id, Branch key, or secret",
        "code": 400
    }
}
JSON

  • Invalid JSON:

{
    "error": {
        "code": 400,
        "message": "Invalid JSON"
    }
}
JSON

  • Missing required fields/Incorrect format types:

{
    "error": {
        "subject_request_type": "not a valid option",
        "submitted_time": "wrong field type",
        "subject_identities": [
            "identity_type": "not a valid option",
            "identity_value": "wrong field type",
            "identity_format": "not a valid option"
        ]
    }
}
JSON
{
    "error": {
        "code": 429,
        "message": "Rate limit reached."
    }
}
JSON
<html>
<head><title>404 Not Found</title></head>
<body bgcolor="white">
<center><h1>404 Not Found</h1></center>
<hr><center>openresty/1.13.6.2</center>
</body>
</html>
XML