Score an order or sign-up for fraud risk from device, IP, bot and order signals
POST /api/v1/fraud/score
POST https://api.trustverify.co.uk/api/v1/fraud/score
At least one of email, ip or deviceFP is required. Combines IP reputation (VPN/Tor), device velocity (how many of your customers share a device fingerprint, live keys only), bot signals from the shopper's browser, billing/shipping mismatch, order history, payment method and order value into a 0–100 score. Test keys run the same logic with no device velocity read or write.
Request body#
| Field | Type | Description |
|---|---|---|
| string | ||
| ip | string | |
| deviceFP | string | Device fingerprint from your client |
| customerId | string | |
| orderValue | number | |
| orderCount | integer | |
| paymentMethod | string | |
| billingAddress | object | |
| billingAddress.country | string | |
| billingAddress.postcode | string | |
| shippingAddress | object | |
| shippingAddress.country | string | |
| shippingAddress.postcode | string | |
| userAgent | string | The shopper's browser User-Agent, forwarded by you |
| botSignals | object | Client probe results from the shopper's browser |
| metadata | object |
Example request#
curl -sS -X POST 'https://api.trustverify.co.uk/api/v1/fraud/score' \
-H "Authorization: Bearer $TRUSTVERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "buyer@example.com",
"ip": "203.0.113.10",
"deviceFP": "fp_3c9a1e7b2d4f"
}'Responses#
200 Fraud score
| Field | Type | Description |
|---|---|---|
| checkIdrequired | string | |
| scorerequired | integer | 0–100, higher is safer |
| fraud_scorerequired | integer | Alias of score |
| scoreSourcerequired | string: "signals" | "heuristic" | "heuristic" when no IP reputation result was available; a heuristic score never returns action "approve" |
| riskTierrequired | string: "low" | "medium" | "high" | "critical" | |
| actionrequired | string: "approve" | "review" | "block" | |
| signalsrequired | object | |
| signals.iprequired | object | |
| signals.ip.providedrequired | boolean | |
| signals.ip.available | boolean | |
| signals.ip.source | string | |
| signals.ip.riskScore | number | |
| signals.ip.isVPN | boolean | |
| signals.ip.isTor | boolean | |
| signals.ip.country | string | |
| signals.emailrequired | object | |
| signals.email.providedrequired | boolean | |
| signals.devicerequired | object | Device velocity (distinct customers seen on this fingerprint) is measured for live keys only |
| signals.device.providedrequired | boolean | |
| signals.device.rejected | boolean | |
| signals.device.distinctCustomers | integer | |
| signals.device.sharedAcrossCustomers | boolean | |
| signals.device.flags | array of string | |
| signals.botrequired | object | |
| signals.bot.providedrequired | boolean | |
| signals.bot.rejected | boolean | |
| signals.bot.score | number | |
| signals.bot.verdict | string | |
| signals.bot.flags | array of string | |
| signals.addressMismatchrequired | boolean | |
| orderValuerequired | number,null | |
| customerIdrequired | string,null | |
| orderCountrequired | number,null | |
| paymentMethodrequired | string,null | |
| completedAtrequired | string | |
| metadatarequired | object |
400 validation_failed — none of email, ip or deviceFP supplied
| Field | Type | Description |
|---|---|---|
| errorrequired | string: "validation_failed" | |
| messagerequired | string | |
| requestId | string |