Skip to main content

DSR API

Background reading: DSR & Grievances.

Both endpoints here require 🔒 principal token — an X-Principal-Token header (see Authentication). There is no externalId field in the submit request; the principal is derived entirely from the token, and status lookups are scoped so a token for one principal can never read another principal's DSR by guessing its referenceId.

DPR and DSR are the same thing. The dashboard calls these Data Principal Requests (DPR). Every path on this page also works with /dpr in place of /dsr (for example POST /dpr and GET /dpr/status/{referenceId}), and both return the same responses. New requests get a referenceId that starts with DPR-; requests made before this change keep their DSR- id, and a status lookup finds a request whether you write its id with DPR- or DSR-.

Submit a DSR request​

POST /dsr

Request body​

FieldTypeRequiredNotes
typestring✅"ACCESS", "CORRECTION", "ERASURE", or "NOMINATION"
payloadstringFree-form details — e.g. what to correct, or context for the request
curl -X POST "$CMP_BASE/dsr" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "type": "ACCESS", "payload": "Please send my data as a CSV." }'

Response — 201 Created​

{
"entity": {
"id": 1,
"orgId": 1,
"dataPrincipal": { "id": 42, "externalId": "user-8231", "...": "..." },
"referenceId": "DPR-20260704-VY2ZT",
"requestType": "ACCESS",
"requestTypeLabel": "Data Access",
"status": "PENDING",
"requestPayload": "Please send my data as a CSV.",
"submittedAt": "2026-07-04T04:50:22.537+00:00"
},
"warnings": [],
"errors": [],
"success": true
}

Store referenceId — it's what the principal uses to check status later, via Check DSR status below. That lookup is still gated on holding a valid token for the same principal who filed it — see that section for what happens otherwise.

Failure — 401 Unauthorized (no envelope)​

Missing, invalid, or expired X-Principal-Token.

Failure — 500 Internal Server Error​

{ "warnings": [], "errors": [{ "message": "Please specify what kind of request you'd like to make -- access, correction, erasure, or nomination.", "code": 18000, "status": false }], "success": false }

Returned if type is missing. Unlike most 18000 messages elsewhere in this API (which are written for a developer reading logs, not the end user), this one is written to be shown to the data principal as-is — you don't need to write your own copy for this case, just render errors[0].message directly in your UI.


Check DSR status​

GET /dsr/status/{referenceId}
curl "$CMP_BASE/dsr/status/DPR-20260704-VY2ZT" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"

Response — 200 OK​

Same shape as Submit a DSR Request, reflecting the current status (see Status lifecycle) — once acknowledged/fulfilled/rejected by an org admin, this response will additionally include acknowledgedAt, resolvedAt, resolvedBy, and resolutionNotes.

Failure — 404 Not Found​

Returned if referenceId doesn't exist for this org, or if it exists but belongs to a different principal than the one identified by your X-Principal-Token — both cases return the same 404, deliberately, so a caller can't distinguish "this reference doesn't exist" from "this reference exists but isn't yours" by guessing referenceId values.


List my DSR requests​

GET /dsr

Lets a principal see their own DSR submission history — every request they've ever filed and its current status — without you having to track and re-query every referenceId yourself.

Query parameters​

ParamTypeRequiredNotes
pagenumberDefaults to 0
sizenumberDefaults to 20
curl "$CMP_BASE/dsr?page=0&size=20" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"

Response — 200 OK​

{
"entity": {
"content": [
{
"id": 1,
"referenceId": "DPR-20260704-VY2ZT",
"requestType": "ACCESS",
"status": "FULFILLED",
"submittedAt": "2026-07-04T04:50:22.537+00:00",
"acknowledgedAt": "2026-07-04T09:12:00.000+00:00",
"resolvedAt": "2026-07-05T10:00:00.000+00:00"
}
],
"number": 0,
"size": 20,
"totalElements": 1,
"totalPages": 1
},
"warnings": [],
"errors": [],
"success": true
}

Sorted newest-first by submittedAt. Scoped strictly to the calling X-Principal-Token's own principal — there is no way to list another principal's requests, or every request across the org (that's admin-facing only).


Communication thread​

DSR handling is often a back-and-forth — the DPO may need more detail before they can fulfil a request, or want to explain why one was rejected. These two endpoints let a principal read and add to that thread for one of their own DSR requests, scoped by referenceId the same way as Check DSR status.

Get the thread​

GET /dsr/{referenceId}/communications

Paginated, like List my DSR requests — a thread on a long-running DSR can grow unbounded.

Query parameters​

ParamTypeRequiredNotes
pagenumberDefaults to 0
sizenumberDefaults to 20
curl "$CMP_BASE/dsr/DPR-20260704-VY2ZT/communications?page=0&size=20" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"

Response — 200 OK​

{
"entity": {
"content": [
{
"id": 501,
"authorType": "DPO_USER",
"authorLabel": "Priya Sharma",
"message": "Could you confirm which email address you'd like the export sent to?",
"createdAt": "2026-07-04T09:15:00.000+00:00"
},
{
"id": 502,
"authorType": "DATA_PRINCIPAL",
"authorLabel": "user-8231",
"message": "Please send it to my registered email.",
"createdAt": "2026-07-04T09:40:00.000+00:00"
},
{
"id": 503,
"authorType": "SYSTEM",
"authorLabel": "System",
"message": "JIRA ticket ABC-123 created.",
"createdAt": "2026-07-04T09:41:00.000+00:00"
}
],
"number": 0,
"size": 20,
"totalElements": 3,
"totalPages": 1
},
"warnings": [],
"errors": [],
"success": true
}

Sorted oldest-first (natural reading order for a conversation) — unlike every other paginated list on this page, which sorts newest-first. authorType is "DPO_USER" for a message from the org's side, "DATA_PRINCIPAL" for one from the principal — including ones sent through the widget/your own integration, so multiple channels stay in the same thread — or "SYSTEM" (authorLabel always "System") for an automatic entry Bytemonk adds itself, currently only "ticket created"/"ticket closed" messages when the org has connected an external ticketing tool. SYSTEM entries are read-only — there's no way to post one yourself via Add a message below.

Add a message​

POST /dsr/{referenceId}/communications
FieldTypeRequiredNotes
messagestring✅
curl -X POST "$CMP_BASE/dsr/DPR-20260704-VY2ZT/communications" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "message": "Please send it to my registered email." }'

Response — 201 Created​

Same shape as one entry of Get the thread above.

Failure — 404 Not Found​

Same "doesn't exist or isn't yours" reasoning as Check DSR status — a referenceId that belongs to a different principal returns 404, not a message revealing it exists.