# Fraud Score

## IDMatchPredict5.0.FraudScore

<mark style="color:green;">`POST`</mark> `https://production.idresponse.com/process/comprehensive/gateway`

Make an **HTTPS POST** request with the following body parameters to find out if the target is a potential fraud risk. You will receive a synchronous response in under 1 second with a **result** object that includes an **action** and a **detail**.

#### Request Body

| Name                                                         | Type   | Description                                            |
| ------------------------------------------------------------ | ------ | ------------------------------------------------------ |
| user<mark style="color:red;">\*</mark>                       | string | Your account's API username                            |
| pass<mark style="color:red;">\*</mark>                       | string | Your account's API password                            |
| service<mark style="color:red;">\*</mark>                    | string | The service name (IDMatchPredict5.0.FraudScore)        |
| rules                                                        | string | See rules explanation below                            |
| reference                                                    | string | A unique identifier for your customer                  |
| target                                                       | object | The individual being sent for verification             |
| account.id<mark style="color:red;">\*</mark>                 | string | The target's unique account ID                         |
| account.registration\_time<mark style="color:red;">\*</mark> | string | The target's account registration timeYYYY-MM-DD HH:MM |
| fn<mark style="color:red;">\*</mark>                         | string | The target's first name                                |
| ln<mark style="color:red;">\*</mark>                         | object | The target's last name                                 |
| addr<mark style="color:red;">\*</mark>                       | string | The target's street address (line 1 and line 2)        |
| city                                                         | string | the target's city                                      |
| state                                                        | string | The target's state                                     |
| zip<mark style="color:red;">\*</mark>                        | string | The target's zip                                       |
| ip\_address<mark style="color:red;">\*</mark>                | string | The target's IP address (v4 or v6)                     |
| phone<mark style="color:red;">\*</mark>                      | string | The target's phone number                              |
| email\_address<mark style="color:red;">\*</mark>             | string | The target's email address                             |
| test\_key                                                    | string | The test key value that you are using to test          |

{% tabs %}
{% tab title="200 Transaction processed and result returned" %}

```javascript
{
    "output": {
        "signals": {
            "phone": {
                "is_valid": true,
                "line_type": "LANDLINE",
                "is_matched_with_name": false,
                "country_code": "US",
                "carrier": "VERIZON"
            },
            "ip_address": {
                "distance_to_phone": 15,
                "date_last_seen": "2021-10-06",
                "is_risky": false,
                "distance_to_address": ""
            },
            "email": {
                "date_first_seen": "2008-04-29",
                "is_valid": true,
                "is_matched_with_name": true
            },
            "identity": {
                "risk_score": 58.2,
                "network_score": 0.401
            },
            "address": {
                "is_valid": false,
                "is_matched_with_name": null
            }
        }
    },
    "meta": {
        "confirmation": 117360891,
        "reference": "",
        "service": "IDMatchPredict5.0.FraudScore",
        "timestamp": "2021-10-06 19:23:45",
        "company": "Veratad Technologies, LLC",
        "user": "root@veratad.com"
    },
    "result": {
        "action": "REVIEW",
        "detail": "TRANSACTION REQUIRES FURTHER ATTENTION",
        "issues": [
            "RISK SCORE GREATER THAN 40 AND LESS THAN 80"
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Sample Request Body

```javascript
{
    "user": "USERNAME",
    "pass": "PASSWORD",
    "service": "IDMatchPredict5.0.FraudScore",
    "reference": "12345 {A UNIQUE ID}",
    "rules": "",
    "target": {
        "fn": "Barbara",
        "ln": "Miller",
        "email_address": "bmiller@veratad.com",
        "ip_address": "2600:100c:b21d:431e:2ac:edaf:20ef:9fd5",
        "account": {
            "id": "587156",
            "registration_time": "2021-07-22 21:45"
        },
        "addr": "123 Main St",
        "city": "Dallas",
        "state": "Tx",
        "zip": "75215",
        "phone": "2015106000",
        "test_key": "predict_fraudscore_review"
    }
}
```

## Action and Detail Responses

The following are all values that will be returned in the result object of the response.

| Action | Detail                                 | Description                                                                                             |
| ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| FAIL   | RISKY CUSTOMER                         | Identity risk score, network score, IP risk score, and email age all exceed their respective thresholds |
| REVIEW | TRANSACTION REQUIRES FURTHER ATTENTION | See the full list of possible issues below                                                              |
| PASS   | ALL CHECKS PASSED                      | Identity risk score, network score, IP risk score, and email age all within their respective thresholds |

## Issues

| Issue                                               | Description                                                    |
| --------------------------------------------------- | -------------------------------------------------------------- |
| RISK SCORE GREATER THAN OR EQUAL TO X SCORE         | The identity risk score greater than or equal to X score       |
| IP RISK SCORE GREATER THAN OR EQUAL TO X SCORE      | The IP risk score is greater than or equal to X score          |
| NETWORK RISK SCORE GREATER THAN OR EQUAL TO X SCORE | The Identity network score is greater than or equal to X score |
| EMAIL IS LESS THAN X DAY(S) OLD                     | The days since email first seen date is less than X days       |

## Rules

IDMatchPredict5.0.FraudScore will process with the default base ruleset unless a different rule set is specified in the query.

{% hint style="success" %}
The base ruleset will return a PASS when:

* Identity risk score < 50
* IP risk score < 60
* Identity network score < 60
* Days since email first seen date >= 100 days
  {% endhint %}

{% hint style="warning" %}
The base ruleset will return a REVIEW when:

* Identity risk score >= 50
* IP risk score >= 60
* Identity network score >= 60
* Days since email first seen date < 100 days
  {% endhint %}

{% hint style="danger" %}
The base ruleset will return a FAIL when:

* Identity risk score >= 50 AND IP risk score >= 60 AND Identity network score >= 60 AND days since email first seen date < 100 days
  {% endhint %}

## Testing

When the test\_key is provided the system will dynamically drop the live data sources and use the testing database. These transactions are free of charge. To access live data do not send this attribute. Here are available test cases for the fraud score service.

| Key                         | Description                                                                    |
| --------------------------- | ------------------------------------------------------------------------------ |
| predict\_fraudscore\_pass   | The action will always return as `PASS` regardless of the target attributes.   |
| predict\_fraudscore\_review | The action will always return as `REVIEW` regardless of the target attributes. |
| predict\_fraudscore\_fail   | The action will always return as `FAIL` regardless of the target attributes.   |