Understanding Fraud Check Results

Locating Fraud Check Results

Once a workflow containing a FRAUD step has been executed, the detailed results are nested within the workflowResult object. To find the specific outcomes of the fraud checks, navigate the JSON response structure as follows:

1. Start with workflowStepResults: In the workflowResult, find the workflowStepResults array.
2. Identify the FRAUD Step: Look for the object where stepName is FRAUD.
3. Examine processResults: Inside this step result is a processResults array. Each object in this array is a Process Result Object (PRO) containing granular data for a specific check (e.g., one PRO for email, one for phone).
4. Drill into supplementaryData: The richest details are in the supplementaryData object within each PRO. The type field here is crucial as it defines the structure and meaning of the data.

Decoding supplementaryData for Fraud Checks

The structure of the supplementaryData object is determined by its type. For fraud checks, you will encounter the following types:

Type: FRAUD_EMAIL_ADDRESS

This object contains the results of the risk analysis for an individual’s email address.

1
"supplementaryData": {
2
  "type": "FRAUD_EMAIL_ADDRESS",
3
  "emailAddressId": "239db6d7-90be-4368-bc35-23194f13eae5",
4
  "riskLevel": "UNACCEPTABLE",
5
  "reference": {
6
    "name": "sardine",
7
    "reference": "https://dashboard.sandbox.sardine.ai/...",
8
    "type": "URL"
9
  },
10
  "indicators": [
11
    {
12
      "name": "emailLevel",
13
      "value": "very_high",
14
      "rules": [
15
        {
16
          "isActive": true,
17
          "name": "Forced very high email risk",
18
          "reference": "30"
19
        }
20
      ]
21
    }
22
  ]
23
}

Key Fields:

• emailAddressId: The unique ID of the email address that was checked.
• riskLevel: The risk level assessed by the provider (e.g., LOW, MEDIUM, HIGH, UNACCEPTABLE).
• indicators: An array of specific signals or rules that were triggered during the check.
• reference: A link or reference to the provider’s system for more details.

Type: FRAUD_PHONE_NUMBER

This object provides the results of the risk analysis for a phone number.

1
"supplementaryData": {
2
  "type": "FRAUD_PHONE_NUMBER",
3
  "phoneNumberId": "a6ba094e-77ec-44bc-8b1c-5152b158276a",
4
  "riskLevel": "LOW",
5
  "reference": {
6
    "name": "sardine",
7
    "reference": "https://dashboard.sandbox.sardine.ai/...",
8
    "type": "URL"
9
  },
10
  "indicators": [
11
    {
12
      "name": "phoneLevel",
13
      "value": "low"
14
    }
15
  ]
16
}

Key Fields:

• phoneNumberId: The unique ID of the phone number that was checked.
• riskLevel: The risk level assessed by the provider.
• indicators: An array of specific signals or rules that were triggered.

Type: FRAUD_DEVICE & FRAUD_IP_ADDRESS

These objects contain the risk analysis for the device and IP address associated with a user’s session. They share a similar structure.

1
"supplementaryData": {
2
  "type": "FRAUD_DEVICE",
3
  "riskLevel": "HIGH",
4
  "session": {
5
    "token": "40508276-14d3-4a51-b59a-343a54e39f93"
6
  },
7
  "device": {
8
    "deviceId": "1d9566b0-9699-460f-8d25-59179155f10e",
9
    "os": "Windows",
10
    "browser": "Chrome",
11
    "isEmulated": true,
12
    "reputation": "medium_risk",
13
    "vpnLikelihood": "HIGH"
14
  },
15
  "indicators": [
16
    {
17
      "name": "deviceLevel",
18
      "value": "high"
19
    }
20
  ]
21
}

Key Fields:

• riskLevel: The risk level assessed by the provider.
• session: Contains the provider’s session token.
• device: An object containing detailed device characteristics, such as OS, browser, and fraud indicators like isEmulated or vpnLikelihood.
• ipAddressInformation: (For FRAUD_IP_ADDRESS type) An object containing IP details like v4Address and connectionType.

Fraud Issues and Risk Factors

The fraud checks directly influence the workflow’s outcome by generating issues and risk factors.

• Issues: When a check returns a HIT result, a corresponding issue is created. For example, a high-risk email will generate an issue with category: FRAUD and issue: FRAUD_EMAIL_ADDRESS.
• Risk Factors: The riskLevel from each check is converted into a risk factor (e.g., fraud_email, fraud_device) which contributes to the entity’s overall risk score.

Resolving and Invalidating Results

Resolving a HIT

If a fraud check results in a HIT, an operator can manually review and resolve it. This is done by changing the manualStatus of the corresponding Process Result Object (PRO).

Call the following endpoint with the processResultId of the PRO to be updated:

$
PATCH /v2/individuals/{entityId}/results/fraud

Manual Status Options:

• FALSE_POSITIVE: The signal is incorrect and not a sign of fraud.
• TRUE_POSITIVE_ACCEPT: The signal is correct, but the risk is acceptable for onboarding.
• TRUE_POSITIVE_REJECT: The signal is correct, and the applicant should be rejected.

Once resolved, re-executing the workflow will take the manual override into account, potentially resulting in a CLEAR or PASS status.

Invalidation of Results

Fraud check results are tied to specific data points and can be automatically invalidated if that data changes:

• MARKED_INVALID: If an email or phone number that was checked is modified or deleted, the associated result’s systemStatus is set to MARKED_INVALID.
• STALE: If a new email or phone with a higher precedence is added to the entity and the workflow is re-run, the old result is marked as STALE.