openapi: 3.2.0
info:
  title: Unified Consent Core Collections API
  description: "> **\U0001F4CD Regional Distribution**  \n> The UC Core API is regionally distributed. Requests originating from the United States are processed in us-east-1, while requests from all other regions are processed in eu-central-1.\n\n# Introduction\n\nThe Unified Consent Core API is a REST API to interact with the Osano Unified Consent platform. Before use, you must sign up at <https://osano.com>. You are bound by the Osano terms of service and limits placed by those terms. All interactions with the API require authentication using an Osano API key, or a Unified Consent API key in the `x-osano-api-key` and `x-uc-api-key` headers respectively. They are detailed in the \"Authentication\" section.\n\n```sh\ncurl --header 'x-uc-api-key: <API_KEY>' https://uc.api.osano.com/v2/consents/check/some-subject-id\n```\n\n## Versioning\n\nAll resources are versioned according to semantic versioning with the major version being specified in the endpoints URI such as `v2`.\n\nAll major versioning will maintain backwards compatibility in that major version. Resources may add new minor versions that are not specified in the URI. The minor versions will never break backward compatibility but may add new resources or enhancements. The enhancements may include new data in the schema. We will never remove data from a schema in the same major version. To prevent your scripts or applications from breaking due to newly added data, do not error on unexpected data.\n\nWe will make a best effort to notify users when we release new major versions. We will deprecate the previous major version. Major versions may have breaking changes from previous versions such as schema changes or resource removal. All users should upgrade to the new major version in a timely manner.\n\n## Authentication\n\nThe Unified Consent Core API uses API keys to authenticate requests that are generated on a per-user basis. All calls require a valid, unexpired API key. There are two types of API keys that can be used with the Unified Consent Core API. They are the Osano API key and the Unified Consent API key. Routes that involve creating, updating, or merging subjects require the Osano API key. All other routes require the Unified Consent API key.\n\n### Osano API key\n\nOsano API keys may be generated within the [Osano settings -> API Keys](https://my.osano.com/api-keys) page. You must be an admin or have the correct privileges to generate an API key.\n\nOnce generated, the API key should be included in the `x-osano-api-key` header of all that involve creating, updating, or merging subjects. For example:\n\n```sh\ncurl --location 'https://uc.api.osano.com/v2/subject/merge' \\\n--header 'x-osano-api-key: <API_KEY>' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"sourceSubjectId\": \"some-source-subject-id\",\n    \"targetSubjectId\": \"some-target-subject-id\"\n}'\n```\n\n### Unified Consent API key\n\nUnified Consent API keys may be generated by using the `/v2/token/create` route. First gather the `configId` and the `customerId` from the Configuration details page. (Select the desired Configuration from the [Configurations list](https://my.osano.com/consent/panels) page) For example:\n\n```sh\ncurl --location 'https://uc.api.osano.com/v2/token/create' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"customerId\": \"some-customer-id\",\n    \"configId\": \"some-config-id\"\n}'\n```\n\nNote: Unified Consent API keys are scoped to a single Configuration, and will not work to submit consents for another Configuration\n\n## Submitting a consent\n\nThe following type describes the body of the request to create a consent. If submitting a GPC request, the actions array in the payload will be ignored and can be omitted. GPC actions are calculated internally based on the configured privacy protocols and the provided or detected geolocation:\n\n```ts\ntype CreateConsentRequest = {\n  compliance?: {\n    privacyPolicy?: {\n      version?: string // The privacy policy version active at the time of submitting the consent\n      url: string // The URL of the privacy policy\n    }\n    gpc?: number // 1 if GPC is enabled, 0 otherwise\n  }\n  subject: {\n    verifiedId?: string // If the subject is verified, provide the subject's verified ID\n    anonymousId?: string // If the subject is anonymous, provide the subject's anonymous ID\n  }\n  jurisdiction?: string | null // The applicable jurisdiction for the subject. Must be one of the configured jurisdictions, or null if none are applicable. Does not affect conflict resolution if omitted, but other features such as consent search may be affected.\n  actions: [\n    {\n      target: string // The privacy protocol ID to submit consent for.\n      vendor: string // The UC configuration ID to associate with the consent.\n      action: string // The subject's consent choice for the privacy protocol. Possble values: 'ACCEPT' | 'REJECT' | 'UNSELECTED'\n      jurisdiction?: string | null // The applicable jurisdiction for the subject. Must be one of the configured jurisdictions, or null if none are applicable. Does not affect conflict resolution if omitted, but other features such as consent search may be affected. Will override the top level jurisdiction if set.\n    },\n  ]\n  tags: string[] // Tags associated with the consent. Can be any string. Ex: ['ccpa', 'tcpa']\n  attributes: { [key: string]: any } // Attributes associated with the consent. `ipAddress` and `userAgent` are automatically populated, and values passed for those keys here will be overwritten.\n  origin?: 'api' | 'gpc' // If submitting a GPC consent, use 'gpc', otherwise use 'api'\n}\n```\n\nApplicable jurisdictions for a UC configuration can be determined by making a request to the `/v2/collections` endpoint.\n\nTo populate the `target` and `vendor` values for a consent it is necessary to determine the privacy protocol ID and the UC configuration ID respectively.\n\n### Finding the UC configuration ID\n\nTo find the UC configuration ID, navigate to the [UC configurations page](https://my.osano.dev/unified-consent/configs). Click on the desired configuration to open the configuration details page. Click on the \"Developers\" tab, revealing the Config ID.\n\n### Finding the privacy protocol ID\n\nTo find the privacy protocol ID, follow the steps above to open the desired UC configuration's details page. Click on the \"Privacy Protocols\" tab. From the list of privacy protocols, pick the desired privacy protocol and click the pencil icon to open the \"Edit Privacy Protocol\" modal. There you will find the Target ID, which is the privacy protocol ID.\n"
  version: 2.0.0
servers:
- url: https://uc.api.osano.com
security:
- ucApiKey: []
tags:
- name: Collections
paths:
  /v2/collections:
    get:
      summary: Retrieves all collections for a given configId based on jurisdiction
      description: "Uses the configId embedded in the Unified Consent API key to retrieve an aggregrate of all \napplicable collections of privacy protocols for a given jurisdiction. The type can either be 'draft' or 'published'. \nIf the type is not provided, the default is 'published'. If the jurisdiction is not provided, IP geolocation is used \nto determine the jurisdiction."
      parameters:
      - schema:
          type: string
        in: query
        name: jurisdiction
        required: false
      - schema:
          type: string
          enum:
          - published
          - draft
          default: published
        in: query
        name: type
        required: false
      responses:
        '200':
          description: The collections matching the query and all available and available jurisdictions
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/def-6'
                description: The collections matching the query and all available and available jurisdictions
      tags:
      - Collections
  /v2/collections/{collectionId}:
    get:
      summary: Retrieves a collection of privacy protocols
      description: Retrieves a collection of privacy protocols by id
      parameters:
      - schema:
          type: string
        in: path
        name: collectionId
        required: true
      responses:
        '200':
          description: The collection
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/def-5'
                description: The collection
      tags:
      - Collections
components:
  schemas:
    def-5:
      type: object
      properties:
        collectionId:
          type: string
        name:
          type: string
        frameworks:
          type: array
          items:
            type: string
        configIds:
          type: array
          items:
            type: string
        jurisdiction:
          type: string
        created:
          type: string
        updated:
          type: string
        type:
          type: string
        consents:
          type: array
          items:
            type: object
            additionalProperties: true
        preferences:
          type: array
          items:
            type: object
            additionalProperties: true
      title: config-collection
    def-6:
      type: object
      properties:
        jurisdictions:
          type: array
          items:
            type: string
        collection:
          $ref: '#/components/schemas/def-5'
      title: config-collections-response
  securitySchemes:
    ucApiKey:
      description: Unified Consent API key
      type: apiKey
      name: x-uc-api-key
      in: header
    osanoApiKey:
      description: Osano API key
      type: apiKey
      name: x-osano-api-key
      in: header