/v1/admin/fraud/detectionThe Detectors screen of the website: whether fraud detection runs, who hears about a flag, when a trader's risk score suspends them and how long a flag keeps counting, what Restrict takes away, and every detector with its level, its score and thresholds and how much it caught.
A trader's risk score is the sum of the scores of every detector they have an
active flag from, once per detector, capped at 100. Only detectors on
monitor or flag add their score. On restrict and block the level is the
consequence and the detector adds nothing, and off adds nothing either.
The detectors are the platform's, the same 24 for every firm and always in this order. A firm chooses only their levels, scores and thresholds. One detector with its open flags and exceptions is a detector, and a change is a save.
Needs a firm. Our own staff name one with the Propper-Workspace header.
Request
curl "https://api.proppertrading.com/v1/admin/fraud/detection" \
-H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
-H "Propper-Workspace: acme"
Response
Shortened to two of the 24 detectors:
{ "data": { "object": "fraud_detection", "global": { "enabled": true, "notify_admins": true, "escalation_enabled": true, "escalation_score": 80, "score_window_days": 90, "sensitivity": "balanced" }, "restrict": { "block_new_orders": true, "hold_payouts": true, "block_purchases": false, "hold_affiliate_payouts": false }, "standing": { "restricted": 6, "suspended": 1 }, "detectors": [ { "object": "fraud_detector", "key": "vpn", "name": "VPN", "description": "A connection through a known commercial VPN exit.", "category": "ip", "default_level": "flag", "default_score": 10, "access": true, "group": false, "level": "flag", "score": 10, "params": {}, "overrides": 2, "flags_30d": 16, "open_flags": 13, "exposure": { "traders": 16 }, "fields": [] }, { "object": "fraud_detector", "key": "max_countries", "name": "Too many countries", "description": "One account logging in from more countries than one person plausibly visits.", "category": "geo", "default_level": "flag", "default_score": 20, "access": false, "group": false, "level": "flag", "score": 20, "params": { "max_countries": 3, "window_days": 30 }, "overrides": 1, "flags_30d": 1, "open_flags": 1, "exposure": { "by_country_count": { "1": 11 } }, "fields": [ { "key": "max_countries", "type": "integer", "default": 3, "min": 1, "max": 50, "unit": "", "options": [], "overridable": true, "label": "Countries allowed", "hint": "Distinct countries an account may log in from inside the window." }, { "key": "window_days", "type": "integer", "default": 30, "min": 1, "max": 90, "unit": "d", "options": [], "overridable": true, "label": "Window", "hint": "The rolling period the countries are counted over." } ] } ] }, "meta": { "request_id": "req_01m50zcm1n6trjh6w07q0fp3mm" } }
| Field | Description |
|---|---|
global | enabled, the master switch: off, no detector runs and nothing is enforced. notify_admins sends admins a notice when a flag needs a decision. escalation_enabled and escalation_score (30 to 100) suspend a trader when a new flag takes their risk score to that or higher, whatever the levels. score_window_days is how long a flag keeps counting after a detector last saw it: 30, 60, 90, 180 or 365, or 0 for until somebody decides it. sensitivity is deprecated and always "balanced": it was replaced by a score per detector and does nothing |
restrict | What a restriction takes away: block_new_orders, hold_payouts, block_purchases, hold_affiliate_payouts |
standing | Traders restricted right now, and flags that suspended somebody |
detectors | Every detector, see below |
| Detector field | Description |
|---|---|
key | Stored on every flag it raises, and never changes |
name, description | In the admin's language |
category | ip, geo, device, linking or affiliate |
default_level | The level of a firm that never chose one |
default_score | The score of a firm that never chose one |
access | Decides who may connect at all. At block it refuses the session instead of suspending the account |
group | One flag names several accounts at once |
level | off, monitor, flag, restrict or block |
score | What a flag of this detector adds to a trader's risk score, 0 to 100 in steps of 5. Kept on every level, but only counts on monitor and flag |
params | The thresholds as the firm set them, by key. {} for a detector without any |
fields | What each threshold is: type (integer, choice or countries), min and max, unit (min, s, d, km, km/h, % or empty), the options of a choice, the default, overridable when an override may change it for one trader, and a label and hint in words |
overrides | Overrides in force on this detector |
flags_30d | Flags it raised in the last 30 days |
open_flags | Its flags that are still active, Monitor ones included |
exposure | Who it would catch, for six detectors only, over the last 30 days. The four anonymiser detectors give traders on such an address. The country policy gives by_country, traders per country code, to count what a policy would catch. Too many countries gives by_country_count, traders by how many countries they used. Null for the rest |
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | workspace_required | Asked by our own staff without naming a firm |
| 401 | invalid_token | Not a token, or the secret does not match |
| 401 | revoked_token | Signed out here or from another device |
| 401 | expired_token | Ninety days without use, or a set expiry passed |
| 403 | admin_access_required | This account no longer helps run the environment |
| 403 | insufficient_scope | This device does not hold admin:read |
| 403 | workspace_not_permitted | The Propper-Workspace header names an environment this account cannot act in |
| 403 | forbidden | Without view_fraud |