Requesting widget structure

Prev Next

To fetch configuration details for a specific widget, including its structure and translations for its elements, you can use a GET request to the endpoint /widgets/{widgetUuid} specifying widget ID as parameter (widgetUuid). The other optional parameter is language (array), that defines what translation variant(-s) of this widget should be returned. If not specified, only the English version will be returned.

Parameters:

  • widgetUuid (required): The unique identifier of the widget, which can be found in the Admin UI on the widget list, or as part of the Widget Structure view available under the drop-down menu for each widget.

  • language (optional): Array of language codes in ISO 639-1 format (e.g.'en').

Response:

The response will contain a JSON object with full configuration of the widget, including:

  • uuid - ID of the widget returned

  • doubleOptIn - boolean flag, if the Double Opt-In flow is activated for the widget

  • hidden - boolean flag, if widget should be displayed by default as part of Preference Center page

  • title - translations for Widget Title field text

  • description - translations for Widget description field text

  • additionalNote - translations for Additional Legal Note field text

  • topics - set of objects relates to each topic configured for the widget

    • uuid - topicID

    • required - boolean, if topic is set as mandatory to submit the data

    • selectType - type of selection: single-selection (radio or drop-down) or multi-selection (checkbox)

    • order - order of the topic to be displayed within the widget

    • title - translations for topic title field text

    • description - translations for topic description field text

    • options - set of objects relates to each option under this topic with similar set of fields

      • uuid - OptionID

      • order - order of the option to be displayed within the widget

      • default - boolean flag, if the option should be displayed as checked by default

      • title - translations of the option title field text

Example:

Calling the endpoint to get widget configuration for two language variants (en and de):

curl -X 'GET' \
  'https://preference-api.preference-management.usercentrics.eu/public/widgets/1234abcd-22bb-33cc-44dd-12345678abcd?language=de&language=en' \
  -H 'accept: application/json'

Response:

{
  "uuid": "1234abcd-22bb-33cc-44dd-12345678abcd", 
  "doubleOptIn": false,
  "hidden": false,
  "title": {
    "de": "Präferenzen für Marketingkommunikation",
    "en": "Marketing communication preferences"
  },
  "description": {
    "de": "Hier können Sie Ihre Präferenzen für unsere Marketingmitteilungen angeben",
    "en": "Here you can specify your preferences on our marketing communications"
  },
  "additionalNote": {
    "de": null,
    "en": null
  },
  "topics": [
    {
      "uuid": "1234abcd-22bb-33cc-44dd-12345678abcd",
      "required": false,
      "selectType": "multi_checkbox",
      "order": 0,
      "title": {
        "de": "Newsletter-Themen",
        "en": "Newsletter Topics"
      },
      "description": {
        "de": "Welche Art von Newslettern möchten Sie von uns erhalten?",
        "en": "What kind of newsletters would you want to receive from us?"
      },
      "options": [
        {
          "uuid": "1234abcd-22bb-33cc-44dd-12345678abcd",
          "order": 0,
          "default": false,
          "title": {
            "de": "Modetrends",
            "en": "Fashion trends"
          }
        },
        {
        ............
        }
      ]
    },
    {
      ............
    }
  ]
}