Users

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).

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"
}

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

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.

Attribute	Good	Better	Best
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 →

Introduction

Data Management v2

Search & Recommendations

Chat

Embeddings

Why send user data?

Schema

Reserved Fields

Example user object

Recommended fields

Relationship to other entities

Endpoint

Example Request

Good, Better, Best Data

​Why send user data?

​Schema

​Reserved Fields

​Example user object

​Recommended fields

​Relationship to other entities

​Endpoint

​Example Request

​Good, Better, Best Data

​Privacy, consent & deletion

Why send user data?

Schema

Reserved Fields

Example user object

Recommended fields

Relationship to other entities

Endpoint

Example Request

Good, Better, Best Data

Privacy, consent & deletion