v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB

Purposes

Create Purpose

Use this this API to create a new Purpose. The new Purpose will be created in Draft status and version 1.

🗒 Things to Know

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

Query parameters

isInternalOrgboolean

Specifies if the Purpose is for internal organization use

Request body

Organizationsstring[]

A list of External Organization Ids.

Namestring required

Name of the Purpose

Descriptionstring required

Detailed description of the Purpose's intended use

ConsentLifeSpaninteger required

The lifespan of consents recorded against this purpose in seconds

DefaultLanguagestring

The default language for the Purpose in BCP 47 format

Type'STANDARD' | 'COOKIE' | 'IAB' | 'MOBILE' | 'NOTIFICATION_OPT_OUT'

Type of the Purpose

ParentPurposeIdstring uuid

Unique identifier of the parent purpose

attributeValuesobject

Map of attribute values associated with the purpose

EnableGeolocationboolean

Flag to enable geolocation tracking for this purpose

CustomPreferenceIdsstring[]

List of custom preference IDs associated with the purpose

ImplicitConsentLifeSpaninteger

Lifespan for implicit consents in seconds

ImplicitConsentConfirmDescstring

Description shown when confirming implicit consent

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.

LastMajorVersioninteger

Version number of the last major update

VersionNotesstring

Release notes for the current version

IsMajorVersionboolean

Indicates if this is a major version update

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 request

{
  "Organizations": [
    "Organization Id-1",
    "Organization Id-2"
  ],
  "Name": "Marketing Communications",
  "Description": "Collect customer emails for marketing purposes",
  "ConsentLifeSpan": 7889238,
  "DefaultLanguage": "en-us",
  "Type": "STANDARD",
  "ParentPurposeId": "ba54eb25-90f0-4633-ab12-c7bf5afdd856",
  "CustomPreferenceIds": [
    "f2229953-b4b5-4042-8cb9-b78038cc4c46",
    "bc4836e2-c117-461b-a7a2-2b268c037a97"
  ],
  "ImplicitConsentLifeSpan": 31536000,
  "ImplicitConsentConfirmDesc": "By continuing, you agree to our terms and conditions",
  "HardOptOutDisplayFormat": "HIDE",
  "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"
      }
    ]
  },
  "LastMajorVersion": 2,
  "VersionNotes": "Updated purpose description and consent lifespan",
  "HardOptOutMessage": "This purpose is required and cannot be opted out"
}

Response

OK - Successfully created purpose

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"
}