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.

Gating is economically safe to experiment with. Claims that are rejected by a gate return 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.
Recommended default: Set to your actual buys. If you only purchase mortgage leads, set ["mortgage"]. There is little reason to leave this unset if you know which verticals you buy.
JSON — requireVerticals example
{
  "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.
Important caveat: A low score does not always mean fraud. Real publisher pages on a specific topic score meaningfully; thin or generic multi-vertical forms score low simply because they contain little vertical-specific content. A score near 0 on a generic lead form is expected, not necessarily suspicious. Keep this in mind when setting your threshold.
Recommended starting point: Start conservative — around 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.
JSON — requireVerifiedScore example
{
  "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 rangeRisk band
0–20high_risk
21–50elevated
51–79normal
80–100high_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.
Recommended starting point: Around 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:

  1. New-input validation, mode, then PII — before eligibility and scoring
  2. requireRecording — recording validity
  3. requireVerticals — declared-intent match
  4. requireVerifiedScore — content-verification check
  5. 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":

JSON — combined gates example
{
  "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

These are starting points — not guarantees. The right values depend on your lead economics, publisher mix, and tolerance for false rejections. Treat every number here as a hypothesis to test with your own data.
  • 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 toward 70+ 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.

Next step: Try these settings in the API Playground, which lets you build claim requests interactively and see the live cURL output before integrating into your pipeline.

Ready to integrate?

Set your claim gates in the API Playground or go straight to the full integration guide.

Privacy choices

Allow optional analytics and masked session recordings to help improve Verfi? We exclude credentials, lead details, and evidence playback. Declining does not affect the service. Privacy policy