Partner API – Usercentrics Support - EN

Table of Contents

⚠️ Important: This part of the documentation is about the Partner API made for resellers/partners that want to configure the CMP via API.

Customers who want to implement the Usercentrics CMP on their website can find all the information in the following sections: CMP Version 2 | CMP Version 1

The Usercentrics Partner API is a simplified representation of a more complex internal system to favor simplicity and usability. If you encounter an unexpected behavior or a missing feature, please reach out to our support team.

The Usercentrics Partner API is a GraphQL-based API. GraphQL-based APIs have some significant differences from traditional REST-based architectures. However, once understood, GraphQL provides many benefits compared to a traditional approach. If you haven’t worked with GraphQL before, this short introduction should help you to understand the most important basics and to get started using our API easily.

GraphQL: the basics

The GraphQL query language is comparable with the JSON format with some extensions
It follows the “you get what you requested” approach. You have to define every property you want to get back as a result, however, it is guaranteed that you get back the exact data structure as requested
Use the Query statement to read data (comparable with GET in REST) and the Mutation statement to create or update data (comparable with POST and PUT in REST)
For all Mutations, the GraphQL API behaves like a “state machine”. In other words: the API will apply all identified differences between the database and your request to match the “state” you sent in. Two examples to clarify:
- The Usercentrics database stores your settings using 3 consentTemplates A,B and C. Sending in a Mutation request which only contains the firstUserInteraction in its argument will not change the consentTemplates data, as the Mutation does not contain the consentTemplates field. Alternatively, you can think about Mutations as "partial update" operations, as they will apply changes only to what was provided in the input and won't change the rest of the record.
- Especially important when working with list/arrays: Given the same example, but this time the Mutation contains a consentTemplates field with one entry Consent D. To match the “state” in the Mutation the API will delete the references to Consents A,B,C and will add Consent D to your setting. Having the “states” principle in mind is important here, because if you would’ve liked to keep the other Consent references you have to send the complete state (containing Consent A,B,C,D) to the API

For a complete introduction and a list of GraphQL clients compatible with your programming language, please refer to https://graphql.org .

Language Concept

You or your end-customer might need to support different languages on his/her website. The Usercentrics API supports creating/updating settings in different languages via the language field. When working with languages, please note the following:

The language field expects a language code in ISO 639-1 format (e.g. "de" for German)
The language of a translatable field (e.g. a category name) must match the language you specify in the language field
The system will always create an English setting for you, which is used as a fallback language. If other languages are required they need to be enabled explicitly.
Each language is represented as its setting document. Therefore you might retrieve the same settingId multiple times when fetching settings using some Query operation.

Environments

Usercentrics provides a Sandbox and Production API environments. The Sandbox will behave exactly like our production system but will not affect any production data as it stands as a completely isolated environment.

Sandbox

GraphQL POST endpoint: https://partner.usercentrics-sandbox.eu/graphql
Playground UI & Documentation: https://partner.usercentrics-sandbox.eu

Production

GraphQL POST endpoint: https://partner.usercentrics.eu/graphql
Playground UI & Documentation: https://partner.usercentrics.eu

Playground and Documentation

The purpose of this document is to provide a first introduction to the Usercentrics API and the most important “GraphQL nodes”. In the Playground you will always find the latest documentation about the available nodes and data types. This interactive documentation provides many more details than what can be included in this document. Please note the Data Types which might re-occur at different positions in the GraphQL structure. The same type ensures you the same sub-data-structure. usercentrics

Authorization

Before sending any requests to the Usercentrics Partner API you need to authenticate the user account you are interacting with. For this, you will need a secret Partner-API token (received from Usercentrics’ Support) and a unique identifier for the user (best practice: The format should explicitly be an EMAIL String).

The API will return a new unique User-Token. You need to provide this token as an HTTP authorization header for all API calls that you are going to make on behalf of this user. User-Tokens are valid for 8 hours.

Security Notice
Your secret Partner-API token should always be kept private! Anyone owning that token can authenticate user accounts against the Usercentrics API under your identity.

Example Request

query {
  authenticate(apiToken: "secret-api-token", user: "user@company.org")
}

Example Response

{
  "data": {
    "authenticate": "Bearer RXhhbXBsZSBUb2tlbgo..."
  }
}

Example Request HTTP headers

POST /graphql HTTP/1.1
Host: partner.usercentrics-sandbox.eu
Connection: keep-alive
Content-Length: 111
accept: */*
Origin: https://partner.usercentrics-sandbox.eu
authorization: Bearer RXhhbXBsZSBUb2tlbgo…
[...]

Example Request in the playground usercentrics

Configuring the CMP

The following section covers the main operations that can be performed through this API, such as creating and updating settings. However, because settings are a complex structure, in depth documentation about specific properties or use cases are documented in Configure the CMP via API page.

Creating new settings

To create new settings for an end-user, the only required parameters are the data controller (the owner of the website e.g. company name) and the language code which defines in which language the Usercentrics UI will be displayed later. For all other not given parameters a default value will be set.

Example Request

mutation {
  setting(
    dataController: "Webshop GmbH"
    language: "en"
  ) {
     settingsId
     language
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "HkvOYLyME"
      "language": "en"
    }
  }
}

Creating new settings with custom categories

All Data Processing Services are displayed in a category. If you don’t specify a custom list of categories, the following default categories are created for you:

categorySlug (id)	label (example english)	isEssential
essential	Essential	true
functional	Functional	false
marketing	Marketing	false

However, it is also possible to define customized categories:

Example Request

mutation {
  setting(
    language: "en"
    categories: [
      {categorySlug:"essential", label:"Essentiell", isEssential: true}
      {categorySlug:"payment", label:"Payment Service", isEssential: true}
      {categorySlug:"marketing", label:"Marketing", isEssential: false}
    ]
  ) {
    settingsId
    categories  {
      categorySlug
    }
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "PFij5LnJo",
      "categories": [
        {
          "categorySlug": "essential"
        },
        {
          "categorySlug": "payment"
        },
        {
          "categorySlug": "marketing"
        }
      ]
    }
  }
}

Creating a setting for a specific legislation

Settings can be set up for specific use cases specifying a "setting template" (Not to be confused with a Consent Template, which represents Data Processing Service (DPS)). This template will ensure that correct default values are set to the new configuration. A template is a combination of a type of setting (web or app) and a legislation, e.g. TCF2, CCPA, etc. For example WEB_TCF2 or APP_CCPA. All possible values for templates are defined in the SettingTemplateString ENUM, which also indicates the legislations supported. Choosing a WEB_* template will apply default texts targeted for the web platform, while APP_* templates will apply default texts rephrased to better fit the mobile world. If no template is explicitly defined, the default value is set to WEB_GDPR.

Example Request

mutation {
  setting(
    dataController: "Webshop GmbH"
    language: "en"
    options: {
      template: WEB_TCF2
    }
  ) {
     settingsId
     tcf2Enabled
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "XYZ",
      "tcf2Enabled": true
    }
  }
}

Updating settings

The operation to update a setting is the same one used to create new settings, the only difference is that you provide an existing settingsId as an additional input parameter.

Example Request

mutation {
  setting(
    language: "de"
    settingsId: "HkvOYLyME"
    firstUserInteraction: STANDARD_BANNER
    consentTemplates: [
      {
        templateId: "S1pcEj_jZX"
        version: "1.2.3"
        categorySlug: "essential"
      }
    ]
  ) {
      settingsId
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "HkvOYLyME"
    }
  }
}

Reminder
As described in the introduction, please be reminded to the “state-machine behavior” of GraphQL. For all complex types like consentTemplates, categories, etc. all non-mentioned elements will be removed from the Setting!

Adding vendors to TCF settings

The Global Vendors List (GVL) can be found here. Additional information about vendors listed in the main list is hosted here.

Once the GVL has been inspected and the relevant vendors for your setting found, you can add them to the list through the setting mutation while creating a setting as described above or while updating it:

Example Request

mutation {
  setting(
    dataController: "Webshop GmbH"
    language: "en"
    options: {
      template: WEB_TCF2
    },
    tcf2: {
      selectedVendorIds: [4]
    }
  ) {
     settingsId
     tcf2Enabled
     tcf2 {
       selectedVendorIds
     }
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "XYZ",
      "tcf2Enabled": true,
      "tcf2": {
        "selectedVendorIds": [ 4 ]
      }
    }
  }
}

Enabling multiple languages

The default CMP language is English ("en"). The property languagesAvailable explicitly defines in which languages the CMP will be shown to the end user. The language switch will only show the languages which are configured in languagesAvailable. The property editableLanguages defines languages that you can configure, but are not visible to the end user.

Both properties can be configured while creating or updating a setting.

Example Request

mutation {
  setting(
    language: "de",
    editableLanguages: ["en", "de"],
    languagesAvailable: ["en", "de"], # <---- enable english and german
    bannerMessage: "Das ist ein Beispiel"
  ) {
    settingsId
    editableLanguages
    languagesAvailable
    bannerMessage
  }
}

Example Response

{
  "data": {
    "setting": {
       "settingsId": "XYZ",
       "editableLanguages": [
         "en",
         "de"
       ],
       "languagesAvailable": [
         "en",
         "de"
       ],
       "bannerMessage": "Das ist ein Beispiel"
    }
  }
}

Adjusting setting styles

This operation modifies the styles of a setting. The language parameter is mandatory, the changes are already propagated to all language documents.

Example Request

mutation {
    setting(
       settingsId: "8yKTozwk",
       language: "en",
       styles: {
        btnAcceptBgColor: "123642", # change accept button background color
        cornerModalHeaderBgColor: "444444" # change the modal header background color
       }
    ) {
      styles{
          btnPrivacyButtonActiveSize
          btnDenyBgColor
          btnAcceptBgColor
          cornerModalHeaderBgColor
      }
     }
}

Example Response

{
  "data": {
    "setting": {
      "styles": {
        "btnPrivacyButtonActiveSize": 100,
        "btnDenyBgColor": "3ba1db",
        "btnAcceptBgColor": "123642",
        "cornerModalHeaderBgColor": "444444"
      }
    }
  }
}

Updating a text in a specific field for different languages

The setTranslationForSettingsField operation updates the value of a specific field in a setting for different languages without automatic translation.

parentField indicates the first level of the property to be updated. e.g. categories.

Some few root-level fields are allowed to be updated directly, in that case, the parentField should be "”.
childField indicates the second level of the property to be updated (a sub-field of the parent field). e.g. description.
childId must be provided in the childField happens to be an array. It will be used do identify which element in the array must be updated. Example Requests

Update label translations in English and German ("en" and "de")

mutation {
  setTranslationForSettingsField(
    parentField: "labels"
    childField: "btnDeny"
    settingsId: "HkvOYLyME"
    childId: null
    translation: { en: "Labels btnDeny message in English", de: "Labels btnDeny Nachricht auf Deutsch" }
  ) {
    settingsId
    language
    version
    labels {
      btnDeny
    }
  }
}

Update a specific template (with exampleTemplateId) description in consentTemplated in English and German ("en" and "de")

mutation {
  setTranslationForSettingsField(
    parentField: "consentTemplates"
    childField: "description"
    settingsId: "HkvOYLyME"
    childId: "exampleTemplateId"
    translation: { en: "Description", de: "Beschreibung" }
  ) {
    settingsId
    language
    version
    consentTemplates {
      templateId
      description
    }
  }
}

Update bannerMessage only in German ("de")

mutation {
  setTranslationForSettingsField(
    settingsId: "HkvOYLyME",
    parentField: "",
    childField: "bannerMessage",
    translation: {
      de: "Banner Nachricht auf Deutsch"
    }) {
      settingsId
      bannerMessage
      language
    }
}

Example Response

{
  "data": {
    "setTranslationForSettingsField": [
      {
        "settingsId": "HkvOYLyME",
        "bannerMessage": "Banner Nachricht auf Deutsch",
        "language": "de"
      },
      {
        "settingsId": "HkvOYLyME",
        "bannerMessage": "",
        "language": "en"
      }
    ]
  }
}

Providing setting access to other users

Adding users to a setting enables them to log into Admin Interface and configure the CMP on their own.

Important
Please be aware that the API User is listed within the users property value per default. If the API User is removed, access to that Setting via API is lost.
API Users can be recognized by the "#" in their account. The API User is added when the Setting was created via API. The Text after the "#" depends on the "user"-String used during Authentication.

Example Request

This request adds two new users to the setting (personA and personB) while still keeping access to the API User (testpartner#user123)

mutation {
  setting(language: "en", users: ["testpartner#user123","personA@customer.com","personB@customer.com"]) {
    settingsId
    users
  }
}

Example Response

{
  "data": {
    "setting": {
      "settingsId": "HkvOYLyME",
      "users": [
        "testpartner#user123"
        "personA@customer.com"
        "personB@customer.com"
      ]
    }
  }
}

Listing available Data Processing Services (Templates)

Example Request

query {
  consentTemplates {
    templateId
    version
    dataProcessors
  }
}

Example Response

{
  "data": {
    "consentTemplates": [
      {
        "templateId": "S1pcEj_jZX",
        "version": "8.2.1",
        "dataProcessors": [
          "Google Maps"
        ]
      },
      {
        "templateId": "S1_9Vsuj-Q",
        "version": "8.2.1",
        "dataProcessors": [
          "Google AdWords"
        ]
      }
    ]
  }
}

Listing settings accessible to the authenticated user

The settings query can list all settings objects that the user has read access to.

Example Request

query {
  settings {
    settingsId
    language
    firstUserInteraction
    consentTemplates {
      template {
        templateId
        dataProcessors
      }
    }
  }
}

Example Response

{
  "data": {
    "settings": [
      {
        "settingsId": "HkvOYLyME",
        "language": "en",
        "consentTemplates": [
          {
            "template": {
              "templateId": "S1pcEj_jZX",
              "dataProcessors": [
                "Google Maps"
              ]
            }
          },
          {
            "template": {
              "templateId": "S1_9Vsuj-Q",
              "dataProcessors": [
                "Google AdWords"
              ]
            }
          }
        ]
      },
      {
        "settingsId": "HkvOYLyME",
        "language": "de",
        "consentTemplates": [
          {
            "template": {
              "templateId": "S1pcEj_jZX",
              "dataProcessors": [
                "Google Maps"
              ]
            }
          },
          {
            "template": {
              "templateId": "S1_9Vsuj-Q",
              "dataProcessors": [
                "Google AdWords"
              ]
            }
          }
        ]
      }
    ]
  }
}

Fetching a specific setting by settingsId

If you know the settingsId and language of the setting you want to retrieve, you can use the setting (singular) endpoint instead. This endpoint behaves exactly like the settings (plural) endpoint, but always returns exactly one setting instead of a list of settings and languages.

Retrieving the Usercentrics CMP script tag

You can find more information on the latest Usercentrics CMP script tag for your customers in Browser CMP.

Accessing the Usercentrics Admin Interface

If you want to allow your customers to access their CMP via Usercentrics Admin Interface, please follow the below instructions to give the best experience to your customers.

Add the Users and Emails that shall get access: Add Users to a Setting
Set the correct Price Package Id: Price Packages
Specify the Domains on which the CMP will be integrated: Domain Whitelisting
Activate the latest CMP Version (V2) of the Admin Interface: Set property selectedSettingsAppVersion:V2
Assign a Data Controller who manages this configuration: Data Controller

Assigning a setting to a company

The operation attachSettingToCustomer attaches an existing setting to a Company/Customer provided both ids

Example Request

query {
  attachSettingToCustomer(customerId: "NxoH8s-Uy", settingsId: "HkvOYLyME")
}

Example Response

{
  "data": {
    "attachSettingToCustomer": true
  }
}

Removing a setting from given company

(does not delete the setting itself)

The operation detachSettingFromCustomer removes an existent setting from a company/customer provided both ids.

Example Request

query {
  detachSettingFromCustomer(customerId: "NxoH8s-Uy", settingsId: "HkvOYLyME")
}

Example Response

{
  "data": {
    "detachSettingFromCustomer": true
  }
}

Deleting settings

The operation deleteSetting can be used to delete a setting. The settingsId is mandatory.

Example Request

mutation {
  deleteSetting (settingsId: "HkvOYLyME")
}

Example Response

{
  "data": {
    "deleteSetting": "setting deleted successfully",
  }
}

Session and Reporting

The API includes two endpoints that can be used to fetch Session and Usage data for certain Settings.

Important
While the impact on our systems is normal it’s nothing that should run for every setting on everyday basis, due to the number of requests/data.

Endpoint sessionsBySettings returns the session count for a particular setting-id daily for a specific timeframe. The maximum timeframe allowed is 90 days.

Should only be used when you are explicitly checking your session (e.g. in an overview). It's best if it's cached on a daily basis, since we only update the values once a day. Although the individual query isn’t very resource-intensive, it becomes so if a Partner runs it 10k times a day (due to 10k settings).
Endpoint totalSessionsForAllSettingsByTimeframe returns the accumulated session count for all setting-ids across the specified timeframe. Maximum Timeframe 60 days.

The use case for this endpoint is rather to do e.g. monthly reports/billing and as such should rather run on a Monthly/Weekly basis, but not every day.

Example Request

query {
    TotalSessionsForAllSettingsByTimeframe(
       from: "2022-01-01",
       to: "2022-01-31"
    ) {
       sessions,
       settingsId
      }
}

Example Response

{
  "data": {
    "totalSessionsForAllSettingsByTimeframe": [
      {
        "sessions": 12521,
        "settingsId": "ABCDEF111"
      },
      {
        "sessions": 195,
        "settingsId": "ABCDEF222"
      }
    ]
  }
}

Common error messages and resolutions

Format is Authorization: Bearer [token] (Code: UNAUTHENTICATED)

Please check if you are sending the HTTP header authorization in the format Bearer eyJhbGciO…. This token can be retrieved using the authorization endpoint described in this documentation.

Field "x" of type "X" must have a selection of subfields. Did you mean "x { ... }"?

In most cases, GraphQL requires you to specify the data you want to have returned from the API. This is also the case for mutation operations. Therefore you MUST specify at least one return value after the mutation parameters, e.g. mutation { setting(paramA: "123") {settingsId} }

You will also see this error when requesting a non-scalar data type (e.g. consentTemplates in settings) and not defining any sub-parameter.

Field "x" argument "y" of type "String!" is required, but it was not provided.

If a GraphQL node supports arguments (e.g. setting()) some of the arguments might be required. You can identify required arguments in the playground documentation by an exclamation mark next to the type. usercentrics