Grievances 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
file 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 grievance by guessing its referenceId.
File a grievance​
POST /grievances
Request body​
| Field | Type | Required | Notes |
|---|---|---|---|
subject | string | ✅ | Short summary |
description | string | ✅ | Full details |
category | string | ✅ | "CONSENT_NOT_HONORED", "DATA_BREACH_CONCERN", "DSR_NOT_FULFILLED", "TARGETING_MINOR", or "OTHER" |
linkedDsrId | number | Optional — the id of a related DSR request this grievance is about. Must be one of this same principal's own DSR requests (checked against the calling X-Principal-Token, same as every other ownership check in this API) — an id that doesn't exist, or belongs to someone else, is rejected rather than silently stored |
curl -X POST "$CMP_BASE/grievances" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"subject": "Marketing emails after I opted out",
"description": "I withdrew marketing consent last week but still received a promotional email today.",
"category": "CONSENT_NOT_HONORED"
}'
Response — 201 Created​
{
"entity": {
"id": 1,
"orgId": 1,
"dataPrincipal": { "id": 42, "externalId": "user-8231", "...": "..." },
"referenceId": "GRV-20260704-QSAWS",
"subject": "Marketing emails after I opted out",
"description": "I withdrew marketing consent last week but still received a promotional email today.",
"category": "CONSENT_NOT_HONORED",
"categoryLabel": "Consent Not Honored",
"linkedDsrId": null,
"status": "OPEN",
"submittedAt": "2026-07-04T04:50:22.688+00:00"
},
"warnings": [],
"errors": [],
"success": true
}
Store referenceId (format GRV-<yyyyMMdd>-<5 random alphanumeric chars>) so the principal can check status later
via Check grievance status below.
Failure — 401 Unauthorized (no envelope)​
Missing, invalid, or expired X-Principal-Token.
Failure — 500 Internal Server Error​
{ "warnings": [], "errors": [{ "message": "Please give your grievance a short subject line.", "code": 18000, "status": false }], "success": false }
Returned if subject, description, or category is missing (one message per field, whichever is checked
first), or if linkedDsrId is supplied but doesn't match one of this principal's own DSR requests. Like the
equivalent DSR validation errors, all of these messages are written to be shown to the data principal directly —
render errors[0].message as-is rather than writing your own copy for these cases.
Check grievance status​
GET /grievances/status/{referenceId}
curl "$CMP_BASE/grievances/status/GRV-20260704-QSAWS" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"
Response — 200 OK​
Same shape as File a Grievance, reflecting the current status (see
Status lifecycle) — once acknowledged/resolved/escalated by
an org admin, this response will additionally include acknowledgedAt, resolvedAt, resolvedBy, and
resolutionNotes. If an org admin has assigned one of their designated Grievance Officers to own this grievance,
assignedOfficerUserId is also present — this is an admin-side action your integration can't trigger, but the
field may appear on a status check.
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 grievances​
GET /grievances
Lets a principal see every grievance they've ever filed and its current status, without tracking each
referenceId yourself.
Query parameters​
| Param | Type | Required | Notes |
|---|---|---|---|
page | number | Defaults to 0 | |
size | number | Defaults to 20 |
curl "$CMP_BASE/grievances?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": "GRV-20260704-QSAWS",
"subject": "Marketing emails after I opted out",
"category": "CONSENT_NOT_HONORED",
"status": "RESOLVED",
"submittedAt": "2026-07-04T04:50:22.688+00:00",
"acknowledgedAt": "2026-07-04T09:00:00.000+00:00",
"resolvedAt": "2026-07-05T11:30:00.000+00:00",
"assignedOfficerUserId": 7
}
],
"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 grievances, or every grievance across the org (that's admin-facing only).
Communication thread​
Same concept as DSR → Communication thread — a place for the DPO/
assigned officer and the principal to go back and forth on a grievance before it's resolved, scoped by
referenceId the same way as Check grievance status.
Get the thread​
GET /grievances/{referenceId}/communications
Paginated, like List my grievances — a thread on a long-running grievance can grow unbounded.
Query parameters​
| Param | Type | Required | Notes |
|---|---|---|---|
page | number | Defaults to 0 | |
size | number | Defaults to 20 |
curl "$CMP_BASE/grievances/GRV-20260704-QSAWS/communications?page=0&size=20" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN"
Response — 200 OK​
{
"entity": {
"content": [
{
"id": 601,
"authorType": "DPO_USER",
"authorLabel": "Priya Sharma",
"message": "We've looked into this — can you confirm the date you unsubscribed?",
"createdAt": "2026-07-04T09:15:00.000+00:00"
},
{
"id": 602,
"authorType": "SYSTEM",
"authorLabel": "System",
"message": "JIRA ticket ABC-124 created.",
"createdAt": "2026-07-04T09:16:00.000+00:00"
}
],
"number": 0,
"size": 20,
"totalElements": 2,
"totalPages": 1
},
"warnings": [],
"errors": [],
"success": true
}
Sorted oldest-first — unlike every other paginated list on this page, which sorts newest-first. authorType is
"DPO_USER" for a message from the org's side (the assigned officer or any DPO), "DATA_PRINCIPAL" for one from
the principal, 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 /grievances/{referenceId}/communications
| Field | Type | Required | Notes |
|---|---|---|---|
message | string | ✅ |
curl -X POST "$CMP_BASE/grievances/GRV-20260704-QSAWS/communications" \
-H "X-Org-Api-Key: $CMP_KEY" \
-H "X-Principal-Token: $PRINCIPAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "message": "I unsubscribed on July 1st." }'
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 grievance status.