Tuning Claim Gates
How and why to tune Verfi's claim-time gates for your acquisition strategy.
The Core Trade-off
Every claim gate trades volume vs. quality and exclusivity. Tighter gates mean fewer sessions clear — but each cleared claim carries higher confidence. Looser gates let more sessions through at the cost of accepting some mismatches or lower-quality leads.
There is no universally correct setting. The right thresholds depend on your lead economics: what you pay per lead, what a conversion is worth, and how much review capacity you have. Gates are a tool to express your own acquisition policy in code.
409 and are not consumed and not charged. You can tighten or loosen thresholds, observe rejection rates, and adjust without paying for the sessions you reject.Single-call PII and mode matching
Release check: These options require API release #707. Verify the selected API's live OpenAPI lists them before use; older APIs ignore unknown fields.
Send requirePII: ["email", "phone"] with emailHash and phoneHash to require both captured values to match. Select just one field for email-only or phone-only matching. Hash the exact captured UTF-8 value using lowercase hexadecimal SHA-256, without normalization or double-hashing. No preliminary lookup is required.
Missing/malformed required hashes return 400 invalid_pii_hash; invalid policies or unselected supplied hashes return 400 invalid_pii_requirement. Missing capture or mismatches return 409 pii_mismatch. Native evidence returns 409 pii_matching_unavailable.
requireClaimMode: "exclusive" (or "multi") checks the publisher's immutable mode; it cannot change it. Omission accepts either. Invalid values return 400 invalid_claim_mode_requirement; mode mismatch returns 409 claim_mode_mismatch.
After wallet receipt lookup and session resolution, new-input validation, mode and PII checks run before session eligibility and the existing recording, vertical, verified-score and quality gates. Rejections create no new claim or debit. Identical wallet retries can replay historical receipts without re-evaluating gates. See the full contract and Home Insurance request.
requireRecording
Set requireRecording: true to require at least two meaningful clicks, scrolls or form interactions. Passive mouse movement alone does not count. Failure returns 409 no_recording before the claim or charge. False or omitted skips this gate.
New web-session claims evaluate recording, declared verticals, verified score, then quality, returning the first failure. Optional PII and mode gates run before these checks; no separate lookup is required. See the agent integration entry point for exact requests, response mapping and retries.
requireVerticals
Set this to the vertical(s) you actually buy. This checks declared labels, not the actual product sold. Multiple selected values mean any overlap; select the matching vertical per lead type. When a claim request includes requireVerticals, Verfi checks whether the session's declared intent verticals overlap with your list. No overlap means rejection.
- This is a hard categorical match — it is low risk to set tight.
- A session with no declared intent is treated as a mismatch and rejected.
- Rejected with
409 intent_mismatch.
["mortgage"]. There is little reason to leave this unset if you know which verticals you buy.{
"requireVerticals": ["mortgage", "home_insurance"]
}requireVerifiedScore (0–1)
This gate applies a cached keyword heuristic to URL, page title and non-PII form metadata against declared starter verticals. It does not inspect replay content. Scores are averaged over declared starter verticals, not just the buyer's requested vertical. Custom-only or absent declarations score zero. A score of 1.0 means strong alignment; 0.0 means little or no signal.
- Higher threshold = you only pay for leads whose session content genuinely resembles the declared vertical.
- Rejected below threshold with
409 verification_below_threshold. - The score is computed lazily on the first claim that checks it, then cached on the session.
0 on a generic lead form is expected, not necessarily suspicious. Keep this in mind when setting your threshold.0.3–0.5 — and tune with real data from your own leads. Going straight to 0.8 on day one may over-reject legitimate leads from publishers using simple forms.{
"requireVerifiedScore": 0.4
}minQualityScore (0–100)
This gate is your bot and lead-quality floor. Verfi scores each session on a 0–100 scale based on behavioral signals — interaction patterns, timing, mouse movement, and other signals that distinguish human-driven sessions from automated or low-quality ones.
Use the table below as a rough guide to what score ranges typically indicate:
| Score range | Risk band |
|---|---|
| 0–20 | high_risk |
| 21–50 | elevated |
| 51–79 | normal |
| 80–100 | high_confidence_human |
- Rejected below threshold with
409 quality_below_threshold. - Raising toward
70+is appropriate for premium or high-cost verticals where the cost of a bad lead is high. - Lowering it means you'd rather review borderline sessions manually than auto-reject them.
50, which matches the product-gate recommendation and sits at the boundary between elevated and normal. Tune up toward 70+ for premium verticals; tune down if your review workflow can catch borderline cases.Combining Gates & Gate Order
All selected gates can be combined in a single claim request to express a complete policy. Gate evaluation runs in a fixed order:
- New-input validation, mode, then PII — before eligibility and scoring
- requireRecording — recording validity
- requireVerticals — declared-intent match
- requireVerifiedScore — content-verification check
- minQualityScore — bot/quality floor last
Evaluation is fail-fast: the first gate that fails returns immediately. A 409 response tells you the first thing that failed, not everything that failed. Use lookup/status for diagnostics; do not weaken a production claim policy to make a rejected lead pass.
A combined policy example — "mortgage leads, content-verified ≥ 0.5, quality ≥ 60":
{
"requireVerticals": ["mortgage"],
"requireVerifiedScore": 0.5,
"minQualityScore": 60
}This body, added to a claim request, means: only claim this session if it was declared as a mortgage lead, its recorded content scores ≥ 0.5 on mortgage-relevance, and its quality score is ≥ 60. Any failure returns 409 at the first failed gate.
Recommended Starting Points
- requireVerticals — set to your actual buys immediately; this is a low-risk, high-value gate.
- requireVerifiedScore — start around
0.3–0.5; observe rejection rates and tune from there. - minQualityScore — start around
50; raise toward70+for premium / high-cost verticals.
Remember that 409'd claims are not consumed and not charged. Running a period of parallel observation — logging what would have been rejected without actually gating — can give you confidence before tightening.
Ready to integrate?
Set your claim gates in the API Playground or go straight to the full integration guide.