User Device Registration

Register or update a user’s device information. This endpoint is typically called during transaction requests to maintain device tracking and security measures.

Note

If you don’t have your own device/IP info, we also offer an external device fingerprinting SDK that provides enhanced device identification capabilities and seamless integration with our API. Contact our team at support@orca-fraud.com to get more info.

API Endpoint

URL: /v1/userDevice
Method: POST

Request Body

The request must include a JSON payload with the device details:


{
  "id": "DEVICE123",
  "userId": "USER123",
  "deviceId": "iPhone13-UDID789",
  "name": "John's iPhone",
  "type": "mobile",
  "sessionKey": "session_123",
  "host": "johns-iphone.local",
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15",
  "remoteIP": "192.168.1.1",
  "status": "active",
  "createdAt": 1734167723000
}

Response

A successful request returns a 200 status code with the registered device details:


{
  "id": "DEVICE123",
  "userId": "USER123",
  "deviceId": "iPhone13-UDID789",
  "name": "John's iPhone",
  "type": "mobile",
  "sessionKey": "session_123",
  "host": "johns-iphone.local",
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15",
  "remoteIP": "192.168.1.1",
  "status": "active",
  "lastSeen": 1734167723000,
  "firstSeen": 1734167723000,
  "createdAt": 1734167723000
}

Error Response Format

See the Error Reference section for a full description of API errors. All API errors follow a consistent JSON structure:


{
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error description",
    "details": ["Additional error details (optional)"]
  },
  "timestamp": 1755602195137
}

In the case of a validation error, the format will be as follows:


{
    "error": {
        "type": "VALIDATION_ERROR",
        "message": "Request validation failed",
        "details": [
            "/id: Expected string"
        ]
    },
    "timestamp": 1755602195137
}

Schema Definition

UserDevice

Property	Type	Required	Description
id	string	Yes	Unique identifier for the device registration
userId	string	Yes	User identifier
deviceId	string	Yes	Unique device identifier
name	string	No	Name of the device
type	string	No	Type of device (e.g., mobile, desktop)
fingerprint	string	No	Unique device fingerprint identifier
sessionKey	string	No	Unique session identifier
source	string	No	Fingerprinting provider (e.g., SHIELD, FingerprintJS)
host	string	No	Hostname of the device
userAgent	string	No	User agent of the device
remoteIP	string	No	Remote IP address of the device
status	string	Yes	Device status (ACTIVE, BLOCKED, SUSPICIOUS)
lastSeen	number	No	Unix timestamp in milliseconds
firstSeen	number	No	Unix timestamp in milliseconds
createdAt	number	Yes	Unix timestamp in milliseconds that device entity was created