> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Understanding Fraud Check Results
Learn how to locate and interpret the results from Onboarding Fraud Checks.
## 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.
```json theme={null}
"supplementaryData": {
"type": "FRAUD_EMAIL_ADDRESS",
"emailAddressId": "239db6d7-90be-4368-bc35-23194f13eae5",
"riskLevel": "UNACCEPTABLE",
"reference": {
"name": "sardine",
"reference": "https://dashboard.sandbox.sardine.ai/...",
"type": "URL"
},
"indicators": [
{
"name": "emailLevel",
"value": "very_high",
"rules": [
{
"isActive": true,
"name": "Forced very high email risk",
"reference": "30"
}
]
}
]
}
```
**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.
```json theme={null}
"supplementaryData": {
"type": "FRAUD_PHONE_NUMBER",
"phoneNumberId": "a6ba094e-77ec-44bc-8b1c-5152b158276a",
"riskLevel": "LOW",
"reference": {
"name": "sardine",
"reference": "https://dashboard.sandbox.sardine.ai/...",
"type": "URL"
},
"indicators": [
{
"name": "phoneLevel",
"value": "low"
}
]
}
```
**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.
```json theme={null}
"supplementaryData": {
"type": "FRAUD_DEVICE",
"riskLevel": "HIGH",
"session": {
"token": "40508276-14d3-4a51-b59a-343a54e39f93"
},
"device": {
"deviceId": "1d9566b0-9699-460f-8d25-59179155f10e",
"os": "Windows",
"browser": "Chrome",
"isEmulated": true,
"reputation": "medium_risk",
"vpnLikelihood": "HIGH"
},
"indicators": [
{
"name": "deviceLevel",
"value": "high"
}
]
}
```
**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:
```bash theme={null}
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`.