API Documentation

• Introduction
• Authentication
  • Osano API key
  • Unified Consent API key
• getRetrieves the unified consent for a subject.
• getChecks whether a subject has given consent in a co
• getRetrieves all collections for given configIds
• getRetrieves a collection
• getRetrieves a UC config
• postCreate and insert a consent
• postCreate and insert a gpc consent
• postMerge subjects (an anonymous and a verified)
• postVerify a subject profile
• postSends a verification email to a subject
• getPublic endpoint for health check purposes
• postCreates a token for UC
• postCreate profile verification code
• postCreate and insert a subject profile

API docs by Redocly

Unified Consent Core API (2.0.0)

Download OpenAPI specification:Download

Introduction

This is the Unified Consent Core API. Use of this API is subject to the Unfied Consent Core API Terms of Service.

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 key

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

https://developers.osano.com/v2/consents/unified/{subjectRef}

Response samples

• 200

Content type

application/json

{

• "unifiedConsent": {

  • "subjectId": "string",
  • "brandId": "string",
  • "channelIds": [

    • "string"

    ],
  • "compliance": {

    • "privacyPolicy": {

      • "version": "string",
      • "url": "string"

      },
    • "gpc": 1

    },
  • "actions": [

    • {

      • "target": "string",
      • "vendor": "string",
      • "action": "string"

      }

    ],
  • "attributes": null,
  • "lastUpdateDate": "string",
  • "lastConflictDate": "string"

  },
• "conflicts": [

  • {

    • "type": "string",
    • "resolution": "string",
    • "actionsInConflict": [

      • {

        • "target": "string",
        • "vendor": "string",
        • "action": "string",
        • "consentId": "string",
        • "channelId": "string",
        • "createdAt": "string"

        }

      ]

    }

  ]

}

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

https://developers.osano.com/v2/consents/check/{subjectId}

Response samples

• 200

Content type

application/json

{

• "exists": true

}

Retrieves all collections for given configIds

Retrieves all collections for given configIds

Authorizations:

ucApiKey

query Parameters

jurisdiction	string
type	string

Responses

https://developers.osano.com/v2/collections

Response samples

• 200

Content type

application/json

{

• "jurisdictions": [

  • "string"

  ],
• "collection": {

  • "collectionId": "string",
  • "name": "string",
  • "frameworks": [

    • "string"

    ],
  • "configIds": [

    • "string"

    ],
  • "jurisdiction": "string",
  • "created": "string",
  • "updated": "string",
  • "type": "string",
  • "consents": [

    • { }

    ],
  • "preferences": [

    • { }

    ]

  }

}

Retrieves a collection

Retrieves a collection

Authorizations:

ucApiKey

path Parameters

collectionId required

string

Responses

https://developers.osano.com/v2/collections/{collectionId}

Response samples

• 200

Content type

application/json

{

• "collectionId": "string",
• "name": "string",
• "frameworks": [

  • "string"

  ],
• "configIds": [

  • "string"

  ],
• "jurisdiction": "string",
• "created": "string",
• "updated": "string",
• "type": "string",
• "consents": [

  • { }

  ],
• "preferences": [

  • { }

  ]

}

Retrieves a UC config

Retrieves a UC config

Authorizations:

ucApiKey

Responses

https://developers.osano.com/v2/config

Response samples

• 200

Content type

application/json

{

• "configId": "string",
• "customerId": "string",
• "name": "string",
• "domains": [

  • "string"

  ],
• "privacyPolicyUrl": "string",
• "privacyPolicyVersion": 0,
• "processingTime": 0,
• "processingUnit": "string",
• "privacyProtocols": [

  • {

    • "privacyProtocolId": "string",
    • "name": "string",
    • "type": "string",
    • "integrations": [

      • {

        • "connection": {

          • "label": "string",
          • "value": "string"

          },
        • "operation": {

          • "label": "string",
          • "value": "string"

          },
        • "additionalFields": true,
        • "fields": { },
        • "protocolValue": [

          • "string"

          ]

        }

      ],
    • "enabled": true,
    • "trigger": "string"

    }

  ],
• "jurisdictionLookup": "string",
• "homepageUrl": "string",
• "created": "string",
• "updated": "string",
• "helpUrl": "string",
• "frameworks": [

  • "string"

  ],
• "headings": {

  • "fontFamily": "string",
  • "color": "string",
  • "backgroundColor": "string"

  },
• "paragraphs": {

  • "fontFamily": "string",
  • "color": "string",
  • "backgroundColor": "string"

  },
• "links": {

  • "fontFamily": "string",
  • "color": "string",
  • "backgroundColor": "string"

  },
• "primaryButtons": {

  • "fontFamily": "string",
  • "color": "string",
  • "backgroundColor": "string"

  },
• "secondaryButtons": {

  • "fontFamily": "string",
  • "color": "string",
  • "backgroundColor": "string"

  },
• "gpcSignalBanner": {

  • "fontFamily": "string",
  • "color": "string",
  • "backgroundColor": "string"

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

https://developers.osano.com/v2/consents

Request samples

• Payload

Content type

application/json

{

• "sessionToken": "string",
• "subject": {

  • "verifiedId": "string",
  • "anonymousId": "string"

  },
• "compliance": {

  • "privacyPolicy": {

    • "version": "string",
    • "url": "string"

    },
  • "gpc": 1

  },
• "actions": [

  • {

    • "target": "string",
    • "vendor": "string",
    • "action": "string"

    }

  ],
• "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

https://developers.osano.com/v2/consents/gpc

Request samples

• Payload

Content type

application/json

{

• "subject": {

  • "verifiedId": "string",
  • "anonymousId": "string"

  },
• "compliance": {

  • "gpc": 1

  },
• "attributes": { },
• "jurisdiction": "string"

}

Response samples

• 201

Content type

application/json

{

• "gpcActions": [

  • {

    • "target": "string",
    • "vendor": "string",
    • "action": "string",
    • "jurisdiction": "string"

    }

  ]

}

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

https://developers.osano.com/v2/subjects/merge

Request samples

• Payload

Content type

application/json

{

• "sourceSubjectId": "string",
• "targetSubjectId": "string"

}

Response samples

• 200

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

https://developers.osano.com/v2/subjects/profile/verify

Request samples

• Payload

Content type

application/json

{

• "email": "user@example.com",
• "code": "string"

}

Response samples

• 200

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

https://developers.osano.com/v2/subjects/send-code

Request samples

• Payload

Content type

application/json

{

• "email": "user@example.com"

}

Public endpoint for health check purposes

Public endpoint for health check purposes

Authorizations:

ucApiKey

Responses

https://developers.osano.com/

Response samples

• 200

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

https://developers.osano.com/v2/token/create

Request samples

• Payload

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

https://developers.osano.com/v2/subjects/profile/verification-code

Request samples

• Payload

Content type

application/json

{

• "email": "user@example.com"

}

Response samples

• 201

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

https://developers.osano.com/v2/subjects/profile

Request samples

• Payload

Content type

application/json

{

• "email": "user@example.com",
• "profile": { }

}