Socure Device Risk

Device Risk collects device data and creates a unique fingerprint. With additional Personal Identifiable Information (PII), Socure then links identities to devices, which is an important part of our fraud and risk analysis.

The flow below describes the best practices to capture your customer's device information using the Socure SDK and processing it through Unit21.

Requirements

In order to use devicerisk, you must:

Socure SDK

Socure requires that you run Javascript code on your platform for this feature.

The JavaScript code creates a deviceSessionId. This ID can be used to identify the device on subsequent visits and must be sent to the Unit21 API:

{
    “sessionId”: "5d86672c-5e07-4813-be6c-6bd3b602371a"
    "result": “Captured”
}

Unit21 API

Once you have capture a deviceSessionId, you can use the Create Entity or Update Entity Unit21 API Endpoints to run Device Risk Workflows.

You must include the UUID returned from Socure as custom_data for the entity on which you wish to perform the workflow: custom data.socure_device_session_id = 5d86672c-5e07-4813-be6c-6bd3b602371a:

curl -X POST \
  https://<API_ENDPOINT>/v1/entities/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "user_data": {
      "first_name": "John",
      "middle_name": "Joseph",
      "last_name": "Smith",
      "day_of_birth": 14,
      "month_of_birth": 1,
      "year_of_birth": 1983,
      "gender": "male",
      "ssn": "733-99-5921"
    },
    "custom_data": {
        "socure_device_session_id": "5d86672c-5e07-4813-be6c-6bd3b602371a"
    },
    "options": {
      "identity_verifications": {
        "workflow_id": "socure_dev_risk",
        "run_verifications": true
      },
    }
  }'

In this example, a Device Risk Verification called socure_dev_risk has already been created. See the Verification Workflows.

If an alert is generated via the workflow, you will receive the Socure response in the alert.

Sample Socure Response (Successful):

A successful API request that includes the Document Verification module will return objects that contain information about the document and a result:

There are 4 possible results:

  • SOCURE_ACCEPT
  • SOCURE_REJECT
  • SOCURE_IDENTIFICATION_CHECK
  • SOCURE_RESUBMIT

The results will appear in the response as well as the header of the alert:

Understanding the Raw Response

You can view the raw response in the alert:

{
   "referenceId": "6ef62bf8-4e3b-4076-ab3e-9cdec2e12567",
   "deviceRisk": {
      "reasonCodes": [
         "I420",
         "I416",
         "I401",
         "I423",
         "I424",
         "I409"
      ],
      "score": -1.0
   },
   "deviceIdentityCorrelation": {
      "reasonCodes": [
         "I403"
      ],
      "score": -1.0
   },
   "deviceData": {
      "information": {
         "deviceManufacturer": "Apple",
         "deviceModelNumber": "IPHONE",
         "operatingSystem": "Mac OS X",
         "operatingSystemVersion": "10.15.7",
         "browserType": "Chrome",
         "browserVersion": "92.0.4515.159"
      },
      "geolocation": {
         "ipGeolocation": {
            "coordinates": "39.03,-77.49",
            "city": "ashburn",
            "state": "va",
            "zip": "20147",
            "country": "usa"
         },
         "gpsGeolocation": {
            "coordinates": "49.41593358427357,32.06630620793315"
         },
      "observations": {
         "firstSeen": "2021-xx-xx 21:09:54",
         "lastSeen": "2021-xx-xx 20:06:53"
      }
   }
}

The deviceRisk and deviceIdentityCorrelation scores are placeholder values for functionality that has yet to be released.
The velocityMetrics object will be removed from the API response when deviceIdentityCorrelation is released. More information will be provided at a later date.


Did this page help you?