> ## 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. # User events API overview > Track user actions and behaviors for fraud detection, compliance monitoring, and analytics — for user behavior tracking and rule-based fraud detection in gu1. ## What are Events? Events represent user actions and system activities that occur within your application. Each event captures who performed the action, what they did, when it happened, and from which device and location. Events are the foundation of fraud detection, compliance monitoring, audit trails, and behavioral analytics. ## Key Features ### 🔍 Fraud Detection Detect suspicious patterns like unusual login locations, multiple failed authentication attempts, rapid credential changes, or abnormal transaction behaviors. ### 📊 Behavioral Analytics Build user behavior profiles, identify anomalies, and detect account takeovers by analyzing event sequences and patterns. ### ✅ Compliance & Audit Trails Maintain detailed audit logs of all user activities for regulatory compliance (GDPR, SOC 2, PCI-DSS) and internal investigations. ### 🤖 Auto Entity Creation Automatically create person or company entities when events are received with tax ID information, streamlining onboarding workflows. ### 📱 Device Integration Automatically register and track devices when events include device information, enabling device-based fraud rules. ## Event Schema Each event record contains: ### Core Fields * `eventType` - Type of event (see Event Types below) * `userId` - Your user identifier * `entityId` - gu1 entity UUID * `entityExternalId` - Your external entity ID * `taxId` - Tax identification number (CPF, CNPJ, etc.) * `timestamp` - When the event occurred (ISO 8601) * `eventDate` - Optional business date for the event; when set, historical rules use it as the starting point for time windows (e.g. "last 7 days"). Defaults to `timestamp` when not sent. ### Device Information * `deviceId` - Unique device identifier * `deviceDetails` - Full device specifications (platform, OS, manufacturer, model, etc.) ### Location & Network * `ipAddress` - IP address of the request * `country` - ISO 3166-1 country code * `isVpn` - VPN detection flag * `isProxy` - Proxy detection flag * `isNewDevice` - New-device flag for fraud rules. **If you send it on create, gu1 stores your value.** If omitted, gu1 infers it when `deviceId` + `deviceDetails` are present (device registry, 5-minute first-seen window). Details: [Create user event — `isNewDevice`](/en/api-reference/events/create#how-isnewdevice-works). ### Event-Specific Data * `failedAttemptsCount` - Failed authentication attempts * `destinationAccountId` - Destination account for transfers * `destinationCuit` - Destination CUIT for transfers * `previousValue` - Previous value (for change events, hashed) * `metadata` - Additional event-specific data ### Metadata * `userAgent` - Browser user agent string * `metadata` - Flexible object for custom data ## Event Types We support 45+ event types across multiple categories: ### Authentication (4 types) * `LOGIN_SUCCESS` - Successful login * `LOGIN_FAILED` - Failed login attempt * `LOGOUT` - User logout * `TOKEN_GENERATED` - Auth token generated ### Credential Changes (5 types) * `PASSWORD_CHANGE` - Password successfully changed * `PASSWORD_CHANGE_FAILED` - Failed password change * `EMAIL_CHANGE` - Email address changed * `PHONE_CHANGE` - Phone number changed * `PIN_CHANGE` - PIN changed ### Account Management (5 types) * `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 (2 types) * `EMAIL_CREATED` - Email created * `EMAIL_ELIMINATED` - Email eliminated ### Navigation (1 type) * `NAVIGATION` - Page/screen navigation ### Transfers (3 types) * `TRANSFER_SUCCESS` - Successful transfer * `TRANSFER_FAILED` - Failed transfer attempt * `TRANSFER_SCHEDULED` - Transfer scheduled ### Account Balance (2 types) * `BALANCE_CHECK` - Balance checked * `BALANCE_CHECK_FAILED` - Balance check failed ### Account Access (2 types) * `ACCOUNTS_VIEW` - Accounts viewed * `ACCOUNTS_VIEW_FAILED` - Accounts view failed ### Transaction History (2 types) * `TRANSACTIONS_VIEW` - Transactions viewed * `TRANSACTIONS_VIEW_FAILED` - Transactions view failed ### Recipients (3 types) * `SEARCH_RECIPIENTS` - Recipients searched * `SEARCH_RECIPIENTS_FAILED` - Recipients search failed * `SCHEDULE_RECIPIENT_FAILED` - Recipient scheduling failed ### Profile Management (2 types) * `PROFILE_VIEW` - Profile viewed * `PROFILE_UPDATED` - Profile updated ### Messages (2 types) * `MESSAGES_VIEW` - Messages viewed * `MESSAGES_VIEW_FAILED` - Messages view failed ### Account Holders (2 types) * `ACCOUNT_HOLDERS_VIEW` - Account holders viewed * `ACCOUNT_HOLDERS_VIEW_FAILED` - Account holders view failed ### Alias Management (4 types) * `ALIAS_VIEW` - Alias viewed * `ALIAS_VIEW_FAILED` - Alias view failed * `ALIAS_CHANGE` - Alias changed * `ALIAS_CHANGE_FAILED` - Alias change failed ### Payment / Device (2 types) * `CARD_ADDED` - Payment card added * `DEVICE_CONNECTED` - Device connected ### Biometric Validation (2 types) * `BIOMETRIC_VALIDATION_SUCCESS` - Biometric validation succeeded * `BIOMETRIC_VALIDATION_ERROR` - Biometric validation failed ### Other (1 type) * `OTHER_EVENT` - Custom/generic event ## Auto Entity Creation Events can automatically create person or company entities when: 1. You include `taxId` in the event 2. You add `?withAutoEntity=true` query parameter 3. The entity doesn't exist yet This eliminates the need to create entities separately before tracking events, streamlining your integration. ```javascript theme={null} // Entity auto-created if it doesn't exist POST /events/user?withAutoEntity=true { "eventType": "LOGIN_SUCCESS", "taxId": "20242455496", "userId": "user_12345" } ``` ## Device Registration When events include `deviceId` and `deviceDetails`, devices are automatically registered and associated with the entity. This enables: * Device fingerprinting * Multi-device detection * Location-based fraud rules * Device behavior analysis ## Quick Start ### 1. Track Login Event ```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', deviceId: '840e89e4d46efd67', ipAddress: '10.40.64.231', country: 'AR', deviceDetails: { platform: 'android', manufacturer: 'samsung', model: 'SM-A156M' } }) }); ``` ### 2. Track Transfer Event ```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' } }) }); ``` ### 3. Query Events ```javascript theme={null} const response = await fetch( 'https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); ``` ## Best Practices ### Always Include Entity Identifiers Provide at least one of: `entityId`, `entityExternalId`, or `taxId` to link events to entities. ### Use Consistent User IDs Use the same `userId` across all events for a user to build accurate behavioral profiles. ### Include Device Information Always send `deviceId` and `deviceDetails` when available to enable device-based fraud detection. ### Timestamp Precision Use ISO 8601 timestamps with timezone information for accurate event ordering and time-based analysis. ### Structured Metadata Use the `metadata` field for event-specific information but keep it structured and consistent across similar event types. ### Event Type Selection Choose the most specific event type available. Use `OTHER_EVENT` only when no specific type matches. ### Failed Event Tracking Always track both successful and failed events (e.g., `LOGIN_SUCCESS` vs `LOGIN_FAILED`) for comprehensive fraud detection. ## Integration Patterns ### Real-Time Event Streaming ```javascript theme={null} // Stream events as they occur async function trackEvent(eventType, userId, details) { try { const response = await fetch('https://api.gu1.ai/events/user', { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ eventType, entityExternalId: userId, timestamp: new Date().toISOString(), ...details }) }); if (!response.ok) { console.error('Event tracking failed:', await response.text()); } } catch (error) { console.error('Event tracking error:', error); } } ``` ### Batch Event Upload ```javascript theme={null} // For historical data migration or bulk uploads async function uploadBatchEvents(events) { for (const event of events) { await trackEvent( event.type, event.userId, { timestamp: event.timestamp, deviceId: event.deviceId, ipAddress: event.ipAddress, metadata: event.metadata } ); // Add delay to respect rate limits await new Promise(resolve => setTimeout(resolve, 100)); } } ``` ### Event Middleware ```javascript theme={null} // Centralize event tracking in middleware function eventTrackingMiddleware(eventType) { return async (req, res, next) => { // Track event before processing request await trackEvent(eventType, req.user.id, { deviceId: req.deviceId, ipAddress: req.ip, userAgent: req.headers['user-agent'] }); next(); }; } app.post('/login', eventTrackingMiddleware('LOGIN_SUCCESS'), loginHandler); ``` ## Use Cases ### Fraud Detection Rules ```javascript theme={null} // Example: Detect rapid transfers const recentTransfers = await fetch( 'https://api.gu1.ai/events/user?' + 'entity_external_id=user_12345&' + 'event_type=TRANSFER_SUCCESS&' + `start_date=${new Date(Date.now() - 3600000).toISOString()}`, // Last hour { headers: { 'Authorization': `Bearer ${API_KEY}` } } ); const data = await recentTransfers.json(); if (data.events.length > 5) { console.warn('Rapid transfer activity detected!'); } ``` ### Compliance Audit Trail ```javascript theme={null} // Generate audit report for an entity const events = await fetch( `https://api.gu1.ai/events/user/entity/${entityId}?limit=1000`, { headers: { 'Authorization': `Bearer ${API_KEY}` } } ); const auditReport = data.events.map(event => ({ timestamp: event.timestamp, action: event.eventType, user: event.userId, device: event.deviceId, location: `${event.city}, ${event.country}` })); ``` ### User Behavior Analytics ```javascript theme={null} // Analyze login patterns const stats = await fetch( 'https://api.gu1.ai/events/user/stats?user_id=user_12345', { headers: { 'Authorization': `Bearer ${API_KEY}` } } ); const loginEvents = stats.data.stats.find(s => s.event_type === 'LOGIN_SUCCESS'); console.log(`Total logins: ${loginEvents.count}`); console.log(`Last login: ${loginEvents.last_occurrence}`); ``` ## Next Steps Send events to the API Query events with filters Get aggregated event statistics Learn about device integration