OneTrust Preferences V2 API

openapi: 3.2.0
info:
  title: Consent & Preferences - Consent Interfaces Preferences V2…
  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 Consent Interfaces APIs are used to integrate external systems and streamline the flow of data with Consent & Preferences user interfaces.
servers:
- url: https://consent-api.onetrust.com
  description: The OneTrust Consent Interfaces endpoint.
tags:
- name: Preferences V2
  description: The Consent Interfaces APIs are used by Consent & Preferences user interfaces to retrieve data subjects' preferences.
  externalDocs:
    description: OpenAPI 3.1.0 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/consent-preferences-consent-interfaces.json
paths:
  /v2/preferences:
    get:
      operationId: getRealtimePreferences
      summary: Get Data Subject's Preferences
      description: 'Use this API to retrieve a list of all consent preferences for a data subject identifier. The response will include details such as the consent date, purpose preferences, and data subject''s geolocation. The response will also include relevant information about data elements and last interaction date, along with the current status of consent for the purposes that the data subject has interacted with.


        > 🗒 Things to Know

        >

        > - This API uses a JSON Web Token (JWT) authorization token that will be passed to OneTrust servers to ensure authenticated access to a user''s consent profile. This is not the OAuth 2.0 client credential or API key. This JWT authorization token is generated using the cross-device consent process. For more information, see Cross-Domain and Cross-Device Consent.

        > - This API does not require an intermediary server-server API call. It is optimized for client-side applications, maintaining security to make quick decisions based on data subject consent.

        > - The response of this API will not return updates made via the Update Data Subject''s Preferences in a Preference Center API.'
      tags:
      - Preferences V2
      x-onetrust:
        highly-available: true
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-consent-interfaces.json
      parameters:
      - name: identifier
        in: header
        description: The data subject identifier of the data subject.
        required: true
        schema:
          type: string
        example: gpburdell@onetrust.com
      - name: tenantId
        in: header
        description: The unique identifier of the OneTrust account. This value is obtained from the OneTrust Platform by clicking the User icon in the Global Header and copying the ID that appears below the email address.
        required: true
        schema:
          type: string
          format: uuid
        example: 33df590e-3fd5-44bd-a50f-3722988021eb
      - name: Authorization
        in: header
        description: The JSON web token (JWT) that will be passed to OneTrust servers to ensure authenticated access to a user's consent profile. This JWT authorization token is generated using the [cross-device consent process](https://my.onetrust.com/s/article/UUID-750c79df-692c-7418-a395-af2acaa45601).
        required: true
        schema:
          type: string
        example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJncGJ1cmRlbGxAb25ldHJ1c3QuY29tIiwibmFtZSI6Ikdlb3JnZSBCdXJkZWxsIiwiaWF0IjoxNTE2MjM5MDIyfQ.UizsCE7HsWYe-d24XHekF5tJLGiwFbpshtHQkNw5bKb
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferencesDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: string
        '429':
          description: Too Many Requests
      security:
      - bearerAuth:
        - sub
components:
  schemas:
    PreferencesDto:
      type: array
      items:
        type: object
        properties:
          identifier:
            description: The data subject identifier of the data subject.
            type: string
            example: gpburdell@onetrust.com
          identifierType:
            description: The type of data subject identifier.
            type: string
            example: Email
          dataElements:
            description: The additional information about the data subject provided via a consent receipt.
            type: object
            example:
              FirstName: John
              LastName: Doe
            additionalProperties:
              type: string
          additionalIdentifiers:
            description: The additional data subject identifiers of the data subject.
            type: object
            example:
              AccountId: A1234
            additionalProperties:
              type: string
          purposes:
            description: The details of the purposes that the data subject interacted with.
            type: array
            items:
              $ref: '#/components/schemas/PurposeDto'
          latestGeolocation:
            description: The geolocation details of the most recent consent receipt.
            $ref: '#/components/schemas/DataSubjectGeolocationDto'
          language:
            description: The language set for the data subject.
            type: string
            example: en-US
    PurposeDto:
      type: object
      properties:
        id:
          description: 'The unique identifier of the purpose. '
          type: string
          format: uuid
          example: c1d9fecb-e679-4c59-87e7-9a1b66afec51
        version:
          description: The version of the purpose.
          type: integer
          example: 1
        status:
          description: The status of the purpose.
          type: string
          enum:
          - EXPIRED
          - WITHDRAWN
          - NO_CONSENT
          - PENDING
          - ACTIVE
          - OPT_OUT
          - ALWAYS_ACTIVE
          - HARD_OPT_OUT
          - EXTEND
          - NOT_OPT_OUT
        consentDate:
          description: The date and time that the data subject provided consent for the purpose.
          type: string
          format: date-time
        customPreferences:
          description: The details of the purpose preferences that the data subject interacted with.
          $ref: '#/components/schemas/CustomPreferencesDto'
        lastInteractionDate:
          description: The most recent date and time that the data subject interacted with the purpose.
          type: string
          format: date-time
        reactivationDate:
          description: Indicates the date and time on which a consent will be reactivated. This is set to snooze a purpose until the specified date and time. The consent remains snoozed until this date, then is automatically reactivated and becomes active again.
          type: string
          format: date-time
        geolocation:
          description: The geolocation details of the consent receipt.
          $ref: '#/components/schemas/DataSubjectGeolocationDto'
    CustomPreferencesDto:
      type: array
      items:
        type: object
        properties:
          id:
            description: The unique identifier of the purpose preference associated with the purpose.
            type: string
            format: uuid
            example: 1ebe272a-736f-4bec-b4b3-77309bb6bdf3
          options:
            description: The unique identifiers of the purpose preference options that the data subject interacted with.
            type: array
            items:
              type: object
              properties:
                id:
                  description: The unique identifiers of the purpose preference options.
                  type: string
                  format: uuid
                  example: 7590d76b-c69f-4c68-805d-bd326595a213
    DataSubjectGeolocationDto:
      type: object
      properties:
        receiptGuid:
          description: The unique identifier of the consent receipt for which geolocation details were sent.
          type: string
          format: uuid
          example: 788ba071-61b0-485f-81a0-a2245777b432
        country:
          description: The country where the consent interaction occurred.
          type: string
          example: US
        state:
          description: The state code where the consent interaction occurred.
          type: string
          example: GA
        stateName:
          description: The name of the state where the consent interaction occurred.
          type: string
          example: Georgia
      title: DataSubjectGeolocationDto
x-onetrust:
  spec-label: OpenAPI 3.1.0
x-readme:
  explorer-enabled: false
  proxy-enabled: false
  metrics-enabled: false