v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB

Purposes V2

Get Purpose

Use this API to retrieve a single Purpose by its unique identifier along with the associated attributes, Purpose Preferences, and created date.

🗒 Things to Know

This API returns Purpose descriptions inside <p> and </p> HTML tags. These can be sanitized depending on your formatting needs.

get/api/consentmanager/v2/purposes/{purposeId}

Path parameters

purposeIdstring uuid required

Example:550e8400-e29b-41d4-a716-446655440000

Unique identifier of the Purpose

Query parameters

status'ACTIVE' | 'DRAFT'

The status of the Purpose to be retrieved (ACTIVE or DRAFT). By default, ACTIVE is returned.

versioninteger

Example:2

Version number of the Purpose to be retrieved

Response

OK - Successfully retrieved purpose

idstring uuid required

Unique identifier of the purpose

labelstring required

Name or label of the purpose version

descriptionstring

Detailed description of the purpose version

status'DRAFT' | 'ACTIVE' | 'RETIRED' required

Current status of the purpose version

versioninteger required

Version number of the purpose

consentLifeSpaninteger

Lifespan of consents recorded against this purpose version in seconds

implicitConsentLifeSpaninteger

Lifespan of implicit consents recorded against this purpose version in seconds

implicitConsentConfirmDescstring

Description text for the implicit consent confirmation checkbox

purposeType'STANDARD' | 'COOKIE' | 'IAB' | 'MOBILE' | 'NOTIFICATION_OPT_OUT' required

Type of the purpose

parentPurposeIdstring uuid

Unique identifier of the parent purpose, if this is a child purpose

retireOnDatestring date-time

Date when the purpose will be retired

createdBystring

ID of the user who created the purpose

createdDatestring date-time

Date and time when the purpose version was created

lastModifiedBystring

ID of the user who last modified the purpose

lastModifiedDatestring date-time

Date and time when the purpose version was last modified

publishedBystring

ID of the user who published the purpose

publishedDatestring date-time

Date and time when the purpose version was published

expiryDateType'LAST_TRANSACTION_DATE' | 'CONSENT_DATE'

Type of date field used for calculating purpose lifespan/expiry

enableGeolocationboolean

Flag indicating whether to capture the data subject's geolocation when consent is provided

attributesobject

Additional attributes attached to the purpose

LastMajorVersioninteger

VersionNotesstring

IsMajorVersionboolean

HardOptOutDisplayFormat'HIDE' | 'LOCK'

The format in which the purpose displays in a Trust Center when the consent status is Hard opt-out. Hard opt-out purposes can either be displayed but locked, or hidden.

HardOptOutMessagestring

The message to display with the purpose when the consent status is Hard opt-out. This message only displays when hardOptOutDisplayFormat is set to LOCK.

receiptInclusionAttributesobject

Attributes that should be included in the receipt

Example response

{
  "id": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
  "label": "Marketing Communications",
  "description": "Collect customer emails for marketing purposes",
  "status": "ACTIVE",
  "version": 2,
  "consentLifeSpan": 31536000,
  "implicitConsentLifeSpan": 31536000,
  "implicitConsentConfirmDesc": "I agree to the processing of my personal data for this purpose",
  "purposeType": "STANDARD",
  "parentPurposeId": "ba54eb25-90f0-4633-ab12-c7bf5afdd856",
  "retireOnDate": "2025-12-31T23:59:59Z",
  "createdBy": "304F7D36-75A2-4967-81A5-5A7D604C6A19",
  "createdDate": "2023-01-01T00:00:00Z",
  "lastModifiedBy": "304F7D36-75A2-4967-81A5-5A7D604C6A19",
  "lastModifiedDate": "2023-01-15T15:30:45Z",
  "publishedBy": "304F7D36-75A2-4967-81A5-5A7D604C6A19",
  "publishedDate": "2023-01-10T10:15:30Z",
  "customPreferences": [
    {
      "id": "c4a57a38-3774-45ad-9fa4-dbc545542232",
      "name": "Email Frequency",
      "displayAs": "BUTTONS"
    }
  ],
  "topics": [
    {
      "id": "497c4383-2c61-4906-aed0-660e3fd03ef0",
      "transactionType": "OPT_IN",
      "name": "Car Marketing",
      "integrationKey": "Marketing-Communications_Car-Marketing",
      "canDelete": true
    }
  ],
  "expiryDateType": "LAST_TRANSACTION_DATE",
  "enableGeolocation": true,
  "HardOptOutDisplayFormat": "HIDE",
  "HardOptOutMessage": "This purpose is required and cannot be opted out",
  "languages": [
    {
      "name": "Marketing Communications",
      "description": "Collect customer emails for marketing purposes",
      "implicitConsentConfirmDesc": "I agree to the processing of my personal data for this purpose",
      "language": "en-US",
      "default": true,
      "hardOptOutMessage": "This purpose is required and cannot be opted out"
    }
  ]
}