Data Subject Request API

Overview

The General Data Protection Regulation (GDPR) 2016/679 is a regulation in EU law on data protection and privacy for all individual residents of the European Union and the European Economic Area. It also addresses the transfer of personal data outside the EU and EEA areas.

The Branch Data Subject Request API supports our customers with two key components of GDPR - the Right to Access personal data and the Right to 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 data, to ask for your data to be deleted from Branch, or for other GDPR 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 – who are the controllers of your personal data under the GDPR – to address your rights under the GDPR.

Authentication

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)

Access Levels

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 Branch’s access levels, please see Access Levels Overview.

Third Party Access

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.

Rate Limits

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

Access Endpoint

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

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

HTTP Header Parameters

Key
Required
Type
Definition

api_key / access token

YES

String

Your API Key / Access Token.

Query Parameters

Key
Required
Type
Definition

app_id

YES

Long

The App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

Body Parameters

Key
Required
Type
Definition

subject_request_type

YES

String

The type of post request being sent. In this case “access

subject_identities

YES

String

This is an array containing the device ID in the below JSON format.

identity_type

YES

String

The 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

String

The browser user identifier such as browser_fingerprint_id.

DEVICE_ID

Either of one identity_type mandatory

String

The device user identifier such as IDFA, IDFV, Google_advertising_id.

USER_ID

Either of one identity_type mandatory

String

The app scoped user-id.

identity_value

YES

String

The value as per the identity_type, IDFA, Google_advertising_id, etc.

identity_format

NO

String

To be sent as “raw”. Branch currently only supports “raw”.

Sample Access Request

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"
                       }
                    ]
                 }
              

Sample Access Response

Response Code: 200

Successful register of the Access request

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

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

Erasure Endpoint

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

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

HTTP Header Parameters

Key
Required
Type
Definition

api_key / access token

YES

String

Your API Key / Access Token.

Query Parameters

Key
Required
Type
Definition

app_id

YES

Long

The App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

Body Parameters

Key
Required
Type
Definition

subject_request_type

YES

String

The type of post request being sent. In this case “erasure

subject_identities

YES

String

This is an array containing the device ID in the below JSON format.

identity_type

YES

String

The 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

String

The browser user identifier such as browser_fingerprint_id.

DEVICE_ID

Either of one identity_type mandatory

String

The device user identifier such as IDFA, IDFV, Google_advertising_id.

USER_ID

Either of one identity_type mandatory

String

The app scoped user-id.

identity_value

YES

String

The value as per the identity_type, IDFA, Google_advertising_id, etc.

identity_format

NO

String

To be sent as “raw”. Branch currently only supports “raw”.

Sample Erasure Request

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"
                       }
                    ]
                 }

Sample Erasure Response

Response Code: 200
Successful register of the Erasure request

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

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

Download / Status Request

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

HTTP Header Parameters

Key
Required
Type
Definition

api_key / access token

YES

String

Your API Key / Access Token.

Query Parameters

Key
Required
Type
Definition

app_id

YES

Long

The App ID as assigned by Branch; available on Dashboard -> Account Settings -> Profile tab -> About your App

Body Parameters

Key
Type
Definition

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.

Sample Download / Status Request

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 '{
                   "request_id": "<ID>",
                 }

Sample Status Response

Response Code: 200
Successful register of the Status request

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

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

Sample Download Response

Response Code: 200
Successful register of the Status request

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

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

String

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

Appendix

Error Codes

1. RC 400 Bad Request

  • Missing or invalid Branch key:
{
    "error": {
        "message": "Invalid or missing app id, Branch key, or secret",
        "code": 400
    }
}
  • Invalid JSON:
{
    "error": {
        "code": 400,
        "message": "Invalid 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"
        ]
    }
}

2. RC 429: Rate limit reached

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

3. RC 404: Not Found/Incorrect API URL

<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>

Updated 3 months ago

Data Subject Request API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.