v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB

Purposes

Create New Purpose Version

Use this API to create a new version of an existing Purpose that is currently in Active status. A new version of the Purpose will be created in Draft status while the Active version of the Purpose will remain unchanged.

🗒 Things to Know

Once the Purpose is in Draft status, the Update Purpose API can be used to edit the Purpose. Changes will only be visible once the new version of the Purpose is published.

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

post/api/consentmanager/v1/purposes/{purposeGuid}

Path parameters

purposeGuidstring uuid required

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

Unique identifier of the Purpose.

Response

OK - Successfully created new purpose version.

Idstring uuid

Globally unique identifier of the Purpose

Labelstring

Name of the Purpose

Descriptionstring

Detailed description of the Purpose's intended use

Status'DRAFT' | 'ACTIVE' | 'RETIRED'

Status of the Purpose

Versioninteger

Current version of the Purpose

RetireOnDatestring date-time

Date when the purpose will be retired

ParentPurposeIdstring uuid

Unique identifier of the parent purpose

ExternalReferencestring

External reference identifier for the purpose

PurposeType'STANDARD' | 'COOKIE' | 'IAB' | 'MOBILE' | 'NOTIFICATION_OPT_OUT'

Type of the purpose

ConsentLifeSpaninteger

Lifespan of the consent in seconds

ImplicitConsentLifeSpaninteger

Lifespan for implicit consents in seconds

ImplicitConsentConfirmDescstring

Description shown when confirming implicit consent

ExpiryDateType'LAST_TRANSACTION_DATE' | 'CONSENT_DATE'

Date field considered for purpose lifespan/expiry

attributeValuesobject

Map of attribute values associated with the purpose

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.

attributesobject

Additional attributes attached to the purpose

EnableGeolocationboolean

Flag to enable geolocation tracking for this purpose

LastMajorVersioninteger

Last major version number of the purpose

VersionNotesstring

Notes about the current version of the purpose

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.

Example response

{
  "Id": "f2229953-b4b5-4042-8cb9-b78038cc4c46",
  "Label": "Marketing Communications",
  "Description": "Collect customer emails for marketing purposes",
  "Status": "ACTIVE",
  "Version": 2,
  "RetireOnDate": "2025-12-31T23:59:59Z",
  "ParentPurposeId": "ba54eb25-90f0-4633-ab12-c7bf5afdd856",
  "ExternalReference": "EXT-REF-12345",
  "PurposeType": "STANDARD",
  "ConsentLifeSpan": 7776000,
  "ImplicitConsentLifeSpan": 31536000,
  "ImplicitConsentConfirmDesc": "By continuing, you agree to our terms and conditions",
  "PurposeCategory": {
    "id": "a34ccec7-1ec0-4d65-9075-bdd0d923f1d1",
    "value": "Text Value",
    "valueKey": "attribute.option.valueKey",
    "colorCode": "red",
    "optionSelectionValue": "\"3.5\"",
    "displayLabel": "United State | San Francisco",
    "associatedAttributeValueInformation": [
      {
        "id": "a34ccec7-1ec0-4d65-9075-bdd0d923f1d1",
        "value": "Text Value",
        "valueKey": "attribute.option.valueKey",
        "colorCode": "red"
      }
    ]
  },
  "Languages": [
    {
      "Name": "Marketing Communications",
      "Description": "Collect customer emails for marketing purposes",
      "Description of Implicit Purpose Confirmation checkbox": "I can confirm",
      "Language": "en-us",
      "Default": true,
      "HardOptOutMessage": "This purpose is required and cannot be opted out"
    }
  ],
  "Topics": [
    {
      "Id": "497c4383-2c61-4906-aed0-660e3fd03ef0",
      "Name": "Car Marketing",
      "IntegrationKey": "Marketing-Communications_Car-Marketing",
      "CanDelete": true
    }
  ],
  "CustomPreferences": [
    {
      "Id": "194e0d3b-0ba8-4bc7-b046-e3ae42b2bd25",
      "Name": "Email Frequency",
      "Description": "Options for different frequencies to receive emails",
      "SelectionType": "SINGLE_CHOICE",
      "DisplayAs": "BUTTONs",
      "CreatedDate": "2023-01-15T10:52:30.974Z",
      "UpdatedDate": "2023-01-15T10:55:30.974Z",
      "NumberOfOptions": 4,
      "NumberOfLanguages": 3,
      "DefaultLanguage": "en-us",
      "Options": [
        {
          "Id": "ca0fc41b-b28a-4335-804c-44d1f0f782ed",
          "Label": "Weekly",
          "Order": 1,
          "IsDefault": true,
          "CanDelete": true
        }
      ],
      "Languages": [
        {
          "Name": "Email Frequency",
          "Description": "Options for different frequencies to receive emails",
          "Language": "en-us",
          "Default": true,
          "Options": [
            {
              "Id": "ca0fc41b-b28a-4335-804c-44d1f0f782ed",
              "Label": "Weekly",
              "Order": 1,
              "IsDefault": true,
              "CanDelete": true
            }
          ]
        }
      ],
      "Organizations": [
        "712a1f61-a548-432f-afc4-5a383c28eeb2"
      ],
      "TotalLinkedActivePurposes": 5,
      "PurposeCustomPreferenceId": "c4a57a38-3774-45ad-9fa4-dbc545542232"
    }
  ],
  "ExpiryDateType": "LAST_TRANSACTION_DATE",
  "HardOptOutDisplayFormat": "HIDE",
  "LastMajorVersion": 2,
  "VersionNotes": "Updated to include new data retention policies",
  "HardOptOutMessage": "This purpose is required and cannot be opted out"
}