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
}
'

import requests

url = "http://api.gu1.ai/devices/entity/{entityId}"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('http://api.gu1.ai/devices/entity/{entityId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/devices/entity/{entityId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/devices/entity/{entityId}"

	payload := strings.NewReader("{\n  \"deviceId\": \"<string>\",\n  \"entityType\": \"<string>\",\n  \"entityExternalId\": \"<string>\",\n  \"entityTaxId\": \"<string>\",\n  \"platform\": \"<string>\",\n  \"manufacturer\": \"<string>\",\n  \"model\": \"<string>\",\n  \"brand\": \"<string>\",\n  \"deviceName\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"systemName\": \"<string>\",\n  \"systemVersion\": \"<string>\",\n  \"browser\": \"<string>\",\n  \"browserVersion\": \"<string>\",\n  \"latitude\": 123,\n  \"longitude\": 123,\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"country\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"isEmulator\": true,\n  \"isRooted\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/devices/entity/{entityId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deviceId\": \"<string>\",\n  \"entityType\": \"<string>\",\n  \"entityExternalId\": \"<string>\",\n  \"entityTaxId\": \"<string>\",\n  \"platform\": \"<string>\",\n  \"manufacturer\": \"<string>\",\n  \"model\": \"<string>\",\n  \"brand\": \"<string>\",\n  \"deviceName\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"systemName\": \"<string>\",\n  \"systemVersion\": \"<string>\",\n  \"browser\": \"<string>\",\n  \"browserVersion\": \"<string>\",\n  \"latitude\": 123,\n  \"longitude\": 123,\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"country\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"isEmulator\": true,\n  \"isRooted\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/devices/entity/{entityId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deviceId\": \"<string>\",\n  \"entityType\": \"<string>\",\n  \"entityExternalId\": \"<string>\",\n  \"entityTaxId\": \"<string>\",\n  \"platform\": \"<string>\",\n  \"manufacturer\": \"<string>\",\n  \"model\": \"<string>\",\n  \"brand\": \"<string>\",\n  \"deviceName\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"systemName\": \"<string>\",\n  \"systemVersion\": \"<string>\",\n  \"browser\": \"<string>\",\n  \"browserVersion\": \"<string>\",\n  \"latitude\": 123,\n  \"longitude\": 123,\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"country\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"isEmulator\": true,\n  \"isRooted\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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
}
'

import requests

url = "http://api.gu1.ai/devices/entity/{entityId}"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('http://api.gu1.ai/devices/entity/{entityId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/devices/entity/{entityId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/devices/entity/{entityId}"

	payload := strings.NewReader("{\n  \"deviceId\": \"<string>\",\n  \"entityType\": \"<string>\",\n  \"entityExternalId\": \"<string>\",\n  \"entityTaxId\": \"<string>\",\n  \"platform\": \"<string>\",\n  \"manufacturer\": \"<string>\",\n  \"model\": \"<string>\",\n  \"brand\": \"<string>\",\n  \"deviceName\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"systemName\": \"<string>\",\n  \"systemVersion\": \"<string>\",\n  \"browser\": \"<string>\",\n  \"browserVersion\": \"<string>\",\n  \"latitude\": 123,\n  \"longitude\": 123,\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"country\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"isEmulator\": true,\n  \"isRooted\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/devices/entity/{entityId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deviceId\": \"<string>\",\n  \"entityType\": \"<string>\",\n  \"entityExternalId\": \"<string>\",\n  \"entityTaxId\": \"<string>\",\n  \"platform\": \"<string>\",\n  \"manufacturer\": \"<string>\",\n  \"model\": \"<string>\",\n  \"brand\": \"<string>\",\n  \"deviceName\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"systemName\": \"<string>\",\n  \"systemVersion\": \"<string>\",\n  \"browser\": \"<string>\",\n  \"browserVersion\": \"<string>\",\n  \"latitude\": 123,\n  \"longitude\": 123,\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"country\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"isEmulator\": true,\n  \"isRooted\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/devices/entity/{entityId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deviceId\": \"<string>\",\n  \"entityType\": \"<string>\",\n  \"entityExternalId\": \"<string>\",\n  \"entityTaxId\": \"<string>\",\n  \"platform\": \"<string>\",\n  \"manufacturer\": \"<string>\",\n  \"model\": \"<string>\",\n  \"brand\": \"<string>\",\n  \"deviceName\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"systemName\": \"<string>\",\n  \"systemVersion\": \"<string>\",\n  \"browser\": \"<string>\",\n  \"browserVersion\": \"<string>\",\n  \"latitude\": 123,\n  \"longitude\": 123,\n  \"city\": \"<string>\",\n  \"region\": \"<string>\",\n  \"country\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"isEmulator\": true,\n  \"isRooted\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

UUID of the entity to associate this device with

Request Body

string

required

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

string

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

string

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

string

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

string

Device platform. Options:

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

Example: "android"

string

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

string

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

string

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

string

User-defined device name or hardware name

string

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

string

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

string

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

string

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

string

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

number

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

number

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

string

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

string

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

string

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

string

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

string

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

boolean

default:"false"

Whether this device is detected as an emulator or simulator

boolean

default:"false"

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

Response

boolean

Indicates if the request was successful

object

The created device object

string

gu1’s internal device UUID

string

Your provided device identifier

string

External device identifier (same as deviceId)

string

UUID of the associated entity

string

Entity’s external ID (denormalized)

string

Entity’s tax ID (denormalized)

string

Device platform (android, ios, web)

string

Device manufacturer

string

Device model

string

Device brand

string

User-defined device name or hardware name

object

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

string

Operating system name

string

Operating system version

string

Browser name (web only)

string

Browser version (web only)

number

Geographic latitude

number

Geographic longitude

string

City name

string

State/province

string

Country name

string

ISO country code

string

IP address

boolean

Emulator detection flag

boolean

Root/jailbreak detection flag

boolean

Whether device is blocked

boolean

Whether device is marked as trusted

string

First time device was seen (ISO 8601 timestamp)

string

Last time device was seen (ISO 8601 timestamp)

string

Device record creation timestamp

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

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

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)

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
});

​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