Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Consent Management v2 APIs

Query consent events

search

Please Note:

Query consent events

This page explains how to use the Ledger API to query the consent ledger in Consent Management v2 for compliance reporting, audits, and user consent history.

All paths are relative to /consent-management.

Operation Method Path
Query consent ledger GET /api/v1/ledgers

The consent ledger is an immutable, append-only audit trail of every consent event in the system. Every time a user grants or revokes consent — for a document or for an attribute processing purpose — a new record is appended to the ledger. Existing records are never modified or deleted.

This design ensures that:

  • You can prove, at any point in time, what a user consented to and when.

  • Compliance records survive document and purpose version changes and localization updates. The ledger stores a snapshot of the definition metadata at the time of consent.

  • The complete consent history of a user can be reconstructed from the ledger alone.

Common ledger record fields

Every ledger entry — regardless of type — contains the following fields:

Field Description
id Unique identifier of this ledger entry
userId The user who gave or revoked consent
consentType The type of consent: DOCUMENT or ATTRIBUTE
consentStatus The consent status: GRANTED or REVOKED
createdDate Timestamp of the consent action (ISO 8601)
createdBy The actor who registered the consent (typically the userId or system)

For entries where consentType is DOCUMENT, the document object is present:

Field Description
document.definitionId Document definition ID at the time of consent (prefixed with DD-)
document.definitionName Document name (denormalized snapshot)
document.type Document type (for example, PRIVACY_POLICY)
document.customTypeKey Custom type key (only present when type is CUSTOM)
document.isMandatory Whether the document was mandatory at the time of consent
document.versionId Document version ID (prefixed with DV-)
document.versionNumber Version number
document.versionName Version name (denormalized snapshot)
document.localizationId Localization ID (prefixed with DL-)
document.locale Language code (for example, en_US)
document.title Localized document title (denormalized snapshot)
document.externalUrl URL to the document content (denormalized snapshot)
document.localizationLineage NEW_CONTENT or DERIVED

For entries where consentType is ATTRIBUTE, the purpose object is present:

Field Description
purpose.definitionId Purpose definition ID at the time of consent (prefixed with PD-)
purpose.definitionName Purpose name (denormalized snapshot)
purpose.legalBasis GDPR Art. 6 legal basis recorded at the time of consent
purpose.identitySchemaSource Identity schema source: OIP or EXTERNAL
purpose.versionId Purpose version ID (prefixed with PV-)
purpose.versionNumber Version number
purpose.versionName Version name (denormalized snapshot)
purpose.localizationId Localization ID (prefixed with PL-)
purpose.locale Language code
purpose.title Localized purpose title (denormalized snapshot)
purpose.legalText Localized legal text at the time of consent
purpose.lineage NEW_CONTENT or DERIVED
purpose.dataScope Object containing attributes: the identity attributes linked to the purpose at the time of consent
purpose.userPreferences Object containing channels: the communication channel preferences selected by the user
purpose.versionPreferences Object containing channels: the channel preferences configured on the purpose version

GET /consent-management/api/v1/ledgers

Use the Ledger API to query consent records for compliance reporting, audit, and investigation.

Authentication: Requires an S2S or M2M token with the consent-management:ledgers:get scope, or an admin user token with the consent_read or consent_write role.

Filter the results

The following filters can be combined freely. All filters use exact matching unless otherwise noted.

Parameter Type Description
userId UUID Filter by a specific user
consentType DOCUMENT or ATTRIBUTE Filter by consent type. If omitted, both types are returned.
consentStatus GRANTED or REVOKED Filter by consent status
definitionId string Filter by definition ID. For document consent: DD- prefix or no prefix. For attribute consent: PD- prefix.
createdDateStart ISO 8601 datetime Records created on or after this date
createdDateEnd ISO 8601 datetime Records created on or before this date
type string Filter by document type (for example, PRIVACY_POLICY). Applies to DOCUMENT consent only.
isMandatory boolean Filter by mandatory flag. Applies to DOCUMENT consent only.
locale string Filter by locale code
localizationLineage NEW_CONTENT or DERIVED Filter by lineage
versionId string Filter by version ID. Document: DV- prefix. Attribute: PV- prefix.
localizationId string Filter by localization ID. Document: DL- prefix. Attribute: PL- prefix.
derivedFromLocalizationId UUID Filter by source localization (for DERIVED records only)
customTypeKey string Filter by custom type key (for CUSTOM document types only)
search string Case-insensitive partial match across definitionName, versionName, title, externalUrl, and legalText. Minimum three characters.

Date range limit: The maximum date range per query is 366 days. For longer periods, use multiple queries.

Sort the results

Parameter Default Allowed values
sortBy createdDate id, createdDate, createdBy, userId, definitionId, definitionName, versionId, versionName, localizationId, locale, title, type, isMandatory, localizationLineage, consentType, consentStatus
sortDir desc asc, desc

Pagination

Parameter Default Maximum
pageSize 50 100
pageNumber 0 10,000

Example requests

All consent grants for a specific user (both types):

GET /consent-management/api/v1/ledgers?userId={userId}&consentStatus=GRANTED&sortBy=createdDate&sortDir=desc

Only attribute consent records for a user:

GET /consent-management/api/v1/ledgers?userId={userId}&consentType=ATTRIBUTE

All consents for a specific document definition, last 90 days:

GET /consent-management/api/v1/ledgers?definitionId={DD-...}&createdDateStart=2025-01-01T00:00:00Z&createdDateEnd=2025-03-31T23:59:59Z

Search for records related to a specific document or purpose:

GET /consent-management/api/v1/ledgers?search=privacy+pol&consentStatus=GRANTED

Compliance use cases

To demonstrate that a user consented to a document or purpose before a specific date:

  1. Filter by userId and definitionId.

  2. Set createdDateEnd to the date you want to prove compliance for.

  3. Inspect the most recent record in the results. If consentStatus is GRANTED, the user had active consent at that point.

To list all users who consented to a specific version of a document:

  1. Filter by versionId (with DV- prefix) and consentStatus: GRANTED.

  2. Export the userId and createdDate from each record.

To list all users who consented to a specific version of a processing purpose:

  1. Filter by versionId (with PV- prefix) and consentStatus: GRANTED.

  2. Export the userId, createdDate, and purpose.userPreferences from each record.

To find all consent records that derive from a specific source localization:

  1. Filter by derivedFromLocalizationId: {localizationId}.

  2. This returns records where users consented to a DERIVED localization that traces back to the specified source.

Find all revocations for a processing purpose

To identify users who have revoked consent for a specific processing purpose:

  1. Filter by definitionId (with PD- prefix), consentType: ATTRIBUTE, and consentStatus: REVOKED.

  2. Export the userId and createdDate from each record.

On this page