--- updatedAt: 2026-05-27T12:49:39.000Z agentTools: projectIndex: https://developer.onetrust.com/onetrust/llms.txt --- # 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. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Consent & Preferences - Universal Consent & Preference Management (OAS)", "version": "1.0", "contact": { "name": "OneTrust Support", "url": "https://my.onetrust.com/s/contactsupport" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "description": "The Universal Consent & Preference Management APIs are used to integrate external systems and streamline the flow of data with Universal Consent & Preference Management in the OneTrust Platform." }, "servers": [ { "url": "https://{hostname}", "variables": { "hostname": { "default": "hostname", "description": "The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com." } } } ], "tags": [ { "name": "Purpose Preferences", "description": "The Purpose Preferences APIs are used to manage preferences related to specific data collection purposes.", "externalDocs": { "description": "OpenAPI 3.1.0 - Download Definition", "url": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json" }, "x-displayName": "Purpose Preferences" } ], "paths": { "/api/consentmanager/v1/custompreferences": { "post": { "operationId": "createCustomPreferenceUsingPOST", "summary": "Create Purpose Preference", "description": "Use this API to create a new Purpose Preference. The Purpose Preference will be created with the details provided in the request body.", "tags": [ "Purpose Preferences" ], "x-onetrust": { "spec-label": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceCreateDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceDto" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceDto" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).", "headers": { "Retry-After": { "schema": { "description": "The number of seconds after which requests will be allowed again.", "format": "int32" } }, "ot-period": { "schema": { "description": "The unit of time for which the rate limit applies", "enum": [ "HOUR", "MINUTE" ] } }, "ot-ratelimit-event-id": { "schema": { "description": "The unique identifier for the rate-limiting event.", "format": "uuid" } }, "ot-request-made": { "schema": { "description": "The number of requests made within the specified period.", "format": "int32" } }, "ot-requests-allowed": { "schema": { "description": "The number of requests allowed within the specified period.", "format": "int32" } } } }, "500": { "description": "Internal Server Error" } }, "security": [ { "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": [ "CONSENT" ] } ] } } }, "components": { "schemas": { "ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceOptionDto": { "properties": { "Id": { "description": "Unique Identifier identifying an Option", "type": "string", "format": "uuid", "example": "ca0fc41b-b28a-4335-804c-44d1f0f782ed" }, "Label": { "description": "The Option label", "type": "string", "example": "Weekly" }, "Order": { "description": "The order of the option, Starts from 0", "type": "integer", "format": "int32", "example": 1 }, "IsDefault": { "description": "Whether the Option is default option or not", "type": "boolean", "example": true }, "CanDelete": { "description": "Whether the Option can be deleted or not", "type": "boolean", "example": true }, "Disabled": { "description": "Whether Custom Preference is disabled or not", "type": "boolean", "example": false } } }, "ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceDto": { "type": "object", "properties": { "Id": { "description": "Unique identifier for the Custom Preference", "type": "string", "format": "uuid", "example": "194e0d3b-0ba8-4bc7-b046-e3ae42b2bd25" }, "Name": { "description": "The display name of the Custom Preference", "type": "string", "example": "Email Frequency", "maxLength": 255, "minLength": 1 }, "Description": { "description": "Detailed description explaining the purpose and usage of this Custom Preference", "type": "string", "example": "Options for different frequencies to receive emails", "maxLength": 1000 }, "SelectionType": { "description": "Defines how options can be selected in this Custom Preference", "type": "string", "example": "SINGLE_CHOICE", "enum": [ "SINGLE_CHOICE", "MULTI_CHOICE", "SINGLE_CHOICE", "MULTI_CHOICE" ] }, "DisplayAs": { "description": "Specifies how the preference options should be displayed in the UI", "type": "string", "example": "BUTTONs", "enum": [ "BUTTONS", "CHECKBOXES", "BUTTONs", "CHECKBOXES", "DROPDOWN", "RADIO_BUTTONS" ] }, "CreatedDate": { "description": "Timestamp when the Custom Preference was created", "type": "string", "format": "date-time", "example": "2023-01-15T10:52:30.974Z" }, "UpdatedDate": { "description": "Timestamp when the Custom Preference was last updated", "type": "string", "format": "date-time", "example": "2023-01-15T10:55:30.974Z" }, "NumberOfOptions": { "description": "Total number of available options for this Custom Preference", "type": "integer", "format": "int64", "example": 4, "minimum": 0 }, "Required": { "description": "Indicates whether a response is mandatory for this Custom Preference", "type": "boolean", "example": false, "default": false }, "NumberOfLanguages": { "description": "Number of languages this Custom Preference has been translated into", "type": "integer", "format": "int64", "example": 3, "minimum": 0 }, "DefaultLanguage": { "description": "The default language code for this Custom Preference (BCP 47 format)", "type": "string", "example": "en-us", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "Disabled": { "description": "Indicates if this Custom Preference is currently disabled", "type": "boolean", "example": false, "default": false }, "Options": { "description": "List of available options for this Custom Preference", "type": "array", "items": { "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceOptionDto" } }, "Languages": { "description": "List of language configurations for this Custom Preference", "type": "array", "items": { "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceLanguageDto" } }, "Organizations": { "description": "List of Organization IDs that have access to this Custom Preference", "type": "array", "items": { "type": "string", "format": "uuid", "example": "712a1f61-a548-432f-afc4-5a383c28eeb2" } }, "TotalLinkedActivePurposes": { "description": "Count of active purposes that reference this Custom Preference", "type": "integer", "format": "int64", "example": 5, "minimum": 0 } }, "required": [ "DisplayAs", "Id", "Name", "SelectionType" ] }, "ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceLanguageDto": { "properties": { "Name": { "description": "The Custom Preference name", "type": "string", "example": "Email Frequency" }, "Description": { "description": "The description of the Custom Preference", "type": "string", "example": "Options for different frequencies to receive emails" }, "Language": { "description": "The Custom Preference content language code", "type": "string", "example": "en-us" }, "Default": { "description": "Whether this language is the default one for the Custom Preference", "type": "boolean", "example": true }, "Options": { "description": "Options associated with a Custom Preference", "type": "array", "items": { "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceOptionDto" } } }, "required": [ "Description", "Name" ] }, "ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceCreateDto": { "properties": { "Name": { "description": "The display name of the Custom Preference. This will be shown to end users in the preference center.", "type": "string", "example": "Email Frequency", "maxLength": 255, "minLength": 1 }, "Description": { "description": "Detailed description explaining the purpose and usage of this Custom Preference. This helps administrators understand the context of this preference.", "type": "string", "example": "Allows users to select how often they would like to receive marketing emails", "maxLength": 1000, "minLength": 1 }, "SelectionType": { "description": "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.", "type": "string", "example": "SINGLE_CHOICE", "enum": [ "SINGLE_CHOICE", "MULTI_CHOICE", "SINGLE_CHOICE", "MULTI_CHOICE" ] }, "DisplayAs": { "description": "Specifies how the preference options should be displayed in the user interface. This affects the visual representation of the preference options.", "type": "string", "example": "BUTTONS", "enum": [ "BUTTONS", "CHECKBOXES", "BUTTONS", "CHECKBOXES", "DROPDOWN", "RADIO_BUTTONS" ] }, "DefaultLanguage": { "description": "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.", "type": "boolean", "example": true, "default": true }, "Language": { "description": "The language code for this Custom Preference in BCP 47 format. This specifies the language of the preference name, description, and options.", "type": "string", "example": "en-US", "minLength": 1, "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "Required": { "description": "Indicates whether a response is mandatory for this Custom Preference. If true, users must select an option before submitting the form.", "type": "boolean", "example": false, "default": false }, "Disabled": { "description": "Indicates if this Custom Preference should be disabled. Disabled preferences are not shown to end users in the preference center.", "type": "boolean", "example": false, "default": false }, "Options": { "description": "List of available options for this Custom Preference. Each option should be a string representing a selectable choice.", "type": "array", "items": { "type": "string", "description": "A single option for the Custom Preference", "example": "Weekly", "maxLength": 255, "minLength": 1 }, "example": [ "Daily", "Weekly", "Monthly", "Never" ], "minItems": 1 }, "Organizations": { "description": "List of organization IDs that should have access to this Custom Preference. If empty, the preference will be available to all organizations.", "type": "array", "items": { "type": "string", "format": "uuid", "description": "A single organization ID", "example": "712a1f61-a548-432f-afc4-5a383c28eeb2" }, "example": [ "712a1f61-a548-432f-afc4-5a383c28eeb2", "862a1f61-e148-032f-afc4-7a383c28eec6" ] }, "Purposes": { "description": "List of Purpose IDs that this Custom Preference should be associated with. This links the preference to specific purposes in the system.", "type": "array", "items": { "type": "string", "format": "uuid", "description": "A single Purpose ID", "example": "a1b2c3d4-e5f6-4a5b-8c7d-9e0f1a2b3c4d" } } }, "required": [ "Description", "DisplayAs", "Language", "Name", "Options", "SelectionType" ] } }, "securitySchemes": { "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://{hostname}/api/access/v1/oauth/token", "scopes": { "CONSENT": "Consent Scope gives the user access to read/write operations", "CONSENT_READ": "Consent Read Scope gives the user read-only access" } } } } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "metrics-enabled": false }, "x-onetrust": { "spec-label": "OpenAPI 3.1.0" } } ``` # Sibling pages * [Get List of Purpose Preferences](https://developer.onetrust.com/onetrust/reference/getlistusingget.md) * [Update Purpose Preference](https://developer.onetrust.com/onetrust/reference/editcustompreferenceusingput.md) * [Get Purpose Preference](https://developer.onetrust.com/onetrust/reference/findbyguidusingget.md)