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

# Create a user event for rules and fraud detection

> Create a user event for fraud detection and rule validation — for user behavior tracking and rule-based fraud detection in gu1, with examples for create use.

## Overview

Creates a new user event to track actions and behaviors within your application. Events are used for fraud detection, compliance monitoring, behavioral analytics, and audit trails. The system automatically registers devices, can optionally create entities when they don't exist, and runs the rules engine to evaluate risk. The response includes `rulesResult` and `rulesExecutionSummary` when rules are triggered.

<Tip>
  📋 Events automatically register devices when `deviceId` and `deviceDetails` are provided, eliminating the need for separate device management.
</Tip>

## Endpoint

```
POST https://api.gu1.ai/events/user
```

## Authentication

Requires a valid API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="withAutoEntity" type="boolean" default="false">
  Enable automatic entity creation when an entity with the provided `taxId` doesn't exist. When true, if the event includes a `taxId` and no entity exists with that tax ID, a new person or company entity will be automatically created.

  Example: `?withAutoEntity=true`
</ParamField>

## Request Body

<ParamField body="eventType" type="string" required>
  Type of event being tracked. Must be one of the supported event types (see [Event Types](#event-types) section below), including authentication, transfers, biometric validation, and more.

  Example: `"LOGIN_SUCCESS"`
</ParamField>

<ParamField body="userId" type="string">
  Your internal user identifier. Used to group events by user across different entities.

  Example: `"user_12345"`
</ParamField>

<ParamField body="entityId" type="string">
  gu1's entity UUID. Provide this if you have the internal gu1 ID.

  <Note>
    **Entity Identification**: You must provide at least ONE of: `entityId`, `entityExternalId`, or `taxId`. These fields support OR logic, so the system will find the entity using any of these identifiers. **SDK exception:** organizations with the SDK enabled may instead send only a [`sessionId`](#sdk-events) for anonymous pre-login events.
  </Note>
</ParamField>

<ParamField body="entityExternalId" type="string">
  Your external entity identifier. This is your unique ID for the entity in your system.

  Example: `"user_12345"`
</ParamField>

<ParamField body="taxId" type="string">
  Tax identification number (CPF, CNPJ, CUIT, etc.). When combined with `?withAutoEntity=true`, this will create the entity if it doesn't exist.

  Example: `"20242455496"`
</ParamField>

<ParamField body="timestamp" type="string">
  When the event occurred in ISO 8601 datetime format. If not provided, defaults to the current server time.

  Example: `"2026-01-30T14:30:00Z"`
</ParamField>

<ParamField body="eventDate" type="string">
  **Business date** for the event. Used by historical rules as the starting point for time windows (e.g. "last 7 days" is calculated backwards from this date).

  **Format:** ISO 8601 datetime string with timezone (e.g. `"2026-01-30T14:30:00Z"` or `"2026-01-30T00:00:00.000Z"`).

  **If you don't send it:** The system uses the same value as `timestamp` (or the current server time if neither is sent). So the event is treated as "now" for historical rules—no need to send it when the event is real-time.
</ParamField>

<Note title="eventDate recap">
  * **Omitted** → We set `eventDate = timestamp` (or now). Historical rules use that as the starting point.
  * **Format** → ISO 8601 with timezone: `"YYYY-MM-DDTHH:mm:ss.sssZ"` (e.g. `"2026-01-30T00:00:00.000Z"`).
  * **When to send** → When the event actually happened on a different date than when you're sending it (e.g. backfilled or batch events).
</Note>

<ParamField body="deviceId" type="string">
  Unique identifier for the device. This should be a stable identifier that persists across sessions.

  Example: `"840e89e4d46efd67"`
</ParamField>

<ParamField body="deviceDetails" type="object">
  Detailed device information. When provided, the device will be automatically registered or updated.

  **Structure:**

  ```json theme={null}
  {
    "platform": "android",
    "osName": "Android",
    "osVersion": "Android 16",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "browser": "Chrome",
    "browserVersion": "120.0.6099.129",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "additionalDetails": {}
  }
  ```
</ParamField>

<ParamField body="ipAddress" type="string">
  IP address from which the event originated (IPv4 or IPv6).

  Example: `"10.40.64.231"`
</ParamField>

<ParamField body="country" type="string">
  ISO 3166-1 alpha-2 country code where the event occurred.

  Example: `"AR"`
</ParamField>

<ParamField body="isVpn" type="boolean" default="false">
  Whether the connection is through a VPN
</ParamField>

<ParamField body="isProxy" type="boolean" default="false">
  Whether the connection is through a proxy
</ParamField>

<ParamField body="isNewDevice" type="boolean">
  **New device flag** stored on the event (`is_new_device` in the database). See [How `isNewDevice` works](#how-isnewdevice-works) below.
</ParamField>

<ParamField body="sessionId" type="string">
  SDK session identifier (`sess_...`, max 64 chars). For organizations with the SDK enabled, an event carrying only a `sessionId` (no entity identifier) is accepted and persisted as an **anonymous pre-login event**; it is linked to the entity later on the first event that carries both `sessionId` and an entity identifier. Without the SDK enabled, an entity identifier is still required.

  Example: `"sess_a1b2c3d4"`
</ParamField>

<ParamField body="sdkSignals" type="object">
  Structured signals emitted by the SDK (kept separate from free-form `metadata`). All fields optional: `sessionId`, `sessionDuration`, `integrityScore` (0–100), `integrityFlags` (`fetchHooked`, `prototypeModified`, `debuggerAttached`, `framingDetected`), and `behavioralSignals` (`keystrokeAvgMs`, `pasteDetected`, `completionTimeMs`, `touchVelocity`).
</ParamField>

<ParamField body="failedAttemptsCount" type="number" default="0">
  Number of failed authentication attempts (for authentication events)

  Example: `3`
</ParamField>

<ParamField body="destinationAccountId" type="string">
  Destination account identifier for transfer events (CBU, CVU, etc.)

  Example: `"0170042640000004234411"`
</ParamField>

<ParamField body="destinationCuit" type="string">
  Destination CUIT for transfer events

  Example: `"27281455496"`
</ParamField>

<ParamField body="previousValue" type="string">
  Previous value for credential change events. This will be automatically hashed using SHA-256 for security.

  Example: `"old_password_hash"`
</ParamField>

<ParamField body="metadata" type="object">
  Additional event-specific data as key-value pairs. Use this for custom fields specific to your use case.

  Example:

  ```json theme={null}
  {
    "amount": 5000,
    "currency": "ARS",
    "concept": "Payment",
    "reference": "INV-12345"
  }
  ```
</ParamField>

<ParamField body="userAgent" type="string">
  Browser user agent string for web events

  Example: `"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."`
</ParamField>

## How `isNewDevice` works

The persisted value on each event drives fraud rules (for example `historical.userEvent.newDevice` and filters like `isNewDevice: true` on `user_events`).

### Priority: your value wins when you send it

| Request                                 | Persisted `isNewDevice`                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| You send `isNewDevice: true` or `false` | **Exactly what you sent** (gu1 does not override it)                                       |
| You omit `isNewDevice`                  | gu1 **computes** a value (see below); defaults to `false` when device data is insufficient |

Use the explicit flag when your app already knows whether the session is on a new device (SDK, local storage, your own device registry). Omit it when you want gu1 to infer it from the device registry.

### When you omit `isNewDevice` (server-side inference)

gu1 only auto-computes when **both** are present:

* `deviceId`
* `deviceDetails`

Flow:

1. **Register or update** the device for the resolved entity (`devices` table).
2. Set `isNewDevice` to `true` if either:
   * No row exists yet for `(organization, entity, deviceId)`, or
   * The device exists but `firstSeenAt` is within the **last 5 minutes** (first-seen window).
3. Otherwise set `isNewDevice` to `false` (device already known to gu1 for that entity).

<Tip>
  Send `deviceId` + `deviceDetails` on login and security-sensitive events even when you set `isNewDevice` yourself, so gu1 keeps the device registry up to date for other rules and audits.
</Tip>

### Request body field name

`POST /events/user` uses **camelCase** in JSON: `isNewDevice`. The snake\_case name `is_new_device` is **not** read on this endpoint (use camelCase).

### Examples

**Client decides (recommended when you already detect new device):**

```json theme={null}
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "isNewDevice": true
}
```

**Let gu1 infer (omit the flag; include device payload):**

```json theme={null}
{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "deviceDetails": { "platform": "android", "manufacturer": "samsung", "model": "SM-A156M" }
}
```

## Event Types

<Tip>
  📋 Choose the most specific event type that matches your use case. Use `OTHER_EVENT` only when no specific type applies.
</Tip>

### Authentication Events

* `LOGIN_SUCCESS` - Successful login
* `LOGIN_FAILED` - Failed login attempt
* `LOGOUT` - User logout
* `TOKEN_GENERATED` - Authentication token generated

### Credential Change Events

* `PASSWORD_CHANGE` - Password successfully changed
* `PASSWORD_CHANGE_FAILED` - Failed password change attempt
* `EMAIL_CHANGE` - Email address changed
* `PHONE_CHANGE` - Phone number changed
* `PIN_CHANGE` - PIN changed

### Account Management Events

* `ACCOUNT_LINKED` - Bank account linked
* `CONTACT_CREATED` - Contact created
* `CONTACT_DELETED` - Contact deleted
* `ADDRESS_CHANGED` - Address updated
* `DEVICE_ADDED` - New device added
* `DEVICE_DELETED` - Device removed

### Email Management Events

* `EMAIL_CREATED` - Email created
* `EMAIL_ELIMINATED` - Email eliminated

### Navigation Events

* `NAVIGATION` - Page or screen navigation

### Transfer Events

* `TRANSFER_SUCCESS` - Successful transfer
* `TRANSFER_FAILED` - Failed transfer attempt
* `TRANSFER_SCHEDULED` - Transfer scheduled for future

### Balance Events

* `BALANCE_CHECK` - Account balance checked
* `BALANCE_CHECK_FAILED` - Balance check failed

### Account Access Events

* `ACCOUNTS_VIEW` - Accounts list viewed
* `ACCOUNTS_VIEW_FAILED` - Accounts view failed

### Transaction Events

* `TRANSACTIONS_VIEW` - Transaction history viewed
* `TRANSACTIONS_VIEW_FAILED` - Transaction view failed

### Recipient Events

* `SEARCH_RECIPIENTS` - Recipients searched
* `SEARCH_RECIPIENTS_FAILED` - Recipients search failed
* `SCHEDULE_RECIPIENT_FAILED` - Recipient scheduling failed

### Profile Events

* `PROFILE_VIEW` - User profile viewed
* `PROFILE_UPDATED` - User profile updated

### Message Events

* `MESSAGES_VIEW` - Messages viewed
* `MESSAGES_VIEW_FAILED` - Messages view failed

### Account Holder Events

* `ACCOUNT_HOLDERS_VIEW` - Account holders viewed
* `ACCOUNT_HOLDERS_VIEW_FAILED` - Account holders view failed

### Alias Events

* `ALIAS_VIEW` - Alias viewed
* `ALIAS_VIEW_FAILED` - Alias view failed
* `ALIAS_CHANGE` - Alias changed
* `ALIAS_CHANGE_FAILED` - Alias change failed

### Payment / Device Events

* `CARD_ADDED` - Payment card added
* `DEVICE_CONNECTED` - Device connected

### Biometric Validation Events

* `BIOMETRIC_VALIDATION_SUCCESS` - Biometric validation succeeded
* `BIOMETRIC_VALIDATION_ERROR` - Biometric validation failed

### SDK Events

* `SESSION_STARTED` - SDK session beacon (pre-login)
* `SESSION_IDENTIFIED` - Session bound to an entity (sent with both `sessionId` and an entity identifier)
* `SCREEN_VIEW` - Screen/navigation tracked by the SDK

### Other Events

* `OTHER_EVENT` - Custom or generic event

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="event" type="object">
  The created event object

  <ResponseField name="event.id" type="string">
    gu1's internal event UUID
  </ResponseField>

  <ResponseField name="event.eventType" type="string">
    Type of event created
  </ResponseField>

  <ResponseField name="event.userId" type="string">
    User identifier
  </ResponseField>

  <ResponseField name="event.entityId" type="string">
    Associated entity UUID
  </ResponseField>

  <ResponseField name="event.entityExternalId" type="string">
    External entity identifier
  </ResponseField>

  <ResponseField name="event.taxId" type="string">
    Tax identification number
  </ResponseField>

  <ResponseField name="event.timestamp" type="string">
    Event timestamp (ISO 8601)
  </ResponseField>

  <ResponseField name="event.eventDate" type="string">
    Business date used by historical rules for time windows (ISO 8601). Equals timestamp when not sent.
  </ResponseField>

  <ResponseField name="event.deviceId" type="string">
    Device identifier
  </ResponseField>

  <ResponseField name="event.ipAddress" type="string">
    IP address
  </ResponseField>

  <ResponseField name="event.country" type="string">
    Country code
  </ResponseField>

  <ResponseField name="event.createdAt" type="string">
    Event record creation timestamp
  </ResponseField>
</ResponseField>

<ResponseField name="entity" type="object">
  Entity information (when auto-created or existing)

  <ResponseField name="entity.id" type="string">
    Entity UUID
  </ResponseField>

  <ResponseField name="entity.wasCreated" type="boolean">
    Whether the entity was auto-created by this event
  </ResponseField>
</ResponseField>

<ResponseField name="rulesResult" type="object">
  Result of rules execution if the rules engine was triggered for this event. Includes:

  * **success** (boolean) - Whether rules executed successfully
  * **rulesTriggered** (number) - Number of rules that were triggered
  * **alerts** (array) - Alerts generated by rules
  * **riskScore** (number) - Final calculated risk score
  * **decision** (string) - Final decision (APPROVE, REJECT, HOLD, REVIEW\_REQUIRED)
  * **rulesExecutionSummary** (object) - Detailed summary; see below.
</ResponseField>

<ResponseField name="rulesExecutionSummary" type="object">
  Only present when the rules engine ran for this event. Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score. See [Rules Execution Summary](/en/api-reference/rules-execution-summary) for the full structure and a complete example.

  * **rulesHit** (array) - Rules whose conditions were met. Each item: **name**, **description**, **score**, **priority**, **category**, **status**, **conditions**, **actions**.
  * **rulesNoHit** (array) - Rules evaluated but conditions not met. Same structure as rulesHit.
  * **actionsExecuted** (object) - Aggregated executed actions: **alerts**, **suggestion**, **status**, **assignedUser**, **customKeys** (array of strings, optional) — custom action keys from rules that matched (e.g. `require_kyc`, `flag_for_review`); for integrations/workflows.
  * **totalScore** (number) - Sum of score of all rules that hit (excluding shadow).
</ResponseField>

## Examples

### Login Event

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/events/user \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "LOGIN_SUCCESS",
      "entityExternalId": "user_12345",
      "userId": "user_12345",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "deviceDetails": {
        "platform": "android",
        "manufacturer": "samsung",
        "model": "SM-A156M",
        "osVersion": "Android 16"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'LOGIN_SUCCESS',
      entityExternalId: 'user_12345',
      userId: 'user_12345',
      deviceId: '840e89e4d46efd67',
      ipAddress: '10.40.64.231',
      country: 'AR',
      deviceDetails: {
        platform: 'android',
        manufacturer: 'samsung',
        model: 'SM-A156M',
        osVersion: 'Android 16'
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/events/user',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'eventType': 'LOGIN_SUCCESS',
          'entityExternalId': 'user_12345',
          'userId': 'user_12345',
          'deviceId': '840e89e4d46efd67',
          'ipAddress': '10.40.64.231',
          'country': 'AR',
          'deviceDetails': {
              'platform': 'android',
              'manufacturer': 'samsung',
              'model': 'SM-A156M',
              'osVersion': 'Android 16'
          }
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Transfer Event

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/events/user \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "TRANSFER_SUCCESS",
      "entityExternalId": "user_12345",
      "destinationAccountId": "0170042640000004234411",
      "destinationCuit": "27281455496",
      "metadata": {
        "amount": 5000,
        "currency": "ARS",
        "concept": "Payment"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'TRANSFER_SUCCESS',
      entityExternalId: 'user_12345',
      destinationAccountId: '0170042640000004234411',
      destinationCuit: '27281455496',
      metadata: {
        amount: 5000,
        currency: 'ARS',
        concept: 'Payment'
      }
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/events/user',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'eventType': 'TRANSFER_SUCCESS',
          'entityExternalId': 'user_12345',
          'destinationAccountId': '0170042640000004234411',
          'destinationCuit': '27281455496',
          'metadata': {
              'amount': 5000,
              'currency': 'ARS',
              'concept': 'Payment'
          }
      }
  )
  ```
</CodeGroup>

### Auto-Create Entity

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.gu1.ai/events/user?withAutoEntity=true" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "eventType": "LOGIN_SUCCESS",
      "taxId": "20242455496",
      "userId": "user_12345"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/events/user?withAutoEntity=true', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventType: 'LOGIN_SUCCESS',
      taxId: '20242455496',
      userId: 'user_12345'
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/events/user?withAutoEntity=true',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'eventType': 'LOGIN_SUCCESS',
          'taxId': '20242455496',
          'userId': 'user_12345'
      }
  )
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "event": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "eventType": "LOGIN_SUCCESS",
    "userId": "user_12345",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityExternalId": "user_12345",
    "taxId": "20242455496",
    "timestamp": "2026-01-30T14:30:00Z",
    "deviceId": "840e89e4d46efd67",
    "ipAddress": "10.40.64.231",
    "country": "AR",
    "createdAt": "2026-01-30T14:30:00Z"
  },
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "wasCreated": false
  },
  "rulesResult": {
    "success": true,
    "rulesTriggered": 1,
    "alerts": [],
    "riskScore": 10,
    "decision": "APPROVE",
    "rulesExecutionSummary": {
      "rulesHit": [
        {
          "name": "Suspicious Login Pattern",
          "score": 10,
          "category": "authentication",
          "actions": ["create_alert"]
        }
      ],
      "rulesNoHit": [],
      "actionsExecuted": {
        "alerts": 0
      },
      "totalScore": 10
    }
  },
  "rulesExecutionSummary": {
    "rulesHit": [
      {
        "name": "Suspicious Login Pattern",
        "score": 10,
        "category": "authentication",
        "actions": ["create_alert"]
      }
    ],
    "rulesNoHit": [],
    "actionsExecuted": {
      "alerts": 0
    },
    "totalScore": 10
  }
}
```

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one entity identifier is required: entityId, entityExternalId, or taxId"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create events"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found. Use ?withAutoEntity=true to auto-create entities."
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "EVENT_CREATE_FAILED",
    "message": "Failed to create event"
  }
}
```

## Use Cases

### Track Authentication Patterns

```javascript theme={null}
// Track successful and failed logins
await createEvent({
  eventType: 'LOGIN_SUCCESS',
  entityExternalId: userId,
  deviceId: deviceFingerprint,
  ipAddress: req.ip
});

// Failed login with attempt count
await createEvent({
  eventType: 'LOGIN_FAILED',
  entityExternalId: userId,
  failedAttemptsCount: 3
});
```

### Monitor Transfer Activity

```javascript theme={null}
// Track transfers for fraud detection
await createEvent({
  eventType: 'TRANSFER_SUCCESS',
  entityExternalId: userId,
  destinationAccountId: destinationAccount,
  metadata: {
    amount: transferAmount,
    currency: 'ARS'
  }
});
```

### Compliance Audit Trail

```javascript theme={null}
// Track all profile changes
await createEvent({
  eventType: 'PROFILE_UPDATED',
  entityExternalId: userId,
  metadata: {
    fieldsChanged: ['email', 'phone'],
    previousEmail: 'old@example.com',
    newEmail: 'new@example.com'
  }
});
```

## Best Practices

### Always Include Timestamps

Provide explicit timestamps when events are queued or buffered to maintain accurate chronological ordering.

### Track Both Success and Failure

Always track both successful and failed events for comprehensive fraud detection and analytics.

### Use Structured Metadata

Keep metadata consistent across similar event types to enable better analysis and querying.

### Device information and `isNewDevice`

Always include `deviceId` and `deviceDetails` when available so gu1 can maintain the device registry. Set `isNewDevice` explicitly when your integration already classifies new devices; otherwise omit it and let gu1 infer (see [How `isNewDevice` works](#how-isnewdevice-works)).

### Handle Auto-Creation Carefully

Use `withAutoEntity=true` only when you're confident the tax ID is valid and you want entities created automatically.

## Next Steps

<CardGroup cols={2}>
  <Card title="List Events" icon="list" href="/en/api-reference/events/list">
    Query events with filters
  </Card>

  <Card title="Event Statistics" icon="chart-bar" href="/en/api-reference/events/stats">
    Get aggregated statistics
  </Card>

  <Card title="Devices API" icon="mobile" href="/en/api-reference/devices/overview">
    Learn about device integration
  </Card>

  <Card title="Fraud Rules" icon="shield-check" href="/en/use-cases/transaction-monitoring/fraud-detection">
    Build rules using event data
  </Card>
</CardGroup>