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

# Data Subject Request API Overview

## Overview

The Branch Data Subject Request API supports you 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 to be forgotten).

With this API, you can programmatically:

- Access end user personal data stored by Branch.
- Erase end user personal data from Branch.

> **Caution**
>
> **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 (which are the controllers of your personal data under the GDPR) to access your personal data, 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're 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. Contact our [support team](https://help.branch.io/account-hub/submit-a-ticket.md) to gain access to this feature.

> **Not available in testing environment**
>
> The Data Subject Request API is not available in test environments.

## Authentication

For calls to the Data Subject Request API, you need your Access Token.

**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 → User** [tab](https://dashboard.branch.io/account-settings/profile).
2. If you have not yet generated an Access Token, select the **Generate token** button.
3. Use the **copy icon** to copy your Access Token.

**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. If you have not yet generated an Access Token, select the **Generate token** button.
3. Use the **copy icon** to copy your Access Token.

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

## Access levels

To access the Data Subject Request API, a user needs **Sensitive Data** access as well as **App Level read/edit access**.

For more details on how to give a user the required access, read [Default Access Levels, Users Roles & Permissions](https://help.branch.io/account-hub/default-access-levels-users-roles-permissions.md).

## Third party access

Because of the unique purpose of the Data Subject Request API, third parties such as agencies are not 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

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

| HTTP header parameters |
| --- |
| **api_key / access token** \| *REQUIRED* \| *String* Your API key / Access Token. |

## Query parameters

| Query parameters |
| --- |
| **app_id** \| *REQUIRED* \| *Long* The app ID as assigned by Branch; available in Branch -> Account Settings -> Profile tab -> About your App |

## Body parameters

| Body parameters |
| --- |
| **subject_request_type** \| *REQUIRED* \| *String* The type of POST request being sent. In this case “**access**”. The app ID as assigned by Branch; available in Branch -> Account Settings -> Profile tab -> About your App |
| **subject_identities** \| *REQUIRED* \| *String* This is an array containing the device ID in the below JSON format. |
| **identity_type** \| *REQUIRED* \| *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](https://branch.io/glossary/idfa/), [IDFV](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor), [Google_advertising_id](https://support.google.com/googleplay/android-developer/answer/6048248?hl=en). |
| **USER_ID** \| *Either of one identity_type mandatory* \| *String* The app-scoped user ID. |
| **identity_value** \| *REQUIRED* \| *String* The value as per the identity_type, IDFA, Google_advertising_id, etc. |
| **identity_format** \| *NOT REQUIRED* \| *String* To be sent as “raw”. Branch currently only supports “raw”. |

## Sample access request

```curl
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 registration of the access request.

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

| 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. <br>• “PENDING”: A correct request has been received and is currently in the queue. <br>• “IN_PROGRESS”: The request is currently being acted on. |

## Erasure endpoint

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

| HTTP header parameters |
| --- |
| **api_key / access token** \| *REQUIRED* \| *String* Your API key / Access Token. |

## Query parameters

| Query parameters |
| --- |
| **app_id** \| *REQUIRED* \| *Long* The app ID as assigned by Branch; available in Branch -> Account Settings -> Profile tab -> About your App |

## Body parameters

| Body parameters |
| --- |
| **subject_request_type** \| *REQUIRED* \| *String* The type of POST request being sent. In this case “**erasure**”. |
| **subject_identities** \| *REQUIRED* \| *String* This is an array containing the device ID in the below JSON format. |
| **identity_type** \| *REQUIRED* \| *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](https://branch.io/glossary/idfa/), [IDFV](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor), [Google_advertising_id](https://support.google.com/googleplay/android-developer/answer/6048248?hl=en). |
| **USER_ID** \| *Either of one identity_type mandatory* \| *String* The app-scoped user ID. |
| **identity_value** \| *REQUIRED* \| *String* The value as per the identity_type, IDFA, Google_advertising_id, etc. |
| **identity_format** \| *NOT REQUIRED* \| *String* To be sent as “raw”. Branch currently only supports “raw”. |

## Sample erasure request

```curl
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 registration of the erasure request.

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

| 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. It can be<br>“SUCCESS”: The request has been fulfilled.<br>“PENDING”: A correct request has been received and is currently in the queue.<br>“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 or erasure POST request.

## HTTP header parameters

| HTTP header parameters |
| --- |
| **api_key / access token** \| *REQUIRED* \| *String* Your API key / Access Token. |

## Query parameters

| Query parameters |
| --- |
| **app_id** \| *REQUIRED* \| *Long* The app ID as assigned by Branch; available in Branch -> Account Settings -> Profile tab -> About your App |

## Body parameters

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

## Sample download / status request

```curl
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>"}'
```

## Sample status response

**Response code: 200**   
Successful registration of the status request.

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

| 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. It can be<br>“SUCCESS”: The request has been fulfilled.<br>“PENDING”: A correct request has been received and is currently in the queue.<br>“IN_PROGRESS”: The request is currently being acted on. |

## Sample download response

**Response code: 200**  
Successful registration of the status request.

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

| 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. It can be<br>“SUCCESS”: The request has been fulfilled.<br>“PENDING”: A correct request has been received and is currently in the queue.<br>“IN_PROGRESS”: The request is currently being acted on. |
| **export_url** \| *String* The pre-signed 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:

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

- Invalid JSON:

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

- Missing required fields or incorrect format types:

```json
{
  "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

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

### 3. RC 404: Not Found/incorrect API URL

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