OneTrust Data Subject Groups V4 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: Data Subject Groups V4
  description: The Data Subjects V4 APIs are used to manage data subject information, preferences, and consent records.
  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: Data Subject Groups V4
paths:
  /rest/api/consent/v4/groups:
    get:
      operationId: getDataSubjectGroupsListV4
      summary: Get List of Data Subject Groups
      description: Use this API to retrieve a list of Data Subject Groups.
      tags:
      - Data Subject Groups V4
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: requestContinuation
        in: header
        description: The token used to paginate a response if the number of records is more than a page.
        required: false
        schema:
          type: string
        example: '{\"compositeToken\": \"jmxpAKZxe9nZkAoAAAAAAA==\"}'
      - name: groupName
        in: header
        description: The name of the Data Subject Group.
        required: false
        schema:
          type: string
        example: Marketing Data Subject Group
      - name: page
        in: query
        description: The page number of the results.
        schema:
          type: integer
          default: 0
          minimum: 0
        example: 1
      - name: size
        in: query
        description: The number of results per page.
        schema:
          type: integer
          default: 20
          maximum: 50
          minimum: 1
        example: 20
      - name: sort
        in: query
        description: The sort criteria that dictates the order of the results.
        schema:
          type: string
          default: createdDate,desc
          enum:
          - createdDate,asc
          - createdDate,desc
        example: createdDate,desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupPageItemSliceDto'
        '400':
          description: Bad Request
        '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. \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:
      - ConsentAPI_OAUTH2:
        - CONSENT
  /rest/api/consent/v4/linkedidentitygroups:
    get:
      operationId: getLinkedIdentityGroupsByDataSubjectV4
      summary: Get List of Data Subject Group Associations by Data Subject
      description: 'Use this API to retrieve details about a data subject''s associations with Data Subject Groups.


        > 🗒 Things to Know

        >

        > - If the `linkedIdentityGroupId` parameter is passed, the response will include details for the data subject''s association with the specified Data Subject Group. If not passed, the response will include details for the data subject''s associations with all Data Subject Groups in which the data subject is a member.'
      tags:
      - Data Subject Groups V4
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: identifier
        in: header
        description: The data subject identifier of the data subject.
        required: true
        schema:
          type: string
        example: example@otprivacy.com
      - name: linkedIdentityGroupId
        in: query
        description: The unique identifier of the data subject group.
        required: false
        schema:
          type: string
          format: uuid
        example: 25d9ccac-db88-4d34-849c-3d602a629961
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupDto'
        '400':
          description: Bad Request
        '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. \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:
      - ConsentAPI_OAUTH2:
        - CONSENT
    post:
      operationId: createDataSubjectGroupV4
      summary: Create Data Subject Group
      description: 'Use this API to create a new Data Subject Group.


        > 🗒 Things to Know

        >

        > - Data Subject Groups must contain at least one primary data subject identifier and two data subjects.'
      tags:
      - Data Subject Groups V4
      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/ConsentAPI_LinkedIdentityGroupRequestDto'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: string
        '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:
      - ConsentAPI_OAUTH2:
        - CONSENT
  /rest/api/consent/v4/linkedidentitygroups/{dataSubjectGroupId}:
    put:
      operationId: updateDataSubjectGroupV4
      summary: Update Data Subject Group
      description: 'Use this API to update an existing Data Subject Group.


        > 🗒 Things to Know

        >

        > - Data Subject Groups must contain at least one primary data subject identifier and two data subjects.

        > - To update the Data Subject Group name, use the `groupName` parameter and enter a new name different from the one already in use.'
      tags:
      - Data Subject Groups V4
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: dataSubjectGroupId
        in: path
        description: The unique identifier for the Data Subject Group to be updated.
        required: true
        schema:
          type: string
          format: uuid
        example: 25d9ccac-db88-4d34-849c-3d602a629961
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupRequestDto'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: string
        '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. \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:
      - ConsentAPI_OAUTH2:
        - CONSENT
  /rest/api/consent/v4/linkedidentitygroups/{dataSubjectGroupId}/members:
    get:
      operationId: getLinkedIdentityGroupMembersV4
      summary: Get List of Data Subject Group Members
      description: Use this API to retrieve a list of all members of a data subject group.
      tags:
      - Data Subject Groups V4
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: dataSubjectGroupId
        in: path
        description: The unique identifier for a Data Subject Group.
        required: true
        schema:
          type: string
          format: uuid
        example: 25d9ccac-db88-4d34-849c-3d602a629961
      - name: requestContinuation
        in: header
        description: The token used to paginate a response if the number of records is more than a page.
        required: false
        schema:
          type: string
        example: '{\"compositeToken\": \"jmxpAKZxe9nZkAoAAAAAAA==\"}'
      - name: page
        in: query
        description: The page number of the results.
        schema:
          type: integer
          default: 0
          minimum: 0
        example: 0
      - name: size
        in: query
        description: The number of results per page.
        schema:
          type: integer
          default: 20
          maximum: 50
          minimum: 1
        example: 20
      - name: sort
        in: query
        description: The sort criteria that dictates the order of the results.
        schema:
          type: string
          enum:
          - addedDate,asc
          - addedDate,desc
        example: addedDate,desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupDtoSliceDto'
        '400':
          description: Bad Request
        '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. \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:
      - ConsentAPI_OAUTH2:
        - CONSENT
components:
  schemas:
    ConsentAPI_LinkedIdentityGroupDto:
      type: object
      properties:
        id:
          description: The unique identifier of the data subject group.
          type: string
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: The name of the data subject group.
          type: string
          example: a2229953-b4b5-4042-8cb9-b78038cc4c41
        identifier:
          description: The data subject identifier of the data subject.
          type: string
          example: example@otprivacy.com
        isPrimary:
          description: This flag indicates whether the data subject identifier is the primary identifier associated with the data subject group.
          type: boolean
          example: true
        addedDate:
          description: The date and time that the data subject was added to the data subject group.
          type: string
          format: date-time
          example: '2020-05-30T12:23:42.145Z'
    ConsentAPI_PageableObject:
      type: object
      properties:
        offset:
          type: integer
          format: int64
        sort:
          $ref: '#/components/schemas/ConsentAPI_SortObject'
        pageNumber:
          type: integer
          format: int32
        paged:
          type: boolean
        pageSize:
          type: integer
          format: int32
        unpaged:
          type: boolean
    ConsentAPI_LinkedIdentityGroupDataSubjectResponseDto:
      type: object
      properties:
        id:
          description: Unique identifier (UUID) of the data subject
          type: string
          format: uuid
          example: a3f8d56a-b123-4b2a-9eab-12cfea1bc456
        identifier:
          description: The original identifier value for the data subject
          type: string
          example: user@example.com
        identifierType:
          description: Type of identifier (e.g., EMAIL, PHONE)
          type: string
          example: EMAIL
        addedDate:
          description: Date and time when the data subject was added to the group
          type: string
          format: date-time
          example: '2024-11-12T10:15:30'
    ConsentAPI_LinkedIdentityGroupResponseDto:
      type: object
      properties:
        id:
          description: Unique identifier of the linked identity group
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
        createdDate:
          description: Date and time when the group was created
          type: string
          format: date-time
          example: '2024-11-12T10:15:30'
        groupName:
          description: Name of the group
          type: string
          example: UserAccountGroup
        primaryDataSubjects:
          description: List of primary data subjects in the group
          type: array
          items:
            $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupDataSubjectResponseDto'
        memberDataSubjects:
          description: List of member data subjects in the group
          type: array
          items:
            $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupDataSubjectResponseDto'
    ConsentAPI_LinkedIdentityGroupPageItemSliceDto:
      type: object
      properties:
        content:
          items:
            $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupPageItemDto'
          type: array
        number:
          description: The page number of the results.
          type: integer
          format: int32
          example: 1
        size:
          description: The number of results per page.
          type: integer
          format: int32
          example: 20
        pageable:
          $ref: '#/components/schemas/ConsentAPI_PageableObject'
        last:
          description: Flag indicating whether this is the last page or not.
          type: boolean
          example: false
        sort:
          $ref: '#/components/schemas/ConsentAPI_SortObject'
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        empty:
          type: boolean
        requestContinuation:
          description: The token used to paginate a response if the number of records is more than a page.
          type: string
          example: '{\"compositeToken\": \"jmxpAKZxe9nZkAoAAAAAAA==\"}'
    ConsentAPI_LinkedIdentityGroupDtoSliceDto:
      type: object
      properties:
        content:
          items:
            $ref: '#/components/schemas/ConsentAPI_LinkedIdentityGroupDto'
          type: array
        number:
          description: The page number of the results.
          type: integer
          format: int32
          example: 1
        size:
          description: The number of results per page.
          type: integer
          format: int32
          example: 20
        pageable:
          $ref: '#/components/schemas/ConsentAPI_PageableObject'
        last:
          description: Flag indicating whether this is the last page or not.
          type: boolean
          example: false
        sort:
          $ref: '#/components/schemas/ConsentAPI_SortObject'
        first:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        empty:
          type: boolean
        requestContinuation:
          description: The token used to paginate a response if the number of records is more than a page.
          type: string
          example: '{\"compositeToken\": \"jmxpAKZxe9nZkAoAAAAAAA==\"}'
    ConsentAPI_LinkedIdentityGroupPageItemDto:
      type: object
      properties:
        id:
          description: The unique identifier for a data subject group.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: The unique name for a data subject group.
          type: string
          example: Marketing Data Subject Group
        createdDate:
          description: The date on which the data subject group was created.
          type: string
          format: date-time
          example: '2020-05-30T12:23:42.145Z'
        lastModifiedDate:
          description: The date on which the data subject group was last modified.
          type: string
          format: date-time
          example: '2020-05-30T12:23:42.145Z'
    ConsentAPI_SortObject:
      type: object
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
    ConsentAPI_LinkedIdentityGroupRequestDto:
      type: object
      properties:
        groupName:
          description: A user-defined name for the group of linked identities.
          type: string
          example: LIG_1
        memberIdentifiers:
          description: A list of all member identifiers that belong to the group.
          type: array
          items:
            type: string
          example:
          - user_12345@ot.com
          - user_67890@ot.com
          - user_54321@ot.com
        primaryIdentifiers:
          description: A List of all identifiers that are primary identifiers. The members in this list need not be present in member identifiers list as they are mutually exclusive.
          type: array
          items:
            type: string
          example:
          - user_primary@ot.com
      required:
      - groupName
      - memberIdentifiers
      - primaryIdentifiers
  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