v1

latestOpenAPI 3.1.0Apache 2.02026-07-245981,1853.0 MB

Purpose Preferences

Create Purpose Preference

Use this API to create a new Purpose Preference. The Purpose Preference will be created with the details provided in the request body.

post/api/consentmanager/v1/custompreferences

Request body

Namestring required

The display name of the Custom Preference. This will be shown to end users in the preference center.

Descriptionstring required

Detailed description explaining the purpose and usage of this Custom Preference. This helps administrators understand the context of this preference.

SelectionType'SINGLE_CHOICE' | 'MULTI_CHOICE' | 'SINGLE_CHOICE' | 'MULTI_CHOICE' required

Defines how options can be selected in this Custom Preference. SINGLE_CHOICE allows only one option to be selected, while MULTI_CHOICE allows multiple selections.

Specifies how the preference options should be displayed in the user interface. This affects the visual representation of the preference options.

DefaultLanguageboolean

Indicates whether the provided language should be set as the default language for this Custom Preference. If true, the language specified in the 'language' field will be used as the default.

Languagestring required

The language code for this Custom Preference in BCP 47 format. This specifies the language of the preference name, description, and options.

Requiredboolean

Indicates whether a response is mandatory for this Custom Preference. If true, users must select an option before submitting the form.

Disabledboolean

Indicates if this Custom Preference should be disabled. Disabled preferences are not shown to end users in the preference center.

Optionsstring[] required

List of available options for this Custom Preference. Each option should be a string representing a selectable choice.

Organizationsstring[]

List of organization IDs that should have access to this Custom Preference. If empty, the preference will be available to all organizations.

Purposesstring[]

List of Purpose IDs that this Custom Preference should be associated with. This links the preference to specific purposes in the system.

Example request

{
  "Name": "Email Frequency",
  "Description": "Allows users to select how often they would like to receive marketing emails",
  "SelectionType": "SINGLE_CHOICE",
  "DisplayAs": "BUTTONS",
  "DefaultLanguage": true,
  "Language": "en-US",
  "Options": [
    "Daily",
    "Weekly",
    "Monthly",
    "Never"
  ],
  "Organizations": [
    "712a1f61-a548-432f-afc4-5a383c28eeb2",
    "862a1f61-e148-032f-afc4-7a383c28eec6"
  ],
  "Purposes": [
    "a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d"
  ]
}

Response

Idstring uuid required

Unique identifier for the Custom Preference

Namestring required

The display name of the Custom Preference

Descriptionstring

Detailed description explaining the purpose and usage of this Custom Preference

SelectionType'SINGLE_CHOICE' | 'MULTI_CHOICE' | 'SINGLE_CHOICE' | 'MULTI_CHOICE' required

Defines how options can be selected in this Custom Preference

Specifies how the preference options should be displayed in the UI

CreatedDatestring date-time

Timestamp when the Custom Preference was created

UpdatedDatestring date-time

Timestamp when the Custom Preference was last updated

NumberOfOptionsinteger

Total number of available options for this Custom Preference

Requiredboolean

Indicates whether a response is mandatory for this Custom Preference

NumberOfLanguagesinteger

Number of languages this Custom Preference has been translated into

DefaultLanguagestring

The default language code for this Custom Preference (BCP 47 format)

Disabledboolean

Indicates if this Custom Preference is currently disabled

Organizationsstring[]

List of Organization IDs that have access to this Custom Preference

TotalLinkedActivePurposesinteger

Count of active purposes that reference this Custom Preference

Example response

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