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

# 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](/api-reference/data-management).

User Field Types get inferred at first data ingest and may be remapped via the dashboard or API.

### Example user object

```json theme={null}
{
  "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

<CodeBlock title="POST /v1/users (Upsert User)">
  ```bash theme={null}
  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
    }'
  ```
</CodeBlock>

## 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](/api-reference/events) →