Register a device for an entity

Create

curl --request POST \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deviceId": "<string>",
  "entityType": "<string>",
  "entityExternalId": "<string>",
  "entityTaxId": "<string>",
  "platform": "<string>",
  "manufacturer": "<string>",
  "model": "<string>",
  "brand": "<string>",
  "deviceName": "<string>",
  "osVersion": "<string>",
  "systemName": "<string>",
  "systemVersion": "<string>",
  "browser": "<string>",
  "browserVersion": "<string>",
  "latitude": 123,
  "longitude": 123,
  "city": "<string>",
  "region": "<string>",
  "country": "<string>",
  "countryCode": "<string>",
  "ipAddress": "<string>",
  "isEmulator": true,
  "isRooted": true
}
'

{
  "success": true,
  "device": {
    "device.id": "<string>",
    "device.deviceId": "<string>",
    "device.externalId": "<string>",
    "device.entityId": "<string>",
    "device.entityExternalId": "<string>",
    "device.entityTaxId": "<string>",
    "device.platform": "<string>",
    "device.manufacturer": "<string>",
    "device.model": "<string>",
    "device.brand": "<string>",
    "device.deviceName": "<string>",
    "device.deviceDetails": {},
    "device.osName": "<string>",
    "device.osVersion": "<string>",
    "device.browser": "<string>",
    "device.browserVersion": "<string>",
    "device.latitude": 123,
    "device.longitude": 123,
    "device.city": "<string>",
    "device.region": "<string>",
    "device.country": "<string>",
    "device.countryCode": "<string>",
    "device.ipAddress": "<string>",
    "device.isEmulator": true,
    "device.isRooted": true,
    "device.isBlocked": true,
    "device.isTrusted": true,
    "device.firstSeenAt": "<string>",
    "device.lastSeenAt": "<string>",
    "device.createdAt": "<string>",
    "device.updatedAt": "<string>"
  }
}

POST

devices

entity

{entityId}

Create

curl --request POST \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deviceId": "<string>",
  "entityType": "<string>",
  "entityExternalId": "<string>",
  "entityTaxId": "<string>",
  "platform": "<string>",
  "manufacturer": "<string>",
  "model": "<string>",
  "brand": "<string>",
  "deviceName": "<string>",
  "osVersion": "<string>",
  "systemName": "<string>",
  "systemVersion": "<string>",
  "browser": "<string>",
  "browserVersion": "<string>",
  "latitude": 123,
  "longitude": 123,
  "city": "<string>",
  "region": "<string>",
  "country": "<string>",
  "countryCode": "<string>",
  "ipAddress": "<string>",
  "isEmulator": true,
  "isRooted": true
}
'

{
  "success": true,
  "device": {
    "device.id": "<string>",
    "device.deviceId": "<string>",
    "device.externalId": "<string>",
    "device.entityId": "<string>",
    "device.entityExternalId": "<string>",
    "device.entityTaxId": "<string>",
    "device.platform": "<string>",
    "device.manufacturer": "<string>",
    "device.model": "<string>",
    "device.brand": "<string>",
    "device.deviceName": "<string>",
    "device.deviceDetails": {},
    "device.osName": "<string>",
    "device.osVersion": "<string>",
    "device.browser": "<string>",
    "device.browserVersion": "<string>",
    "device.latitude": 123,
    "device.longitude": 123,
    "device.city": "<string>",
    "device.region": "<string>",
    "device.country": "<string>",
    "device.countryCode": "<string>",
    "device.ipAddress": "<string>",
    "device.isEmulator": true,
    "device.isRooted": true,
    "device.isBlocked": true,
    "device.isTrusted": true,
    "device.firstSeenAt": "<string>",
    "device.lastSeenAt": "<string>",
    "device.createdAt": "<string>",
    "device.updatedAt": "<string>"
  }
}

Overview

Manually register a device for a specific entity. This endpoint allows you to add device information when it’s not automatically captured through events, useful for data migrations, testing, or manual registration workflows.

Automatic Registration: In most cases, devices are automatically registered when you create user events with device information. Manual registration is typically only needed for:

Migrating existing device data
Testing and development
Backfilling historical device records

Endpoint

POST https://api.gu1.ai/devices/entity/{entityId}

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

entityId

string

required

UUID of the entity to associate this device with

Request Body

deviceId

string

required

Unique identifier for this device. This should be a stable identifier that persists across sessions (e.g., device fingerprint, IMEI, advertising ID)

entityType

string

Entity type for audit trail. Options: person, company. Default: "person"

entityExternalId

string

External ID of the entity (your system’s identifier). Stored denormalized on the device for queries.

entityTaxId

string

Entity’s tax ID (e.g., CUIT, CPF). Stored denormalized on the device for queries.

platform

string

Device platform. Options:

android - Android device
ios - iOS device
web - Web browser

Example: "android"

manufacturer

string

Device manufacturer name (e.g., “samsung”, “Apple”, “Google”)

model

string

Device model identifier (e.g., “SM-A156M”, “iPhone 15 Pro”, “Pixel 8”)

brand

string

Device brand name (e.g., “samsung”, “Apple”)

deviceName

string

User-defined device name or hardware name

osVersion

string

Operating system version (e.g., “Android 16”, “iOS 17.2”, “Windows 11”)

systemName

string

System name for iOS devices (e.g., “iOS”)

systemVersion

string

System version for iOS devices (e.g., “17.2”)

browser

string

Browser name for web platform (e.g., “Chrome”, “Safari”, “Firefox”)

browserVersion

string

Browser version for web platform (e.g., “120.0.6099.129”)

latitude

number

Geographic latitude coordinate (-90 to 90)Example: -34.6037

longitude

number

Geographic longitude coordinate (-180 to 180)Example: -58.3816

city

string

City name (e.g., “Buenos Aires”, “New York”, “London”)

region

string

State or province (e.g., “Buenos Aires”, “California”, “Ontario”)

country

string

Country name (e.g., “Argentina”, “United States”, “Canada”)

countryCode

string

ISO 3166-1 alpha-2 country code (e.g., “AR”, “US”, “CA”)

ipAddress

string

IP address (IPv4 or IPv6) from which the device is accessingExample: "10.40.64.231"

isEmulator

boolean

default:"false"

Whether this device is detected as an emulator or simulator

isRooted

boolean

default:"false"

Whether this device is rooted (Android) or jailbroken (iOS)

Response

success

boolean

Indicates if the request was successful

device

object

The created device object

device.id

string

gu1’s internal device UUID

device.deviceId

string

Your provided device identifier

device.externalId

string

External device identifier (same as deviceId)

device.entityId

string

UUID of the associated entity

device.entityExternalId

string

Entity’s external ID (denormalized)

device.entityTaxId

string

Entity’s tax ID (denormalized)

device.platform

string

Device platform (android, ios, web)

device.manufacturer

string

Device manufacturer

device.model

string

Device model

device.brand

string

Device brand

device.deviceName

string

User-defined device name or hardware name

device.deviceDetails

object

Additional device metadata (JSON object). Platform-specific: Android (hardware, buildId, sdkVersion), iOS (systemName, identifierForVendor), Web (userAgent, etc.)

device.osName

string

Operating system name

device.osVersion

string

Operating system version

device.browser

string

Browser name (web only)

device.browserVersion

string

Browser version (web only)

device.latitude

number

Geographic latitude

device.longitude

number

Geographic longitude

device.city

string

City name

device.region

string

State/province

device.country

string

Country name

device.countryCode

string

ISO country code

device.ipAddress

string

IP address

device.isEmulator

boolean

Emulator detection flag

device.isRooted

boolean

Root/jailbreak detection flag

device.isBlocked

boolean

Whether device is blocked

device.isTrusted

boolean

Whether device is marked as trusted

device.firstSeenAt

string

First time device was seen (ISO 8601 timestamp)

device.lastSeenAt

string

Last time device was seen (ISO 8601 timestamp)

device.createdAt

string

Device record creation timestamp

device.updatedAt

string

Device record last update timestamp

Examples

curl -X POST https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "840e89e4d46efd67",
    "platform": "android",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "osVersion": "Android 16",
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "ipAddress": "10.40.64.231"
  }'

Response Example

{
  "success": true,
  "device": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deviceId": "840e89e4d46efd67",
    "externalId": "840e89e4d46efd67",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "entityExternalId": null,
    "entityTaxId": null,
    "deviceName": null,
    "deviceDetails": {},
    "platform": "android",
    "manufacturer": "samsung",
    "model": "SM-A156M",
    "brand": "samsung",
    "osName": "Android",
    "osVersion": "Android 16",
    "browser": null,
    "browserVersion": null,
    "latitude": -34.6037,
    "longitude": -58.3816,
    "city": "Buenos Aires",
    "region": "Buenos Aires",
    "country": "Argentina",
    "countryCode": "AR",
    "ipAddress": "10.40.64.231",
    "isEmulator": false,
    "isRooted": false,
    "isBlocked": false,
    "isTrusted": false,
    "firstSeenAt": "2026-01-30T10:00:00Z",
    "lastSeenAt": "2026-01-30T10:00:00Z",
    "createdAt": "2026-01-30T10:00:00Z",
    "updatedAt": "2026-01-30T10:00:00Z"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "MISSING_DEVICE_ID",
    "message": "Device ID is required"
  }
}

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

404 Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "DEVICE_CREATE_FAILED",
    "message": "Failed to create device"
  }
}

Use Cases

Testing Fraud Rules

Create test devices with specific characteristics to verify your fraud detection rules work correctly:

// Create a suspicious device for testing
await createDevice({
  deviceId: 'test_emulator_001',
  platform: 'android',
  isEmulator: true,
  isRooted: true
});

Data Migration

Migrate historical device data from your existing system:

// Bulk import devices from legacy system
for (const legacyDevice of legacyDevices) {
  await createDevice({
    deviceId: legacyDevice.id,
    platform: legacyDevice.platform,
    manufacturer: legacyDevice.manufacturer,
    model: legacyDevice.model,
    city: legacyDevice.location.city,
    country: legacyDevice.location.country
  });
}

Manual Device Enrollment

Allow customers to manually register their devices:

// Customer manually adds a new trusted device
await createDevice({
  deviceId: deviceFingerprint,
  platform: 'web',
  browser: 'Chrome',
  browserVersion: '120.0',
  city: userLocation.city,
  country: userLocation.country
});

Next Steps

List Devices

Query devices for an entity

Events API

Auto-register devices via events

Devices API overview List devices for an entity

⌘I

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Examples

​Response Example

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Use Cases

​Testing Fraud Rules

​Data Migration

​Manual Device Enrollment

​Next Steps

List Devices

Events API

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Examples

Response Example

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Use Cases

Testing Fraud Rules

Data Migration

Manual Device Enrollment

Next Steps