OneTrust Purpose Preferences API

openapi: 3.2.0
info:
  title: Consent & Preferences - Universal Consent & Preference…
  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:
    get:
      operationId: getListUsingGET
      summary: Get List of Purpose Preferences
      description: Use this API to retrieve a list of all Purpose Preferences. The response will include basic details such as the Purpose Preference name, languages, number of options, created date, and updated date.
      tags:
      - Purpose Preferences
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: page
        in: query
        description: The page number of the results (0-based).
        schema:
          type: integer
          example: 0
          default: 0
          minimum: 0
      - name: size
        in: query
        description: The number of results per page.
        schema:
          type: integer
          example: 20
          default: 20
          maximum: 100
          minimum: 1
      - name: sort
        in: query
        description: 'Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.'
        schema:
          type: string
          example: createdDate,desc
          enum:
          - name,asc
          - name,desc
          - createdDate,asc
          - createdDate,desc
          - lastModifiedDate,asc
          - lastModifiedDate,desc
          - selectionType,asc
          - selectionType,desc
      responses:
        '200':
          description: OK - List of Custom Preferences retrieved successfully.
          content:
            application/json:
              schema:
                type: string
        '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
        - CONSENT_READ
    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
  /api/consentmanager/v1/custompreferences/{customPreferenceId}:
    put:
      operationId: editCustomPreferenceUsingPUT
      summary: Update Purpose Preference
      description: Use this API to edit a specific Purpose Preference. The Purpose Preference will be updated 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
      parameters:
      - name: customPreferenceId
        in: path
        description: The unique identifier of the Purpose Preference to update.
        required: true
        schema:
          type: string
          format: uuid
          example: 82bd54d4-433a-451e-8512-950da5f9c1c6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceDto'
      responses:
        '200':
          description: OK - Purpose Preference updated successfully.
          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
  /api/consentmanager/v1/custompreferences/{custompreferenceId}:
    get:
      operationId: findByGuidUsingGET
      summary: Get Purpose Preference
      description: Use this API to retrieve a single Purpose Preference by its unique identifier along with details such as the Purpose Preference name, languages, number of options, created date, and updated date.
      tags:
      - Purpose Preferences
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: custompreferenceId
        in: path
        description: The UUID of the Custom Preference to be retrieved
        required: true
        schema:
          type: string
          format: uuid
      - name: includeTranslations
        in: query
        description: Parameter to include all of the Custom Preference's translations (by default is set to false)
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK - Purpose Preference retrieved successfully.
          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
        - CONSENT_READ
components:
  schemas:
    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
    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_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_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
  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
    ConsentAPI_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
    DSPreferneceCache_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