Create a user event for rules and fraud detection

curl --request POST \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "userId": "<string>",
  "entityId": "<string>",
  "entityExternalId": "<string>",
  "taxId": "<string>",
  "timestamp": "<string>",
  "eventDate": "<string>",
  "deviceId": "<string>",
  "deviceDetails": {},
  "ipAddress": "<string>",
  "country": "<string>",
  "isVpn": true,
  "isProxy": true,
  "isNewDevice": true,
  "failedAttemptsCount": 123,
  "destinationAccountId": "<string>",
  "destinationCuit": "<string>",
  "previousValue": "<string>",
  "metadata": {},
  "userAgent": "<string>"
}
'

{
  "success": true,
  "event": {
    "event.id": "<string>",
    "event.eventType": "<string>",
    "event.userId": "<string>",
    "event.entityId": "<string>",
    "event.entityExternalId": "<string>",
    "event.taxId": "<string>",
    "event.timestamp": "<string>",
    "event.eventDate": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  },
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

events

user

Create a user event for rules and fraud detection

curl --request POST \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "userId": "<string>",
  "entityId": "<string>",
  "entityExternalId": "<string>",
  "taxId": "<string>",
  "timestamp": "<string>",
  "eventDate": "<string>",
  "deviceId": "<string>",
  "deviceDetails": {},
  "ipAddress": "<string>",
  "country": "<string>",
  "isVpn": true,
  "isProxy": true,
  "isNewDevice": true,
  "failedAttemptsCount": 123,
  "destinationAccountId": "<string>",
  "destinationCuit": "<string>",
  "previousValue": "<string>",
  "metadata": {},
  "userAgent": "<string>"
}
'

{
  "success": true,
  "event": {
    "event.id": "<string>",
    "event.eventType": "<string>",
    "event.userId": "<string>",
    "event.entityId": "<string>",
    "event.entityExternalId": "<string>",
    "event.taxId": "<string>",
    "event.timestamp": "<string>",
    "event.eventDate": "<string>",
    "event.deviceId": "<string>",
    "event.ipAddress": "<string>",
    "event.country": "<string>",
    "event.createdAt": "<string>"
  },
  "entity": {
    "entity.id": "<string>",
    "entity.wasCreated": true
  },
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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.

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

Endpoint

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

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

withAutoEntity

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

Request Body

eventType

string

required

Type of event being tracked. Must be one of the supported event types (see Event Types section below), including authentication, transfers, biometric validation, and more.Example: "LOGIN_SUCCESS"

userId

string

Your internal user identifier. Used to group events by user across different entities.Example: "user_12345"

entityId

string

gu1’s entity UUID. Provide this if you have the internal gu1 ID.

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.

entityExternalId

string

Your external entity identifier. This is your unique ID for the entity in your system.Example: "user_12345"

taxId

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"

timestamp

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"

eventDate

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.

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

deviceId

string

Unique identifier for the device. This should be a stable identifier that persists across sessions.Example: "840e89e4d46efd67"

deviceDetails

object

Detailed device information. When provided, the device will be automatically registered or updated.Structure:

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

ipAddress

string

IP address from which the event originated (IPv4 or IPv6).Example: "10.40.64.231"

country

string

ISO 3166-1 alpha-2 country code where the event occurred.Example: "AR"

isVpn

boolean

default:"false"

Whether the connection is through a VPN

isProxy

boolean

default:"false"

Whether the connection is through a proxy

isNewDevice

boolean

New device flag stored on the event (is_new_device in the database). See How isNewDevice works below.

failedAttemptsCount

number

default:"0"

Number of failed authentication attempts (for authentication events)Example: 3

destinationAccountId

string

Destination account identifier for transfer events (CBU, CVU, etc.)Example: "0170042640000004234411"

destinationCuit

string

Destination CUIT for transfer eventsExample: "27281455496"

previousValue

string

Previous value for credential change events. This will be automatically hashed using SHA-256 for security.Example: "old_password_hash"

metadata

object

Additional event-specific data as key-value pairs. Use this for custom fields specific to your use case.Example:

{
  "amount": 5000,
  "currency": "ARS",
  "concept": "Payment",
  "reference": "INV-12345"
}

userAgent

string

Browser user agent string for web eventsExample: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."

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:

Register or update the device for the resolved entity (devices table).
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).
Otherwise set isNewDevice to false (device already known to gu1 for that entity).

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.

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

{
  "eventType": "LOGIN_SUCCESS",
  "taxId": "20242455496",
  "deviceId": "840e89e4d46efd67",
  "isNewDevice": true
}

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

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

Event Types

📋 Choose the most specific event type that matches your use case. Use OTHER_EVENT only when no specific type applies.

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

Other Events

OTHER_EVENT - Custom or generic event

Response

success

boolean

Indicates if the request was successful

event

object

The created event object

event.id

string

gu1’s internal event UUID

event.eventType

string

Type of event created

event.userId

string

User identifier

event.entityId

string

Associated entity UUID

event.entityExternalId

string

External entity identifier

event.taxId

string

Tax identification number

event.timestamp

string

Event timestamp (ISO 8601)

event.eventDate

string

Business date used by historical rules for time windows (ISO 8601). Equals timestamp when not sent.

event.deviceId

string

Device identifier

event.ipAddress

string

IP address

event.country

string

Country code

event.createdAt

string

Event record creation timestamp

entity

object

Entity information (when auto-created or existing)

entity.id

string

Entity UUID

entity.wasCreated

boolean

Whether the entity was auto-created by this event

rulesResult

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.

rulesExecutionSummary

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

Examples

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

Transfer Event

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

Auto-Create Entity

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

Response Example

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

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

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create events"
  }
}

404 Not Found

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

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "EVENT_CREATE_FAILED",
    "message": "Failed to create event"
  }
}

Use Cases

Track Authentication Patterns

// 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

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

Compliance Audit Trail

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

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

List Events

Query events with filters

Event Statistics

Get aggregated statistics

Devices API

Learn about device integration

Fraud Rules

Build rules using event data

User events API overview List user events

⌘I

​Overview

​Endpoint

​Authentication

​Query Parameters

​Request Body

​How isNewDevice works

​Priority: your value wins when you send it

​When you omit isNewDevice (server-side inference)

​Request body field name

​Examples

​Event Types

​Authentication Events

​Credential Change Events

​Account Management Events

​Email Management Events

​Navigation Events

​Transfer Events

​Balance Events

​Account Access Events

​Transaction Events

​Recipient Events

​Profile Events

​Message Events

​Account Holder Events

​Alias Events

​Payment / Device Events

​Biometric Validation Events

​Other Events

​Response

​Examples

​Login Event

​Transfer Event

​Auto-Create Entity

​Response Example

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Use Cases

​Track Authentication Patterns

​Monitor Transfer Activity

​Compliance Audit Trail

​Best Practices

​Always Include Timestamps

​Track Both Success and Failure

​Use Structured Metadata

​Device information and isNewDevice

​Handle Auto-Creation Carefully

​Next Steps

List Events

Event Statistics

Devices API

Fraud Rules

Overview

Endpoint

Authentication

Query Parameters

Request Body

How `isNewDevice` works

Priority: your value wins when you send it

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

Request body field name

Examples

Event Types

Authentication Events

Credential Change Events

Account Management Events

Email Management Events

Navigation Events

Transfer Events

Balance Events

Account Access Events

Transaction Events

Recipient Events

Profile Events

Message Events

Account Holder Events

Alias Events

Payment / Device Events

Biometric Validation Events

Other Events

Response

Examples

Login Event

Transfer Event

Auto-Create Entity

Response Example

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Use Cases

Track Authentication Patterns

Monitor Transfer Activity

Compliance Audit Trail

Best Practices

Always Include Timestamps

Track Both Success and Failure

Use Structured Metadata

Device information and `isNewDevice`

Handle Auto-Creation Carefully

Next Steps