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
device fields| Field | Type | Description | Example |
|---|---|---|---|
device.id | String | Unique UUID for the device. | 234ac3ff-3ed1-42de-8f33-8f332febfa54 |
device.sessionCreatedAt | String | The time at which the session was created | 2024-12-23T18:06:52.248985937Z |
device.deviceCapturedAt | String | The 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.globalDeviceId | String | Unique 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
device.computed fieldsField | Type | Description | Example |
|---|---|---|---|
| String | Statistical ID used for statistical relinking. Note: DO NOT USE as a unique identifier. |
|
| Boolean | Set to |
|
| Integer | The age of the session in minutes, calculated from when the session was created to now. |
|
| Boolean | Set to |
|
device.network fields
device.network fields| Field | Type | Description | Example |
|---|---|---|---|
device.network.connectionIp | String | The IP address detected by the connection to the ingestion service. | 38.48.122.126 |
device.network.forwardedForIps | Array | The collection of IP addresses in the X-Forwarded-For header during the ingestion request. | ['78.32.11.221', '70.45.2.1'] |
device.network.webRtcPublicIp | String | The public facing IP address as detected by WebRTC when available. | 176.124.54.12 |
device.network.webRtcInternalIp | String | The internal facing IP address as detected by WebRTC when available. | 192.168.1.85 |
device.network.realIp | String | Real 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.isTor | Boolean | Set to true if the IP is a TOR exit node. | |
device.network.isProxy | Boolean | Set to true if a Proxy is detected. | |
device.network.isVpn | Boolean | Set to true if the device appears to be connected via a VPN. | |
device.network.isConsumerPrivacy | Boolean | Set 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.isRiskyNetwork | Boolean | Set 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.isp | String | Name of the Internet Service Provider associated with the IP address. | comcast |
device.network.ispType | String | Returns the type of Internet Service Providers (ISP) connection. Possible values can be 'home' or 'business'. | home |
device.network.asn | Integer | Unique ASN (Autonomous System Numbers) identifier. | 27364 |
device.network.asnName | String | Name associated to the ASN identifier. | armstrong |
device.network.domainName | String | Domain name associated with the IP address. | zoominternet.net |
device.network.org | String | Name of the organization associated with the IP address. | comcast |
device.network.isMobileCarrier | Boolean | Set to true if IP appears to be associated with a mobile carrier. | |
device.network.speed | String | Provides connection type and speed information. | cable |
device.network.networkLocation.countryCode | String | ISO 3166-1 alpha-2 country code. | US |
device.network.networkLocation.region | String | State, Province, or Region 2 Char code. | WA |
device.network.networkLocation.city | String | City Name. | Tacoma |
device.network.networkLocation.postalCode | String | Postal or ZIP code. | 98401 |
device.network.networkLocation.latitude | Number | Latitude. | 47.2529001 |
device.network.networkLocation.longitude | Number | Longitude. | -122.4443 |
device.network.networkLocation.metroCode | Integer | Metro Code. | 819 |
device.network.networkLocation.continentCode | String | ISO 2 Char (ISO-3166) Continent Codes. | na |
device.network.networkLocation.timezoneName | String | The unique name of the timezone in the form "Area/Location". | America/New_York |
device.network.networkLocation.gmtOffset | String | The 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
device.attributes fields| Field | Type | Description | Example |
|---|---|---|---|
device.attributes.sdkVersion | String | The version of the Socure SDK reporting the data. | 3.0.1 |
device.attributes.platform | String | The SDK platform used to create the platform. | iOS |
device.attributes.os | String | The operating system in use. | iOS |
device.attributes.osVersion | String | The version of the operating system in use. | 17.0 |
device.attributes.deviceModel | String | The model of the device being used. | iphone14,7 |
device.attributes.deviceManufacturer | String | The manufacturer of the device. | Apple |
device.attributes.deviceType | String | The format of the device being used. | tablet |
device.attributes.viewportWidth | Number | The logical width of the viewport on native devices and the logical innerWidth of the window on web. | 600 |
device.attributes.viewportHeight | Number | The logical height of the viewport on native devices and the logical innerHeight of the window on web. | 400 |
device.attributes.screenHeight | Number | The logical height of the screen. | 1080 |
device.attributes.screenWidth | Number | The logical width of the screen. | 1920 |
device.attributes.devicePixelRatio | Number | The number of physical pixels for each logical pixel on the screen. | 1.5 |
device.attributes.network | Object | General network information about the device. Note that this is different from the mobile network cellular information contained in mobileNetwork. | |
device.attributes.network.vpnStatus | Boolean | true if the VPN is enabled, false otherwise. Note that this value is not available for web. | true |
device.attributes.location.latitude | Number | Latitude from GPS. | 41.50 |
device.attributes.location.longitude | Number | Longitude from GPS. | -81.69 |
device.attributes.location.horizontalAccuracy | Number | Radius of location uncertainty in meters. | 2.1 |
device.attributes.location.altitude | Number | Altitude in meters. | 998.2 |
device.attributes.location.verticalAccuracy | Number | Accuracy of altitude in meters. | 0 |
device.attributes.location.bearing | Number | Bearing in degrees. | 32 |
device.attributes.location.bearingAccuracy | Number | Accuracy of bearing in degrees. | 2.1 |
device.attributes.location.speed | Number | Speed in meters per second. | 1.3 |
device.attributes.location.speedAccuracy | Number | Accuracy of speed in meters per second. | 0.2 |
device.attributes.battery | Object | Information regarding the battery for the device. | |
device.attributes.battery.batteryState | String | Charging status for the battery. | charging |
device.attributes.battery.batteryLevel | Number | Battery level where 0 is empty and 1 is full. | 0.47 |
device.attributes.timeZone | String | Device timezone name. | America/New_York |
device.attributes.timeZoneOffset | Number | Minutes offset from UTC. | -480 |
device.attributes.language | String | Primary device language. | en-US |
device.attributes.deviceArchitecture | String | Device CPU architecture. | arm64 |
device.attributes.applicationType | String | SDK application type. | native |
device.attributes.isEmulator | Boolean | Set to true if the device is detected to be an emulator. | true |
device.attributes.deviceContext | String | Context passed into processDevice(...). | homepage |
device.attributes.androidAttributes | Object | Android-specific device attributes (present when collected on Android). | |
device.attributes.androidAttributes.isRooted | Boolean | Set to true if the Android device is rooted. | true |
device.attributes.androidAttributes.mobileNetwork | Array | Cellular network details observed on Android devices. | |
device.attributes.androidAttributes.mobileNetwork[*].carrierName | String | Mobile carrier name (Android). | T-Mobile |
device.attributes.androidAttributes.mobileNetwork[*].isoCountryCode | String | Carrier ISO country code (Android). | us |
device.attributes.iOSAttributes | Object | iOS-specific device attributes (present when collected on iOS). | |
device.attributes.iOSAttributes.isRooted | Boolean | Set to true if the iOS device is jailbroken. | true |
device.attributes.iOSAttributes.mobileNetwork | Array | Cellular network details observed on iOS devices. | |
device.attributes.iOSAttributes.mobileNetwork[*].carrierName | String | Mobile carrier name (iOS). | T-Mobile |
device.attributes.iOSAttributes.mobileNetwork[*].isoCountryCode | String | Carrier ISO country code (iOS). | us |
device.attributes.webAttributes | Object | Web-specific device/browser attributes (present when collected on web). | |
device.attributes.webAttributes.userAgent | String | Browser user agent string. | Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) ... |
device.attributes.webAttributes.userAgentExtractionRequired | Boolean | Indicates whether user agent extraction was required. | true |
device.attributes.webAttributes.browser | String | Browser name. | Google Chrome |
device.attributes.webAttributes.browserVersion | String | Browser version. | 116 |
device.attributes.webAttributes.pixelDepth | Number | Pixel depth. | 24 |
device.attributes.webAttributes.hardwareConcurrency | Number | Number of logical processors available. | 8 |
device.attributes.webAttributes.maxTouchPoints | Number | Maximum touch points supported. | 1 |
device.attributes.webAttributes.colorDepth | Number | Color depth. | 24 |
device.attributes.webAttributes.webGlUnmaskedVendor | String | WebGL unmasked vendor string (when available). | Google Inc. (Apple) |
device.attributes.webAttributes.webGlUnmaskedRenderer | String | WebGL unmasked renderer string (when available). | ANGLE (Apple, ANGLE Metal Renderer: Apple M1 Pro, Unspecified Version) |
device.attributes.webAttributes.viewportScale | Number | Viewport scale factor. | 2.7 |
device.networkCaptures
device.networkCaptures| Field | Type | Description | Example |
|---|---|---|---|
| device.networkCaptures | Array | Contains data captured and extrapolated from captured network packets. | |
| device.networkCaptures[*].createdAt | String | ISO datetime when the network capture was recorded. | 2024-12-23T18:09:12.735Z |
| device.networkCaptures[*].srcIp | String | Source IP observed for the capture. | 38.48.122.126 |
| device.networkCaptures[*].os | String | OS observed/derived for the capture. | iOS |
| device.networkCaptures[*].osFlavor | String | OS flavor/variant (when available). | iOS |
| device.networkCaptures[*].linkType | String | Link/connection type observed (when available). | wifi |
device.history fields
device.history fieldsField | Type | Description | Example |
|---|---|---|---|
| String | The time the device profile was first seen as an ISO Date. |
|
| String | The last time the device profile was seen as an ISO Date. |
|
| 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. |
|
| 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. |
|
| 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. |
|
| 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. |
|
behavioral fields
behavioral fields| Field | Type | Description | Example |
|---|---|---|---|
behavioral.sessionId | String | Session ID generated by Device utilized to identify a unique user session. | d34304a6-a726-4dec-b1cd-9c4a3c192a0d |
behavioral.serverCreated | String | The ISO datetime for when the server first processed an event for this session. | 2021-09-01T11:19:58.796Z |
behavioral.serverUpdated | String | The ISO datetime for when the server last processed an event for this session. | 2021-09-11T16:19:58.796Z |
behavioral.clientUpdated | String | The browser or mobile app based ISO datetime for the last event submitted. | 2021-09-11T16:14:58.796Z |
behavioral.duration | Integer | The entire duration of the session in milliseconds. | 120910 |
behavioral.source | String | Where the user originated from when the session began also known as the referrer. | https://example.com/ |
behavioral.aggregations.totalEventCount | Integer | The combined number of events that occurred during the session. | 26 |
behavioral.aggregations.focusCount | Integer | The number of times a form field gained focus (became the active element) during the session. | 0 |
behavioral.aggregations.blurCount | Integer | The number of times a form field lost focus (no longer the active element) during the session. | 3 |
behavioral.aggregations.inputChangeCount | Integer | The number of times the value of a form input field was changed during the session. | 6 |
behavioral.aggregations.submissionCount | Integer | The number of times an HTML form was submitted during the session. Only occurs on Web. | 1 |
behavioral.aggregations.clickCount | Integer | The number of times a form element was clicked during the session. | 3 |
behavioral.aggregations.pasteCount | Integer | The number of times a value was pasted into a form field during the session. | 0 |
latestNavigationContexts fields
latestNavigationContexts fields| Field | Type | Description | Example |
|---|---|---|---|
latestNavigationContexts | Array | Summary of behavioral data for the latest occurrence of each navigation context. | |
latestNavigationContexts[*].tabId | String | Tab/context identifier. | 9c2d… |
latestNavigationContexts[*].combinedContext | String | Combined navigation context. | /checkout#step1 |
latestNavigationContexts[*].estimatedStartTimestamp | String | Estimated ISO start timestamp. | 2024-12-23T18:07:01.000Z |
latestNavigationContexts[*].timeInContext | Number | Time spent in this context. | 12.4 |
latestNavigationContexts[*].timeInForeground | Number | Time spent in foreground. | 9.8 |
latestNavigationContexts[*].ipAddresses | Array | IPs observed in this context. | |
latestNavigationContexts[*].ipAddresses[*] | String | An observed IP address. | 38.48.122.126 |
latestNavigationContexts[*].submissionCount | Number | Submissions observed in this context. | 1 |
latestNavigationContexts[*].backgroundCount | Number | Background transitions in this context. | 0 |
entityProfiler fields
entityProfiler fieldsField | Type | Description | Example |
|---|---|---|---|
| String | The unique identifier for the entity (e.g., email or phone number). | |
| String | The type of the entity. |
|
| Integer | The number of times the entity has been seen in the system. |
|
| String | The first time the entity was observed in the system. |
|
| String | The last time the entity was observed in the system. |
|
| Array | The most recent device types associated with the entity. |
|
| Array | The most recent device models associated with the entity. |
|
| Array | The most recent ISPs (Internet Service Providers) associated with the entity. |
|
| Array | The most recent device languages associated with the entity. |
|
| Array | The most recent timezones associated with the entity. |
|
| Array | The most recent states inferred from the entity's network location. |
|
| Array | The most recent postal codes inferred from the entity's network location. |
|
velocityMetrics fields
velocityMetrics fields| Field | Type | Description | Example |
|---|---|---|---|
velocityMetrics | Object | Device-level historical velocity metrics associated with the Digital Intelligence profile. | |
velocityMetrics.historicalCount | Object | Historical unique count and share metrics grouped by entity attribute. | |
velocityMetrics.historicalCount.firstName | Object | Historical velocity metrics related to first name usage on this device. | |
velocityMetrics.historicalCount.firstName.uniqueCount | Integer | Unique first names seen for this device historically. | 1 |
velocityMetrics.historicalCount.firstName.uniqueSharePercent | Integer | Percentage of transactions matching the most frequently seen first name. | 100 |
velocityMetrics.historicalCount.surName | Object | Historical velocity metrics related to surname usage on this device. | |
velocityMetrics.historicalCount.surName.uniqueCount | Integer | Unique surnames seen for this device historically. | 1 |
velocityMetrics.historicalCount.surName.uniqueSharePercent | Integer | Percentage of transactions matching the most frequently seen surname. | 100 |
velocityMetrics.historicalCount.email | Object | Historical velocity metrics related to email usage on this device. | |
velocityMetrics.historicalCount.email.uniqueCount | Integer | Unique emails seen for this device historically. | 2 |
velocityMetrics.historicalCount.email.uniqueSharePercent | Integer | Percentage of transactions matching the most frequently seen email. | 87 |
velocityMetrics.historicalCount.mobileNumber | Object | Historical velocity metrics related to mobile number usage on this device. | |
velocityMetrics.historicalCount.mobileNumber.uniqueCount | Integer | Unique mobile numbers seen for this device historically. | 1 |
velocityMetrics.historicalCount.mobileNumber.uniqueSharePercent | Integer | Percentage of transactions matching the most frequently seen mobile number. | 100 |
Updated 3 days ago
