Skip to main content

​
What are Devices?

Devices represent the physical or virtual hardware used by your entities (persons or companies) to access your application. Each device record includes detailed information about the platform, operating system, manufacturer, model, geolocation, and security flags.

​
Key Features

​
🔍 Fraud Detection

Track multiple device logins, detect suspicious patterns, and identify potential account takeovers by monitoring device usage across entities.

​
🛡️ Security Monitoring

Automatically detect emulators, rooted/jailbroken devices, VPNs, and proxies to prevent fraudulent activities and enforce security policies.

​
📍 Geolocation Tracking

Capture precise geographic information including latitude, longitude, city, region, and country for each device to detect anomalous access patterns.

​
📊 User Behavior Analytics

Analyze device fingerprints, track device changes, and build behavioral profiles to identify normal vs. suspicious patterns.

​
Device Schema

Each device record contains the following information:

​
Platform Information

  • platform - android, ios, or web
  • osName - Operating system name (e.g., “Android”, “iOS”, “Windows”)
  • osVersion - OS version (e.g., “Android 16”, “iOS 17.2”)
  • manufacturer - Device manufacturer (e.g., “samsung”, “Apple”)
  • model - Device model (e.g., “SM-A156M”, “iPhone 15 Pro”)
  • brand - Device brand
  • deviceName - User-defined device name

​
Browser Information (Web Platform)

  • browser - Browser name (e.g., “Chrome”, “Safari”)
  • browserVersion - Browser version

​
Geolocation

  • latitude - Geographic latitude (-90 to 90)
  • longitude - Geographic longitude (-180 to 180)
  • city - City name
  • region - State or province
  • country - Country name
  • countryCode - ISO 3166-1 alpha-2 code
  • ipAddress - Last known IP address

​
Security Flags

  • isEmulator - Detected as emulator or simulator
  • isRooted - Device is rooted (Android) or jailbroken (iOS)
  • isBlocked - Device has been blocked for security reasons
  • isTrusted - Device has been marked as trusted

​
Tracking

  • firstSeenAt - First time this device was seen
  • lastSeenAt - Most recent activity timestamp

​
Integration with Events

Devices are automatically registered when you create user events using the Events API. When an event includes deviceId and deviceDetails, the system will:
  1. Check if device exists - Look for an existing device record
  2. Create or update - Create a new device record or update the existing one with latest information
  3. Track activity - Update lastSeenAt timestamp
  4. Link to entity - Associate the device with the entity from the event
This automatic registration eliminates the need for manual device management in most cases.

​
Use Cases

​
Account Takeover Detection

Monitor when an entity suddenly uses a new device or multiple devices in a short time period to detect potential account takeovers.

​
Geographic Anomaly Detection

Track device locations and identify suspicious access patterns, such as logins from different countries within impossible timeframes.

​
Emulator Detection

Block or flag accounts using emulators, which are commonly associated with automation and fraud.

​
Device Fingerprinting

Build unique device profiles to track entities across sessions and detect multi-accounting or account sharing.

​
Compliance Requirements

Maintain audit trails of devices used for access, required for many compliance frameworks (PCI-DSS, SOC 2, etc.).

​
Quick Start

​
1. Automatic Registration via Events

// Devices are automatically created when you send events
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',
    deviceDetails: {
      platform: 'android',
      manufacturer: 'samsung',
      model: 'SM-A156M',
      osVersion: 'Android 16'
    },
    ipAddress: '10.40.64.231',
    city: 'Buenos Aires',
    country: 'Argentina',
    countryCode: 'AR'
  })
});

​
2. Manual Device Registration

// Or register devices manually
const response = await fetch('https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deviceId: '840e89e4d46efd67',
    platform: 'android',
    manufacturer: 'samsung',
    model: 'SM-A156M',
    osVersion: 'Android 16',
    city: 'Buenos Aires',
    country: 'Argentina',
    countryCode: 'AR'
  })
});

​
3. Query Devices

// Get all devices for an entity
const response = await fetch('https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

​
Best Practices

​
Always Include Device Information

When sending events, always include deviceId and as much device detail as possible to improve fraud detection accuracy.

​
Use Consistent Device IDs

Ensure your client applications generate stable device identifiers that persist across app launches and sessions.

​
Track Geographic Changes

Monitor the city and countryCode fields to detect suspicious location changes.

​
Review Security Flags

Regularly review devices with isEmulator: true or isRooted: true and take appropriate action.

​
Set Trust Levels

Mark known good devices as isTrusted: true to reduce false positives in your fraud rules.

​
Next Steps

Create Device

Register a device manually for an entity

List Devices

Query all devices for an entity

Events API

Learn about automatic device registration via events

Fraud Rules

Build fraud detection rules using device data