Capturing preferences for non-authenticated users

Prev Next

To simplify the collection of user preferences in scenarios where server-side implementation is not feasible, our platform provides the POST /loyal/preferences endpoint. This endpoint allows for preference submissions from non-authenticated users using a specialized Public API Key. This key can be generated within the Account Settings section of the Admin Interface and does not require a pre-generated token, making it ideal for non-authenticated workflows.

The key scenarios this end-point can be a good option:

  • Front-End Integration: Easily integrate with existing website forms to capture preferences for non-authenticated users (like registration, contact forms, etc).
  • Server-Side Option: Alternatively, implement server-side calls to seamlessly send data to the Preference Manager database.

Parameters:

The endpoint uses the following parameters:

  • x-user-email (optional): The email of the user to be used in a transactional emails in case UserID is not email (i.e. in case of Double-opt-In).
  • behalf (optional): If true, preference is saved on behalf of the user, so in the audit log the author of the change will be displayed as userID. If false (default)- the author of the change will remain the owner of the API Key with which the request is authorized.

Request body

This end-point will accept the JSON payload containing all information about the submission, including ConfigurationID, WidgetID, UserID and dedicated object with list of the optionIDs as answers.

{
  "pacId": "string",   // The unique ID of the preference configuration.
  "widgetId": "string", // The ID of the widget associated with the preference.
  "userId": "string",   // The user's unique identifier, e.g., email.
  "answers": [          // Array of option IDs selected by the user.
    "string"
  ]
}

Example of usage with Javascript:

<script>
  fetch(
    "https://preference-api.preference-management.usercentrics.eu/public/loyal/preferences",
    {
      headers: {
        "x-api-key": "{{apiKey}}",
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      method: "POST",
      body: JSON.stringify({
        pacId: "1234abcd-22bb-33cc-44dd-12345678abcd",
        widgetId: "1234abcd-22bb-33cc-44dd-12345678abcd",
        userId: "user@domain.com",
        answers: "1234abcd-22bb-33cc-44dd-12345678abcd",
      }),
    }
  );
</script>

Example of implementation using the server-side call:

Preference data submission request:

curl -X 'POST' \
  'https://preference-api.preference-management.usercentrics.eu/public/loyal/preferences' \
  -H 'accept: application/json' \
  -H 'x-user-email: etstt' \
  -H 'X-API-KEY: 7b931a0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxa0d1' \
  -H 'Content-Type: application/json' \
  -d '{
  "pacId": "1234abcd-22bb-33cc-44dd-12345678abcd",
  "widgetId": "1234abcd-22bb-33cc-44dd-12345678abcd",
  "userId": "user@domain.com",
  "answers": [
    "1234abcd-22bb-33cc-44dd-12345678abc1", "1234abcd-22bb-33cc-44dd-12345678abc2"
  ]
}'

Important Notes:

  1. Preference Overwrite: Subsequent submissions overwrite the previous state of the preference data object. For ongoing data management, we recommend using endpoints secured with Private API keys or tokens.
  2. Data Security: The Public API Key allows access to the Preference Manager. Using a Public API Key on the front end can expose it to the public. That’s why this type of API key can only be used with this endpoint. In addition, we can recommend to consider activation of Double Opt-In setting for the widget, the data being submitted to, so every submission for the new user will be validated via email.
  3. Audit Trails: Ensure transparency with audit logs tracking changes based on the API key owner or acting user.

By leveraging this endpoint, you can streamline preference management for non-authenticated users while maintaining compliance with privacy standards.