Integration Guide

Customers who have integrated the Digital Intelligence SDKs can retrieve session-level device, behavioral, and entity data by invoking the Digital Intelligence enrichment through the RiskOS™ Evaluation endpoint. The response includes the full set of Digital Intelligence enrichments—device attributes, network signals, behavioral telemetry, and entity profiling data—captured during the user session.


Example response

The following example shows an Evaluation response that includes Digital Intelligence device, behavioral, and entity profile data.

{
  "data_enrichments": [
    ...
    {
        "digitalIntelligence": {
          "device": {
            "id": "234ac3ff-3ed1-42de-8f33-8f332febfa54",
            "globalDeviceId": "8e74d510-92c6-4b51-8648-d19ab4d997a8",
            "sessionCreatedAt": "2024-12-23T18:06:52.248985937Z",
            "deviceCapturedAt": "2024-12-23T18:09:12.735992851Z",
            "computed": {
              "statisticalId": "9349d69fef75cd356744293487462f8cd912",
              "isVirtualMachine": false,
              "isTamperedAndroidBuild": true,
              "sessionAgeMinutes": 45
            },
            "network": {
              "connectionIp": "38.48.122.126",
              "forwardedForIps": [
                "78.32.11.221",
                "70.45.2.1"
              ],
              "webRtcPublicIp": "176.124.54.12",
              "webRtcInternalIp": "192.168.1.85",
              "realIp": "38.48.122.126",
              "isTor": true,
              "isProxy": true,
              "isVpn": true,
              "isConsumerPrivacy": true,
              "isRiskyNetwork": true,
              "isp": "comcast",
              "ispType": "home",
              "asn": 27364,
              "asnName": "armstrong",
              "domainName": "zoominternet.net",
              "org": "comcast",
              "isMobileCarrier": true,
              "speed": "cable",
              "networkLocation": {
                "countryCode": "US",
                "region": "WA",
                "city": "Tacoma",
                "postalCode": "98401",
                "latitude": 47.25,
                "longitude": -122.44,
                "metroCode": 819,
                "continentCode": "na",
                "timezoneName": "America/New_York",
                "gmtOffset": "-0400"
              }
            },
            "attributes": {
              "sdkVersion": "3.0.1",
              "platform": "iOS",
              "os": "iOS",
              "osVersion": "17.0",
              "deviceModel": "iphone14,7",
              "deviceManufacturer": "Apple",
              "deviceType": "tablet",
              "viewportWidth": 600,
              "viewportHeight": 400,
              "screenHeight": 1080,
              "screenWidth": 1920,
              "devicePixelRatio": 1.5,
              "network": {
                "vpnStatus": true
              },
              "location": {
                "latitude": 41.50,
                "longitude": -81.69,
                "horizontalAccuracy": 2.1,
                "altitude": 998.2,
                "verticalAccuracy": 0,
                "bearing": 32,
                "bearingAccuracy": 2.1,
                "speed": 1.3,
                "speedAccuracy": 0.2
              },
              "battery": {
                "batteryState": "charging",
                "batteryLevel": 0.47
              },
              "timeZone": "America/New_York",
              "timeZoneOffset": -480,
              "language": "en-US",
              "deviceArchitecture": "arm64",
              "applicationType": "native",
              "isEmulator": true,
              "deviceContext": "homepage",
              "androidAttributes": {
                "isRooted": true,
                "mobileNetwork": [
                  {
                    "carrierName": "T-Mobile",
                    "isoCountryCode": "us"
                  }
                ]
              },
              "iOSAttributes": {
                "isRooted": true,
                "mobileNetwork": [
                  {
                    "carrierName": "T-Mobile",
                    "isoCountryCode": "us"
                  }
                ]
              },
              "webAttributes": {
                "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/21A5291h [FBAN/FBIOS;FBDV/iPhone15,3;FBMD/iPhone;FBSN/iOS;FBSV/17.0;FBSS/3;FBID/phone;FBLC/fr_FR;FBOP/5]",
                "userAgentExtractionRequired": true,
                "browser": "Google Chrome",
                "browserVersion": "116",
                "pixelDepth": 24,
                "hardwareConcurrency": 8,
                "maxTouchPoints": 1,
                "colorDepth": 24,
                "webGlUnmaskedVendor": "Google Inc. (Apple)",
                "webGlUnmaskedRenderer": "ANGLE (Apple, ANGLE Metal Renderer: Apple M1 Pro, Unspecified Version)",
                "viewportScale": 2.7
              }
            },
            "history": {
              "firstSeen": "2023-10-24T15:55:16.368Z",
              "lastSeen": "2023-10-24T15:55:16.368Z",
              "ips": [
                "78.32.11.221",
                "70.45.2.1"
              ],
              "isps": [
                "RogersCable",
                "T-Mobile"
              ],
              "daysSeen": [
                "2023-10-24"
              ],
              "networkLocations": [
                "chicago, il",
                "new york, ny",
                "paris, fr"
              ]
            }
          },
          "behavioral": {
            "sessionId": "d34304a6-a726-4dec-b1cd-9c4a3c192a0d",
            "serverCreated": "2021-09-01T11:19:58.796Z",
            "serverUpdated": "2021-09-11T16:19:58.796Z",
            "clientUpdated": "2021-09-11T16:14:58.796Z",
            "duration": 120910,
            "source": "https://example.com/",
            "aggregations": {
              "totalEventCount": 26,
              "focusCount": 0,
              "blurCount": 3,
              "inputChangeCount": 6,
              "submissionCount": 1,
              "clickCount": 3,
              "pasteCount": 0
            }
          },
          "entityProfiler": [
            {
              "entity": "12223334444",
              "entityType": "phone",
              "profile": {
                "seenCount": 2,
                "firstSeen": "2019-08-24T14:15:22Z",
                "lastSeen": "2019-08-24T14:15:22Z",
                "deviceTypes": [
                  "phone",
                  "tablet"
                ],
                "deviceModels": [
                  "iphone14,7",
                  "GT70053G"
                ],
                "deviceisps": [
                  "comcast",
                  "t-mobile"
                ],
                "deviceLanguages": [
                  "en-us",
                  "es-us"
                ],
                "deviceTimezones": [
                  "america/new_york",
                  "america/los_angeles"
                ],
                "networkLocationStates": [
                  "ca",
                  "az"
                ],
                "networkLocationPostalCodes": [
                  "12345",
                  "56789"
                ]
              }
            },
            {
              "entity": "[email protected]",
              "entityType": "email",
              "profile": {
                "seenCount": 5,
                "firstSeen": "2020-09-10T10:22:45Z",
                "lastSeen": "2020-09-15T13:45:32Z",
                "deviceTypes": [
                  "phone",
                  "desktop"
                ],
                "deviceModels": [
                  "moto g"
                ],
                "deviceisps": [
                  "at&t"
                ],
                "deviceLanguages": [
                  "en-us"
                ],
                "deviceTimezones": [
                  "america/los_angeles"
                ],
                "networkLocationStates": [
                  "or"
                ],
                "networkLocationPostalCodes": [
                  "56789"
                ]
              }
            },
            {
              "entity": "111223333",
              "entityType": "nationalId",
              "profile": {
                "seenCount": 3,
                "firstSeen": "2023-01-15T09:30:00Z",
                "lastSeen": "2023-09-10T14:45:00Z",
                "deviceTypes": [
                  "phone",
                  "tablet"
                ],
                "deviceModels": [
                  "GT70053G"
                ],
                "deviceisps": [
                  "comcast"
                ],
                "deviceLanguages": [
                  "de_us"
                ],
                "deviceTimezones": [
                  "america/chicago"
                ],
                "networkLocationStates": [
                  "il"
                ],
                "networkLocationPostalCodes": [
                  "12345"
                ]
              }
            }
          ]
        }
      }
    }
  ]
}

Response schema

device fields

FieldTypeDescriptionExample
device.idStringUnique UUID for the device.234ac3ff-3ed1-42de-8f33-8f332febfa54
device.sessionCreatedAtStringThe time at which the session was created2024-12-23T18:06:52.248985937Z
device.deviceCapturedAtStringThe time at which device metadata was captured. If multiple captures were made against the given session, this is the most recent timestamp.2024-12-23T18:09:12.735992851Z
device.globalDeviceIdStringUnique UUID for the Global Device ID. This is the primary device ID in the Socure Identity Graph.52ea4752-d261-4f5b-9b85-4223abd8f63f

device.computed fields

Field

Type

Description

Example

device.computed.statisticalId

String

Statistical ID used for statistical relinking. Note: DO NOT USE as a unique identifier.

9349d69fef75cd356 744293487462f8cd912

device.computed.isVirtualMachine

Boolean

Set to true if the server believes the fingerprint to be sent by a virtual machine.

false

device.computed.sessionAgeMinutes

Integer

The age of the session in minutes, calculated from when the session was created to now.

45

device.computed.isTamperedAndroidBuild

Boolean

Set to true if the Android OS build is suspected to be modified or tampered with (e.g., the device is not running the standard manufacturer-provided Android build). Only reported for Android devices.

true


device.network fields

FieldTypeDescriptionExample
device.network.connectionIpStringThe IP address detected by the connection to the ingestion service.38.48.122.126
device.network.forwardedForIpsArrayThe collection of IP addresses in the X-Forwarded-For header during the ingestion request.['78.32.11.221', '70.45.2.1']
device.network.webRtcPublicIpStringThe public facing IP address as detected by WebRTC when available.176.124.54.12
device.network.webRtcInternalIpStringThe internal facing IP address as detected by WebRTC when available.192.168.1.85
device.network.realIpStringReal IP address detected in association with the lastSeen time. This address is computed to be the most specific address associated with the user. All attributes are relative to this address.38.48.122.126
device.network.isTorBooleanSet to true if the IP is a TOR exit node.
device.network.isProxyBooleanSet to true if a Proxy is detected.
device.network.isVpnBooleanSet to true if the device appears to be connected via a VPN.
device.network.isConsumerPrivacyBooleanSet to true if the device is detected to be using a consumer privacy relay such as iCloud Private Relay or Google One VPN.
device.network.isRiskyNetworkBooleanSet to true if the device appears to be part of a known high risk IP address or IP block. This is something that we will calculate.
device.network.ispStringName of the Internet Service Provider associated with the IP address.comcast
device.network.ispTypeStringReturns the type of Internet Service Providers (ISP) connection. Possible values can be 'home' or 'business'.home
device.network.asnIntegerUnique ASN (Autonomous System Numbers) identifier.27364
device.network.asnNameStringName associated to the ASN identifier.armstrong
device.network.domainNameStringDomain name associated with the IP address.zoominternet.net
device.network.orgStringName of the organization associated with the IP address.comcast
device.network.isMobileCarrierBooleanSet to true if IP appears to be associated with a mobile carrier.
device.network.speedStringProvides connection type and speed information.cable
device.network.networkLocation.countryCodeStringISO 3166-1 alpha-2 country code.US
device.network.networkLocation.regionStringState, Province, or Region 2 Char code.WA
device.network.networkLocation.cityStringCity Name.Tacoma
device.network.networkLocation.postalCodeStringPostal or ZIP code.98401
device.network.networkLocation.latitudeNumberLatitude.47.2529001
device.network.networkLocation.longitudeNumberLongitude.-122.4443
device.network.networkLocation.metroCodeIntegerMetro Code.819
device.network.networkLocation.continentCodeStringISO 2 Char (ISO-3166) Continent Codes.na
device.network.networkLocation.timezoneNameStringThe unique name of the timezone in the form "Area/Location".America/New_York
device.network.networkLocation.gmtOffsetStringThe UTC offset is the difference in hours and minutes between Coordinated Universal Time (UTC) and local solar time, at a particular place. This difference is expressed with respect to UTC and is generally shown in the format ±[hh]:[mm], ±[hh][mm], or ±[hh].-0400

device.attributes fields

FieldTypeDescriptionExample
device.attributes.sdkVersionStringThe version of the Socure SDK reporting the data.3.0.1
device.attributes.platformStringThe SDK platform used to create the platform.iOS
device.attributes.osStringThe operating system in use.iOS
device.attributes.osVersionStringThe version of the operating system in use.17.0
device.attributes.deviceModelStringThe model of the device being used.iphone14,7
device.attributes.deviceManufacturerStringThe manufacturer of the device.Apple
device.attributes.deviceTypeStringThe format of the device being used.tablet
device.attributes.viewportWidthNumberThe logical width of the viewport on native devices and the logical innerWidth of the window on web.600
device.attributes.viewportHeightNumberThe logical height of the viewport on native devices and the logical innerHeight of the window on web.400
device.attributes.screenHeightNumberThe logical height of the screen.1080
device.attributes.screenWidthNumberThe logical width of the screen.1920
device.attributes.devicePixelRatioNumberThe number of physical pixels for each logical pixel on the screen.1.5
device.attributes.networkObjectGeneral network information about the device. Note that this is different from the mobile network cellular information contained in mobileNetwork.
device.attributes.network.vpnStatusBooleantrue if the VPN is enabled, false otherwise. Note that this value is not available for web.true
device.attributes.location.latitudeNumberLatitude from GPS.41.50
device.attributes.location.longitudeNumberLongitude from GPS.-81.69
device.attributes.location.horizontalAccuracyNumberRadius of location uncertainty in meters.2.1
device.attributes.location.altitudeNumberAltitude in meters.998.2
device.attributes.location.verticalAccuracyNumberAccuracy of altitude in meters.0
device.attributes.location.bearingNumberBearing in degrees.32
device.attributes.location.bearingAccuracyNumberAccuracy of bearing in degrees.2.1
device.attributes.location.speedNumberSpeed in meters per second.1.3
device.attributes.location.speedAccuracyNumberAccuracy of speed in meters per second.0.2
device.attributes.batteryObjectInformation regarding the battery for the device.
device.attributes.battery.batteryStateStringCharging status for the battery.charging
device.attributes.battery.batteryLevelNumberBattery level where 0 is empty and 1 is full.0.47
device.attributes.timeZoneStringDevice timezone name.America/New_York
device.attributes.timeZoneOffsetNumberMinutes offset from UTC.-480
device.attributes.languageStringPrimary device language.en-US
device.attributes.deviceArchitectureStringDevice CPU architecture.arm64
device.attributes.applicationTypeStringSDK application type.native
device.attributes.isEmulatorBooleanSet to true if the device is detected to be an emulator.true
device.attributes.deviceContextStringContext passed into processDevice(...).homepage
device.attributes.androidAttributesObjectAndroid-specific device attributes (present when collected on Android).
device.attributes.androidAttributes.isRootedBooleanSet to true if the Android device is rooted.true
device.attributes.androidAttributes.mobileNetworkArrayCellular network details observed on Android devices.
device.attributes.androidAttributes.mobileNetwork[*].carrierNameStringMobile carrier name (Android).T-Mobile
device.attributes.androidAttributes.mobileNetwork[*].isoCountryCodeStringCarrier ISO country code (Android).us
device.attributes.iOSAttributesObjectiOS-specific device attributes (present when collected on iOS).
device.attributes.iOSAttributes.isRootedBooleanSet to true if the iOS device is jailbroken.true
device.attributes.iOSAttributes.mobileNetworkArrayCellular network details observed on iOS devices.
device.attributes.iOSAttributes.mobileNetwork[*].carrierNameStringMobile carrier name (iOS).T-Mobile
device.attributes.iOSAttributes.mobileNetwork[*].isoCountryCodeStringCarrier ISO country code (iOS).us
device.attributes.webAttributesObjectWeb-specific device/browser attributes (present when collected on web).
device.attributes.webAttributes.userAgentStringBrowser user agent string.Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) ...
device.attributes.webAttributes.userAgentExtractionRequiredBooleanIndicates whether user agent extraction was required.true
device.attributes.webAttributes.browserStringBrowser name.Google Chrome
device.attributes.webAttributes.browserVersionStringBrowser version.116
device.attributes.webAttributes.pixelDepthNumberPixel depth.24
device.attributes.webAttributes.hardwareConcurrencyNumberNumber of logical processors available.8
device.attributes.webAttributes.maxTouchPointsNumberMaximum touch points supported.1
device.attributes.webAttributes.colorDepthNumberColor depth.24
device.attributes.webAttributes.webGlUnmaskedVendorStringWebGL unmasked vendor string (when available).Google Inc. (Apple)
device.attributes.webAttributes.webGlUnmaskedRendererStringWebGL unmasked renderer string (when available).ANGLE (Apple, ANGLE Metal Renderer: Apple M1 Pro, Unspecified Version)
device.attributes.webAttributes.viewportScaleNumberViewport scale factor.2.7


device.networkCaptures

FieldTypeDescriptionExample
device.networkCapturesArrayContains data captured and extrapolated from captured network packets.
device.networkCaptures[*].createdAtStringISO datetime when the network capture was recorded.2024-12-23T18:09:12.735Z
device.networkCaptures[*].srcIpStringSource IP observed for the capture.38.48.122.126
device.networkCaptures[*].osStringOS observed/derived for the capture.iOS
device.networkCaptures[*].osFlavorStringOS flavor/variant (when available).iOS
device.networkCaptures[*].linkTypeStringLink/connection type observed (when available).wifi

device.history fields

Field

Type

Description

Example

device.history.firstSeen

String

The time the device profile was first seen as an ISO Date.

"2023-10-24T15:55:16.368Z"

device.history.lastSeen

String

The last time the device profile was seen as an ISO Date.

"2023-10-24T15:55:16.368Z"

device.history.ips

Array

Last 20 unique IPs, sorted from oldest to newest. Note if an IP was observed multiple times then only the most recent occurrence of the IP will be recorded.

['78.32.11.221', '70.45.2.1']

device.history.isps

Array

Last 20 unique ISPs, sorted from oldest to newest. Note if an ISP was observed multiple times then only the most recent occurrence of the ISP will be recorded.

['RogersCable', 'T-Mobile']

device.history.daysSeen

Array

Dates corresponding to the last 20 times the device was seen, sorted from oldest to newest. If a device was observed multiple times during a day then only one record for the day will be recorded.

"2023-10-24"

device.history.networkLocations

Array

Last 20 unique city/region level location trail based on IP geo data. Note if a location was observed multiple times then only the most recent occurrence of the location will be recorded.

['chicago, il', 'new york, ny', 'paris, fr']


behavioral fields

FieldTypeDescriptionExample
behavioral.sessionIdStringSession ID generated by Device utilized to identify a unique user session.d34304a6-a726-4dec-b1cd-9c4a3c192a0d
behavioral.serverCreatedStringThe ISO datetime for when the server first processed an event for this session.2021-09-01T11:19:58.796Z
behavioral.serverUpdatedStringThe ISO datetime for when the server last processed an event for this session.2021-09-11T16:19:58.796Z
behavioral.clientUpdatedStringThe browser or mobile app based ISO datetime for the last event submitted.2021-09-11T16:14:58.796Z
behavioral.durationIntegerThe entire duration of the session in milliseconds.120910
behavioral.sourceStringWhere the user originated from when the session began also known as the referrer.https://example.com/
behavioral.aggregations.totalEventCountIntegerThe combined number of events that occurred during the session.26
behavioral.aggregations.focusCountIntegerThe number of times a form field gained focus (became the active element) during the session.0
behavioral.aggregations.blurCountIntegerThe number of times a form field lost focus (no longer the active element) during the session.3
behavioral.aggregations.inputChangeCountIntegerThe number of times the value of a form input field was changed during the session.6
behavioral.aggregations.submissionCountIntegerThe number of times an HTML form was submitted during the session. Only occurs on Web.1
behavioral.aggregations.clickCountIntegerThe number of times a form element was clicked during the session.3
behavioral.aggregations.pasteCountIntegerThe number of times a value was pasted into a form field during the session.0

latestNavigationContexts fields

FieldTypeDescriptionExample
latestNavigationContextsArraySummary of behavioral data for the latest occurrence of each navigation context.
latestNavigationContexts[*].tabIdStringTab/context identifier.9c2d…
latestNavigationContexts[*].combinedContextStringCombined navigation context./checkout#step1
latestNavigationContexts[*].estimatedStartTimestampStringEstimated ISO start timestamp.2024-12-23T18:07:01.000Z
latestNavigationContexts[*].timeInContextNumberTime spent in this context.12.4
latestNavigationContexts[*].timeInForegroundNumberTime spent in foreground.9.8
latestNavigationContexts[*].ipAddressesArrayIPs observed in this context.
latestNavigationContexts[*].ipAddresses[*]StringAn observed IP address.38.48.122.126
latestNavigationContexts[*].submissionCountNumberSubmissions observed in this context.1
latestNavigationContexts[*].backgroundCountNumberBackground transitions in this context.0

entityProfiler fields

Field

Type

Description

Example

entityProfiler.entity

String

The unique identifier for the entity (e.g., email or phone number).

[email protected]

entityProfiler.entityType

String

The type of the entity.

phone

entityProfiler.profile.seenCount

Integer

The number of times the entity has been seen in the system.

5

entityProfiler.profile.firstSeen

String

The first time the entity was observed in the system.

2019-08-24T14:15:22Z

entityProfiler.profile.lastSeen

String

The last time the entity was observed in the system.

2019-08-24T14:15:22Z

entityProfiler.profile.deviceTypes

Array

The most recent device types associated with the entity.

['phone', 'tablet']

entityProfiler.profile.deviceModels

Array

The most recent device models associated with the entity.

['iphone14,7', 'GT70053G']

entityProfiler.profile.deviceisps

Array

The most recent ISPs (Internet Service Providers) associated with the entity.

['comcast', 't-mobile']

entityProfiler.profile.deviceLanguages

Array

The most recent device languages associated with the entity.

['en-us', 'es-us']

entityProfiler.profile.deviceTimezones

Array

The most recent timezones associated with the entity.

['America/New_York', 'Asia/Kolkata']

entityProfiler.profile.networkLocationStates

Array

The most recent states inferred from the entity's network location.

['ca', 'az']

entityProfiler.profile.networkLocationPostalCodes

Array

The most recent postal codes inferred from the entity's network location.

['12345', '56789']


velocityMetrics fields

FieldTypeDescriptionExample
velocityMetricsObjectDevice-level historical velocity metrics associated with the Digital Intelligence profile.
velocityMetrics.historicalCountObjectHistorical unique count and share metrics grouped by entity attribute.
velocityMetrics.historicalCount.firstNameObjectHistorical velocity metrics related to first name usage on this device.
velocityMetrics.historicalCount.firstName.uniqueCountIntegerUnique first names seen for this device historically.1
velocityMetrics.historicalCount.firstName.uniqueSharePercentIntegerPercentage of transactions matching the most frequently seen first name.100
velocityMetrics.historicalCount.surNameObjectHistorical velocity metrics related to surname usage on this device.
velocityMetrics.historicalCount.surName.uniqueCountIntegerUnique surnames seen for this device historically.1
velocityMetrics.historicalCount.surName.uniqueSharePercentIntegerPercentage of transactions matching the most frequently seen surname.100
velocityMetrics.historicalCount.emailObjectHistorical velocity metrics related to email usage on this device.
velocityMetrics.historicalCount.email.uniqueCountIntegerUnique emails seen for this device historically.2
velocityMetrics.historicalCount.email.uniqueSharePercentIntegerPercentage of transactions matching the most frequently seen email.87
velocityMetrics.historicalCount.mobileNumberObjectHistorical velocity metrics related to mobile number usage on this device.
velocityMetrics.historicalCount.mobileNumber.uniqueCountIntegerUnique mobile numbers seen for this device historically.1
velocityMetrics.historicalCount.mobileNumber.uniqueSharePercentIntegerPercentage of transactions matching the most frequently seen mobile number.100