Personalization

How it works

You send a free-form JSON object as data.additional_context with a suggestion request, and the suggestions that come back are conditioned on it. For a coffee ordering flow, one round looks like this:

1. The user types "Iced latte with", and AI Autocomplete suggests the next field to fill. Here, that is milk.
2. Your app has already sent the customer's saved preference, milk: "oat milk", as part of the additional context.
3. The options for milk arrive with oat milk listed first. A first-time visitor with no context sees the default order instead.
4. The user picks, and the next field is suggested the same way. Context shapes which parameters and options are offered; it never fills anything in on the user's behalf.

What to send

The object is yours to shape. Send whatever your app knows that a good barista, sales assistant, or support agent would want to know about this person before they finish typing.

• Values for your product's own fields carry the most weight. A key named after a field (size, milk, destination) whose value is one of that field's options is listed first whenever the field is suggested.
• A profile and preferences: tier, home store, dietary restrictions, default settings, the workspace or project that is open.
• Recent activity: the last few orders, searches, or documents. Keep a short rolling window rather than the full history.
• Nest as deeply as you like. Any JSON value is accepted, and the shape is never checked against a schema.
• Send nothing when there is nothing to add. An empty object behaves the same as no context at all.

{
  "tier": "gold",
  "home_store": "Gangnam Station",
  "allergies": ["peanut"],
  "preferences": { "milk": "oat milk", "size": "grande" },
  "favorites": ["iced americano", "cold brew"],
  "recent_orders": [
    { "drink": "iced caramel macchiato", "size": "grande", "at": "2026-08-18" }
  ]
}

Step 1: Pass the context

Include the object as data.additional_context in the body of every suggestion request you want personalized. It is not remembered between requests, so a request without it is answered without personalization.

{
  "data": {
    "raw_query": "I want a",
    "additional_context": {
      "tier": "gold",
      "home_store": "Gangnam Station",
      "allergies": ["peanut"],
      "preferences": { "milk": "oat milk", "size": "grande" },
      "favorites": ["iced americano", "cold brew"],
      "recent_orders": [
        { "drink": "iced caramel macchiato", "size": "grande", "at": "2026-08-18" }
      ]
    }
  },
  "meta": {
    "request_id": "0c6a3b8e-5d2f-4e1a-9b7c-2d4e6f8a0b1c",
    "request_at": "2026-08-19T09:15:00Z",
    "session_id": "9e5b7c0e-2a1b-4f8e-9c2d-3e4f5a6b7c8d"
  }
}

Step 2: Keep it current

Context can change mid-session: the user places an order, switches workspace, or signs in. Because every request carries its own copy, there is nothing to invalidate. Build the object fresh each time you send a request.

• Only the object on the current request counts. Earlier requests in the same session do not carry over.
• Omit the field entirely when there is nothing to add. An empty object is treated the same as absent.

// Build the context fresh for every request so it always reflects the
// latest state. Nothing is remembered between requests.
const recentOrders = [];

function contextFor(customer) {
  return {
    tier: customer.tier,
    preferences: { milk: customer.defaultMilk, size: customer.defaultSize },
    // A rolling window keeps the object under the size cap as the session grows.
    recent_orders: recentOrders.slice(-10).map((o) => ({ drink: o.drink, size: o.size })),
  };
}

async function suggest(rawQuery, completedParams, customer) {
  const res = await fetch("https://api.ai-autocomplete.com/api/suggest", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + (await getAccessToken()),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      data: {
        raw_query: rawQuery,
        completed_params: completedParams,
        additional_context: contextFor(customer),
      },
      meta: {
        request_id: crypto.randomUUID(),
        request_at: new Date().toISOString(),
        session_id: sessionId,
      },
    }),
  });
  return res.json();
}

function onOrderPlaced(order) {
  // The next request's context carries this order.
  recentOrders.push(order);
}

Size limit

Context is capped at 2000 bytes, measured on the compacted JSON (whitespace does not count). That is roughly a full profile plus a couple dozen history entries.

• Anything past the cap is truncated with a trailing "…" rather than rejected. Nothing errors, but the tail is silently lost.
• Put the most useful keys first: field values and preferences before history.
• Non-ASCII text costs more than one byte per character (three for most Korean or Japanese text), so such a profile reaches the cap sooner.
• For history, keep a rolling window (the last ten orders, not every order) so the object stays under the cap as the session grows.

Privacy and safety

• Context is treated strictly as data. Instructions, role changes, or prompt-like text inside it are ignored.
• Context values are never written into the query on the user's behalf. They only steer which options are offered, and in what order.
• Send only what suggestions can benefit from. Names, emails, phone numbers, and account identifiers add nothing to the ranking, so leave them out.
• PII masking of completed parameters does not extend to context. Masking hides what the user picked; it does not filter what you put in the context object.
• Context travels only with suggestion requests. It is not attached to telemetry, and it is not remembered between requests.