Skip to main content

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​

FieldTypeRequiredNotes
subjectstring✅Short summary
descriptionstring✅Full details
categorystring✅"CONSENT_NOT_HONORED", "DATA_BREACH_CONCERN", "DSR_NOT_FULFILLED", "TARGETING_MINOR", or "OTHER"
linkedDsrIdnumberOptional — 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​

ParamTypeRequiredNotes
pagenumberDefaults to 0
sizenumberDefaults 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​

ParamTypeRequiredNotes
pagenumberDefaults to 0
sizenumberDefaults 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
FieldTypeRequiredNotes
messagestring✅
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.