Skip to main content

Consent Records

A consent record is the actual evidence of what a principal agreed to — created every time a principal responds to a notice, and updated (to WITHDRAWN) when they later withdraw.

Fields​

FieldTypeNotes
idnumber
statusenumACTIVE or WITHDRAWN
consentMethodenumWhich channel consent came through — see Grant Consent → Consent method values for the full list
captureMethodenumHow consent was physically captured (CHECKBOX, TOGGLE_SWITCH, BUTTON_CLICK, ...) — a separate axis from consentMethod, optional on grant
ipAddress / userAgentstringCaptured automatically server-side from the request
timestampdatetimeWhen this record was created
sha256ChecksumstringNon-repudiation checksum — see below
purposeRecordsarrayPer-purpose grant/deny breakdown for this record

Each entry in purposeRecords has a status of GRANTED or DENIED, corresponding to one purpose on the notice this record was created against.

The non-repudiation checksum​

sha256Checksum is computed server-side as a hash over the record's id, the principal's id, the notice's id, and the timestamp. It exists so that, months later, you (or a regulator) can independently verify a specific consent record hasn't been tampered with — recomputing the hash from the stored fields and comparing it to the stored checksum. You don't need to do anything with this field in a typical integration; it's there for audit/compliance tooling, not for your widget's UI logic.

This is the practical consequence of the version model described in Consent Notices: a consent record points at the specific notice id the principal saw when they responded — not at the noticeGroupKey. If the org later publishes a new version, existing consent records keep pointing at the old, now-ARCHIVED version, unchanged. This is deliberate: it's what lets you prove exactly what someone agreed to, even after the notice text has since changed.

Practically, this means:

  • Withdrawing consent (POST /consent/withdraw) and checking status (GET /consent/status) both take the specific noticeId the principal originally consented under — not just the noticeGroupKey.
  • If you always fetch "the current notice" via GET /notice?groupKey=... (as recommended), you'll naturally have the right noticeId to hand for these calls, since that's the same id you used when the principal first granted consent in this session.

Granting vs. withdrawing​

Granting (POST /consent/grant) always creates a new consent record — it doesn't update a previous one in place. If a principal changes their purpose selections and grants again, you get a second record with a newer timestamp; the previous one isn't deleted, preserving history.

Withdrawing (POST /consent/withdraw) finds the token's principal's most recent record for that noticeId and withdraws it — it doesn't delete the record either. By default (no purposeCode) this flips the whole record's status to WITHDRAWN. Pass a purposeCode to withdraw just that one purpose instead — its purposeRecords entry flips to DENIED while the rest of the record is untouched, and the record's overall status only becomes WITHDRAWN once every purpose on it has ended up DENIED this way.

Listing a principal's current consents​

GET /consent/records returns a principal's current consent state across every notice they've ever responded to — one entry per distinct notice (the latest record for that notice, reflecting any withdrawals), not the full grant/withdraw history. It's paginated the same way as the admin API. Useful for building a "manage your consents" screen without knowing every noticeId up front. See List my consent records.

See the Consent API reference for full request/response shapes.