Integration Guide

Overview

The Verfi SDK captures session recordings on your lead forms — mouse movements, clicks, scrolls, and form interactions — creating independent, third-party proof of the consumer's consent experience.

Integration requires a single script tag. No form modifications, no backend changes, no build step.

Quick Start

Add the SDK script to any page with a lead capture form:

<script async
  src="https://sdk.verfi.io/v2/index.min.js?apiKey=pk_live_YOUR_KEY">
</script>

That's it. The SDK will:

1. Auto-detect all <form> elements on the page
2. Start recording the session (mouse movements, clicks, scrolls, form interactions)
3. Detect and hash PII fields automatically
4. Generate a unique Verfi ID for the session
5. Inject a hidden verfiProof field into each form with the proof URL
6. Submit the session recording to Verfi when the form is submitted

How It Works

Proof Field

On form submission, the SDK automatically injects a hidden field containing the proof URL. By default, this field is named verfiProof.

Your form backend receives the proof URL alongside the rest of the form data:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "555-0100",
  "verfiProof": "https://proof.verfi.io/VF-4af0a15a"
}
            

Store this URL with the lead record and pass it to buyers. They can click it to view the full session replay — no Verfi account required.

Custom field name

If verfiProof conflicts with an existing field in your form, use the field parameter to change it:

<script async
  src="https://sdk.verfi.io/v2/index.min.js?apiKey=pk_live_YOUR_KEY&field=consent_proof">
</script>

This will inject a hidden field named consent_proof instead of verfiProof.

PII Handling

The SDK automatically detects and protects personally identifiable information:

• Auto-detection: Fields containing emails, phone numbers, SSNs, and other PII patterns are identified automatically based on field names, types, and input patterns
• Hashing: PII values are SHA-256 hashed in the browser before any data is sent to Verfi — raw PII never leaves the page
• Session recordings: Text inputs in the session replay show masked values, not actual PII

Explicit PII tagging

For fields that aren't auto-detected, you can explicitly mark them as PII:

<input type="text" name="custom_id"
  data-verfi-pii
  data-verfi-pii-category="ID" />

Supported PII categories: EMAIL, PHONE, SSN, NAME, ADDRESS, ID

SPA Support

The SDK works with single page applications out of the box:

• Starts recording immediately, even if no forms are present on initial load
• Monitors for dynamically added forms
• Periodically saves session data for long-lived pages
• Only saves sessions where meaningful user interaction occurred (prevents saving bounce sessions)

No additional configuration is needed for React, Vue, Next.js, or other SPA frameworks.

Managing Sessions (API)

Lead buyers use the Verfi REST API to search, claim, and manage sessions. Authentication uses a secret API key (sk_ prefix) with Bearer token auth.

Search / Validate a Session

Look up a session by its Verfi ID. Optionally pass hashed email and phone to verify the lead data matches:

curl "https://api.verfi.io/tenant/v1/sessions/VF-4af0a15a?email={email_hash}&phone={phone_hash}" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

The email and phone parameters are optional SHA-256 hashes. If provided, Verfi checks them against the hashed PII captured during the session — giving you independent verification that the lead data matches what was submitted.

Claim a Session

Claiming a session associates it with your tenant and starts the retention period:

curl -X POST "https://api.verfi.io/tenant/v1/sessions/VF-4af0a15a/claim"   -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"   -H "Content-Type: application/json"   -d '{"expirationDate": "2029-04-09T00:00:00Z"}'
            

The expirationDate field sets custom retention (ISO 8601 format, max 5 years from claim date). Default retention is 3 years.

List Claimed Sessions

Retrieve all sessions claimed by your tenant with pagination and filtering:

curl "https://api.verfi.io/tenant/v1/sessions?page=1&limit=20&status=claimed" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

Supports page, limit (1–100, default 20), and status filters.

Update Expiration

Extend or shorten the retention period on a claimed session:

curl -X PUT "https://api.verfi.io/tenant/v1/sessions/VF-4af0a15a/expiration"   -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"   -H "Content-Type: application/json"   -d '{"expirationDate": "2030-04-09T00:00:00Z"}'
            

Limited to 3 updates per month per session with a 24-hour cooldown between changes.

Unclaim a Session

Release a previously claimed session:

curl -X POST "https://api.verfi.io/tenant/v1/sessions/VF-4af0a15a/unclaim" \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY"

Proof Links

Every session generates a shareable proof link at proof.verfi.io. These links:

• Show a full session replay — mouse movements, clicks, scrolls, form interactions
• Display the consent disclosure language that was present on the page
• Are accessible without a Verfi account — anyone with the link can view
• Are retained for 3 years by default (up to 5 years with custom retention on claim)

Share proof links with buyers, compliance teams, or legal counsel. The session replay provides independent, visual evidence of the consumer's consent experience.

Testing

In-App Playground

The fastest way to test is the SDK Playground in your dashboard — it loads the SDK with your key, provides a sample form, and lets you submit a test session and view the recording immediately.

Debug mode

Add debug=true to the script URL to enable verbose console logging:

<script async
  src="https://sdk.verfi.io/v2/index.min.js?apiKey=pk_live_YOUR_KEY&debug=true">
</script>

This logs form detection, PII field identification, event counts, and submission status to the browser console. Look for [VERFI SDK v2] messages.

Test keys

Use a test API key (pk_test_...) during development. Test sessions work identically but are flagged as test data in the dashboard.

Verify your integration

1. Add the SDK script tag to your form page
2. Open browser DevTools → Console
3. Look for [VERFI SDK v2] log messages confirming initialization and form detection
4. Fill out and submit the form
5. Check that a verfiProof value appears in your form submission data
6. Click the proof URL to view the session replay on proof.verfi.io

FAQ