A risk score answers “how suspicious is this?”. Your product needs a different answer: “what do I do with this signup?”. Use-case decisions give that answer for the six moments where small businesses lose the most money.
| Use case | Typical abuse it is tuned for | What it looks at first |
|---|---|---|
signup | Fake and duplicate accounts, signup bots | Accounts already on the device, automation, disposable email |
free_trial | The same person taking trial after trial | Trials already started on the device, disposable email, VPN, proxy and datacenter networks |
bonus | Welcome bonuses, referral credits and promo codes claimed by linked accounts | Bonuses already claimed on the device, new accounts on devices that already hold accounts |
login | Account takeover, credential stuffing | First login from this device, a country change within an hour, the account on many devices, repeated attempts |
checkout | Card testing, stolen cards, promo stacking | Checkouts per hour from the device, several accounts paying from one device |
extra_seat | One paid seat used by a whole team | The account used from 3 or more devices, or from more than one country, in 24 hours |
paywall | Free-article limits bypassed with a private window, cleared cookies or a new account | Distinct articles read on the device (and the account, when sent) in the window |
sms | SMS pumping (toll fraud), resend abuse, bots burning your SMS budget | Codes per device, per number and per network; one device asking for many numbers; sequential numbers from one number block across every Prynt customer; expensive destinations requested from another country; traffic spikes |
Every use case also checks the same basics: devices or accounts you labeled fraud, your deny list, fraud reported elsewhere, automation, a browser altering its own fingerprint, and Tor. Account clusters will be added to the signup and bonus decisions when account clusters ship.
Each decision has three possible outcomes:
allow— continue normally. Most requests.step_up— continue after one step, given instep. See the friction ladder.block— Prynt recommends not continuing. Your code decides; Prynt never blocks on its own.
Use-case decisions are part of Prynt Control.
Send the use case
// Browser: the moment the user submits the form
const { requestId } = await prynt.identify({ useCase: 'free_trial', linkedId: account.id });
// send requestId to your server with the form
useCase is one of signup, free_trial, bonus, login, checkout, extra_seat, sms or paywall (trial,
seat, otp and article are accepted as aliases). On a Control account, sending a known use case turns on extendedResult for that call, since
the decision needs the full set of signals. A value Prynt does not know is ignored: the request is identified as usual,
without a control block. On other plans the use case is stored on the event, and no control block comes back.
Send your own account id as linkedId (see Send your user id). The decisions count accounts per
device, so they need it; the login and extra_seat checks run only when it is present. The disposable-email check
runs when the identification also carries the email the user typed.
Protect SMS and OTP codes
Call identify with useCase: 'sms' and the number, before you ask your SMS provider to send the code, and only
send it when the decision is allow (or after the step):
const { requestId } = await prynt.identify({ useCase: 'sms', phone: '+14155550101', linkedId: account?.id });
// your server reads the decision for requestId; allow → send the code, step_up → captcha first, block → don't send
The number must include its country code (E.164). Prynt never stores it: only keyed hashes of the number and of its
1,000-number block, plus its country, so it can count how often codes go to it. Number-block pumping is counted across
every Prynt customer, which catches attacks no single site sees enough of. In Decisions, you can list the countries
you send codes to (allowCountries); a number from any other country is blocked.
Meter a paywall
Call identify with useCase: 'paywall' on every article view. The meter counts distinct articles (the page URL
without query or fragment) per device, so a private window or cleared cookies do not reset it, and per account when
you send linkedId:
const { requestId } = await prynt.identify({ useCase: 'paywall' });
// server: control.meter = { viewed: 6, limit: 5, remaining: 0, windowDays: 30 }
// allow → show the article · step_up → show your wall (verify_email = sign-up wall, card_or_passkey = subscribe)
Set the free articles and the wall in Decisions (freeArticles, default 5; maxStep, default
card_or_passkey). Report a subscription with POST /v1/control/steps
and the device reads freely for 30 days.
Count cards per device
Send an opaque card identifier with checkout: Stripe’s card.fingerprint, or the BIN and last 4 digits. Prynt keeps
only a keyed hash of it.
await prynt.identify({ useCase: 'checkout', linkedId: account.id, paymentMethod: card.fingerprint });
Trusted devices on login
Every login decision with a linkedId carries deviceTrust:
{ "deviceTrust": { "level": "trusted", "knownSince": "2026-09-14T10:02:11Z",
"reason": "This device has used the account before and nothing risky was seen" } }
trusted means the device used this account on an earlier day (or passed a step) and nothing risky was seen now:
you can skip your own 2FA code. new is a device without that history; risky lists what was seen. Skipping 2FA is
your choice; Prynt only tells you which devices have earned it.
Apply the decision on your server
// Node / Express
app.post('/trials', async (req, res) => {
const event = await fetch(`https://api.pryntid.com/v1/events/${req.body.requestId}`, {
headers: { Authorization: `Bearer ${process.env.PRYNT_SECRET_KEY}` },
}).then((r) => r.json());
// No control block: unknown use case, or not a Control account. Fall back to your usual flow.
const { decision, step, reasons } = event.control || { decision: 'allow' };
if (decision === 'block') {
await audit.log('trial_refused', { account: req.user.id, reasons });
return res.status(403).json({ error: 'trial_unavailable' });
}
if (decision === 'step_up') {
return res.json({ next: step }); // "captcha" | "verify_email" | "card_or_passkey"
}
await startTrial(req.user);
res.json({ ok: true });
});
The event (GET /v1/events/{requestId}, secret key) carries useCase and the control block; the identify response
carries the same control block:
{
"requestId": "req_…",
"useCase": "free_trial",
"control": {
"useCase": "free_trial",
"mode": "enforce",
"decision": "step_up",
"step": "verify_email",
"reasons": [
{ "code": "DEVICE_HAD_TRIAL", "text": "This device started a trial 12 days ago" },
{ "code": "DISPOSABLE_EMAIL", "text": "The email domain is a disposable inbox" }
]
}
}
| Field | Values |
|---|---|
useCase | The use case you sent, in its canonical name |
mode | enforce, or mirror while mirror mode is active |
decision | allow, step_up or block |
step | none, captcha, verify_email, card_or_passkey or block |
reasons | Up to 8 { code, text }, strongest first |
cappedAt | Present only when your ceiling lowered the step (see below) |
The control block is additive: the general decision.decision (allow, challenge or block) is still there and
does not change.
The reason text is in English and is written for your team, not for the person on the other side. Show the user
something neutral when you refuse or add a step (“We need to confirm your email before the trial starts”).
Reason codes
| Code | Use cases | When | Step |
|---|---|---|---|
KNOWN_FRAUD | all | The device or account was labeled fraud before | block |
DENYLISTED | all | The device, account or network is on your deny list | block |
NETWORK_FRAUD | all | The device or network was reported for fraud elsewhere | card_or_passkey |
AUTOMATION | all | Signs of automation in the browser or the form | captcha |
TAMPERING | all | The browser is altering its own fingerprint (privacy extensions do this too, so it only asks for the light step) | verify_email |
TOR | all | The request comes through Tor | verify_email |
ANONYMIZED_NETWORK | free_trial, bonus | A VPN, proxy or datacenter network | verify_email |
DISPOSABLE_EMAIL | signup, free_trial, bonus | The email domain is a disposable inbox (needs email) | verify_email |
HIGH_RISK | all | The general decision is block and none of the checks above applies | card_or_passkey |
ELEVATED_RISK | all | The general decision is challenge and none of the checks above applies | verify_email |
DEVICE_HAS_ACCOUNTS | signup | 1–2 other accounts on the device in the repeat window; 3 or more | verify_email; card_or_passkey |
DEVICE_HAD_TRIAL | free_trial | 1 other account started a trial on the device; 2 or more | verify_email; card_or_passkey |
BONUS_ON_DEVICE | bonus | 1–2 other accounts claimed a bonus on the device | card_or_passkey |
BONUS_REPEATED | bonus | 3 or more other accounts claimed a bonus on the device | block |
NEW_ACCOUNT_KNOWN_DEVICE | bonus | A new account on a device that already has accounts | verify_email |
NEW_DEVICE | login | First login to this account from this device, while it uses others | verify_email |
IMPOSSIBLE_TRAVEL | login | The device changed country within an hour | card_or_passkey |
ACCOUNT_ON_MANY_DEVICES | login | The account was used from many devices in 24 hours | card_or_passkey |
LOGIN_VELOCITY | login | Many attempts from this device in a few minutes | captcha |
CHECKOUT_VELOCITY | checkout | 5 or more checkouts from the device in the last hour | captcha |
CARD_TESTING | checkout | 20 or more checkouts from the device in the last hour | block |
CHECKOUT_MANY_ACCOUNTS | checkout | 2 or more other accounts checked out from the device in the repeat window | verify_email |
SHARED_SEAT | extra_seat | The account was used from 3 or more devices, or more than one country, in 24 hours | verify_email |
PAYWALL_LIMIT | paywall | More distinct articles than freeArticles in the window | your wall step |
PAYWALL_PRIVATE_WINDOW | paywall | Over the limit and reading in a private window | your wall step |
MANY_CARDS_ON_DEVICE | checkout | 3–4 different cards on the device today (needs paymentMethod); 5–7 | captcha; card_or_passkey |
CARD_TESTING_MANY_CARDS | checkout | 8 or more different cards on the device today | block |
CARD_ON_MANY_DEVICES | checkout | The same card used from 4 or more devices today | verify_email |
CARD_ON_MANY_ACCOUNTS | checkout | The same card paid for 3 or more accounts in 30 days | card_or_passkey |
PHONE_INVALID | sms | The number is not a valid international number with a country code | block |
SMS_NO_NUMBER | sms | No phone was sent with the check | verify_email |
SMS_COUNTRY_NOT_ALLOWED | sms | The number’s country is not in your allowCountries | block |
SMS_DEVICE_VELOCITY | sms | 3 or more codes requested from the device in 10 minutes | captcha |
SMS_DEVICE_FLOOD | sms | 10 or more codes requested from the device in an hour | block |
SMS_DEVICE_MANY_NUMBERS | sms | The device asked for codes to 3 or more numbers in 24 hours; 6 or more | card_or_passkey; block |
SMS_NUMBER_RESEND | sms | 3 or more codes for the same number in 10 minutes | captcha |
SMS_NUMBER_FLOOD | sms | 8 or more codes for the same number in an hour | block |
SMS_RANGE_PUMPING | sms | 5 or more numbers of the same 1,000-number block got codes in an hour, across Prynt; 12 or more | card_or_passkey; block |
SMS_IP_VELOCITY | sms | 20 or more codes requested from the same network in an hour | captcha |
ANONYMIZED_NETWORK | sms | A VPN, proxy, datacenter network or Tor | captcha |
SMS_HIGH_RISK_DESTINATION | sms | A destination often used for SMS pumping, requested from another country; with automation or a hidden network | captcha; card_or_passkey |
SMS_TRAFFIC_SPIKE | sms | 30 or more codes this hour and more than 5 times your usual hourly volume | captcha |
STEP_PASSED | all | The device passed a step for this use case in the last 30 days | lowers the answer to allow |
STEP_FAILED | all | The device failed or abandoned a step in the last 7 days | one rung up, at most card_or_passkey |
When several reasons apply, the strongest step wins. block needs direct evidence: a label, your deny list, a device
that keeps claiming the same bonus, or card testing. STEP_PASSED never softens a block, and does not apply when the
evidence now calls for a higher step than the one passed. Steps are reported with
POST /v1/control/steps.
Tune a use case to your business
Each use case starts from defaults that suit most small products. In the console, Decisions (in the Control section of the sidebar) lets you set, per use case:
repeatDays: how far back a repeat on the same device counts, from 1 to 730 days (for example, one trial per device every 90 days);maxStep: the strongest step you are willing to ask for:captcha,verify_emailorcard_or_passkey. Some products never ask for a card.blockcan still be returned when the evidence is direct.
| Use case | maxStep | repeatDays |
|---|---|---|
signup | card_or_passkey | 30 |
free_trial | card_or_passkey | 90 |
bonus | card_or_passkey | 365 |
login | card_or_passkey | 30 |
checkout | card_or_passkey | 30 |
extra_seat | verify_email | 7 |
sms | card_or_passkey | 1 |
paywall | card_or_passkey | 30 |
When a step is lowered to your ceiling, the block says so:
{ "useCase": "free_trial", "mode": "enforce", "decision": "step_up", "step": "verify_email",
"reasons": [{ "code": "DEVICE_HAD_TRIAL", "text": "3 other accounts started a trial on this device in the last 90 days" }],
"cappedAt": "verify_email" }
The console page uses these endpoints, authenticated with your console session:
| Endpoint | What it does |
|---|---|
GET /admin/control/settings | Settings per use case, with the defaults and the allowed values |
PUT /admin/control/settings with { "useCases": { "free_trial": { "maxStep": "verify_email", "repeatDays": 60 } } } | Change one or more use cases; the others keep their values |
GET /admin/control/summary?days=30 | Counts per use case, decision and step, and the latest step-ups and blocks |
You can also add your own rules on top, starting in evaluate mode.
Mirror mode
While mirror mode is active, the control block answers allow with step none, and the
real verdict goes in wouldBe:
{
"control": {
"useCase": "free_trial",
"mode": "mirror",
"decision": "allow",
"step": "none",
"wouldBe": { "decision": "step_up", "step": "verify_email" },
"reasons": [{ "code": "DEVICE_HAD_TRIAL", "text": "This device started a trial 12 days ago" }]
}
}
So the code above is safe to ship before you have seen a single decision. The counts in Decisions are the real verdicts, mirror mode included.
Webhooks
Every block and every step_up also arrives as a signed webhook (control.decision), with the same control
block, if you prefer to react asynchronously — for example, to hold a bonus payout for review instead of refusing it
at the moment of the claim. The webhook does not fire in mirror mode; the visitor.identified payload still carries
the control block with wouldBe.