Skip to main content

API Documentation

API docs by Redocly

Unified Consent Core API (2.0.0)

Download OpenAPI specification:Download

Introduction

The 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.

curl --header 'x-uc-api-key: <API_KEY>' https://uc.api.osano.com/v2/consents/check/some-subject-id

Versioning

All resources are versioned according to semantic versioning with the major version being specified in the endpoints URI such as v2.

All 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.

We 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.

Authentication

The 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.

Osano API key

Osano API keys may be generated within the Osano settings -> API Keys page. You must be an admin or have the correct privileges to generate an API key.

Once 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:

curl --location 'https://uc.api.osano.com/v2/subject/merge' \
--header 'x-osano-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "sourceSubjectId": "some-source-subject-id",
    "targetSubjectId": "some-target-subject-id"
}'

Unified 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 page) For example:

curl --location 'https://uc.api.osano.com/v2/token/create' \
--header 'Content-Type: application/json' \
--data '{
    "customerId": "some-customer-id",
    "configId": "some-config-id"
}'

Note: Unified Consent API keys are scoped to a single Configuration, and will not work to submit consents for another Configuration

Retrieves the unified consent for a subject.

Retrieves the unified consent for a subject.

Authorizations:
ucApiKey
path Parameters
subjectRef
required
string

Anonymous id, verified id, or a valid session id.

query Parameters
ref
string
Enum: "subject" "session"

Indicates what type of reference is provided for the subject. Supports a subject id or a session id.

header Parameters
x-country-code-override
string

Valid ISO 3166-1 country code to override the country resolution based on the IP address.

x-region-code-override
string

Valid ISO 3166-2 region code to override the region resolution based on the IP address

Responses

Response samples

Content type
application/json
{
  • "unifiedConsent": {
    },
  • "conflicts": [
    ]
}

Checks whether a subject has given consent in a co

Checks whether a subject has given consent in a configuration.

Authorizations:
ucApiKey
path Parameters
subjectId
required
string
header Parameters
x-country-code-override
string

Valid ISO 3166-1 country code to override the country resolution based on the IP address.

x-region-code-override
string

Valid ISO 3166-2 region code to override the region resolution based on the IP address

Responses

Response samples

Content type
application/json
{
  • "exists": true
}

Retrieves all collections for a given configId based on jurisdiction

Uses the configId embedded in the Unified Consent API key to retrieve an aggregrate of all applicable collections of privacy protocols for a given jurisdiction. The type can either be 'draft' or 'published'. If the type is not provided, the default is 'published'. If the jurisdiction is not provided, IP geolocation is used to determine the jurisdiction.

Authorizations:
ucApiKey
query Parameters
jurisdiction
string
type
string
Default: "published"
Enum: "draft" "published"

Responses

Response samples

Content type
application/json
{
  • "jurisdictions": [
    ],
  • "collection": {
    }
}

Retrieves a collection of privacy protocols

Retrieves a collection of privacy protocols by id

Authorizations:
ucApiKey
path Parameters
collectionId
required
string

Responses

Response samples

Content type
application/json
{
  • "collectionId": "string",
  • "name": "string",
  • "frameworks": [
    ],
  • "configIds": [
    ],
  • "jurisdiction": "string",
  • "created": "string",
  • "updated": "string",
  • "type": "string",
  • "consents": [
    ],
  • "preferences": [
    ]
}

Retrieves a UC config

Retrieves a UC config

Authorizations:
ucApiKey

Responses

Response samples

Content type
application/json
{
  • "configId": "string",
  • "customerId": "string",
  • "name": "string",
  • "domains": [
    ],
  • "privacyPolicyUrl": "string",
  • "privacyPolicyVersion": 0,
  • "processingTime": 0,
  • "processingUnit": "string",
  • "privacyProtocols": [
    ],
  • "jurisdictionLookup": "string",
  • "homepageUrl": "string",
  • "created": "string",
  • "updated": "string",
  • "helpUrl": "string",
  • "frameworks": [
    ],
  • "headings": {
    },
  • "paragraphs": {
    },
  • "links": {
    },
  • "primaryButtons": {
    },
  • "secondaryButtons": {
    },
  • "gpcSignalBanner": {
    },
  • "pageBackground": "string",
  • "published": "string",
  • "unpublishedPageId": 0,
  • "publishedPageId": 0,
  • "welcomePageEnabled": true
}

Create and insert a consent

Create and insert a consent

Authorizations:
ucApiKey
header Parameters
x-country-code-override
string

Valid ISO 3166-1 country code to override the country resolution based on the IP address.

x-region-code-override
string

Valid ISO 3166-2 region code to override the region resolution based on the IP address

Request Body schema: application/json
sessionToken
string

Optional session token returned by the create profile endpoint.

required
object
object (compliance)
required
Array of objects
attributes
required
object
origin
string
jurisdiction
string

Responses

Request samples

Content type
application/json
{
  • "sessionToken": "string",
  • "subject": {
    },
  • "compliance": {
    },
  • "actions": [
    ],
  • "attributes": { },
  • "origin": "string",
  • "jurisdiction": "string"
}

Create and insert a gpc consent

Create and insert a gpc consent

Authorizations:
ucApiKey
header Parameters
x-country-code-override
string

Valid ISO 3166-1 country code to override the country resolution based on the IP address.

x-region-code-override
string

Valid ISO 3166-2 region code to override the region resolution based on the IP address

Request Body schema: application/json
required
object
object (gpc-compliance)
attributes
required
object
jurisdiction
string

Responses

Request samples

Content type
application/json
{
  • "subject": {
    },
  • "compliance": {
    },
  • "attributes": { },
  • "jurisdiction": "string"
}

Response samples

Content type
application/json
{
  • "gpcActions": [
    ]
}

Merge subjects (an anonymous and a verified)

Merge subjects (an anonymous and a verified)

Authorizations:
osanoApiKey
header Parameters
content-type
required
string
Value: "application/json"

The payload is a valid serialized JSON object

Request Body schema: application/json
required
sourceSubjectId
required
string non-empty
targetSubjectId
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "sourceSubjectId": "string",
  • "targetSubjectId": "string"
}

Response samples

Content type
application/json
"string"

Verify a subject profile

Verify a subject profile

Authorizations:
osanoApiKey
header Parameters
content-type
required
string
Value: "application/json"

The payload is a valid serialized JSON object

Request Body schema: application/json
required
email
required
string <email> non-empty
code
required
string = 6 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "verifiedId": "string"
}

Sends a verification email to a subject

Sends a verification email to a subject

Authorizations:
ucApiKey
header Parameters
content-type
required
string
Value: "application/json"

The payload is a valid serialized JSON object

Request Body schema: application/json
required
email
required
string <email> non-empty

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Public endpoint for health check purposes

Public endpoint for health check purposes

Authorizations:
ucApiKey

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "version": "string",
  • "commit": "string",
  • "branch": "string"
}

Creates a token for UC

Creates a token for UC

Authorizations:
ucApiKey
Request Body schema: application/json
configId
string
customerId
string

Responses

Request samples

Content type
application/json
{
  • "configId": "string",
  • "customerId": "string"
}

Create profile verification code

Create profile verification code

Authorizations:
osanoApiKey
header Parameters
content-type
required
string
Value: "application/json"

The payload is a valid serialized JSON object

Request Body schema: application/json
required
email
required
string <email> non-empty

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "code": "string"
}

Create and insert a subject profile

Create and insert a subject profile

Authorizations:
osanoApiKey
query Parameters
resultType
string
Enum: "subject" "session"
header Parameters
content-type
required
string
Value: "application/json"

The payload is a valid serialized JSON object

Request Body schema: application/json
required
email
required
string <email> non-empty
profile
object

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "profile": { }
}