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
| Field | Type | Notes |
|---|---|---|
id | number | |
status | enum | ACTIVE or WITHDRAWN |
consentMethod | enum | Which channel consent came through — see Grant Consent → Consent method values for the full list |
captureMethod | enum | How consent was physically captured (CHECKBOX, TOGGLE_SWITCH, BUTTON_CLICK, ...) — a separate axis from consentMethod, optional on grant |
ipAddress / userAgent | string | Captured automatically server-side from the request |
timestamp | datetime | When this record was created |
sha256Checksum | string | Non-repudiation checksum — see below |
purposeRecords | array | Per-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.
Consent is scoped to one notice version, permanently
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 specificnoticeIdthe principal originally consented under — not just thenoticeGroupKey. - If you always fetch "the current notice" via
GET /notice?groupKey=...(as recommended), you'll naturally have the rightnoticeIdto 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.