Documentation · Prynt Control

Use-case decisions

Ready-made decisions for signup, free trial, bonus or promo, login, checkout and extra seat. Each one answers allow, step-up or block, with the reasons and the suggested step.

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 caseTypical abuse it is tuned forWhat it looks at first
signupFake and duplicate accounts, signup botsAccounts already on the device, automation, disposable email
free_trialThe same person taking trial after trialTrials already started on the device, disposable email, VPN, proxy and datacenter networks
bonusWelcome bonuses, referral credits and promo codes claimed by linked accountsBonuses already claimed on the device, new accounts on devices that already hold accounts
loginAccount takeover, credential stuffingFirst login from this device, a country change within an hour, the account on many devices, repeated attempts
checkoutCard testing, stolen cards, promo stackingCheckouts per hour from the device, several accounts paying from one device
extra_seatOne paid seat used by a whole teamThe account used from 3 or more devices, or from more than one country, in 24 hours
paywallFree-article limits bypassed with a private window, cleared cookies or a new accountDistinct articles read on the device (and the account, when sent) in the window
smsSMS pumping (toll fraud), resend abuse, bots burning your SMS budgetCodes 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 in step. 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" }
    ]
  }
}
FieldValues
useCaseThe use case you sent, in its canonical name
modeenforce, or mirror while mirror mode is active
decisionallow, step_up or block
stepnone, captcha, verify_email, card_or_passkey or block
reasonsUp to 8 { code, text }, strongest first
cappedAtPresent 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

CodeUse casesWhenStep
KNOWN_FRAUDallThe device or account was labeled fraud beforeblock
DENYLISTEDallThe device, account or network is on your deny listblock
NETWORK_FRAUDallThe device or network was reported for fraud elsewherecard_or_passkey
AUTOMATIONallSigns of automation in the browser or the formcaptcha
TAMPERINGallThe browser is altering its own fingerprint (privacy extensions do this too, so it only asks for the light step)verify_email
TORallThe request comes through Torverify_email
ANONYMIZED_NETWORKfree_trial, bonusA VPN, proxy or datacenter networkverify_email
DISPOSABLE_EMAILsignup, free_trial, bonusThe email domain is a disposable inbox (needs email)verify_email
HIGH_RISKallThe general decision is block and none of the checks above appliescard_or_passkey
ELEVATED_RISKallThe general decision is challenge and none of the checks above appliesverify_email
DEVICE_HAS_ACCOUNTSsignup1–2 other accounts on the device in the repeat window; 3 or moreverify_email; card_or_passkey
DEVICE_HAD_TRIALfree_trial1 other account started a trial on the device; 2 or moreverify_email; card_or_passkey
BONUS_ON_DEVICEbonus1–2 other accounts claimed a bonus on the devicecard_or_passkey
BONUS_REPEATEDbonus3 or more other accounts claimed a bonus on the deviceblock
NEW_ACCOUNT_KNOWN_DEVICEbonusA new account on a device that already has accountsverify_email
NEW_DEVICEloginFirst login to this account from this device, while it uses othersverify_email
IMPOSSIBLE_TRAVELloginThe device changed country within an hourcard_or_passkey
ACCOUNT_ON_MANY_DEVICESloginThe account was used from many devices in 24 hourscard_or_passkey
LOGIN_VELOCITYloginMany attempts from this device in a few minutescaptcha
CHECKOUT_VELOCITYcheckout5 or more checkouts from the device in the last hourcaptcha
CARD_TESTINGcheckout20 or more checkouts from the device in the last hourblock
CHECKOUT_MANY_ACCOUNTScheckout2 or more other accounts checked out from the device in the repeat windowverify_email
SHARED_SEATextra_seatThe account was used from 3 or more devices, or more than one country, in 24 hoursverify_email
PAYWALL_LIMITpaywallMore distinct articles than freeArticles in the windowyour wall step
PAYWALL_PRIVATE_WINDOWpaywallOver the limit and reading in a private windowyour wall step
MANY_CARDS_ON_DEVICEcheckout3–4 different cards on the device today (needs paymentMethod); 5–7captcha; card_or_passkey
CARD_TESTING_MANY_CARDScheckout8 or more different cards on the device todayblock
CARD_ON_MANY_DEVICEScheckoutThe same card used from 4 or more devices todayverify_email
CARD_ON_MANY_ACCOUNTScheckoutThe same card paid for 3 or more accounts in 30 dayscard_or_passkey
PHONE_INVALIDsmsThe number is not a valid international number with a country codeblock
SMS_NO_NUMBERsmsNo phone was sent with the checkverify_email
SMS_COUNTRY_NOT_ALLOWEDsmsThe number’s country is not in your allowCountriesblock
SMS_DEVICE_VELOCITYsms3 or more codes requested from the device in 10 minutescaptcha
SMS_DEVICE_FLOODsms10 or more codes requested from the device in an hourblock
SMS_DEVICE_MANY_NUMBERSsmsThe device asked for codes to 3 or more numbers in 24 hours; 6 or morecard_or_passkey; block
SMS_NUMBER_RESENDsms3 or more codes for the same number in 10 minutescaptcha
SMS_NUMBER_FLOODsms8 or more codes for the same number in an hourblock
SMS_RANGE_PUMPINGsms5 or more numbers of the same 1,000-number block got codes in an hour, across Prynt; 12 or morecard_or_passkey; block
SMS_IP_VELOCITYsms20 or more codes requested from the same network in an hourcaptcha
ANONYMIZED_NETWORKsmsA VPN, proxy, datacenter network or Torcaptcha
SMS_HIGH_RISK_DESTINATIONsmsA destination often used for SMS pumping, requested from another country; with automation or a hidden networkcaptcha; card_or_passkey
SMS_TRAFFIC_SPIKEsms30 or more codes this hour and more than 5 times your usual hourly volumecaptcha
STEP_PASSEDallThe device passed a step for this use case in the last 30 dayslowers the answer to allow
STEP_FAILEDallThe device failed or abandoned a step in the last 7 daysone 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_email or card_or_passkey. Some products never ask for a card. block can still be returned when the evidence is direct.
Use casemaxSteprepeatDays
signupcard_or_passkey30
free_trialcard_or_passkey90
bonuscard_or_passkey365
logincard_or_passkey30
checkoutcard_or_passkey30
extra_seatverify_email7
smscard_or_passkey1
paywallcard_or_passkey30

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:

EndpointWhat it does
GET /admin/control/settingsSettings 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=30Counts 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.

Next: Friction ladder