Skip to main content

API Documentation

API docs by Redocly

Unified Consent Core API (2.0.0)

Download OpenAPI specification:Download

📍 Regional Distribution
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.

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 except the health check (GET /) and token creation (POST /v2/token/create) 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 except GET / and POST /v2/token/create 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. The routes that create or update subject profiles (POST /v2/subjects/profile and POST /v2/subjects/profile/verification-code) require the Osano API key. All other routes, including POST /v2/subjects/merge, 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 those routes. For example:

curl --location 'https://uc.api.osano.com/v2/subjects/profile' \
--header 'x-osano-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "email": "person@example.com"
}'

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

Merging an anonymous subject

To keep an anonymous visitor's consents after they log in, call POST /v2/subjects/merge with the anonymous ID as sourceSubjectId and the verified ID as targetSubjectId:

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

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 the unified consent for a subject.

Retrieves the unified consent for a subject.

Authorizations:
ucApiKey
path Parameters
hashedSubjectId
required
string
query Parameters
configId
required
string non-empty
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": [
    ]
}

Retrieves all collections for a given configId based on jurisdiction

Uses the configId embedded in the Unified Consent API key to retrieve an aggregate 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. The response merges the configuration's default collection, the collections of the jurisdiction's parents and the jurisdiction's own collection, so 'us-ca' also returns the 'us' protocols. When nothing matches, the response has no collection.

Authorizations:
ucApiKey
query Parameters
jurisdiction
string
Examples:
  • jurisdiction=us -
  • jurisdiction=us-ca -
  • jurisdiction=fr -

A country code, optionally followed by more specific levels separated by '-', such as 'us', 'us-ca' or 'ca-qc'. Case-insensitive. Use a value from the jurisdictions array of the response.

type
string
Default: "published"
Enum: "published" "draft"

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 subject by id or from a valid session

Retrieves subject by id or from a valid session

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.

Responses

Response samples

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

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,
  • "smsVerificationEnabled": true,
  • "cuiTextCustomizations": [
    ]
}

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
required
object

Custom key/value attributes, e.g. { "platform": "Linux x86_64" }. ipAddress and userAgent are set by the API.

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)
required
object

Custom key/value attributes, e.g. { "platform": "Linux x86_64" }. ipAddress and userAgent are set by the API.

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

The anonymous subject id to merge from.

targetSubjectId
required
string non-empty

The verified subject id to merge into.

Responses

Request samples

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

Response samples

Content type
application/json
"string"

Verify a subject profile using Email

Verify a subject profile using Email

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
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"
}

Verify a subject profile using SMS

Verify a subject profile using SMS

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
phone
required
string non-empty
code
required
string = 8 characters
session
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "phone": "string",
  • "code": "stringst",
  • "session": "string"
}

Response samples

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

Get a subject profile

Get a subject profile

Authorizations:
ucApiKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "email": "string",
  • "subjectId": "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"
}

Send a verification text to a subject

Send a verification text 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
phone
required
string non-empty

Responses

Request samples

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

Public endpoint for health check purposes

Public endpoint for health check purposes

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

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
Default: "subject"
Enum: "subject" "session"

'subject' returns the verifiedId, 'session' returns a sessionId for the Consumer UI.

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

The payload is a valid serialized JSON object

Request Body schema: application/json

Requires email or phone.

Any of
email
required
string <email>
phone
string
profile
object

Responses

Request samples

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

Response samples

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