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

# Register a device for an entity

> Register a device for a person or company entity in gu1 — supports device fingerprinting, fraud prevention, and downstream rule-based risk checks.

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

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

## Endpoint

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

## Authentication

Requires a valid API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="entityId" type="string" required>
  UUID of the entity to associate this device with
</ParamField>

## Request Body

<ParamField body="deviceId" type="string" required>
  Unique identifier for this device. This should be a stable identifier that persists across sessions (e.g., device fingerprint, IMEI, advertising ID)
</ParamField>

<ParamField body="entityType" type="string">
  Entity type for audit trail. Options: `person`, `company`. Default: `"person"`
</ParamField>

<ParamField body="entityExternalId" type="string">
  External ID of the entity (your system's identifier). Stored denormalized on the device for queries.
</ParamField>

<ParamField body="entityTaxId" type="string">
  Entity's tax ID (e.g., CUIT, CPF). Stored denormalized on the device for queries.
</ParamField>

<ParamField body="platform" type="string">
  Device platform. Options:

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

  Example: `"android"`
</ParamField>

<ParamField body="manufacturer" type="string">
  Device manufacturer name (e.g., "samsung", "Apple", "Google")
</ParamField>

<ParamField body="model" type="string">
  Device model identifier (e.g., "SM-A156M", "iPhone 15 Pro", "Pixel 8")
</ParamField>

<ParamField body="brand" type="string">
  Device brand name (e.g., "samsung", "Apple")
</ParamField>

<ParamField body="deviceName" type="string">
  User-defined device name or hardware name
</ParamField>

<ParamField body="osVersion" type="string">
  Operating system version (e.g., "Android 16", "iOS 17.2", "Windows 11")
</ParamField>

<ParamField body="systemName" type="string">
  System name for iOS devices (e.g., "iOS")
</ParamField>

<ParamField body="systemVersion" type="string">
  System version for iOS devices (e.g., "17.2")
</ParamField>

<ParamField body="browser" type="string">
  Browser name for web platform (e.g., "Chrome", "Safari", "Firefox")
</ParamField>

<ParamField body="browserVersion" type="string">
  Browser version for web platform (e.g., "120.0.6099.129")
</ParamField>

<ParamField body="latitude" type="number">
  Geographic latitude coordinate (-90 to 90)

  Example: `-34.6037`
</ParamField>

<ParamField body="longitude" type="number">
  Geographic longitude coordinate (-180 to 180)

  Example: `-58.3816`
</ParamField>

<ParamField body="city" type="string">
  City name (e.g., "Buenos Aires", "New York", "London")
</ParamField>

<ParamField body="region" type="string">
  State or province (e.g., "Buenos Aires", "California", "Ontario")
</ParamField>

<ParamField body="country" type="string">
  Country name (e.g., "Argentina", "United States", "Canada")
</ParamField>

<ParamField body="countryCode" type="string">
  ISO 3166-1 alpha-2 country code (e.g., "AR", "US", "CA")
</ParamField>

<ParamField body="ipAddress" type="string">
  IP address (IPv4 or IPv6) from which the device is accessing

  Example: `"10.40.64.231"`
</ParamField>

<ParamField body="isEmulator" type="boolean" default="false">
  Whether this device is detected as an emulator or simulator
</ParamField>

<ParamField body="isRooted" type="boolean" default="false">
  Whether this device is rooted (Android) or jailbroken (iOS)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="device" type="object">
  The created device object

  <ResponseField name="device.id" type="string">
    gu1's internal device UUID
  </ResponseField>

  <ResponseField name="device.deviceId" type="string">
    Your provided device identifier
  </ResponseField>

  <ResponseField name="device.externalId" type="string">
    External device identifier (same as deviceId)
  </ResponseField>

  <ResponseField name="device.entityId" type="string">
    UUID of the associated entity
  </ResponseField>

  <ResponseField name="device.entityExternalId" type="string">
    Entity's external ID (denormalized)
  </ResponseField>

  <ResponseField name="device.entityTaxId" type="string">
    Entity's tax ID (denormalized)
  </ResponseField>

  <ResponseField name="device.platform" type="string">
    Device platform (android, ios, web)
  </ResponseField>

  <ResponseField name="device.manufacturer" type="string">
    Device manufacturer
  </ResponseField>

  <ResponseField name="device.model" type="string">
    Device model
  </ResponseField>

  <ResponseField name="device.brand" type="string">
    Device brand
  </ResponseField>

  <ResponseField name="device.deviceName" type="string">
    User-defined device name or hardware name
  </ResponseField>

  <ResponseField name="device.deviceDetails" type="object">
    Additional device metadata (JSON object). Platform-specific: Android (hardware, buildId, sdkVersion), iOS (systemName, identifierForVendor), Web (userAgent, etc.)
  </ResponseField>

  <ResponseField name="device.osName" type="string">
    Operating system name
  </ResponseField>

  <ResponseField name="device.osVersion" type="string">
    Operating system version
  </ResponseField>

  <ResponseField name="device.browser" type="string">
    Browser name (web only)
  </ResponseField>

  <ResponseField name="device.browserVersion" type="string">
    Browser version (web only)
  </ResponseField>

  <ResponseField name="device.latitude" type="number">
    Geographic latitude
  </ResponseField>

  <ResponseField name="device.longitude" type="number">
    Geographic longitude
  </ResponseField>

  <ResponseField name="device.city" type="string">
    City name
  </ResponseField>

  <ResponseField name="device.region" type="string">
    State/province
  </ResponseField>

  <ResponseField name="device.country" type="string">
    Country name
  </ResponseField>

  <ResponseField name="device.countryCode" type="string">
    ISO country code
  </ResponseField>

  <ResponseField name="device.ipAddress" type="string">
    IP address
  </ResponseField>

  <ResponseField name="device.isEmulator" type="boolean">
    Emulator detection flag
  </ResponseField>

  <ResponseField name="device.isRooted" type="boolean">
    Root/jailbreak detection flag
  </ResponseField>

  <ResponseField name="device.isBlocked" type="boolean">
    Whether device is blocked
  </ResponseField>

  <ResponseField name="device.isTrusted" type="boolean">
    Whether device is marked as trusted
  </ResponseField>

  <ResponseField name="device.firstSeenAt" type="string">
    First time device was seen (ISO 8601 timestamp)
  </ResponseField>

  <ResponseField name="device.lastSeenAt" type="string">
    Last time device was seen (ISO 8601 timestamp)
  </ResponseField>

  <ResponseField name="device.createdAt" type="string">
    Device record creation timestamp
  </ResponseField>

  <ResponseField name="device.updatedAt" type="string">
    Device record last update timestamp
  </ResponseField>
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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',
      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'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          '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'
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_DEVICE_ID",
    "message": "Device ID is required"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to create devices"
  }
}
```

### 404 Not Found

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

### 500 Internal Server Error

```json theme={null}
{
  "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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="List Devices" icon="list" href="/en/api-reference/devices/list">
    Query devices for an entity
  </Card>

  <Card title="Events API" icon="bolt" href="/en/api-reference/events/create">
    Auto-register devices via events
  </Card>
</CardGroup>