OneTrust Geolocation Rules API

openapi: 3.2.0
info:
  title: Consent & Preferences - Cookie Consent Geolocation Rules 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: Geolocation Rules
  description: The Geolocation Rules APIs are used to manage geographic rules that determine how consent experiences are applied based on user location.
  externalDocs:
    description: OpenAPI 3.1.0 - Download Definition
    url: https://developer.onetrust.com/onetrust/openapi/consent-preferences-cookie-consent.json
paths:
  /api/cmp/v1/georulegroups:
    get:
      operationId: getGeoRuleGroups
      summary: Get List of Geolocation Rule Groups
      description: Use this API to retrieve a paginated list of geolocation rule groups. The `search` parameter can be used to optionally filter results by name.
      tags:
      - Geolocation Rules
      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 geo rule groups by name
        required: false
        schema:
          type: string
          maxLength: 255
        example: Default Geo Rule Group
      - name: sortBy
        in: query
        description: Field to sort by.
        required: false
        schema:
          type: string
          default: geoRuleGroupName
          enum:
          - geoRuleGroupName
          - status
          - version
        example: geoRuleGroupName
      - 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/PageGeoRuleGroupDto'
        '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/georulegroups/{geoRuleGroupId}:
    get:
      operationId: getGeoRuleGroupDetails
      summary: Get Geolocation Rule Group
      description: Use this API to retrieve detailed information for all geolocation rules within a specified geolocation rule group, including regions, consent model, cookie categories, and other attributes.
      tags:
      - Geolocation Rules
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-cookie-consent.json
      parameters:
      - name: geoRuleGroupId
        in: path
        description: Unique identifier of the geo rule group
        required: true
        schema:
          type: string
          format: uuid
        example: f2229953-b4b5-4042-8cb9-b78038cc4c46
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoRuleGroupDetailDto'
        '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/georulegroups/{geoRuleGroupId}/assign:
    put:
      operationId: assignEntitiesToGeoRuleGroup
      summary: Assign Geolocation Rule Group
      description: Use this API to assign or unassign multiple domains and/or applications to a specified geolocation rule group. For each domain or application, set the value to `true` to assign or `false` to unassign.
      tags:
      - Geolocation Rules
      x-onetrust:
        spec-label: https://developer.onetrust.com/onetrust/openapi/consent-preferences-cookie-consent.json
      parameters:
      - name: geoRuleGroupId
        in: path
        description: Unique identifier of the geo rule group
        required: true
        schema:
          type: string
          format: uuid
        example: f2229953-b4b5-4042-8cb9-b78038cc4c46
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeoRuleGroupAssignRequestDto'
      responses:
        '200':
          description: OK
        '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
components:
  schemas:
    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
    PageGeoRuleGroupDto:
      type: object
      properties:
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        size:
          type: integer
          format: int32
        content:
          items:
            $ref: '#/components/schemas/GeoRuleGroupDto'
          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
    StateResponseDto:
      type: object
      properties:
        id:
          description: Unique identifier of the state.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: Name of the state.
          type: string
          example: California
        code:
          description: State code.
          type: string
          example: CA
        countryCode:
          description: ISO country code of the country this state belongs to.
          type: string
          example: US
    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
    GeoRuleDto:
      type: object
      properties:
        geoRuleId:
          description: Unique identifier of the geo rule.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        geoRuleName:
          description: Name of the geo rule.
          type: string
          example: Europe Rule
          maxLength: 255
          minLength: 1
        consentModel:
          description: Consent model applied to this geo rule.
          type: string
          example: Opt-In
          maxLength: 50
          minLength: 1
        default:
          type: boolean
        global:
          type: boolean
    GeoRuleGroupDetailDto:
      type: object
      properties:
        geoRuleGroupId:
          description: Unique identifier of the geo rule group.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        geoRuleGroupName:
          description: Name of the geo rule group.
          type: string
          example: My new Geo Rule Group
          maxLength: 255
          minLength: 1
        geoRules:
          description: List of geo rules within this group.
          type: array
          items:
            $ref: '#/components/schemas/GeoRuleDetailDto'
          example:
          - geoRuleId: f2229953-b4b5-4042-8cb9-b78038cc4c46
            geoRuleName: Europe Rule
            isDefault: false
            isGlobal: false
            audienceLogicEnabled: true
            showBanner: true
            enableGoogleConsent: false
            consentModel: Opt-In
            regions:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
              name: Europe
            countries:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
              name: Germany
              code: DE
            states:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
              name: California
              code: CA
            cookieCategories:
            - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
              name: Strictly Necessary
              status: Opt-out
              customCategoryName: C0001
              type: COOKIE
              sequence: 1
            templateName: Default Template
            templateId: f2229953-b4b5-4042-8cb9-b78038cc4c46
          maxItems: 1000
          minItems: 0
        defaultConsentModel:
          description: Default consent model for the geo rule group.
          type: string
          example: Opt-In
          maxLength: 50
          minLength: 1
        associatedDomains:
          description: Map of domain IDs to domain URLs associated with this geo rule group.
          type: object
          example:
            f2229953-b4b5-4042-8cb9-b78038cc4c46: example.com
            a1234567-b4b5-4042-8cb9-b78038cc4c47: test.com
          additionalProperties:
            type: string
        assignedMobileApps:
          description: Map of mobile app IDs to app names assigned to this geo rule group.
          type: object
          example:
            c3456789-b4b5-4042-8cb9-b78038cc4c48: MyApp
            d4567890-b4b5-4042-8cb9-b78038cc4c49: TestApp
          additionalProperties:
            type: string
        status:
          description: Current status of the geo rule group.
          type: string
          example: ACTIVATED
          enum:
          - DRAFT
          - ACTIVATED
          - PUBLISHED
          - DISABLED
        orgId:
          description: Organization ID that owns this geo rule group.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        orgName:
          description: Organization name
          type: string
          example: OneTrust
          maxLength: 255
          minLength: 1
        description:
          description: Description of the geo rule group.
          type: string
          example: Default Geo Rule Group for all regions
          maxLength: 1000
          minLength: 1
        version:
          description: Version number of the geo rule group.
          type: integer
          format: int64
          example: 1
        default:
          type: boolean
    GeoRuleGroupDto:
      type: object
      properties:
        geoRuleGroupId:
          description: Unique identifier of the geo rule group.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        geoRuleGroupName:
          description: Name of the geo rule group.
          type: string
          example: Your New Geo Rule Group
          maxLength: 255
          minLength: 1
        geoRules:
          description: List of geo rules within this group.
          type: array
          items:
            $ref: '#/components/schemas/GeoRuleDto'
          example:
          - geoRuleId: f2229953-b4b5-4042-8cb9-b78038cc4c46
            geoRuleName: Europe Rule
            consentModel: Opt-In
            default: false
            global: false
          maxItems: 1000
          minItems: 0
        defaultConsentModel:
          description: Default consent model for the geo rule group.
          type: string
          example: Opt-In
          maxLength: 50
          minLength: 1
        associatedDomains:
          description: Map of domain IDs to domain URLs associated with this geo rule group.
          type: object
          example:
            f2229953-b4b5-4042-8cb9-b78038cc4c46: example.com
            a1234567-b4b5-4042-8cb9-b78038cc4c47: test.com
          additionalProperties:
            type: string
        assignedMobileApps:
          description: Map of mobile app IDs to app names assigned to this geo rule group.
          type: object
          example:
            c3456789-b4b5-4042-8cb9-b78038cc4c48: MyApp
            d4567890-b4b5-4042-8cb9-b78038cc4c49: TestApp
          additionalProperties:
            type: string
        status:
          description: Current status of the geo rule group.
          type: string
          example: ACTIVE
          enum:
          - DRAFT
          - ACTIVATED
          - PUBLISHED
          - DISABLED
        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 that owns this geo rule group.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        orgName:
          description: Organization name
          type: string
          example: OneTrust
          maxLength: 255
          minLength: 1
        description:
          description: Description of the geo rule group.
          type: string
          example: Default geo rule group for all regions
          maxLength: 1000
          minLength: 1
        version:
          description: Version number of the geo rule group.
          type: integer
          format: int32
          example: 1
        default:
          type: boolean
    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
    CookieCategoryDto:
      type: object
      properties:
        id:
          description: Unique identifier of the cookie category.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: Name of the cookie category.
          type: string
          example: Strictly Necessary
          maxLength: 255
          minLength: 1
        status:
          description: Consent status for this category.
          type: string
          example: Opt-out
          maxLength: 50
          minLength: 1
        customCategoryName:
          description: Custom category name.
          type: string
          example: C0001
          maxLength: 255
          minLength: 1
        customCategoryId:
          description: Unique identifier of the custom category.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        type:
          description: Type of the cookie category.
          type: string
          example: COOKIE
          maxLength: 50
          minLength: 1
        doNotTrackEnabled:
          description: Indicates if Do Not Track is enabled for this category.
          type: boolean
          example: false
        globalPrivacyControlEnabled:
          description: Indicates if Global Privacy Control is enabled for this category.
          type: boolean
          example: false
        cookiepediaCategoryId:
          description: Cookiepedia category ID.
          type: integer
          format: int32
          example: 123
        sequence:
          description: Sequence of the cookie category.
          type: integer
          format: int32
          example: 1
    RegionResponseDto:
      type: object
      properties:
        id:
          description: Unique identifier of the region.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: Name of the region.
          type: string
          example: Europe
    GeoRuleDetailDto:
      type: object
      properties:
        geoRuleId:
          description: Unique identifier of the geo rule.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        geoRuleName:
          description: Name of the geo rule.
          type: string
          example: Europe Rule
          maxLength: 255
          minLength: 1
        createdDate:
          description: Date when the geo rule was created.
          type: string
          format: date-time
          example: '2025-01-01T00:00:00Z'
        audienceLogicEnabled:
          description: Indicates if audience logic is enabled for this geo rule.
          type: boolean
          example: true
        showBanner:
          description: Indicates if the consent banner should be displayed.
          type: boolean
          example: true
        enableGoogleConsent:
          description: Indicates if Google Consent Mode is enabled.
          type: boolean
          example: false
        consentModel:
          description: Consent model applied to this geo rule.
          type: string
          example: Opt-In
          maxLength: 50
          minLength: 1
        regions:
          description: List of regions assigned to this geo rule.
          type: array
          items:
            $ref: '#/components/schemas/RegionResponseDto'
          example:
          - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            name: Europe
          maxItems: 1000
          minItems: 0
        countries:
          description: List of countries assigned to this geo rule.
          type: array
          items:
            $ref: '#/components/schemas/CountryResponseDto'
          example:
          - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            name: Germany
            code: DE
          maxItems: 1000
          minItems: 0
        states:
          description: List of states assigned to this geo rule.
          type: array
          items:
            $ref: '#/components/schemas/StateResponseDto'
          example:
          - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            name: California
            code: CA
          maxItems: 1000
          minItems: 0
        cookieCategories:
          description: List of cookie categories and their consent status for this geo rule.
          type: array
          items:
            $ref: '#/components/schemas/CookieCategoryDto'
          example:
          - id: f2229953-b4b5-4042-8cb9-b78038cc4c46
            name: Strictly Necessary
            status: Opt-out
            customCategoryName: C0001
            customCategoryId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            type: COOKIE
            doNotTrackEnabled: false
            globalPrivacyControlEnabled: false
            cookiepediaCategoryId: 123
            sequence: 1
          maxItems: 1000
          minItems: 0
        attributes:
          description: Map of template attributes for this geo rule.
          type: object
          example:
            showBanner:
              value: true
              type: BOOLEAN
            audienceLogic:
              value: false
              type: BOOLEAN
            bannerPosition:
              value: bottom
              type: STRING
          additionalProperties:
            $ref: '#/components/schemas/AttributeDto'
        templateName:
          description: Name of the template associated with this geo rule.
          type: string
          example: Default Template
          maxLength: 255
          minLength: 1
        templateId:
          description: Unique identifier of the template associated with this geo rule.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        default:
          type: boolean
        global:
          type: boolean
    GeoRuleGroupAssignRequestDto:
      type: object
      properties:
        domainIds:
          description: List of domain IDs to assign to the geo rule group.
          type: array
          items:
            type: string
            format: uuid
          example:
          - f2229953-b4b5-4042-8cb9-b78038cc4c46
          - a1234567-b4b5-4042-8cb9-b78038cc4c47
          maxItems: 1000
          minItems: 0
        applicationIds:
          description: List of application IDs to assign to the geo rule group.
          type: array
          items:
            type: string
            format: uuid
          example:
          - c3456789-b4b5-4042-8cb9-b78038cc4c48
          - d4567890-b4b5-4042-8cb9-b78038cc4c49
          maxItems: 1000
          minItems: 0
    CountryResponseDto:
      type: object
      properties:
        id:
          description: Unique identifier of the country.
          type: string
          format: uuid
          example: f2229953-b4b5-4042-8cb9-b78038cc4c46
        name:
          description: Name of the country.
          type: string
          example: Germany
        code:
          description: ISO country code.
          type: string
          example: DE
        regionCode:
          description: ISO region code of the region this country belongs to.
          type: string
          example: AS
  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