OneTrust Data Subject Groups 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
  description: The Data Subject Groups APIs are used to manage groups of data subjects.
  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
paths:
  /api/consentmanager/v2/linkedidentitygroups:
    get:
      operationId: getLinkedIdentityGroupsUsingGET
      summary: Get List of Data Subject Groups
      description: Use this API to retrieve a list of all Data Subject Groups. The response will include the Data Subject Group ID, number of data subjects, and details of the primary data subjects in the group.
      tags:
      - Data Subject Groups
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: primaryDataSubjectIdentifier
        in: header
        description: In order to retrieve a list of Linked Identity Groups whose primary identifier is equal to the primaryDataSubjectIdentifier header value
        required: false
        schema:
          type: string
          example: user@example.com
      - name: primaryDataSubjectIdentifierType
        in: header
        description: In order to retrieve a list of Linked Identity Groups whose primary identifier type is equal to the primaryDataSubjectIdentifierType header value
        required: false
        schema:
          type: string
          example: Email
      - name: requestContinuation
        in: header
        description: Token for pagination
        required: false
        schema:
          type: string
        example: eyJpZCI6IjEyMzQ1Njc4OTAiLCJ0aW1lc3RhbXAiOjE2MDAwMDAwMDB9
      - name: displayOrganizations
        in: query
        description: Include organization information for Data Subject Groups
        required: false
        schema:
          type: boolean
          example: false
      - name: page
        in: query
        description: Results page you want to retrieve (0..N).
        schema:
          type: integer
          example: 0
          default: 0
          minimum: 0
      - name: size
        in: query
        description: Number of records 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:
          - lastModifiedDate,asc
          - lastModifiedDate,desc
          - lastUpdatedDate,asc
          - lastUpdatedDate,desc
          - expiryDate,asc
          - expiryDate,desc
          - addedDate,asc
          - addedDate,desc
          - createdDate,asc
          - createdDate,desc
      responses:
        '200':
          description: OK - Successfully retrieved Data Subject Groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PageLinkedIdentityGroupDto_Page'
        '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: createLinkedIdentityGroupUsingPOST
      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
      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_LinkedIdentityGroupRequest_Detailed'
      responses:
        '200':
          description: OK - Successfully created Data Subject Group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupDto_Detailed'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupDto_Detailed'
        '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/v2/linkedidentitygroups/{linkedIdentityGroupId}:
    get:
      operationId: getLinkedIdentityGroupUsingGET
      summary: Get Data Subject Group
      description: Use this API to retrieve a single Data Subject Group by its unique identifier along with details such as the Data Subject Group ID and the list of data subjects within its group.
      tags:
      - Data Subject Groups
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: linkedIdentityGroupId
        in: path
        description: Unique identifier identifying a Data Subject Group.
        required: true
        schema:
          type: string
          format: uuid
          example: 3d8c79aa-5a14-48a4-b88d-f023913ec2ca
      - name: displayOrganizations
        in: query
        description: Include organization information in the response.
        required: false
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: OK - Successfully retrieved Data Subject Group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupDto_Detailed'
        '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
    put:
      operationId: updateLinkedIdentityGroupUsingPUT
      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
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: linkedIdentityGroupId
        in: path
        description: Unique identifier identifying a Data Subject Group.
        required: true
        schema:
          type: string
          format: uuid
          example: 3d8c79aa-5a14-48a4-b88d-f023913ec2ca
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupRequest_Detailed'
      responses:
        '200':
          description: OK - Successfully updated Data Subject Group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupDto_Detailed'
        '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
    delete:
      operationId: deleteUsingDELETE
      summary: Delete Data Subject Group
      description: Use this API to delete an existing Data Subject Group.
      tags:
      - Data Subject Groups
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json
      parameters:
      - name: linkedIdentityGroupId
        in: path
        description: Unique identifier identifying a Data Subject Group
        required: true
        schema:
          type: string
          format: uuid
          example: 3d8c79aa-5a14-48a4-b88d-f023913ec2ca
      responses:
        '200':
          description: OK - Successfully deleted Data Subject Group
        '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_LinkedIdentityGroupDto_Page:
      properties:
        id:
          description: Globally unique identifier of a Linked Identity Group
          type: string
          format: uuid
          example: b0a6b5da-4ea2-4a9f-a25a-fb3e212efc30
        numberOfDataSubjects:
          description: The number of Data Subjects in a Linked Identity Group
          type: integer
          format: int64
          example: 6
        createdDate:
          description: Creation date of a Linked Identity Group
          type: string
          format: date-time
          example: '2020-05-30T10:52:30.974Z'
        lastModifiedDate:
          description: Last modified date of a Linked Identity Group
          type: string
          format: date-time
          example: '2020-05-30T12:23:42.145Z'
        primaryDataSubjects:
          description: List of primary Data Subjects in the Linked Identity Group
          type: array
          items:
            $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectEntry_Page'
        organizations:
          description: Set of organization UUIDs associated with the linked identity group
          type: array
          items:
            type: string
            format: uuid
            description: Set of organization UUIDs associated with the linked identity group
          example:
          - 550e8400-e29b-41d4-a716-446655440000
          - 6ba7b810-9dad-11d1-80b4-00c04fd430c8
          uniqueItems: true
        primaryDataSubjectId:
          description: Globally unique identifier of the primary Data Subject
          type: string
          format: uuid
          example: c43a9190-ffd6-4be3-aeff-95b46d0fa59f
        primaryDataSubjectIdentifier:
          description: The identifier value of the primary Data Subject
          type: string
          example: example@otprivacy.com
        primaryDataSubjectIdentifierType:
          description: The identifier type of the primary Data Subject
          type: string
          example: Email
        isPrimary:
          description: Boolean flag that denotes if the Data Subject is the primary of the group
          type: boolean
          example: false
        groupName:
          description: The name of the linked identity group
          type: string
          example: Customer Group A
        key:
          description: The type of the linked identity group
          type: string
          enum:
          - PRIMARY
          - CHILD
          - GROUP_NAME
    ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupDto_Detailed:
      type: object
      properties:
        id:
          description: Globally unique identifier of a Linked Identity Group
          type: string
          format: uuid
          example: b0a6b5da-4ea2-4a9f-a25a-fb3e212efc30
        createdDate:
          description: Creation date of a Linked Identity Group
          type: string
          format: date-time
          example: '2020-05-30T10:52:30.974Z'
        primaryDataSubject:
          $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectEntry_Detailed'
        primaryDataSubjects:
          description: List of primary Data Subjects in the Linked Identity Group
          type: array
          items:
            $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectEntry_Detailed'
        dataSubjects:
          description: A list of all the linked Data Subjects in the group
          type: array
          items:
            $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectEntry_Detailed'
        groupName:
          description: The name of the linked identity group
          type: string
          example: Customer Group A
    ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupRequest_Detailed:
      type: object
      properties:
        identifiers:
          description: A list of all the Data Subject identifiers to be added to the group; must be at least 2
          type: array
          items:
            type: string
          example:
          - example@otprivacy.com
          - example@onetrust.com
          maxItems: 2147483647
          minItems: 2
        primaryIdentifier:
          description: List of all primary Data Subject identifiers of the group; must be contained in the identifiers list
          type: array
          items:
            type: string
          example:
          - example@otprivacy.com
          maxItems: 2147483647
          minItems: 1
        groupName:
          description: Name of the Linked Identity Group
          type: string
          example: Customer Support Group
    ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectEntry_Detailed:
      properties:
        id:
          description: Unique identifier of the Data Subject
          type: string
          format: uuid
          example: c43a9190-ffd6-4be3-aeff-95b46d0fa59f
        identifier:
          description: The identifier value of the Data Subject
          type: string
          example: example@otprivacy.com
        identifierType:
          description: The type of identifier used for the Data Subject (e.g., Email, Phone, CustomID)
          type: string
          example: Email
        isPrimary:
          description: Boolean flag that denotes if the Data Subject is the primary of the group
          type: boolean
          example: false
        canBePrimary:
          description: Boolean flag that denotes if the Data Subject is allowed to be the group primary
          type: boolean
          example: false
        addedDate:
          description: The date that the Data Subject was added to the group
          type: string
          format: date-time
          example: '2020-05-30T12:23:42.145Z'
        numberOfLinkedGroups:
          description: The number of Other Linked Groups the Data Subject is a member of
          type: integer
          format: int64
          example: 2
        magicLinkToken:
          description: Authentication token used for magic link functionality
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        magicLinkTokenEncoded:
          description: URL-encoded version of the magic link token for direct use in URLs
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        organizations:
          description: Set of organization UUIDs associated with this Data Subject
          type: array
          items:
            type: string
            format: uuid
            description: Set of organization UUIDs associated with this Data Subject
          example:
          - 550e8400-e29b-41d4-a716-446655440000
          uniqueItems: true
      required:
      - identifier
      - identifierType
    ConsentPreferences-UniversalConsentPreferenceManag_SortObject_Page:
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean
    ConsentPreferences-UniversalConsentPreferenceManag_PageableObject_Page:
      properties:
        offset:
          type: integer
          format: int64
        sort:
          $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_SortObject_Page'
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        paged:
          type: boolean
        unpaged:
          type: boolean
    ConsentPreferences-UniversalConsentPreferenceManag_PageLinkedIdentityGroupDto_Page:
      type: object
      properties:
        content:
          description: The list of items for the current page.
          items:
            $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_LinkedIdentityGroupDto_Page'
          type: array
        empty:
          description: The flag to check if the entity is empty or not.
          type: boolean
          example: false
        first:
          description: The flag to check if the entity is first entity or not.
          type: boolean
          example: true
        last:
          description: The flag to check if the entity is last entity or not.
          type: boolean
          example: false
        number:
          description: The number associated with the result.
          type: integer
          format: int32
          example: 0
        numberOfElements:
          description: Total number of elements in the result.
          type: integer
          format: int32
          example: 20
        pageable:
          $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PageableObject_Page'
        sort:
          $ref: '#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_SortObject_Page'
        totalPages:
          description: Total number of pages in the result list.
          type: integer
          format: int32
          example: 5
        totalElements:
          description: Total number of elements in the result.
          type: integer
          format: int64
          example: 50
        size:
          description: Size of the result list.
          type: integer
          format: int32
          example: 20
    ConsentPreferences-UniversalConsentPreferenceManag_DataSubjectEntry_Page:
      properties:
        id:
          description: Unique identifier of the Data Subject
          type: string
          format: uuid
          example: c43a9190-ffd6-4be3-aeff-95b46d0fa59f
        identifier:
          description: The identifier value of the Data Subject
          type: string
          example: example@otprivacy.com
        identifierType:
          description: The type of identifier used for the Data Subject (e.g., Email, Phone, CustomID)
          type: string
          example: Email
      required:
      - identifier
      - identifierType
  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