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

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 a template metadata field (third-party integration / signaling ID)

If you need to integrate consent templates with third-party systems (e.g., analytics/ads platforms, tag managers, or proprietary tooling), you can attach a template metadata field to store an external signaling ID (or any other integration identifier). This makes it easier to map a template in your system to the corresponding entity in the third-party service.

Example Request

mutation {
  mutateTemplates(
    settingsId: "HkvOYLyME"
    language: "en"
    consentTemplates: {
      updated: [{
        templateId: "S1pcEj_jZX",
        metadata: "example metadata value"
      }]
    }
  ) {
      consentTemplates {
        templateId
        metadata
      }
  }
}

Example Response

{
  "data": {
    "mutateTemplates": {
      "consentTemplates": [
        {
          "templateId": "S1pcEj_jZX",
          "metadata": "example metadata value"
        }
      ]
    }
  }
}

Reminder
We recommend the mutateTemplates operation as one way to add/update the attribute.
You also can use the setting operation. This operation expects the full list of consent templates with all the fields, all non-mentioned elements will be removed from the Setting. Make sure you include all templates you want to keep when updating, not only the one you're changing.

Updating scan configuration¶

The upsertScanConfiguration mutation allows you to configure automated scanning for a setting — including scan frequency, the list of domains to scan, and optional HTTP query parameters to inject into scan requests.

Example Request

mutation {
  upsertScanConfiguration(
    settingsId: "ABCDEF1234"
    scanFrequency: WEEKLY
    domainScanConfigurations: [
      {
        domainUrl: "https://mywebsite.com"
        httpRequestInjections: {
          queryParameters: [{ key: "uc_test", value: "true" }]
          scope: AllPages
        }
      }
    ]
  ) {
    configurationId
    domainScanConfigurations {
      domainUrl
      domainScanConfigurationIdentifier
      httpRequestInjections {
        queryParameters {
          key
          value
        }
        scope
      }
    }
  }
}

Example Response

{
  "data": {
    "upsertScanConfiguration": {
      "configurationId": "scan-cfg-xyz",
      "domainScanConfigurations": [
        {
          "domainUrl": "https://mywebsite.com",
          "domainScanConfigurationIdentifier": "dom-cfg-abc",
          "httpRequestInjections": {
            "queryParameters": [{ "key": "utm_content", "value": "buffercf3b2" }],
            "scope": "AllPages"
          }
        }
      ]
    }
  }
}

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

Deleting settings

To delete a setting simply provide the settingsId and set the delete flag to true:

Example Request

mutation {
  setting(
    settingsId: "HkvOYLyME"
    delete: true
  ) {
    settingsId
  }
}

Example Response

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