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 consent for a document, a new record is appended to the consent_ledger_history table. 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 version changes and localization updates. The ledger stores a snapshot of the document metadata at the time of consent.

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

What each ledger record contains

A successful response includes the ledger record fields:

Field Description
id Unique identifier of this ledger entry
userId The user who gave consent
consentStatus GRANTED
consentType DOCUMENT
createdDate Timestamp of the consent action (ISO 8601)
createdBy The actor who registered the consent (typically the userId or system)
document.definitionId Document definition ID at the time of consent
document.definitionName Document name (denormalized snapshot)
document.type Document type (for example, PRIVACY_POLICY)
document.isMandatory Whether the document was mandatory at the time of consent
document.versionId Document version ID
document.versionNumber Version number
document.versionName Version name (denormalized snapshot)
document.localizationId Localization ID
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

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
definitionId UUID Filter by document definition (with or without DD- prefix)
consentStatus GRANTED Filter by consent status
consentType DOCUMENT Filter by consent type
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)
isMandatory boolean Filter by mandatory flag
locale string Filter by locale code
localizationLineage NEW_CONTENT or DERIVED Filter by lineage
versionId UUID Filter by document version
localizationId UUID Filter by localization
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, and externalUrl. 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:

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

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

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

Search for records related to a specific document:

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

Compliance use cases

To demonstrate that a user consented to a document 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 and consentStatus: GRANTED.

  2. Export the userId and createdDate 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.

On this page