Client API reference | Privacy Requests

Your first request

1. Create and save a token

As a Business workspace Admin, open Settings → API. Give the service a recognizable name, select cases:read, choose an expiry and create the credential. Copy the token now: the full value is shown only once. Store it in your server's secret store.

2. List cases

These examples use Bash and curl. Enter the token at the hidden prompt so it is not saved in shell history. An empty cases array is a successful response for a new workspace.

export API_BASE='https://app.privacyrequests.co/api/v1'
read -rsp 'API token: ' API_TOKEN; printf '\n'
export API_TOKEN
curl --fail-with-body "$API_BASE/cases" \
  -H "Authorization: Bearer $API_TOKEN"

Cases are returned 50 at a time in ascending ID order. If nextCursor is not null, pass that exact value as after. Continue until it is null.

curl --fail-with-body --get "$API_BASE/cases" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data-urlencode 'after=PASTE_NEXT_CURSOR'

3. Create a case

Use a token with cases:create. Running this example creates a real case, without sending a requester email. Replace the example details with the request you intend to log. receivedAt must be the actual receipt time, in the past. This example uses the previous minute.

read -rsp 'Token with cases:create: ' API_TOKEN; printf '\n'
RECEIVED_AT=$(node -e 'console.log(new Date(Date.now()-60000).toISOString())')
IDEMPOTENCY_KEY=$(node -e 'console.log(crypto.randomUUID())')
curl --fail-with-body "$API_BASE/cases" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data "{\"requesterName\":\"Example Requester\",\"requesterEmail\":\"requester@example.com\",\"requestType\":\"access\",\"jurisdiction\":\"Staff review required\",\"originalWording\":\"Please provide my personal data.\",\"receivedAt\":\"$RECEIVED_AT\"}"

The timestamp/key helpers require Node.js. Generate them once per new request. When retrying, keep the same token, key and body: a replay returns HTTP 200 with replayed: true. New cases return HTTP 201 with caseId and reference; different details with the same key return HTTP 409.

4. Grant task access and read tasks

Create a token with tasks:read and tasks:update. In Settings → API, choose Manage tasks for that credential, select the tasks and save. The picker shows the latest 100 tasks on open real cases; existing older grants are preserved. Up to 90 grants are allowed. Scopes alone do not grant access to any task.

read -rsp 'Token with tasks:read and tasks:update: ' API_TOKEN; printf '\n'
curl --fail-with-body "$API_BASE/tasks" \
  -H "Authorization: Bearer $API_TOKEN"

5. Update a granted task

Running this changes the task's real status and notes. Copy its id and exact updated_at from the latest response. On HTTP 409, read again and reconcile the change before retrying.

TASK_ID='PASTE_TASK_ID'
curl --fail-with-body --request PATCH "$API_BASE/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"status":"In Progress","notes":"Started checking the assigned system.","expectedUpdatedAt":"PASTE_UPDATED_AT"}'
unset API_TOKEN

Data Found, Deleted, Corrected and Needs Review outcomes require evidence already uploaded through the app. Tasks on closed, completed or rejected cases cannot be changed. Staff remain responsible for reviewing outcomes.

Access, limits and token lifecycle

Business and Admin access: an active workspace Admin manages credentials and grants. Tokens authenticate a workspace service, not a personal staff login, and only have their selected scopes. They do not sign users into the app.
Scope: cases:read lists and reads real case summaries, including requester contact details; cases:create logs cases. tasks:read and tasks:update apply only to explicit task grants. Practice cases are excluded.
Limits: 10 active tokens per workspace; expiry 1–365 days; 90 task grants per token; 60 calls per minute per token. HTTP 429 includes Retry-After in seconds and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Wait before retrying. JSON request bodies are limited to 8192 bytes.
Expiry, revocation and downgrade: expired or revoked tokens return 401. Loss of Business access returns 403. Existing unexpired, unrevoked credentials resume when Business access returns. Admins can still view and revoke credentials after a downgrade.
Rotate by replacement: create a replacement with the required scopes, configure its task grants, switch your integration and verify a request, then revoke the old token. Leave a spare slot when planning rotation. Keep the original token for pending case-creation retries because idempotency keys are token-specific. Revocation is permanent.
Human review: this API cannot approve responses, send deliveries, upload evidence or close cases. Deadlines are suggestions for staff review, not legal advice.
MCP is separate: AI connections use OAuth and their own permissions. REST tokens are not OAuth access tokens and cannot authenticate MCP connections.

Send credentials only in the Authorization header. Never include them in URLs, browser application code, analytics or logs. Use a server-side secret store for integrations.

Swagger API reference

This reference is public. To call the API, choose Authorize and paste your token, then select an operation, Try it out and Execute. Requests use this site's origin. POST and PATCH ask for confirmation before changing real data. Your staff session does not authenticate these calls.

Tokens stay in this page's memory and are cleared on reload; authorization is not saved to browser storage. No external validator or analytics receives your requests. Clear authorization or close this page when finished. Removing authorization reloads the reference to clear request history too.

Connect your case workflow