> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Users

> Send user registration and profile update events to Atlas for player analytics and compliance.

<Snippet file="snippets/api-key-auth.mdx" />

## Event Types

User events are sent to `POST /api/v1/user`. The Kafka topic is fixed: `atlas.events.raw.user`.

| Event      | Description                  |
| ---------- | ---------------------------- |
| `register` | Player creates a new account |
| `update`   | Player updates their profile |

## Track a Registration

Send this event when a player creates a new account on your platform.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://events.atlas.io/api/v1/user \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "org_abc123",
      "brand_id": "brand_xyz",
      "event": "register",
      "user_id": "user_12345",
      "email": "joao.silva@example.com",
      "full_name": "João Silva",
      "document": "***.***.***-**",
      "birthdate": "1990-05-15",
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "phone": "+55 11 9****-****",
      "kyc_status": "pending",
      "registered_at": "2026-03-11T14:30:00Z"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://events.atlas.io/api/v1/user', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ATLAS_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      org_id: 'org_abc123',
      brand_id: 'brand_xyz',
      event: 'register',
      user_id: 'user_12345',
      email: 'joao.silva@example.com',
      full_name: 'João Silva',
      country: 'BR',
      kyc_status: 'pending',
      registered_at: new Date().toISOString(),
    }),
  });
  ```

  ```go Go theme={null}
  type UserEventRequest struct {
    OrgID      string `json:"org_id"`
    BrandID    string `json:"brand_id"`
    Event      string `json:"event"`
    UserID     string `json:"user_id"`
    Email      string `json:"email"`
    FullName   string `json:"full_name"`
    Document   string `json:"document"`
    Birthdate  string `json:"birthdate"`
    Country    string `json:"country"`
    KYCStatus  string `json:"kyc_status"`
    RegisteredAt string `json:"registered_at"`
  }
  ```
</CodeGroup>

## Track a Profile Update

Send this event when a player updates their profile data, KYC status changes, or address is verified. Only include the fields that changed.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://events.atlas.io/api/v1/user \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "org_abc123",
      "brand_id": "brand_xyz",
      "event": "update",
      "user_id": "user_12345",
      "kyc_status": "approved",
      "updated_at": "2026-03-11T15:00:00Z"
    }'
  ```
</CodeGroup>

## Request Fields

### Envelope Fields (all events)

<ParamField body="org_id" type="string" required>
  Your organization ID. Found in Dashboard -> Settings -> Organization.
</ParamField>

<ParamField body="brand_id" type="string" required>
  Brand identifier where this user belongs.
</ParamField>

<ParamField body="event" type="string" required>
  Event type: `register` or `update`.
</ParamField>

<ParamField body="ip" type="string">
  Player IP address at event time (IPv4 or IPv6).
</ParamField>

<ParamField body="geolocation_lat" type="number">
  Player latitude at event time.
</ParamField>

<ParamField body="geolocation_long" type="number">
  Player longitude at event time.
</ParamField>

### User Profile Fields

<ParamField body="user_id" type="string" required>
  Your internal user identifier. Must be stable across all events for the same player.
</ParamField>

<ParamField body="full_name" type="string">
  Player full name.
</ParamField>

<ParamField body="email" type="string">
  Player email. Must be a valid email format when provided.
</ParamField>

<ParamField body="phone" type="string">
  Player phone number.
</ParamField>

<ParamField body="document" type="string">
  Player document (CPF or equivalent). Send masked or hashed values whenever possible.
</ParamField>

<ParamField body="birthdate" type="string">
  Birth date as string (for example `1990-05-15`).
</ParamField>

<ParamField body="gender" type="integer">
  Gender code from your platform model.
</ParamField>

<ParamField body="country" type="string">
  Country code (for example `BR`).
</ParamField>

<ParamField body="post_code" type="string">
  Postal code / ZIP code.
</ParamField>

<ParamField body="city" type="string">
  City name.
</ParamField>

<ParamField body="state" type="string">
  State / region code.
</ParamField>

<ParamField body="registered_at" type="string">
  Registration timestamp in ISO 8601.
</ParamField>

<ParamField body="updated_at" type="string">
  Profile update timestamp in ISO 8601.
</ParamField>

<ParamField body="registration_platform" type="string">
  Allowed values: `DESKTOP`, `MOBILE`, `APP`.
</ParamField>

<ParamField body="status" type="string">
  Allowed values: `ACTIVE`, `BLOCKED`, `SUSPENDED`, `BANNED`, `SELF_EXCLUDED`, `DEACTIVATED`, `PENDING`.
</ParamField>

<ParamField body="is_test_account" type="boolean">
  Indicates whether this user is a test account.
</ParamField>

<ParamField body="kyc_status" type="string">
  KYC verification status from your platform workflow.
</ParamField>

## Batch Registration

For bulk imports (e.g., migrating players from a legacy system):

```bash theme={null}
curl -X POST https://events.atlas.io/api/v1/user/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "register",
        "user_id": "user_001",
        "email": "player1@example.com",
        "registered_at": "2025-01-01T00:00:00Z"
      },
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "register",
        "user_id": "user_002",
        "email": "player2@example.com",
        "registered_at": "2025-01-02T00:00:00Z"
      }
    ]
  }'
```

<Tip>
  For historical data migrations, include the original `registered_at` timestamp. Atlas will
  backfill the analytics using the actual registration dates.
</Tip>

## Privacy & PII

<Warning>
  User events may contain PII (Personally Identifiable Information). Atlas handles all data
  in compliance with LGPD (Lei Geral de Proteção de Dados) and GDPR.

  **Best practice:** Never send raw CPF or document numbers — always hash or mask them
  before sending to Atlas unless your Data Processing Agreement explicitly allows it.
</Warning>