The user preferences API allows clients to submit user preference data, which Constructor can utilize to conduct experiments and deliver a richer, more personalized user experience. The endpoint supports two content types: application/json and multipart/form-data. The Content-Type header must be set accordingly. Additionally, every request requires a mandatory key query parameter, specifying the index key to be used.

API endpoints

Upload user preferences

Why the user preferences API is important

The user preferences API bridges the gap between the rich customer data you already collect—such as preferences, demographics, or survey responses—and the powerful behavioral insights generated from user interactions on your website. By combining these data sources, you gain a true 360-degree view of your customers, enabling deeper understanding and more meaningful engagement.

When you send data via user preferences, personalization can become more precise and effective. For example, sharing details like a shopper’s beauty preferences, such as skin tone or type, allows recommendations to align perfectly with their unique needs. Beyond personalization, this API unlocks advanced capabilities such as precise user segmentation, predictive scoring, and full user journey optimization.

Merchandising teams can also leverage these enriched user profiles to design targeted campaigns that resonate with specific customer groups, ensuring the right products and messages reach the right audiences at the right time. The result is a powerful blend of data and insight that drives loyalty, boosts engagement, and strengthens your brand’s connection with each customer.

When to use the user preferences API

When you know something semi-permanent about a user (e.g., loyalty status, skin type, demographics, survey responses, food preferences, etc.), you can pass that information using the user preferences API.

While Constructor does have a user segment parameter (us) for the Search, Browse, Autocomplete, and Recommendation endpoints, its use should be limited to temporary or transient information about a user request or session. For example, the origin of the request (either location or campaign source) or information about an anonymous user.

JSON upload

To submit smaller sets of user preference updates, such as when a user completes a preference questionnaire, JSON may be used. Requests must have the Content-Type header set to application/json. The request body should include a single user_preferences key containing a list of preference objects.

preference_key: the identifier for the preference category
preference_values: the selected preference values
ui: the customer user id

Example request body

{
  "user_preferences": [
    {
      "preference_key": "fit",
      "preference_values": ["slim", "regular"],
      "ui": "101"
    },
    {
      "preference_key": "fit",
      "preference_values": ["loose"],
      "ui": "201"
    }
  ]
}

Payloads are limited to a maximum of 100 items.

File upload

For bulk data imports or to backfill existing preferences for all users, file based uploads may be used. This requires uploading a JSONL file via a multipart/form-data request. Files compressed via gzip are supported as well.

Each line in the JSONL file must represent a single preference object in the same format as the short upload:

{"preference_key": "fit", "preference_values": ["slim", "regular"], "ui": "101"}
{"preference_key": "fit", "preference_values": ["loose"], "ui": "201"}

Unlike JSON upload, there is no limit on the number of preference items per request.