Consent Docs
Open console

Withdraw or erase a person

Withdraw everything a person agreed to, or erase what identifies them, with one call from your server, and act on the webhooks that follow.

How-to2 min readFor web, backend and mobile developers

Withdraw when a person takes back their consent but stays with you. Erase when they close their account or ask you to delete their data. Erasing ends the consent too, so one call is enough.

Before you start#

  • A secret key with the scope subjects:withdraw or subjects:erase. Grant it under Scopes on the key in Install.
  • The client from Record consent from your server.

Withdraw everything#

  1. Call withdrawSubject with the identifier, its type and a reason.

    Node.jsJavaScript
    const { withdrawn } = await client.withdrawSubject(
  'usr_8f2K1xQz',
  'USER_ID',
  {
    reason: 'Account closed at the learner’s request',
    idempotencyKey: 'close-usr_8f2K1xQz',
  },
);
    Python
    withdrawn = client.withdraw_subject(
    "usr_8f2K1xQz",
    "USER_ID",
    reason="Account closed at the learner’s request",
    idempotency_key="close-usr_8f2K1xQz",
)
    cURLShell
    curl -X POST https://console.dpconsent.com/consent/sdk/v1/subjects/withdraw \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: close-usr_8f2K1xQz" \
  -d '{
    "subjectId": "usr_8f2K1xQz",
    "subjectType": "USER_ID",
    "reason": "Account closed at the learner’s request"
  }'

  2. Stop the processing that relied on the consent.

Every record that is not erased and not already withdrawn becomes WITHDRAWN, on every form, with every optional purpose refused. withdrawn is how many records changed. Calling again returns 0.

A consent.withdrawn webhook is sent once for each record withdrawn. The person's identifiers stay. To remove them as well, erase.

Erase a person#

  1. Call eraseSubject with the identifier, its type and a reason.

    Node.jsJavaScript
    const { erased } = await client.eraseSubject(
  'usr_8f2K1xQz',
  'USER_ID',
  {
    reason: 'Erasure requested by the learner',
    idempotencyKey: 'erase-usr_8f2K1xQz',
  },
);
    Python
    erased = client.erase_subject(
    "usr_8f2K1xQz",
    "USER_ID",
    reason="Erasure requested by the learner",
    idempotency_key="erase-usr_8f2K1xQz",
)
    cURLShell
    curl -X POST https://console.dpconsent.com/consent/sdk/v1/subjects/erase \
  -H "Authorization: Bearer $PIEDAP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erase-usr_8f2K1xQz" \
  -d '{
    "subjectId": "usr_8f2K1xQz",
    "subjectType": "USER_ID",
    "reason": "Erasure requested by the learner"
  }'

  2. Delete your own copy of the person's data: your user table, mailing lists and exports.

erased is how many records this call erased. Calling again returns 0.

What erasing does#

For each record of the person that is not already erased, in this order:

  1. It is withdrawn first, if it is still in force. A record with the status GRANTED, PARTIAL or PENDING becomes WITHDRAWN.
  2. Its identifiers are cleared: the readable copy of the identifier if your project keeps one, the fingerprint, the IP address hash, the browser, the page address and your metadata.
  3. Its linked identifiers are deleted.
  4. erasedOn is set, and the erasure is sealed as an event in the record's history.

In the same transaction, each partner you registered as a Data Processor gets an erase task, and the person is removed from every notice campaign. The hashes the person was known by are kept, so an import or a campaign never brings them back.

The service then sends consent.withdrawn for each record that was still in force, followed by subject.erased for each record erased, with the tasks in processors. Both carry the person's fingerprint as it was before the erasure. Deliveries can arrive in any order, so handle either one first.

The one-year hold under the DPDP Act

For a record under the DPDP Act whose last processing was less than a year ago, step 2 is delayed. The values are kept until one year after that processing, and a daily job clears them then. Steps 1, 3 and 4 happen at once, so the record counts as erased everywhere. Records under other laws are cleared at once.

What stays after erasure

The record is not deleted. The decisions, the form version, the times, the sealed history and the keyed hash of its own identifier remain as proof. A look-up by the identifier it was recorded under still returns it, with erasedOn set. A look-up by a linked identifier returns nothing. An erased record cannot be updated.

↑↓ to move, Enter to open