Skip to main content
This page explains everything you need to know about the User table: what it represents, why it matters for personalization, its exact schema, and how to keep it in sync with our platform. The user table is a special table that represents your users.

​
Why send user data?

While click‑stream events fuel short‑term (session‑level) personalization, user profiles enable long‑term learning and cold‑start quality. Typical benefits include:
  • Better default ranking for first‑page visits
  • Audience‑level experimentation and A/B analysis
  • Cross‑device continuity (e.g., “Recently viewed”)
Best practice is to push a User upsert any time you: create an account, collect new profile fields, or recalculate vectors/embeddings.

​
Schema

The User object is intentionally minimalist: one required primary key plus any other attributes that belong to your users.

​
Reserved Fields

FieldTypeRequiredExampleNotes
uidstringYes"user_34544345"Must be globally unique and immutable.
created_attimeauto"2025-05-14T09:12:33Z"First time we see the record.
updated_attimeauto"2025-05-14T09:12:33Z"Overwritten on each upsert.
is_deletedbooleanfalseSoft-delete flag (false by default).
All other keys are Custom Fields—choose any name, provided the value uses one of the field types (string, number, boolean, array<string>, time, embedding, relation), defined in Uploading & Managing Your Data. User Field Types get inferred at first data ingest and may be remapped via the dashboard or API.

​
Example user object

{
  "uid": "u_9e1c7fbb",
  "country": "US",
  "language": "en",
  "loyalty_tier": "gold",
  "preferred_categories": ["Electronics", "Gaming"],
  "total_orders": 27,
  "avg_order_value": 274.26,
  "profile_embedding_v2": [
    -0.113, 0.052, 0.441, 0.003,
    0.091
  ],
  "gdpr_consent": true,
  "created_at": "2025-05-14T09:12:33Z",
  "updated_at": "2025-05-14T09:12:33Z",
  "is_deleted": false,
  "_table": "users"
}
Key name (example)TypeWhy it helps
country, languagestringGeo & localisation boosts.
signup_channel, loyalty_tierstringFunnel and lifetime‑value models.
total_orders, avg_order_valuenumberHigh‑spend user prioritisation.
preferred_categoriesarray<string>First‑party interest signals.
profile_embedding_v1embeddingDense vector for sophisticated similarity search.

​
Relationship to other entities

Events: Every impression, click, or conversion can carry the same uid. This links behavioural logs back to the user profile for real‑time modelling.

​
Endpoint

POST /v1/users

​
Example Request

curl -X POST https://api.sequen.com/v1/users \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "uid": "u_9e1c7fbb",
    "country": "US",
    "language": "en",
    "loyalty_tier": "gold",
    "preferred_categories": ["Electronics", "Gaming"],
    "total_orders": 27,
    "avg_order_value": 274.26
  }'

​
Good, Better, Best Data

Our data request is divided into three tiers: Good, Better, and Best. Below, we outline the data included in each category, with “Good” covering the mandatory requirements for a baseline model, while “Better” and “Best” provide additional data to enhance performance.
AttributeWhat Is It?GoodBetterBest
age✅✅✅
gender✅✅✅
address✅✅✅
created_at✅✅✅
status✅✅✅
previous_reviews✅✅✅
past_trips✅✅
review_categories✅✅
labels✅✅
last_login✅✅
session_frequency✅✅
loyalty_programs✅
  • Always hash or redact direct PII that is not required for ranking (email, phone).
  • Supply a country field so we can respect region‑specific regulations (GDPR, CCPA).
  • To delete a user permanently, call DELETE /v1/users/{uid} – we remove profile and events within 24 h, and models forget within seven days.
Next, learn about Events →