Documentation Index
Fetch the complete documentation index at: https://client-integrations-api-dev.sequen.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
| Field | Type | Required | Example | Notes |
|---|
| uid | string | Yes | "user_34544345" | Must be globally unique and immutable. |
| created_at | time | auto | "2025-05-14T09:12:33Z" | First time we see the record. |
| updated_at | time | auto | "2025-05-14T09:12:33Z" | Overwritten on each upsert. |
| is_deleted | boolean | | false | Soft-delete flag (false by default). |
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"
}
Recommended fields
| Key name (example) | Type | Why it helps |
|---|
| country, language | string | Geo & localisation boosts. |
| signup_channel, loyalty_tier | string | Funnel and lifetime‑value models. |
| total_orders, avg_order_value | number | High‑spend user prioritisation. |
| preferred_categories | array<string> | First‑party interest signals. |
| profile_embedding_v1 | embedding | Dense 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
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.
| Attribute | What Is It? | Good | Better | Best |
|---|
| age | | ✅ | ✅ | ✅ |
| gender | | ✅ | ✅ | ✅ |
| address | | ✅ | ✅ | ✅ |
| created_at | | ✅ | ✅ | ✅ |
| status | | ✅ | ✅ | ✅ |
| previous_reviews | | ✅ | ✅ | ✅ |
| past_trips | | | ✅ | ✅ |
| review_categories | | | ✅ | ✅ |
| labels | | | ✅ | ✅ |
| last_login | | | ✅ | ✅ |
| session_frequency | | | ✅ | ✅ |
| loyalty_programs | | | | ✅ |
Privacy, consent & deletion
- 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 →
