OneTrust Templates API

openapi: 3.2.0
info:
  title: Consent & Preferences - Cookie Consent Templates API
  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 Cookie Consent APIs are used to integrate external systems and streamline the flow of data with Cookie Consent 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: Templates
  description: The Templates APIs are used to manage reusable consent templates that define the structure and behavior of consent experiences.
  externalDocs:
    description: OpenAPI 3.1.0 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/consent-preferences-cookie-consent.json
paths:
  /api/cmp/v1/templates:
    get:
      operationId: getTemplates
      summary: Get List of Templates
      description: Use this API to retrieve a paginated list of templates with their details, including template name, type, current version, and status.
      tags:
      - Templates
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-cookie-consent.json
      parameters:
      - name: searchStr
        in: query
        description: Search string to filter templates by name
        required: false
        schema:
          type: string
          maxLength: 255
        example: my-template
      - name: sortBy
        in: query
        description: Field to sort by.
        required: false
        schema:
          type: string
          default: templateName
          enum:
          - templateName
          - templateType
          - status
          - currentVersion
        example: templateName
      - name: direction
        in: query
        description: Sort direction.
        required: false
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
        example: asc
      - name: page
        in: query
        description: The page number for pagination results, starting from 0.
        required: false
        schema:
          type: integer
          example: 1
          default: 0
          minimum: 0
      - name: size
        in: query
        description: The number of items to return per page.
        required: false
        schema:
          type: integer
          example: 10
          default: 10
          maximum: 100
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageTemplateDto'
        '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:
      - OAUTH2:
        - COOKIE_READ
  /api/cmp/v1/templates/{templateId}:
    get:
      operationId: getTemplateDetails
      summary: Get Template Details
      description: Use this API to retrieve detailed information of a template, including banner setup, preference center setup and the cookie list.
      tags:
      - Templates
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-cookie-consent.json
      parameters:
      - name: templateId
        in: path
        description: Unique identifier of the template
        required: true
        schema:
          type: string
          format: uuid
        example: f2229953-b4b5-4042-8cb9-b78038cc4c46
      - name: language
        in: query
        description: Optional language-country code to retrieve localized template content
        required: false
        schema:
          type: string
          maxLength: 5
          minLength: 2
        example: en-US
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateDetailDto'
        '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:
      - OAUTH2:
        - COOKIE_READ
components:
  schemas:
    SortObject:
      type: object
      properties:
        empty:
          description: This flag indicates whether the result set is empty.
          type: boolean
        sorted:
          description: This flag indicates whether the results are sorted.
          type: boolean
        unsorted:
          description: This flag indicates whether the results are in unsorted order.
          type: boolean
    IABSourceIllustrationsDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        displayGroupId:
          description: Unique identifier of the display group.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        illustration:
          description: Illustration text.
          type: string
          example: This is an example illustration
          maxLength: 1000
          minLength: 1
        sequence:
          description: Sequence order of the illustration.
          type: integer
          format: int32
          example: 1
        custom:
          type: boolean
    TemplateDto:
      type: object
      properties:
        id:
          description: UUID of the template
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        currentVersion:
          description: The current version number of the template
          type: integer
          format: int32
          example: 12
        templateName:
          description: Name of the template
          type: string
          example: my-template-2026
          maxLength: 255
          minLength: 1
        templateType:
          description: The category of the template
          type: string
          example: GDPR
          enum:
          - GDPR
          - IAB
          - CCPA
          - IAB2
          - GENERIC
          - LGPD
          - GENERIC_PROMPT
          - CPRA
          - CDPA
          - USNATIONAL
          - COLORADO
          - CTDPA
          - UCPA
          - QUEBEC
          - IABC
          - IAB2V2
          - OCPA
          - MODPA
          - VCDPA
          - UKGDPR
          - IND_DPDPA
          - CUSTOM
        status:
          description: The template's status, published if status is ACTIVATED
          type: string
          example: DRAFTED
          enum:
          - DRAFTED
          - ACTIVATED
        isDefault:
          description: Indicates if the template is the default template
          type: boolean
          example: false
        isUniversalDefault:
          description: Indicates if the template is the universal default template
          type: boolean
          example: false
        isOrgDefault:
          description: Indicates if the template is the default template for the organization
          type: boolean
          example: false
        orgDefaultEnabled:
          description: Indicates if the organization default is enabled
          type: boolean
          example: false
        orgId:
          description: Organization ID
          type: string
          example: org-123
          maxLength: 255
          minLength: 1
        orgName:
          description: Organization name
          type: string
          example: OneTrust
          maxLength: 255
          minLength: 1
        languages:
          description: List of enabled language codes for this template
          type: array
          items:
            type: string
          example:
          - en
          - fr-CA
          - es
    PageableObject:
      type: object
      properties:
        offset:
          description: The starting position for paginated results.
          type: integer
          format: int64
        sort:
          description: The sorting configuration applied to the results.
          $ref: '#/components/schemas/SortObject'
        paged:
          description: This flag indicates whether pagination is enabled.
          type: boolean
        pageSize:
          description: The number of items displayed per page.
          type: integer
          format: int32
        pageNumber:
          description: The current page number in the pagination sequence.
          type: integer
          format: int32
        unpaged:
          description: This flag indicates whether pagination is disabled.
          type: boolean
    TemplateDetailDto:
      type: object
      properties:
        template:
          description: Template details
          $ref: '#/components/schemas/TemplateDto'
        pcAdvancedConfig:
          description: Root display group tree
          $ref: '#/components/schemas/DisplayGroupTreeDto'
        bannerAttributes:
          description: Map of branding attributes keyed by attribute name - For Banner
          type: object
          example:
            dBannerButtonColor:
              id: f2229953-b4b5-4042-8cb9-b78038cc4c46
              name: dBannerButtonColor
              value: '#000000'
              type: STRING
              section: BANNER
              important: false
            dBannerPosition:
              id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              name: dBannerPosition
              value: bottom
              type: STRING
              section: BANNER
              important: false
          additionalProperties:
            $ref: '#/components/schemas/BrandingAttributeDTO'
        pcAttributes:
          description: Map of branding attributes keyed by attribute name - For Preferences Center
          type: object
          example:
            dPCButtonColor:
              id: f2229953-b4b5-4042-8cb9-b78038cc4c46
              name: dPCButtonColor
              value: '#0066FF'
              type: STRING
              section: PREFERENCE_CENTER
              important: false
            dPCShowCookieList:
              id: b2c3d4e5-f6g7-8901-bcde-f12345678901
              name: dPCShowCookieList
              value: true
              type: BOOLEAN
              section: PREFERENCE_CENTER
              important: false
          additionalProperties:
            $ref: '#/components/schemas/BrandingAttributeDTO'
        clistattributes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BrandingAttributeDTO'
    BrandingAttributeDTO:
      type: object
      properties:
        id:
          description: Attribute ID
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: Attribute name
          type: string
          example: dBannerButtonColor
          maxLength: 255
          minLength: 1
        value:
          description: Attribute value
          type: object
          example: '#000000'
        type:
          description: Attribute type
          type: string
          example: STRING
          enum:
          - STRING
          - LONG
          - BOOLEAN
          - UUID
        important:
          description: Attribute is important
          type: boolean
          example: false
    DisplayGroupTreeDto:
      type: object
      properties:
        nodeId:
          description: Unique identifier of the tree node.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        sequence:
          description: Sequence order of the node within its level.
          type: integer
          format: int32
          example: 1
        attributes:
          description: Map of attributes associated with this display group node.
          type: object
          example:
            showBanner:
              value: true
              type: BOOLEAN
          additionalProperties:
            $ref: '#/components/schemas/AttributeDto'
        displayGroup:
          description: Display group entity details associated with this node.
          $ref: '#/components/schemas/DisplayGroupEntityDto'
        cookiepediaCategoryId:
          description: Cookiepedia category ID associated with this display group.
          type: integer
          format: int32
          example: 123
    DisplayGroupEntityDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          description: Name of the display group.
          type: string
          example: Strictly Necessary Cookies
          maxLength: 255
          minLength: 1
        type:
          description: Type of the display group.
          type: string
          example: COOKIE
          enum:
          - ROOT
          - BRANCH
          - COOKIE
          - IAB
          - IAB2_PURPOSE
          - IAB2_STACK
          - IAB2_FEATURE
          - IAB2_SPL_PURPOSE
          - IAB2_SPL_FEATURE
          - MOB_DEVICE_PERMISSION
          - IAB2V2_PURPOSE
          - IAB2V2_STACK
          - IAB2V2_FEATURE
          - IAB2V2_SPL_PURPOSE
          - IAB2V2_SPL_FEATURE
          - IAB2V2_DATA_CATEGORY
        creationMode:
          description: Creation mode of the display group.
          type: string
          example: MANUAL
          enum:
          - SEEDED
          - MANUAL
        description:
          description: Description of the display group for web platforms.
          type: string
          example: These cookies are essential for the website to function.
          maxLength: 5000
          minLength: 0
        mobileDescription:
          description: Description of the display group for mobile platforms.
          type: string
          example: Essential cookies for mobile app.
          maxLength: 5000
          minLength: 0
        ottDescription:
          description: Description of the display group for OTT (Over-The-Top) platforms.
          type: string
          example: Essential cookies for OTT app.
          maxLength: 5000
          minLength: 0
        mobileName:
          description: Name of the display group for mobile platforms.
          type: string
          example: Essential Cookies
          maxLength: 255
          minLength: 0
        ottName:
          description: Name of the display group for OTT platforms.
          type: string
          example: Essential Cookies
          maxLength: 255
          minLength: 0
        showMobDesc:
          description: Indicates if mobile description should be displayed.
          type: boolean
          example: true
        showOTTDesc:
          description: Indicates if OTT description should be displayed.
          type: boolean
          example: true
        alwaysShowCategory:
          description: Indicates if the category should always be shown on web platforms.
          type: boolean
          example: false
        mobileAlwaysShowCategory:
          description: Indicates if the category should always be shown on mobile platforms.
          type: boolean
          example: false
        ottAlwaysShowCategory:
          description: Indicates if the category should always be shown on OTT platforms.
          type: boolean
          example: false
        descriptionLegal:
          description: Legal description of the display group.
          type: string
          example: Legal text for this category.
          maxLength: 5000
          minLength: 0
        customCategoryId:
          description: Unique identifier of the custom category.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        customCategoryName:
          description: Name of the custom category.
          type: string
          example: C0001
          maxLength: 255
          minLength: 0
        enable:
          description: Indicates if the display group is enabled.
          type: boolean
          example: true
        show:
          description: Indicates if the display group should be shown.
          type: boolean
          example: true
        iabIllustrations:
          description: List of IAB source illustrations associated with this display group.
          type: array
          items:
            $ref: '#/components/schemas/IABSourceIllustrationsDto'
          example:
          - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            displayGroupId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            illustration: This is an example illustration
            sequence: 1
            custom: false
          maxItems: 1000
          minItems: 0
        machineTranslated:
          type: boolean
        iabPurpose:
          type: boolean
    AttributeDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        value:
          type: object
        audit:
          description: Indicates if this attribute should be audited
          type: boolean
          example: true
        translatable:
          description: Indicates if this attribute is translatable
          type: boolean
          example: false
        type:
          type: string
          enum:
          - STRING
          - LONG
          - BOOLEAN
          - UUID
        customized:
          description: Indicates if this attribute is customized
          type: boolean
          example: false
    PageTemplateDto:
      type: object
      properties:
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        size:
          type: integer
          format: int32
        content:
          items:
            $ref: '#/components/schemas/TemplateDto'
          type: array
        number:
          type: integer
          format: int32
        sort:
          $ref: '#/components/schemas/SortObject'
        pageable:
          $ref: '#/components/schemas/PageableObject'
        first:
          type: boolean
        last:
          type: boolean
        numberOfElements:
          type: integer
          format: int32
        empty:
          type: boolean
  securitySchemes:
    OAUTH2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{hostname}/api/access/v1/oauth/token
          scopes:
            COOKIE: Cookie Scope gives the user access to read/write operations inside the Cookie Consent module.
            COOKIE_READ: Cookie Read Scope gives the user read-only access to the Cookie Consent module.
x-onetrust:
  spec-label: OpenAPI 3.1.0
x-readme:
  explorer-enabled: false
  proxy-enabled: false
  metrics-enabled: false