Skip to Content
B2C APIUser Device Endpoints

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",
  "fingerprint": "fp_123",
  "name": "John's iPhone",
  "type": "mobile",
  "platform": "iOS",
  "sessionKey": "session_123",
  "source": "FingerprintJS",
  "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",
  "ipAddress": "192.168.1.1",
  "ipCountry": "US",
  "gpsCountry": "US",
  "ipCoordinates": "37.7749,-122.4194",
  "gpsCoordinates": "37.7750,-122.4195",
  "status": "ACTIVE",
  "lastLoginAttempt": 1734167723000,
  "lastLoginSuccess": true,
  "lastSeen": 1734167723000,
  "firstSeen": 1734167723000,
  "city": "San Francisco",
  "region": "California",
  "postalCode": "94103",
  "country": "US",
  "operatingSystemName": "iOS",
  "operatingSystemVersion": "15.0",
  "deviceModel": "iPhone 13",
  "browserName": "Safari",
  "browserVersion": "15.0",
  "timezone": "America/Los_Angeles",
  "deviceAgeHours": 720,
  "isEmulator": false,
  "isRemoteSoftware": false,
  "isRooted": false,
  "isTamperedApp": false,
  "isProxy": false,
  "isTor": false,
  "isIncognito": false,
  "isVPN": false,
  "isSpoofed": false,
  "isBot": false,
  "isBogon": false,
  "isDatacenter": false,
  "isKnownAttacker": false,
  "isKnownAbuser": false,
  "isIcloudRelay": false,
  "debuggerConnected": false,
  "fingerprintConfidence": 0.95,
  "asnNumber": "AS16509",
  "asnName": "Amazon.com, Inc.",
  "asnType": "hosting",
  "asnRoute": "203.0.113.0/24",
  "carrierCountryCode": "655",
  "carrierNetworkCode": "01",
  "carrierName": "Vodacom",
  "vpnRiskLevel": "low",
  "proxyRiskLevel": "low",
  "threatRiskLevel": "low",
  "overallRiskLevel": "low",
  "ipType": "residential",
  "sessionIpCount": 1,
  "countryCount": 1,
  "distractionCount": 0
}

Response

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

{
  "id": "DEVICE123",
  "userId": "USER123",
  "deviceId": "iPhone13-UDID789",
  "fingerprint": "fp_123",
  "name": "John's iPhone",
  "type": "mobile",
  "platform": "iOS",
  "sessionKey": "session_123",
  "source": "FingerprintJS",
  "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",
  "ipAddress": "192.168.1.1",
  "ipCountry": "US",
  "gpsCountry": "US",
  "ipCoordinates": "37.7749,-122.4194",
  "gpsCoordinates": "37.7750,-122.4195",
  "status": "ACTIVE",
  "lastLoginAttempt": 1734167723000,
  "lastLoginSuccess": true,
  "lastSeen": 1734167723000,
  "firstSeen": 1734167723000,
  "city": "San Francisco",
  "region": "California",
  "postalCode": "94103",
  "country": "US",
  "operatingSystemName": "iOS",
  "operatingSystemVersion": "15.0",
  "deviceModel": "iPhone 13",
  "browserName": "Safari",
  "browserVersion": "15.0",
  "timezone": "America/Los_Angeles",
  "deviceAgeHours": 720,
  "isEmulator": false,
  "isRemoteSoftware": false,
  "isRooted": false,
  "isTamperedApp": false,
  "isProxy": false,
  "isTor": false,
  "isIncognito": false,
  "isVPN": false,
  "isSpoofed": false,
  "isBot": false,
  "isBogon": false,
  "isDatacenter": false,
  "isKnownAttacker": false,
  "isKnownAbuser": false,
  "isIcloudRelay": false,
  "debuggerConnected": false,
  "fingerprintConfidence": 0.95,
  "asnNumber": "AS16509",
  "asnName": "Amazon.com, Inc.",
  "asnType": "hosting",
  "asnRoute": "203.0.113.0/24",
  "carrierCountryCode": "655",
  "carrierNetworkCode": "01",
  "carrierName": "Vodacom",
  "vpnRiskLevel": "low",
  "proxyRiskLevel": "low",
  "threatRiskLevel": "low",
  "overallRiskLevel": "low",
  "ipType": "residential",
  "sessionIpCount": 1,
  "countryCount": 1,
  "distractionCount": 0
}

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

PropertyTypeRequiredDescription
idstringNoUnique identifier for the device entity
deviceIdstringNoUnique device identifier
userIdstringYesUser identifier
fingerprintstringNoUnique device fingerprint identifier
sessionKeystringNoUnique session identifier
namestringNoName of the device
typestringNoType of device (e.g., mobile, desktop)
platformstringNoDevice platform (e.g., iOS, Android, Web)
sourcestringNoFingerprinting provider (e.g., SHIELD, FingerprintJS)
hoststringNoHostname of the device
userAgentstringNoUser agent of the device
remoteIPstringNoDeprecated. Remote IP address of the device. Use ipAddress instead
ipAddressstringNoIP address of the device
ipCountrystringNoCountry derived from IP address. ISO 3166-1 alpha-2 (e.g., ZA, US, GB)
gpsCountrystringNoCountry derived from GPS coordinates. ISO 3166-1 alpha-2 (e.g., ZA, US, GB)
ipCoordinatesstringNoCoordinates derived from IP geolocation. Formatted as "lat,lon" (e.g., "-26.2041,28.0473")
gpsCoordinatesstringNoCoordinates from device GPS. Formatted as "lat,lon" (e.g., "-26.2041,28.0473")
statusstringNoDevice status (ACTIVE, BLOCKED, SUSPICIOUS)
lastLoginAttemptnumberNoUnix timestamp in milliseconds of last login attempt
lastLoginSuccessbooleanNoWhether the last login attempt succeeded
lastSeennumberNoUnix timestamp in milliseconds
firstSeennumberNoUnix timestamp in milliseconds
createdAtnumberNoUnix timestamp in milliseconds that device entity was created
updatedAtnumberNoUnix timestamp in milliseconds when last updated

Location Fields

PropertyTypeRequiredDescription
citystringNoCity of the device (e.g., Cape Town)
regionstringNoRegion/state of the device (e.g., Western Cape)
postalCodestringNoPostal/ZIP code of the device (e.g., 7701)
countrystringNoCountry code (supported country). ISO 3166-1 alpha-2 (e.g., ZA, US, GB)

Device Signal Fields

These fields are flat on the request but mapped to a deviceSignals nested object internally.

PropertyTypeRequiredDescription
operatingSystemNamestringNoOperating system name
operatingSystemVersionstringNoOperating system version
deviceModelstringNoDevice model name
browserNamestringNoBrowser name
browserVersionstringNoBrowser version
timezonestringNoDevice timezone (e.g., America/Los_Angeles)
deviceAgeHoursnumberNoDevice age in hours
isEmulatorbooleanNoWhether the device is an emulator
isRemoteSoftwarebooleanNoWhether remote software is detected
isRootedbooleanNoWhether the device is rooted/jailbroken
isTamperedAppbooleanNoWhether the app has been tampered with
isProxybooleanNoWhether a proxy is detected
isTorbooleanNoWhether Tor is detected
isIncognitobooleanNoWhether incognito/private mode is active
isVPNbooleanNoWhether a VPN is detected
isSpoofedbooleanNoWhether spoofing is detected
isBotbooleanNoWhether a bot is detected
debuggerConnectedbooleanNoWhether a debugger is connected

Security Signal Fields

These fields are flat on the request but mapped to a securitySignals nested object internally.

PropertyTypeRequiredDescription
fingerprintConfidencenumberNoConfidence score for the fingerprint (0–1)
vpnRiskLevelstringNoVPN risk level (low, medium_low, medium, high, very_high)
proxyRiskLevelstringNoProxy risk level (low, medium_low, medium, high, very_high)
threatRiskLevelstringNoThreat risk level (low, medium_low, medium, high, very_high)
overallRiskLevelstringNoOverall risk level (low, medium_low, medium, high, very_high)
behaviorBiometricLevelstringNoBehavior biometric risk level (low, medium, high)
remoteAccessLevelstringNoRemote access risk level (low, medium, high)
osAnomalyLevelstringNoOS anomaly risk level (low, medium, high)

Network Fields

These fields are flat on the request but mapped to a networkInfo nested object internally.

PropertyTypeRequiredDescription
ipTypestringNoIP address type (e.g., residential, datacenter)
sessionIpCountnumberNoNumber of IPs observed in the session
countryCountnumberNoNumber of distinct countries observed
isKnownAttackerbooleanNoWhether the IP is a known attacker
isKnownAbuserbooleanNoWhether the IP is a known abuser
isIcloudRelaybooleanNoWhether the IP is an iCloud Private Relay exit node
isBogonbooleanNoWhether the IP is a bogon (unallocated/reserved) address
isDatacenterbooleanNoWhether the IP belongs to a datacenter
asnNumberstringNoASN identifier of the IP (e.g., AS16509)
asnNamestringNoOrganisation name associated with the ASN
asnTypestringNoASN type (hosting, isp, cdn, edu, gov, mil, business)
asnRoutestringNoCIDR network prefix associated with the ASN (e.g., 203.0.113.0/24)
carrierCountryCodestringNo3-digit Mobile Country Code (MCC) of the carrier (e.g., 655 for South Africa)
carrierNetworkCodestringNo2–3 digit Mobile Network Code (MNC) of the carrier (e.g., 01 for Vodacom ZA)
carrierNamestringNoName of the mobile carrier

Biometric Fields

These fields are flat on the request but mapped to a biometrics nested object internally.

PropertyTypeRequiredDescription
distractionCountnumberNoNumber of distractions detected during the session
Last updated on
User EndpointsPayment Instrument Endpoints