Consent Docs
Open console

Processor tasks

The endpoints that list stop and erase tasks for your Data Processors and record what each processor reported, with parameters, outcomes and codes.

Reference5 min readFor developers calling the REST API

A processor task tells one registered Data Processor to stop or to erase. It is written when a person withdraws, changes their choices, a consent expires or a person is erased. These endpoints list tasks and record what each processor reported. Paths are relative to https://console.dpconsent.com/consent/sdk/v1. The task is in Pass instructions to processors.

Shared rules#

Rule Detail
Key A secret key with the endpoint's scope. A publishable key gets 403 SCOPE_REQUIRED.
Test and live A test key reaches tasks of test records only. A live key reaches live tasks only.
Identifiers A task holds none. Match it to your user by consentId.
Budget 60 calls a minute for each key, shared with the calls on a person, on top of the key's own budget.

Endpoints#

GET /processor-tasks#

Lists tasks oldest first, with a cursor.

Key Scope Idempotency-Key Webhook sent
Secret processors:read Ignored None

Parameters

Name Type Required Description
status string No OPEN, DONE, REJECTED or SUPERSEDED.
partnerKey string No One processor's key.
action string No STOP or ERASE.
overdue boolean No true for open tasks past their due date only.
consentId string, up to 60 No The tasks of one record.
limit integer, 1 to 500 No Tasks in the page. Default 100.
cursor string, up to 200 No The nextCursor of the previous page.

Request

Shell
curl -G https://console.dpconsent.com/consent/sdk/v1/processor-tasks \
  -d status=OPEN -d partnerKey=nilgiri-mailers \
  -H "Authorization: Bearer $PIEDAP_PROCESSOR_KEY"

Response

200:

JSON
{
  "items": [
    {
      "taskId": "2b9e4f61-0c3d-4a7e-8f15-6d2c9b0a7e34",
      "consentId": "cns_3f1c9a7e2b8d4c6fa0e5d1b7c9f2a4e8",
      "partnerKey": "nilgiri-mailers",
      "partnerName": "Nilgiri Mailers",
      "action": "ERASE",
      "cause": "ERASURE",
      "purposes": ["marketing", "analytics"],
      "issuedOn": "2026-10-03T09:30:12.004Z",
      "dueOn": "2026-11-02T09:30:12.004Z",
      "retainLogsUntil": "2027-10-03T09:30:12.004Z",
      "status": "OPEN",
      "outcome": null,
      "closedOn": null,
      "overdue": false,
      "test": false,
      "subject": { "type": "EMAIL", "fingerprint": "a71c…" }
    }
  ],
  "nextCursor": "WyIyMDI2LTEwLTAzVDA5OjMwOjEyLjAwNFoiLCIyYjllNGY2MS0uLi4iXQ"
}
Field Type Description
taskId UUID The task. The same id is in the webhook's processors.
consentId string The record the task is about.
partnerKey, partnerName string The processor.
action string STOP or ERASE.
cause string WITHDRAWAL, CHANGE, EXPIRY, ERASURE or INACTIVITY_ERASURE.
purposes array The purposes to stop or erase for.
issuedOn, dueOn time When the task was written, and when it is due by the processor's days in the register.
retainLogsUntil time or null On an ERASE: until when the processor may keep processing logs.
status string See Task status.
outcome string or null The final or refused outcome reported.
closedOn time or null When the task was closed.
overdue boolean true when it is open past dueOn.
subject object The record's identifier type and fingerprint. The fingerprint is null once kept details are cleared after an erasure.
nextCursor string or null Send it as cursor for the next page.

Errors

Status Code When
400 INVALID_CURSOR cursor is not one this endpoint returned.
400 None. The message is a list A filter or limit is not valid.
403 SCOPE_REQUIRED The key lacks processors:read.
429 None The budget for calls on a person was reached.

POST /processor-tasks/acknowledge#

Records what processors reported, for up to 200 tasks in one call.

Key Scope Idempotency-Key Webhook sent
Secret processors:write Honoured None

Parameters

Name Type Required Description
acknowledgements array, 1 to 200 Yes One report for each task. A task may appear once.
acknowledgements[].taskId UUID Yes The task.
acknowledgements[].outcome string Yes STOPPED, ERASED, RETAINED_UNDER_LAW or REJECTED.
acknowledgements[].completedOn string No The day, or day and time, the processor says it acted, such as 2026-10-04.
acknowledgements[].reference string, up to 200 No The processor's ticket or request number.
acknowledgements[].note string, up to 1,000 For RETAINED_UNDER_LAW and REJECTED Which law and for how long, or why the processor did not act.
acknowledgements[].evidence object No A file you keep: fileName, sha256, sizeBytes and contentType. The file itself is never sent.

Write no names in note, reference or evidence.fileName. A value with an email address or a run of 10 to 13 digits is refused.

Request

Shell
curl -X POST https://console.dpconsent.com/consent/sdk/v1/processor-tasks/acknowledge \
  -H "Authorization: Bearer $PIEDAP_PROCESSOR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nm-req-20431" \
  -d '{
    "acknowledgements": [{
      "taskId": "2b9e4f61-0c3d-4a7e-8f15-6d2c9b0a7e34",
      "outcome": "ERASED",
      "completedOn": "2026-10-12T10:00:00Z",
      "reference": "NM-REQ-20431"
    }]
  }'

Response

200:

JSON
{
  "results": [
    {
      "taskId": "2b9e4f61-0c3d-4a7e-8f15-6d2c9b0a7e34",
      "result": "RECORDED",
      "status": "DONE",
      "outcome": "ERASED"
    },
    {
      "taskId": "8c11d2e0-5a7f-4b2c-9e31-0d6f4a8b2c17",
      "result": "REFUSED",
      "code": "OUTCOME_NOT_VALID_FOR_ACTION",
      "message": "An ERASE task takes ERASED, RETAINED_UNDER_LAW or REJECTED"
    }
  ]
}
result Meaning
RECORDED The report was stored. status and outcome are the task's new state.
UNCHANGED The task already had this outcome. Nothing was stored.
REFUSED Nothing was stored. code says why.
Code in a result Meaning
TASK_NOT_FOUND No task with this id for the key's environment.
OUTCOME_NOT_VALID_FOR_ACTION A STOP takes STOPPED, ERASED, RETAINED_UNDER_LAW or REJECTED. An ERASE takes ERASED, RETAINED_UNDER_LAW or REJECTED.
NOTE_REQUIRED RETAINED_UNDER_LAW or REJECTED was sent without a note.
COMPLETED_IN_FUTURE completedOn is more than 5 minutes ahead.
COMPLETED_BEFORE_TASK completedOn is more than 5 minutes before the task was issued.
TASK_ALREADY_DONE The task is done with another outcome. The first report stands.
TASK_SUPERSEDED REJECTED was sent for a task that is no longer needed.
TEXT_LOOKS_PERSONAL note, reference or the file name holds an email address or a phone number.

Errors

Status Code When
400 DUPLICATE_TASK_ID The same task appears twice in the call.
400 None. The message is a list A field is missing or not valid, or more than 200 reports were sent.
403 SCOPE_REQUIRED The key lacks processors:write.
409, 422 IDEMPOTENCY_REQUEST_IN_PROGRESS, IDEMPOTENCY_KEY_REUSED See Idempotency.
429 None The budget for calls on a person was reached.

Each call writes one audit entry, ACKNOWLEDGE_PROCESSOR_TASKS, with the key's name and the counts.

Task status#

Status Meaning A report of
OPEN Waiting for the processor A final outcome closes it as DONE. REJECTED makes it REJECTED.
REJECTED The processor did not act A final outcome closes it as DONE.
DONE A final outcome was reported The same outcome is UNCHANGED. Another is refused.
SUPERSEDED No longer needed: the person allowed the processor again, or an erase task replaced it A final outcome closes it as DONE.

The final outcomes are STOPPED, ERASED and RETAINED_UNDER_LAW. Only an OPEN task past its due date is overdue.

When tasks are written#

Event Tasks
A withdrawal, an expiry, or a change that refuses a processor A STOP for each processor that was allowed before and is not after, on purposes based on consent
An erasure, or an erasure for inactivity An ERASE for each processor the person ever allowed, on any purpose
  • Only partners registered as Data Processors get tasks.
  • A record known only by a cookie or session id gets no tasks, except on an erasure you asked for.
  • Tasks are written in the same transaction as the sealed change. A change is never recorded without its tasks.
  • Tasks are kept as long as the record.

↑↓ to move, Enter to open