--- title: "Configure the CMP via API" slug: "configure-a-cmp-via-api" updated: 2026-11-17T04:32:59Z published: 2026-11-17T04:32:59Z canonical: "usercentrics.com/configure-a-cmp-via-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://usercentrics.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Configure the CMP via API This API is made for resellers that want to enable the CMP configuration via their own frontend. Read the [Partner API](/v1/docs/graphql-basics) documentation prior to this article if you are not familiar with our API structure yet. ## Introduction Below you will find a couple of features that our CMP offers and how those can be managed with the Partner API. ## Configuration ### Data controller The data controller is the person or legal entity that is responsible for the domain entered below. This role can be shared by more than one person, company or other organization. **Example Request** ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    dataController: "John Doe"  ) { settingsId } } ``` ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(153).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=tTEtUM4LAY9%2B%2BrFMo1U8Zj1g1UyGL8fC2ngA6DRn%2FbM%3D) ### Imprint and privacy URLs The CMP allows you to adjust imprint and privacy URLs. They will be shown in the layers of the CMP. You can specify absolute URLs and relative paths. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    imprintUrl: "http://mywebsite.com/imprint"    privacyPolicyUrl: "http://mywebsite.com/privacypolicy"  ) { settingsId } } ``` **Notes** This feature is on language level. If `disableAutoTranslate` is set to *true* (default *false*), the URLs will be set only for the specific language. If `disableAutoTranslate` is set to *false*, the URLs will be set across all enabled languages. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(154).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=WKNNQTSaSPYpESwggq8%2Fjew0i1MrEBtTRC169lrbNzA%3D) ### Banner message: predefined message The banner message appears in first layer. A predefined banner message in all languages will be set per default. The values will always be set when a new setting is created or a new language is added. If you modified the standard message, you can reset the value by setting `bannerMessage` to *null*. | Language | value | | --- | --- | | en | This site uses third-party website tracking technologies to provide and continually improve our services, and to display advertisements according to users' interests. I agree and may revoke or change my consent at any time with effect for the future. | | de | Diese Seite nutzt Website Tracking-Technologien von Dritten, um ihre Dienste anzubieten, stetig zu verbessern und Werbung entsprechend der Interessen der Nutzer anzuzeigen. Ich bin damit einverstanden und kann meine Einwilligung jederzeit mit Wirkung für die Zukunft widerrufen oder ändern. | | fr | Ce site utilise des technologies de tracking de sites Web tiers pour fournir et améliorer continuellement nos services et pour afficher des publicités en fonction des intérêts des utilisateurs. J'accepte et je peux révoquer ou modifier mon consentement à tout moment avec effet pour l'avenir. | | es | Este sitio utiliza tecnologías de tracking de sitios web de terceros para proporcionar y mejorar continuamente nuestros servicios, y para mostrar anuncios de acuerdo con los intereses de los usuarios. Acepto y puedo revocar o cambiar mi consentimiento en cualquier momento con efecto para el futuro. | | it | Questo sito utilizza tecnologie di tracciamento di siti Web di terze parti per fornire e migliorare continuamente i nostri servizi e per visualizzare annunci pubblicitari in base agli interessi degli utenti. Sono d'accordo e posso revocare o modificare il mio consenso in qualsiasi momento con effetto per il futuro. | ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    bannerMessage: null  ) { settingsId } } ``` **Notes** This feature is on language level. If `disableAutoTranslate` is set to *true* (default *false*), the banner message will be auto-translated and set for every language. ### Banner message: custom message A custom banner message can be adjusted. The message can be set for an individual language or set across all languages by using auto-translate feature. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    bannerMessage: "This message will be translated and set for all languages"  ) { settingsId } } ``` ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    bannerMessage: "This message will only apply to EN banners"    disableAutoTranslate: true  ) { settingsId } } ``` **Notes** This feature is on language level. If `disableAutoTranslate` is set to *true* (default *false*), the banner message will be auto-translated and set for every language. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(155).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=aYGHkngF09sQ8zhXHGzJUJurJVj2GNen5V4EnJMti6I%3D) ### Price packages Price packages are connected to a set of features and correspond to individual plans. A price package should always be applied. They are used to enforce limitations and are relevant for activating and exposing of features within the PartnerAPI and Admin Interface. Price package identifiers are generated and maintained by Usercentrics. | Plan | PricePackageId | | --- | --- | | Standard | khcXQCLZi | | Business | gbXCTitO7 | | Enterprise | uKtA3w_HZ | ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    featureConfig: {      pricePackageId: "gbXCTitO7" # Activating Usercentrics Business Plan    }  ) { settingsId } } ``` **Notes** If no pricing package is defined, no limitation is applied. ### Reshow policy The reshow policy defines under which circumstances the CMP banner should be shown to the user again. Depending on the country, different regulations may apply. **We strongly recommend to set at least** `Major`. | Value | Description | | --- | --- | | Major | Legally relevant changes, e.g. Data Controller, Data Scopes, adding new Services. | | Minor | Changes that do not effect Services or the data processing. | | Patch | Appearance or other small changes. | You can apply multiple values. You can apply no value (default), in that case the banner will never be shown again. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    showInitialViewForVersionChange: ["Major"]  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The default value `showInitialViewForVersionChange` is *[""]* (empty). ## Appearance ### Custom brand color The brand color is used to create a custom color palette for your Consent Management Platform. The expected value is required to be in HEX without leading #(hash)-character. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    customization: { color: { primary: "ff0000" } }  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. Secondary colors will be automatically added based on your brand color to ensure visibility and accessibility. The default value `customization { color { primary } }` is *0045A5* ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(157).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=hHlRjQUhkoNrLrad7604DwkDTaGk2ehmN4bfxTa7mJ0%3D) ### Custom brand logo Specify the URL to a logo that will be displayed in the top left corner of both layers. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    customization: { logoUrl: "https://mydomain.com/logo.png" }  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. Secondary colors will be automatically added based on your brand color to ensure visibility and accessibility. The default value `customization { logoUrl }` is empty *""*. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(158).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=5Fh1Ea0qSyk6TnFfHcboky8ZCjD77Hm%2FiMZO%2B7hvbHk%3D) ### Font family Specify a font family that will be used in both layers. You can specify predefined fonts or use customized fonts. It is necessary to have the relevant font files on the website in order for custom fonts to work. | Standard Fonts | | --- | | helvetica | | verdana | | georgia | | arial | ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    customization: { font: { family: "verdana" } }  ) { settingsId } } ``` This feature is on setting level. The value will be automatically set across all languages. The default value `customization { font { family } }` is *BlinkMacSystemFont,-apple-system,Segoe UI,Roboto,Oxygen-Sans,Ubuntu,Cantarell,Fira Sans,Droid Sans,Helvetica Neue,Helvetica,Arial,sans-serif*. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(159).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=2Qstw%2FpenAjZ1z5tsDo8xwe7cX%2BmdiSg7dSZMOP30gw%3D) ### Font size Specify a font size that will be used in both layers. Any value will be represented in px unit. We recommend to only allow certain sizes to ensure visibility and accessibility. | Standard Sizes | | --- | | 12 | | 14 (Default) | | 16 | | 18 | ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    customization: { font: { size: "12" } }  ) { settingsId } } ``` This feature is on setting level. The value will be automatically set across all languages. The default value `customization { font { size } }` is *14*. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(160).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=CKJZtaHeqMgTtdTdrn82gUv8q3dKcbrD6qeRdEqPPtM%3D) ### First layer layout: privacy banner The first layer is displayed to the user when the website / app is accessed for the very first time (without any preexisting consent information) and contains all information that must be disclosed to the user in order to obtain a valid consent. The "Privacy Banner" is shown as a sticky-footer on the clients website. **Example Request** ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    firstLayer:    {        variant: BANNER    }  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The default value of `firstLayer { variant }` is *BANNER* ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(161).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=sfFJArHOosV%2F4nLA2qEMyJYuxghHGxzaaJaKeJPx%2FTc%3D) ### First layer layout: privacy wall The first layer is displayed to the user when the website / app is accessed for the very first time (without any preexisting consent information) and contains all information that must be disclosed to the user in order to obtain a valid consent. The "Privacy Wall" is shown as a horizontally and vertically centered element on the clients website. **Example Request** ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    firstLayer:    {        variant: WALL    }  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The default value of `firstLayer { variant }` is *BANNER* ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(162).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=mt1v2DZ3hG1UzxZ%2Fnazi1PKnE8b%2FCqOF%2F3ccS0biT%2Fc%3D) ### Second layer layout: privacy settings center The second layer contains detailed information about the integrated Data Processing Services and Categories. It enables the user to view current privacy settings and to adapt them on a granular level at any time The "Privacy Settings Center" is shown as a horizontally and vertically centered element on the clients website. **Example Request** ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    secondLayer:    {        variant: CENTER    }  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The default value of `secondLayer { variant }` is *CENTER* ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(163).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=LhqRC9gLrOa5UsTdSFjCAb8niVDfHJFMfOHHhlokH7o%3D) ### Second layer layout: privacy settings side The second layer contains detailed information about the integrated Data Processing Services and Categories. It enables the user to view current privacy settings and to adapt them on a granular level at any time The "Privacy Banner" is shown as a right-side pinned element on the clients website. **Example Request** ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    secondLayer:    {        variant: SIDE    }  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The default value of `secondLayer { variant }` is *CENTER* ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(164).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=DazaaX3Nh0R4iMqqdzm%2BqxlqhElLMbrq%2FNhiX9qBfH4%3D) ### Privacy trigger: privacy button The privacy button is a visual element that will be placed on the bottom of the clients website. Usercentrics provides a couple of predefined button icons. Below you will find the links to the respective images. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    privacyButtonIsVisible: true    buttonPrivacyOpenIconUrl: "https://img.usercentrics.eu/misc/icon-fingerprint.svg"  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The value `privacyButtonIsVisible` defines whether a privacy button will be shown *true* or not *false*. The value `buttonPrivacyOpenIconUrl` defines which button icon will be displayed. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(165).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=xI3mUjRE9lMhqNXMpPowzFh%2BObqDogpwhlDS4vbPeI4%3D) ### Privacy trigger: privacy link The privacy link gives your users access to their current privacy settings (i.e. second layer). The link must be placed onto the website. Enabling privacy link implies deactivating privacy button. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    privacyButtonIsVisible: false  ) { settingsId } } ``` Include the following link into the website in order for your users to be able to change their privacy settings. ```plaintext Privacy Settings ``` The default value `privacyButtonIsVisible` is *true*. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(166).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=YxkEJSZ3rTBfGuXutJ57QsZopAj3dO2e5TSwYCXqE2E%3D) ### Privacy button: predefined icons Usercentrics provides a couple of predefined button icons. Below you will find the links to the images. | Name | Icon URL | | --- | --- | | Fingerprint | https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/icon-fingerprint.svg | | Settings | https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/icon-settings.svg | | Security | https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/icon-security.svg | ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    privacyButtonIsVisible: true    buttonPrivacyOpenIconUrl: "https://img.usercentrics.eu/misc/icon-security.svg"  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(167).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=lkoXX7GKyZ1wUjvTSRitef1bJg3YLMWdbrgcPzKDzUc%3D) ### Privacy button: custom icons You can specify a custom Icon Url that will be used to display the privacy button. ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    buttonPrivacyOpenIconUrl: "https://mydomain.com/privacy_icon.png"  ) { settingsId } } ``` **Notes** This feature is on setting level. The value will be automatically set across all languages. The default value of `buttonPrivacyOpenIconUrl` is *https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/icon-fingerprint.svg*. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(168).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=lsYCHGUXh%2BD81DgFU0ASP1AJ5XGPJBAZqBIo0%2B2zOY8%3D) ### Privacy button: position (left / right position) The privacy button can be positioned at bottom left and bottom right. | Position | value | | --- | --- | | left | bl | | right | br | ```plaintext mutation {  setting(    settingsId: "ABCDEF1234"    language: "en"    buttonDisplayLocation: "br"  ) { settingsId } } ``` The default value `buttonDisplayLocation` is *bl*. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(169).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=VX%2BePCnBF%2Bu8tMxeblt0wfkxDeZjl%2B8bZj2NqFjDeEQ%3D) ### Background overlay for layers The background overlay adds a gray transparent container above the website, highlighting the CMP layers. ```plaintext mutation { setting(    settingsId: "ABCDEF1234"    language: "de"    firstLayer: { isOverlayEnabled: false  }    secondLayer: { isOverlayEnabled: false  }  ) { settingsId } } ``` **Notes** The default value `firstLayer { isOverlayEnabled }` is *true*. The default value `secondLayer { isOverlayEnabled }` is *true*. This feature is on setting level. The value will be automatically set across all languages. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(170).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=tU374j38Km7YsOmNhlwiaVDpL9SO8zuVHmlLMY7eTDI%3D) ## Service categories ### Service categories: create a custom category Usercentrics enables you to classify the used Data Processing Services into different categories. You can use our predefined categories without any concern or create your own categories and description texts based on your needs. ```plaintext mutation {  mutateCategories(    settingsId: "ABCDEF1234"    language: "en"    disableAutoTranslation: true    categories: {      added: {        categorySlug: "Payment",        label: "Payment",        description: "Custom Payment Vendor Category",        isEssential: false,      }    }  ) { settingsId } } ``` **Notes** The value `categorySlug` represents the unique key of this category across all languages. This key is mandatory and is required also when adding new vendors to categories or when deleting a category. The value `label` contains the name of the category and will be displayed in the UI. The value `description` contains the description of the category and will be displayed in the UI. The value `isEssential` defines whether a category is classified as essential. Vendors inside the essential category are automatically activated. This feature is on setting and language level. While categories are configured on setting level, you can have `label` and `description` localized. If `disableAutoTranslate` is set to *true* (default *false*), `label` and `description` are not going to be translated. ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(171).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=IdK4RT45sYLYQhfpN3CregbJ5qaaBzrbqPxRRkbY6qA%3D) ### Service categories: delete a category The CMP API enables you to delete any existing category entirely. Make sure the category is empty and has no vendors assigned to it before removing it. ```plaintext mutation { mutateCategories(    settingsId: "ABCDEF1234"    language: "de"    categories: {      removed: "Payment"    }  ) { settingsId } } ``` **Notes** The category has to be empty. There cannot be any vendors assigned to that category. This feature is on setting level. While categories are configured on setting level, you can have `label` and `description` localized. ## Data processing services Also known as DPS, `consentTemplate` or "Vendor". ### List all available DPSs Usercentrics maintains and provides an extensive list of predefined vendor templates. ```plaintext query {  consentTemplates {    templateId    version    dataProcessors  } } ``` ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(172).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=IEe5Z2XhTIW24hnCUM4AuJVy%2FDYRf2HDs8t7OEPiNjY%3D) ### Add DPS to category Any DPS can be added to a specific category. ```plaintext mutation { mutateTemplates(    settingsId: "ABCDEF1234"    language: "de"    consentTemplates: {      added: {        templateId:"JiFH1ubU"        categorySlug:"Payment"        isAutoUpdateAllowed:true        type:"predefined"      }    }  ) { settingsId } } ``` ![](https://cdn.document360.io/17f91ed2-e9be-4746-9f2b-1fa43f97e9b5/Images/Documentation/image(173).png?sv=2026-02-06&spr=https&st=2026-11-19T08%3A01%3A23Z&se=2026-11-19T09%3A01%3A23Z&sr=b&sp=r&sig=T5CL6bWzb9pHpppvezJPfyJXhIPmaHN8jdA%2FGwzkHrM%3D) **Notes** This feature is on setting level. If a template cannot be assigned to multiple categories. An error will be shown when trying to add a template to more than one category The value `templateId` contains the respective ID of the predefined template. *JiFH1ubU* is the Paypal template. The value `categorySlug` defines the category in which the template will be added. The value `isAutoUpdateAllowed` ensures that the template is always set to the latest version and will contain the latest updates. The value `type` can be *predefined* or *custom*, depending on the template you want to add. If taken from our database, it should always be *predefined*. ### Modify predefined data processing services The predefined DPSs provided by Usercentrics are maintained internally and can't be modified by customers directly. However, it's possible to create a custom DPS based on a predefined one, which is then owned by the user and can be modified: ```plaintext mutation {  transformTemplate(    settingsId: "ABCDEF1234"    templateId: "Hko_qNsuiXX"    language: "en"    categorySlug: "functional"    defaultConsentStatus: true  ) {    templateId    type  } } ``` **Notes** - `settingsId` indicates to which setting the new service must be added - `templateId: Hko_qNsuiXX` indicates that this template must be used as a base for the new template, so all data is copied from it. - `defaultConsentStatus` indicates this service's suggested default consent status, which can be overridden at the configuration level. The new service (`templateId` returned from the operation above) can then be updated. The operation below updates the `addressOfProcessingCompany` and `description` properties, for example. **Example Request** ```plaintext mutation {  updateConsentTemplate(    consentTemplate: {      addressOfProcessingCompany: "Munich, Germany"      templateId: "we3ZUuoCamXxLo"      type: "custom"      language: "en"      description: "New description text"      meaningHasChanged: true    },    allowedSettingsIds: ["settings2", "settings3"]  ) {    addressOfProcessingCompany    description    version    language    dataProcessor  } ``` **Example Response** ```plaintext {  "data": {    "updateConsentTemplate": [      {        "addressOfProcessingCompany": "Munich, Germany",        "description": "New description text",        "version": "2.1.0",        "dataProcessor": "Google Tag Manager",        "language": "en"      },      {        "addressOfProcessingCompany": "Munich, Germany",        "version": "2.1.0",        "description": "Нов текст на описанието",        "dataProcessor": "Google Tag Manager",        "language": "bg"      },      {        "addressOfProcessingCompany": "Munich, Germany",        "version": "2.1.0",        "description": "新的描述文字",        "dataProcessor": "Google Tag Manager",        "language": "zh"      }    ]  } } ``` **Notes** - **IMPORTANT:** `meaningHasChanged` indicates whether the properties updated here should be carried over to other languages of this template and auto-translated if applicable, which is the case for `description`. If `meaningHasChanged` isn't set, the operation above will only be applied for the language `en`. - `allowedSettingsIds` isn't required but was applied here to demonstrate that it can be used to allow other configurations to use this service. ### Crawling and scanning We provide *two* endpoints that can be used to scan and crawl websites. - Endpoint `getTechnologies` scans URLs or Sitemaps and returns a list of all services detected. - Endpoint `addTechnology` scans URLs or Sitemaps and adds the detected services directly to the specified SettingId in a predefined category. For both Endpoints, you can specify a List of URLs or specify a Sitemap to be scanned. Nested Sitemaps are supported to a depth of 2. **Basic authentication** Both endpoints allow to specify Usernames and Passwords within the URL to enable basic authentication. Format of URL with basic authentication: `<protocol>://<user>:<password>@<host>:<port>/<url-path>` **Example:** ```plaintext http://myuser:mypassword@shop.website.com/uk/sitemap.xml ``` > **Important** Since crawling a website isn’t a very fast task this API call can take a few minutes and so the caller should make sure to display a loading dialog to provide good UX to the user. **The** `getTechnologies` **endpoint** Technology you (or your end-customer) need to know about the technology present in the website and that can be retrieved via `url or sitemap of the website` in `getTechnologies` entrypoint node. The parameter `isSitemap` tells the API if the provided url is the `url` to a sitemap. E.g. `https://usercentrics.com/sitemap.xml`. **Example Request** ```plaintext # Write your query or mutation here query { getTechnologies(url: "http://bl.plattenspieler-nadel.com/", isSitemap: false) {   label    templateId  } } ``` **Example Response** ```plaintext {  "data": {    "getTechnologies": [      {        "label": "Google WebFonts",        "templateId": "HkYNq4sdjbm"      },      {        "label": "Mapbox scripts",        "templateId": "U8QkTd2W"      },      {        "label": "Facebook Widgets (comments, like, page, login)",        "templateId": "XYQZBUojc"      }    ]  } } ``` **The** `addTechnology` **endpoint** This requests triggers our crawler functionality which scans a specific website for used technologies. After scanning the website the crawler automatically adds the appropriate consent templates for the found technologies to the provided setting. The category is predefined by Usercentrics. All three parameters are mandatory. The parameter `isSitemap` tells the API if the provided url is the `url` to a sitemap. E.g. `https://usercentrics.com/sitemap.xml`. **Example Request** ```plaintext mutation {  addTechnology(    settingsId: "HkvOYLyME",    isSitemap: true,    url: "https://usercentrics.com/sitemap.xml") {      settingsId      consentTemplates {        templateId      }    } } ``` **Example Response** ```plaintext {  "data": {    "addTechnology": {      "consentTemplates": [        {          "templateId": "HJI5SmLm7"        },        {          "templateId": "S1pcEj_jZX"        },      ],      "settingsId": "HkvOYLyME",    }  } } ``` ### Using subconsents Request to mutate subconsents. The settingsId and language parameter are mandatory. **Example Request** ```plaintext mutation {  mutateTemplates(    settingsId: "8yKTozwk"    language: "en"    consentTemplates: {      updated: [        {          templateId: "H1Vl5NidjWX"          subConsents: [            { templateId: "H1MvxcVjOoZ7", type: "predefined", version: "1.0.0" }            { templateId: "rkt8g9Niuo-7", type: "predefined", version: "1.0.0" }          ]        }      ]    }  ) {    language    consentTemplates {      templateId      version      categorySlug      description      subConsents {        templateId        type        version      }    }  } } ``` **Example Response** ```plaintext {  "data":  {    "mutateTemplates":  {      "consentTemplates":  [         {          "categorySlug": "essential",          "description": "",          "subConsents":  [             {              "templateId": "H1MvxcVjOoZ7",              "type": "predefined",              "version": "1.0.0",            },             {              "templateId": "rkt8g9Niuo-7",              "type": "predefined",              "version": "1.0.0",            },          ],          "templateId": "H1Vl5NidjWX",          "version": "10.2.15",        },      ],      "language": "en",    },  }, } ``` ## Geolocation rules Geolocation rules (rulesets) will enable you to set up and display different CMP Configurations on your website based on the user’s location. Please refer to [this documentation page](/v1/docs/geolocation-rules), which explores rulesets, its components, implementation, and important configuration changes required for using geolocation rules with specific legislations, such as CCPA and TCF. The sections below focus only on managing geolocation rules via the Partner API. ### Prerequisites As pointed [here](/v1/docs/setting-up-your-account), in configurations defined in regional rules, there must be no region limitation set in the setting itself. This can be verified via API inspecting the settings data: - The `displayOnlyForEU` property must be set to `false` (Already `false` by default) - In the case of a setting configured for an US legislation (CCPA, CPRA, CPA, and so on), the property `ccpa.region` must be set to `ALL`. (`US_CA_ONLY` by default). ### Operations All mutation operations listed below accept an array as input, which means that with a single operation, multiple rulesets can be created, updated, or deleted. > The examples provided below are for reference only. For an extensive documentation about all the available fields check our API documentation here. ### Creating rulesets Example of creating a ruleset, which defines two regional rules: - For users accessing my website from France and Spain, a banner with the configuration `settings2` will be displayed. - For users accessing my website from Great Britain, a banner with the configuration `settings3` will be displayed. Beyond that, all users accessing the website where this ruleset is implemented from any other location will have a banner displayed with the configuration `settings1` (the fallback/default configuration). (Note the `noShow` property set to `false` here. Were it set to `true`, no banner would be displayed to users from other locations). > Note: Location codes must correspond to ISO3166_1 or ISO3166_2 ISO standards. E.g. "DE" Germany, "DEBY" for Germany Bavaria. The country always includes all state regions, and therefore overrules them. **Request Example** ```plaintext mutation CreateRuleSets {  createRuleSets(    ruleSets: [      {        name: "new ruleset"        defaultRule: { settingsId: "settings1", noShow: false }        description: "some description"        rules: [          {            locations: ["FR", "ES"]            name: "France-Spain region"            settingsId: "settings2"          },           {            locations: ["GB"]            name: "Great Britain region"            settingsId: "settings3"          }        ]      }    ]  ) {    defaultRule {      noShow      setting {        settingsId      }    }    ruleSetId    name    rules {      locations      name      setting {        settingsId      }    }  } } ``` **Response Example** ```plaintext {  "data": {    "createRuleSets": [      {        "defaultRule": {          "noShow": false,          "setting": {            "settingsId": "settings1"          }        },        "ruleSetId": "ruleSet1",        "name": "new ruleset",        "rules": [          {            "locations": ["FR", "ES"],            "name": "France-Spain region",            "setting": {              "settingsId": "settings2"            }          },          {            "locations": ["GB"],            "name": "Great Britain region",            "setting": {              "settingsId": "settings3"            }          }        ]      }    ]  } } ``` ### Updating rulesets To update a ruleset data, use the `mutation updateRuleSets`. This mutation works based on partial updates, this means only the fields to be updated need to be provided in the input. > IMPORTANT: To modify the rules list an updated version of it, possible copying the original and modifying it. As with all the other properties, any value provided on this property will completely override the current one. **Request Example** Updating the list or rules for the ruleset created above. ```plaintext mutation Mutation {  updateRuleSets(    ruleSets: [      {        ruleSetId: "ruleSet1"        rules: [          {            locations: ["FR", "ES", "PT"]            name: "France-Spain-PT region"            settingsId: "settings1"          }          {            locations: ["GB"]            name: "Great Britain region"            settingsId: "settings2"          }        ]      }    ]  ) {    ruleSetId    rules {      name      locations      setting {        settingsId      }    }  } } ``` ### Listing rulesets The `Query ruleSets` operation can list all your rulesets or entries by id. In case the argument `ruleSetIds` is omitted, all RuleSets are returned. To define a list of IDs to be returned, provide a list of Ruleset IDs to this argument. #### Pagination The result returned by the `Query ruleSets` is always paginated. To control the pagination, two arguments are used: - `limit` defines the maximal amount of documents to be returned in a single request and can be used to represent a page size. Its default is set to `100` and the maximal value allowed is `200`. - `skip` can be used to define the idea of page number once the limit (or page size) is known. Its default value is set to `0`. **Request Example** ```plaintext query RuleSets {  ruleSets(ruleSetIds: ["xxxxxxx", "yyyyyyy"]) {    name    description    rules {      name    }  } } ``` ### Deleting rulesets Deleting rulesets only requires the list of IDs to be provided: **Request Example** ```plaintext mutation DeleteRuleSets {  deleteRuleSets(ruleSetIds: ["ruleset1", "ruleset2"]) } ``` **Response Example** Contains the list of IDs deleted. Either all IDs are deleted or an error is returned: ```plaintext {  "data": {    "deleteRuleSets": ["ruleset1", "ruleset2"]  } } ```