---
title: Data Subject Requests API
slug: docs/data-subject-requests-api
createdAt: 2026-03-26T07:16:25.562Z
---

# Data Subject Requests API

Submit and manage GDPR and CCPA data subject requests programmatically on behalf of your end users.

This API follows the field naming conventions of the [OpenDSR v2 specification](https://github.com/opengdpr/OpenDSR), making it compatible with privacy tooling that supports the OpenDSR standard.

**Base URL:** `https://ds.jomablue.com/v1`
**API version:** `1.0`

***

## Authentication

All requests require a bearer token in the `Authorization` header:

```javascript
Authorization: Bearer <your_api_key>
```

Contact us to obtain an API key for your account.

***

## Endpoints

### Submit a request

`POST /v1/gdpr/requests`

```json
{
  "subject_request_type": "access | erasure",
  "regulation": "gdpr | ccpa",
  "subject_identities": [
    {
      "identity_type": "string",
      "identity_value": "string",
      "identity_format": "raw | sha256 | md5"
    }
  ],
  "callback_email": "string",
  "notes": "string"
}
```

| Field                                  | Required              | Notes                                                            |
| -------------------------------------- | --------------------- | ---------------------------------------------------------------- |
| `subject_request_type`                 | Yes                   | `access` to retrieve data, `erasure` to delete it                |
| `regulation`                           | No                    | `gdpr` (default) or `ccpa`                                       |
| `subject_identities`                   | Yes                   | At least one identifier required                                 |
| `subject_identities[].identity_type`   | Yes                   | e.g. `contact_id`, `user_id`                                     |
| `subject_identities[].identity_value`  | Yes                   | The identifier value                                             |
| `subject_identities[].identity_format` | No                    | `raw` (default), `sha256`, or `md5`                              |
| `callback_email`                       | Required for `access` | Where the requested data will be returned. Ignored on `erasure`. |
| `notes`                                | No                    | Any additional context about the request                         |

**Response — 200 OK**

```json
{
  "subject_request_id": "a7551968-d5d6-44b2-9831-815ac9017798",
  "subject_request_type": "erasure",
  "regulation": "gdpr",
  "status": "pending",
  "expected_completion_time": "2026-04-19",
  "received_time": "2026-03-20T09:15:00Z",
  "api_version": "1.0"
}
```

Save the `subject_request_id` — you'll need it to check status or cancel the request. The `expected_completion_time` is always 30 days from `received_time`, in line with the GDPR Article 12 deadline.

***

### Get request status

`GET /v1/gdpr/requests/{subject_request_id}`

Returns the current status of a request. You may only query requests submitted by your account.

**Response — 200 OK**

```json
{
  "subject_request_id": "a7551968-d5d6-44b2-9831-815ac9017798",
  "subject_request_type": "access",
  "regulation": "gdpr",
  "request_status": "in_progress",
  "expected_completion_time": "2026-04-19",
  "received_time": "2026-03-20T09:15:00Z",
  "api_version": "1.0"
}
```

**Request statuses**

| Status        | Meaning                                                 |
| ------------- | ------------------------------------------------------- |
| `pending`     | Received and queued for action                          |
| `in_progress` | Being actively worked on                                |
| `completed`   | Fulfilled — data returned or deleted                    |
| `rejected`    | Could not be fulfilled (e.g. no matching records found) |
| `cancelled`   | Cancelled before completion                             |

***

### Cancel a request

`DELETE /v1/gdpr/requests/{subject_request_id}`

Cancels a request. Only requests in `pending` status can be cancelled, and you may only cancel requests submitted by your account.

**Response — 200 OK**

```json
{
  "subject_request_id": "a7551968-d5d6-44b2-9831-815ac9017798",
  "status": "cancelled",
  "received_time": "2026-03-20T09:15:00Z",
  "api_version": "1.0"
}
```

***

## Rate limits

Requests are subject to two limits:

- **Global:** 10 requests/second across all customers, with a burst allowance of 20.
- **Per account:** 100 requests/day by default. Contact us if you need this increased.

When your daily limit is reached you will receive a `429` response with the following headers:

```javascript
X-RateLimit-Limit: 100
X-RateLimit-Used: 101
Retry-After: 86400
```

Limits reset at midnight UTC. The `Retry-After` value is always `86400` (24 hours).

***

## Errors

All errors return a consistent shape:

```json
{
  "error": "error_code",
  "message": "Human-readable description."
}
```

| HTTP | Code                     | Description                                                      |
| ---- | ------------------------ | ---------------------------------------------------------------- |
| 400  | `missing_callback_email` | `callback_email` is required for `access` requests               |
| 400  | `invalid_request`        | Malformed body or invalid identity object                        |
| 400  | `invalid_request_type`   | `subject_request_type` must be `access` or `erasure`             |
| 400  | `invalid_regulation`     | `regulation` must be `gdpr` or `ccpa`                            |
| 400  | `missing_identities`     | `subject_identities` must contain at least one entry             |
| 401  | `unauthorized`           | API key missing or invalid                                       |
| 403  | `forbidden`              | You do not have permission to access this request                |
| 404  | `not_found`              | No request found with this ID                                    |
| 409  | `invalid_status`         | Request cannot be cancelled — it is no longer in `pending` state |
| 429  | `rate_limit_exceeded`    | Daily request limit reached — see rate limit headers             |
| 500  | `internal_error`         | Unexpected server error — please retry                           |

***

## Quick start

**Submit an erasure request:**

```bash
curl -X POST https://ds.jomablue.com/v1/gdpr/requests \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_request_type": "erasure",
    "regulation": "gdpr",
    "subject_identities": [
      {
        "identity_type": "contact_id",
        "identity_value": "003Dn00000RGvTHIA1"
      }
    ]
  }'
```

**Submit an access request:**

```bash
curl -X POST https://ds.jomablue.com/v1/gdpr/requests \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_request_type": "access",
    "regulation": "gdpr",
    "subject_identities": [
      {
        "identity_type": "contact_id",
        "identity_value": "003Dn00000RGvTHIA1"
      }
    ],
    "callback_email": "subject@example.com"
  }'
```

**Check status:**

```bash
curl https://ds.jomablue.com/v1/gdpr/requests/a7551968-d5d6-44b2-9831-815ac9017798 \
  -H "Authorization: Bearer <your_api_key>"
```

**Cancel a pending request:**

```bash
curl -X DELETE https://ds.jomablue.com/v1/gdpr/requests/a7551968-d5d6-44b2-9831-815ac9017798 \
  -H "Authorization: Bearer <your_api_key>"
```

