Manage consent documents

This page explains how to create and manage consent documents, versions, and localizations using the Consent Management v2 Configuration API. All operations require administrative privileges.

Document management involves three levels, each managed through dedicated API endpoints:

Document definitions

A document definition is the top-level object in the Consent Management v2 data model. It is the logical container for a consent document, such as a privacy policy. It identifies the document type, whether it is mandatory, and the default language.

Document definition responses

A successful response returns the document definition properties:

Document types

The documentType field classifies the document. The following standard types are available:

Create a document definition (POST)

POST /consent-management/api/v1/config/documents

To create a document definition, send a request with the following fields:

Example: Mandatory privacy policy in English

{
  "name": "Privacy Policy",
  "documentType": "PRIVACY_POLICY",
  "defaultLocale": "en_US",
  "isMandatory": true,
  "description": "Our privacy policy explains how we collect and protect your data."
}

Update a document definition (PATCH)

PATCH /consent-management/api/v1/config/documents/{definitionId}

Update the name, description, defaultLocale, and isMandatory fields. The documentType and customTypeKey fields are immutable after creation.

Delete a document definition

A document definition can only be deleted if it has no versions, or all of its versions are in DRAFT status. Versions in SCHEDULED, ACTIVE, SUNSET, or ARCHIVED status must be removed or transitioned before the definition can be deleted.

Document versions

A document version represents a specific revision of a document's content, along with all of its localizations.

Document version responses

A successful response returns the document version properties:

Each document definition can have multiple versions, but only one version can be ACTIVE at any given time.

A document version holds the lifecycle dates for a specific revision of a document, along with all of its localizations.

Version lifecycle

Document version statuses are computed automatically from dates. Administrators do not set statuses manually. The system derives the status of each version in real time based on the current time and the version's lifecycle dates.

Status definitions

Status transitions

Document versions transition through the following statuses:

DRAFT -> SCHEDULED -> ACTIVE -> SUNSET -> ARCHIVED

• DRAFT -> SCHEDULED: Set an effectiveDate in the future.
• SCHEDULED -> ACTIVE: Happens automatically when the clock reaches effectiveDate.
• ACTIVE -> SUNSET: Happens automatically when the clock reaches sunsetDate.
• SUNSET -> ARCHIVED: Happens automatically when the clock reaches archiveDate.
• SCHEDULED -> DRAFT: Remove the effectiveDate (un-schedule the version).

Grace period

When a new version becomes ACTIVE, the previous version transitions to SUNSET. If the previous version has an archiveDate in the future, users who already consented to it are in a grace period. During the grace period:

• Existing users can continue to access the service without re-consenting.

• The Runtime API returns the new ACTIVE version as outstanding, with a previousVersionOnGracePeriod field indicating when the grace period ends.

• After the archiveDate, the grace period ends and users who have not consented to the new version are blocked from accessing the service.

Create a version (POST)

POST /consent-management/api/v1/config/documents/{definitionId}/versions

Send a request with the following fields:

All versions are created in DRAFT status. Lifecycle dates (effectiveDate, sunsetDate, archiveDate) are set using the Update Version API after creation.

Example: Create a version

{
  "versionName": "Q1 2025 Update",
  "contentMode": "EXTERNAL_URL",
  "localizations": [
    {
      "locale": "en_US",
      "title": "Privacy Policy",
      "lineage": "NEW_CONTENT",
      "externalUrl": "https://example.com/legal/privacy-en-v3"
    },
    {
      "locale": "fr_FR",
      "title": "Politique de confidentialité",
      "lineage": "DERIVED",
      "derivedFromLocalizationId": "DL-..."
    }
  ]
}

Version lifecycle management (PATCH)

PATCH /consent-management/api/v1/config/documents/{definitionId}/versions/{versionId}

After you create a DRAFT version, you can manage its lifecycle using the update version API.

Clone a version (POST)

POST /consent-management/api/v1/config/documents/{definitionId}/versions/{versionId}/clone

You can clone any existing version (regardless of status). The clone is created as a DRAFT with all localizations copied and lifecycle dates cleared.

Cloning is useful for the following scenarios:

• Creating a new version based on an existing version with minor changes.

• Restoring an archived version as a new draft.

Delete a version

Only DRAFT versions can be deleted. A SCHEDULED version must be unscheduled first. ACTIVE, SUNSET, and ARCHIVED versions cannot be deleted.

Document localizations

A document localization provides the language-specific content for a version. Each version can have localizations for multiple languages, but only one localization per language.

Document localization responses

A successful response returns the document localization properties:

Localization fields

Content lineage

Content lineage determines whether a new localization represents genuinely new legal content (requiring re-consent) or is legally equivalent to an existing localization (not requiring re-consent).

NEW_CONTENT

A localization with lineage NEW_CONTENT introduces original legal content. It is the root of a lineage chain. Users must actively consent to it.

Use NEW_CONTENT when:

• The legal text of the document has changed in this language.

• This is the first time a document is published in this language.

Provide the externalUrl pointing to the document content. Do not provide derivedFromLocalizationId.

DERIVED

A localization with lineage DERIVED is legally equivalent to another localization (the source). A user who has consented to the source localization, or any localization that traces back to the same root, is considered to have also consented to the derived one.

Use DERIVED when:

• You are publishing a translation of existing content without changing its meaning.

• You are creating a new version as a minor cosmetic update (reformatting, fixed typos) in a language where the legal meaning has not changed.

Provide the derivedFromLocalizationId of the source localization. Do not provide externalUrl. It is inherited automatically from the source.

How lineage traversal works

The system traverses the lineage chain from the current active localization back to the root NEW_CONTENT localization. If the user's previously consented localization shares the same root, the user is compliant and no re-consent is required.

V1 EN  (NEW_CONTENT, root A)  <- user consented here
  │
V2 EN  (DERIVED from V1 EN)   <- still root A
  │
V3 EN  (DERIVED from V2 EN)   <- still root A -> user is compliant, no re-consent needed

If the legal content changes in a new version, a NEW_CONTENT localization must be created in the new version, establishing a new root. All users must then re-consent.

V1 EN  (NEW_CONTENT, root A)
V2 EN  (NEW_CONTENT, root B)  <- legal content changed -> user must re-consent

Edit localizations (PATCH)

PATCH /consent-management/api/v1/config/documents/{definitionId}/versions/{versionId}/localizations/{localizationId}

Update the title and externalUrl of a localization. The locale and lineage fields are immutable after creation.

Version invariants

The following invariants are enforced at scheduling time and when deleting localizations:

• A version must have at least one localization before it can be scheduled.
• A version must include a localization for the document's defaultLocale before it can be scheduled.

Common document workflows

Publish a new consent document

1. Create a document definition with the appropriate type and isMandatory setting.

2. Create a new version with a name (for example, Initial Version).

3. Add a localization for the defaultLocale with lineage: NEW_CONTENT and an externalUrl.

4. Add localizations for additional languages as needed.

5. Schedule the version. Set the effectiveDate to the activation date that you want.

6. On the effectiveDate, the version automatically becomes ACTIVE and is available to users.

Update legal content and trigger re-consent

1. Create a new version of the existing document definition.

2. Add localizations with lineage: NEW_CONTENT for all languages where the legal text has changed.

3. For languages where only translations changed, use lineage: DERIVED, referencing the previous version's localization.

4. Set a sunsetDate on the previous version equal to the effectiveDate of the new version.

5. Set an archiveDate on the previous version to define the end of the grace period.

6. Schedule the new version with effectiveDate.

7. When the new version becomes ACTIVE, users who consented to the previous version enter the grace period. After the archiveDate, they must re-consent to the new version.

Add a new language without re-consent

1. Identify the localization in the current ACTIVE version for which the new translation is equivalent.

2. Create a new version (or add to the ACTIVE version directly. ACTIVE versions accept new localizations).

3. Add the new localization with lineage: DERIVED and reference the existing localization as derivedFromLocalizationId.

4. Users who consented to the source localization are automatically compliant for the new language.

API endpoints reference

For full request and response schemas, see the Config API reference.

All paths are relative to /consent-management.