Manage consent purposes

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

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

Purpose definitions

A purpose definition is the top-level object in the attribute consent data model. It represents a specific processing purpose (for example, Email Marketing) and identifies the legal basis under GDPR Art. 6 for processing personal data.

Purpose definition responses

A successful response returns the purpose definition properties:

Legal basis values

Create a purpose definition (POST)

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

Example: Create a purpose definition

{
  "name": "Email Marketing",
  "legalBasis": "CONSENT",
  "description": "Processing of personal data to send marketing emails and newsletters.",
  "defaultLocale": "en_US"
}

Update a purpose definition (PATCH)

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

All fields are optional (partial update):

Delete a purpose definition (DELETE)

DELETE /consent-management/api/v1/config/purposes/{definitionId}

A purpose definition can only be deleted if it has no versions, or if all of its versions are in DRAFT status. Deletion is a hard-delete: the definition and all its versions and localizations are permanently removed.

Purpose versions

A purpose version represents a specific revision of a processing purpose, along with its linked identity attributes, communication channel preferences, and localizations.

Purpose version responses

A successful response returns the purpose version properties:

Version lifecycle

Purpose version statuses are computed automatically from dates. The lifecycle for purpose versions does not include SUNSET — it transitions directly from ACTIVE to ARCHIVED.

Status transitions

DRAFT -> SCHEDULED -> ACTIVE -> ARCHIVED

• DRAFT → SCHEDULED: Set effectiveDate to a future date.
• SCHEDULED → ACTIVE: Automatic when effectiveDate is reached (±60-minute tolerance for immediate activation).
• SCHEDULED → DRAFT: Remove effectiveDate (set to null).
• ACTIVE → ARCHIVED: Automatic when a new version becomes ACTIVE, or when archiveDate is reached.

Create a version (POST)

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

All versions are created in DRAFT status.

Example: Create a version

{
  "versionName": "2025 Version",
  "identitySchemaSource": "OIP",
  "dataScope": {
    "attributes": [
      { "name": "personal.email" },
      { "name": "personal.firstName" }
    ]
  },
  "preferences": {
    "channels": [
      {
        "channelType": "EMAIL",
        "attributes": [{ "name": "personal.email" }],
        "frequencies": ["MONTHLY", "WEEKLY"]
      }
    ]
  }
}

Version lifecycle management (PATCH)

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

The PATCH request body uses two sections: versionPatch for version-level fields, and localization delta operations.

versionPatch fields

Localization delta operations

localizationsAdded/localizationsUpdated/localizationsDeleted and the localizations full-replacement array are mutually exclusive.

Clone a version (POST)

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

Creates a DRAFT copy of any existing version (regardless of status), with all localizations copied and lifecycle dates cleared.

The response includes the cloned version with all fields, plus clonedFromVersionId and clonedFromVersionName reference fields.

Delete a version (DELETE)

DELETE /consent-management/api/v1/config/purposes/{definitionId}/versions/{versionId}

Only DRAFT versions can be deleted. A SCHEDULED version must be unscheduled first (set effectiveDate to null). ACTIVE and ARCHIVED versions cannot be deleted.

Data scope and identity attributes

Each purpose version can define a data scope — the set of identity attributes that are linked to the processing purpose.

Get available attributes

GET /consent-management/api/v1/config/identity-schema/attributes

Returns the list of identity attributes available for the tenant, including their name (dot-notation, for example personal.firstName) and optional displayName.

Data scope in version requests

The dataScope object uses full-replacement semantics on PATCH: providing a new dataScope replaces the entire previous data scope.

{
  "versionPatch": {
    "dataScope": {
      "attributes": [
        { "name": "personal.email" },
        { "name": "personal.firstName" },
        { "name": "personal.lastName" }
      ]
    }
  }
}

To clear the data scope entirely, provide an empty attributes array.

Preferences and channels

Each purpose version can define communication channel preferences — which channels are permitted for this purpose, which identity attributes are associated with each channel, and what contact frequencies are allowed.

Channel types

Contact frequencies

Preferences in version requests

The preferences object uses full-replacement semantics on PATCH. A maximum of 10 channels can be specified per version.

{
  "versionPatch": {
    "preferences": {
      "channels": [
        {
          "channelType": "EMAIL",
          "attributes": [{ "name": "personal.email" }],
          "frequencies": ["MONTHLY", "QUARTERLY"]
        },
        {
          "channelType": "SMS",
          "attributes": [{ "name": "personal.mobilePhone" }],
          "frequencies": ["WEEKLY"]
        }
      ]
    }
  }
}

To clear preferences entirely, provide an empty channels array.

Purpose localizations

A purpose localization provides the language-specific content for a version. Each version can have one localization per language. Unlike document localizations, purpose localizations contain a legal text field (the full text of the purpose shown to users) in addition to a title.

Purpose localization fields

Content lineage

The lineage model for purpose localizations follows the same rules as document localizations:

• NEW_CONTENT: The legal text is original or has changed. Users must actively consent to this localization.
• DERIVED: The legal text is legally equivalent to the source localization. Users who consented to the source are automatically compliant.

For details on how lineage traversal works, see Manage consent documents — Content lineage.

Adding localizations via version PATCH

Localizations are managed via delta operations in the version PATCH endpoint:

Add a new localization:

{
  "localizationsAdded": [
    {
      "locale": "en_US",
      "title": "Email Marketing",
      "legalText": "We will use your email address to send you marketing communications, including newsletters and promotional offers. You may withdraw your consent at any time.",
      "lineage": "NEW_CONTENT"
    }
  ]
}

Add a derived localization:

{
  "localizationsAdded": [
    {
      "locale": "fr_FR",
      "title": "Marketing par email",
      "lineage": "DERIVED",
      "derivedFromLocalizationId": "PL-a1b2c3d4-..."
    }
  ]
}

Update an existing localization:

{
  "localizationsUpdated": [
    {
      "localizationId": "PL-a1b2c3d4-...",
      "title": "Email Marketing (Updated)",
      "legalText": "Updated legal text for this localization."
    }
  ]
}

Delete a localization:

{
  "localizationsDeleted": ["PL-a1b2c3d4-..."]
}

Version scheduling invariants

The following rules are enforced when scheduling a version (setting effectiveDate):

• The version must have at least one localization.
• The version must include a localization for the purpose's defaultLocale.

Common purpose workflows

Publish a new processing purpose

1. Create a purpose definition with the appropriate legalBasis and defaultLocale.

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

3. Configure the dataScope (linked attributes) and preferences (channels) as needed.

4. Add a localization for the defaultLocale with lineage: NEW_CONTENT and the required legalText.

5. Add localizations for additional languages as needed.

6. Schedule the version by setting effectiveDate to the activation date.

7. On the effectiveDate, the version automatically becomes ACTIVE.

Update legal text and require re-consent

1. Clone the current ACTIVE version or create a new version.

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

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

4. Schedule the new version with effectiveDate.

5. When the new version becomes ACTIVE, the previous version is automatically archived. Users who consented to the previous version must re-consent if their localization traces to a different NEW_CONTENT root.

Add a new language without re-consent

1. Add a new localization to the current ACTIVE version (or create a new version).

2. Set lineage: DERIVED and reference the existing localization for the language the translation is equivalent to.

3. 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 Configuration API reference.

All paths are relative to /consent-management.