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

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 - Whether this is the first time seeing this device

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 41 different event types across 11 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 - 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

Other (1 type)

OTHER_EVENT - Custom/generic event

Auto Entity Creation

Events can automatically create person or company entities when:

You include taxId in the event
You add ?withAutoEntity=true query parameter
The entity doesn’t exist yet

This eliminates the need to create entities separately before tracking events, streamlining your integration.

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

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

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

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

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

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

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

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

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

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

Create Event

Send events to the API

List Events

Query events with filters

Event Statistics

Get aggregated event statistics

Devices API

Learn about device integration

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​What are Events?

​Key Features

​🔍 Fraud Detection

​📊 Behavioral Analytics

​✅ Compliance & Audit Trails

​🤖 Auto Entity Creation

​📱 Device Integration

​Event Schema

​Core Fields

​Device Information

​Location & Network

​Event-Specific Data

​Metadata

​Event Types

​Authentication (4 types)

​Credential Changes (5 types)

​Account Management (5 types)

​Email Management (2 types)

​Navigation (1 type)

​Transfers (3 types)

​Account Balance (2 types)

​Account Access (2 types)

​Transaction History (2 types)

​Recipients (3 types)

​Profile Management (2 types)

​Messages (2 types)

​Account Holders (2 types)

​Alias Management (4 types)

​Other (1 type)

​Auto Entity Creation

​Device Registration

​Quick Start

​1. Track Login Event

​2. Track Transfer Event

​3. Query Events

​Best Practices

​Always Include Entity Identifiers

​Use Consistent User IDs

​Include Device Information

​Timestamp Precision

​Structured Metadata

​Event Type Selection

​Failed Event Tracking

​Integration Patterns

​Real-Time Event Streaming

​Batch Event Upload

​Event Middleware

​Use Cases

​Fraud Detection Rules

​Compliance Audit Trail

​User Behavior Analytics

​Next Steps

Create Event

List Events

Event Statistics

Devices API

What are Events?

Key Features

🔍 Fraud Detection

📊 Behavioral Analytics

✅ Compliance & Audit Trails

🤖 Auto Entity Creation

📱 Device Integration

Event Schema

Core Fields

Device Information

Location & Network

Event-Specific Data

Metadata

Event Types

Authentication (4 types)

Credential Changes (5 types)

Account Management (5 types)

Email Management (2 types)

Navigation (1 type)

Transfers (3 types)

Account Balance (2 types)

Account Access (2 types)

Transaction History (2 types)

Recipients (3 types)

Profile Management (2 types)

Messages (2 types)

Account Holders (2 types)

Alias Management (4 types)

Other (1 type)

Auto Entity Creation

Device Registration

Quick Start

1. Track Login Event

2. Track Transfer Event

3. Query Events

Best Practices

Always Include Entity Identifiers

Use Consistent User IDs

Include Device Information

Timestamp Precision

Structured Metadata

Event Type Selection

Failed Event Tracking

Integration Patterns

Real-Time Event Streaming

Batch Event Upload

Event Middleware

Use Cases

Fraud Detection Rules

Compliance Audit Trail

User Behavior Analytics

Next Steps