---
title: "Create Purpose Preference"
method: POST
path: "/api/consentmanager/v1/custompreferences"
tags: ["Purpose Preferences"]
---

# Create Purpose Preference

`POST /api/consentmanager/v1/custompreferences`

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

## Request body

- ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceCreateDto
  - `Name` string, required — The display name of the Custom Preference. This will be shown to end users in the preference center.
  - `Description` string, 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.
  - `DisplayAs` 'BUTTONS' | 'CHECKBOXES' | 'BUTTONS' | 'CHECKBOXES' | 'DROPDOWN' | 'RADIO_BUTTONS', required — Specifies how the preference options should be displayed in the user interface. This affects the visual representation of the preference options.
  - `DefaultLanguage` boolean — 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.
  - `Language` string, required — The language code for this Custom Preference in BCP 47 format. This specifies the language of the preference name, description, and options.
  - `Required` boolean — Indicates whether a response is mandatory for this Custom Preference. If true, users must select an option before submitting the form.
  - `Disabled` boolean — Indicates if this Custom Preference should be disabled. Disabled preferences are not shown to end users in the preference center.
  - `Options` string[], required — List of available options for this Custom Preference. Each option should be a string representing a selectable choice.
  - `Organizations` string[] — List of organization IDs that should have access to this Custom Preference. If empty, the preference will be available to all organizations.
  - `Purposes` string[] — List of Purpose IDs that this Custom Preference should be associated with. This links the preference to specific purposes in the system.

## Response `200`

OK

- ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceDto
  - `Id` string, uuid, required — Unique identifier for the Custom Preference
  - `Name` string, required — The display name of the Custom Preference
  - `Description` string — 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
  - `DisplayAs` 'BUTTONS' | 'CHECKBOXES' | 'BUTTONs' | 'CHECKBOXES' | 'DROPDOWN' | 'RADIO_BUTTONS', required — Specifies how the preference options should be displayed in the UI
  - `CreatedDate` string, date-time — Timestamp when the Custom Preference was created
  - `UpdatedDate` string, date-time — Timestamp when the Custom Preference was last updated
  - `NumberOfOptions` integer — Total number of available options for this Custom Preference
  - `Required` boolean — Indicates whether a response is mandatory for this Custom Preference
  - `NumberOfLanguages` integer — Number of languages this Custom Preference has been translated into
  - `DefaultLanguage` string — The default language code for this Custom Preference (BCP 47 format)
  - `Disabled` boolean — Indicates if this Custom Preference is currently disabled
  - `Options` ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceOptionDto[] — List of available options for this Custom Preference
    - `Id` string, uuid — Unique Identifier identifying an Option
    - `Label` string — The Option label
    - `Order` integer — The order of the option, Starts from 0
    - `IsDefault` boolean — Whether the Option is default option or not
    - `CanDelete` boolean — Whether the Option can be deleted or not
    - `Disabled` boolean — Whether Custom Preference is disabled or not
  - `Languages` ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceLanguageDto[] — List of language configurations for this Custom Preference
    - `Name` string, required — The Custom Preference name
    - `Description` string, required — The description of the Custom Preference
    - `Language` string — The Custom Preference content language code
    - `Default` boolean — Whether this language is the default one for the Custom Preference
    - `Options` ConsentPreferencesUniversalConsentPreferenceManagCustomPreferenceOptionDto[] — Options associated with a Custom Preference
      - `Id` string, uuid — Unique Identifier identifying an Option
      - `Label` string — The Option label
      - `Order` integer — The order of the option, Starts from 0
      - `IsDefault` boolean — Whether the Option is default option or not
      - `CanDelete` boolean — Whether the Option can be deleted or not
      - `Disabled` boolean — Whether Custom Preference is disabled or not
  - `Organizations` string[] — List of Organization IDs that have access to this Custom Preference
  - `TotalLinkedActivePurposes` integer — Count of active purposes that reference this Custom Preference

## Other responses

- `201` — Created
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests. For more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).
- `500` — Internal Server Error

---

[API](https://skmtc.net/onetrust/apis/platform-access-management.md) · [All operations](https://skmtc.net/onetrust/apis/platform-access-management/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onetrust/platform-access-management/versions/21de3aa0b170/schema)