# Check a buyer

> POST /check returns a verdict (allow, flag, block), a level, a score and reasons for a buyer, from hashed identifiers, before the order.

```http
POST /check
```

Call it before the order is placed, with the hashes of the buyer's identifiers ([hashing](https://docs.uptools.io/trustorder/api/hashing/)). Only `email_hash` is required; send every hash you have.

```json
{
  "email_hash": "8cd79ce2224abde026ddc67563fe5edb8b5eb41846c63cd550a76ea76cc2eddd",
  "phone_hash": "038e5821814169825ae568bfefdb18ca31d4d2e0a0f5941b6da27df45d50ddf4",
  "address_hash": "956b4ad633a194c484c3fdd6d6145ec1ac929b211438b3452e79b4853f65df96",
  "email_domain_hashes": ["4672a2431309380c7954c449b3ff20d2cd31968853d6e98137dd3b0be3652dae"],
  "email_domain_mx": true,
  "strictness": "normal"
}
```

| Field | Type | |
|---|---|---|
| `email_hash` | hash | required |
| `phone_hash` | hash or `null` | |
| `address_hash` | hash or `null` | shipping address |
| `email_domain_hashes` | array of hashes, at most 5 | the domain and its parent suffixes |
| `email_domain_mx` | `true`, `false` or `null` | your own MX check |
| `strictness` | `lenient`, `normal` (default), `strict` | how a risky buyer is handled |

Unknown fields are rejected with `400`. A test key sees test reports only.

## Response

```json
{
  "verdict": "block",
  "level": "blocked",
  "score": 33,
  "reasons": ["NEGATIVE_MULTI_ACCOUNT", "NEGATIVE_RECENT", "LOW_SCORE"],
  "stats": { "delivered": 0, "refused": 2, "accounts_refused": 2 },
  "check_id": "01a1a17c-7e54-7032-95b4-ba478164249b"
}
```

| Field | Meaning |
|---|---|
| `verdict` | what to do: `allow`, `flag` or `block` |
| `level` | `trusted`, `unknown`, `risky` or `blocked` |
| `score` | 0 to 100; 75 without any history |
| `reasons` | the codes below, in a fixed order |
| `stats` | pick-ups, refusals and the number of accounts that reported a refusal, for the worst identifier, over three years |
| `check_id` | an id for support requests; also in the `X-Check-Id` header |

## Level

Each identifier (e-mail, phone, address) is scored on its own, and the worst one counts. A new e-mail address cannot clean a phone number with refusals.

| Level | When |
|---|---|
| `blocked` | fresh refusals from at least two accounts, and a score below 60 |
| `risky` | a refusal in the last 365 days, or a score below 60, or a disposable or mail-less e-mail domain |
| `trusted` | at least three pick-ups and no fresh refusal |
| `unknown` | everything else, for example no history |

A refusal counts as fresh for 365 days. The address weighs half as much as the e-mail and the phone, because many people share one (blocks of flats, parcel points).

## Verdict

The level and the `strictness` of the request give the verdict:

| Strictness | `blocked` | `risky` | `unknown`, `trusted` |
|---|---|---|---|
| `lenient` | `block` | `allow` | `allow` |
| `normal` | `block` | `flag` | `allow` |
| `strict` | `block` | `block` | `allow` |

A shop exception overrides it: `allow` always gives `allow`, `deny` always gives `block` ([exceptions](https://docs.uptools.io/trustorder/api/other/#exceptions)). The level and the score are still computed.

## Reasons

| Code | Meaning |
|---|---|
| `NEGATIVE_MULTI_ACCOUNT` | refused at several accounts: this made the level `blocked` |
| `NEGATIVE_RECENT` | a refusal in the last 365 days |
| `LOW_SCORE` | the score is below 60 |
| `DISPOSABLE_DOMAIN` | the e-mail domain belongs to a disposable e-mail service |
| `DOMAIN_NO_MX` | the e-mail domain cannot receive mail (your `email_domain_mx` was `false`) |
| `NO_HISTORY` | no report for any identifier yet |
| `SHOP_ALLOW` | your exception allows this buyer |
| `SHOP_DENY` | your exception blocks this buyer |

## What to do with the verdict

The verdict is a suggestion; the shop decides. For example: on `block` hide cash on delivery and offer prepayment, on `flag` show a note to the shop staff, on `allow` change nothing. Never leave the buyer with no way to pay.
