Snapshots

Snapshots capture assessment progress so visitors can save, share, and resume their work. When someone completes an assessment on your site, they can share a link with colleagues or return later to pick up where they left off.

Why snapshots matter

Snapshots enable three key scenarios:

Scenario	Description	Business value
Save and resume	Visitor starts assessment, leaves, returns later	Higher completion rates
Share with team	Visitor sends link to colleague or decision-maker	Expands reach within accounts
Handoff to Deep Fathom	Assessment data flows to signup/onboarding	Seamless lead conversion

How snapshots work

When a visitor interacts with the configurator, their progress can be captured in two ways:

1. URL-based snapshots (stateless)

Assessment state is compressed and stored in the URL hash:

https://yoursite.com/assessment#df_onramp=eJxNj0EO...

Pros: No backend required, works immediately Cons: URLs can be long; limited to ~2KB of data; PII redacted by default

2. Service-based snapshots (stateful)

Assessment state is stored on a backend service, referenced by ID:

https://yoursite.com/assessment?df_snapshot=snap_abc123

Pros: Clean URLs, full data preserved, supports large assessments Cons: Requires snapshot service endpoint

Configuring snapshots

URL snapshots (default)

URL snapshots work automatically. No configuration needed.

To allow company names in URL snapshots (disabled by default for privacy):

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-allow-url-pii="true"
></div>

caution

Only enable data-allow-url-pii for internal or demo contexts. Shareable URLs with company names may expose sensitive information.

Service-based snapshots

Point to your snapshot service endpoint:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-snapshot-endpoint="https://api.deepfathom.ai/snapshots"
></div>

When configured, the SDK will:

1. Save: POST snapshot data to the endpoint when visitors share or complete
2. Load: GET snapshot data when visitors return via a snapshot URL

Snapshot service API

If you're implementing your own snapshot service, here's the expected contract:

Save a snapshot

POST /snapshots
Content-Type: application/json

{
  "sessionId": "abc123",
  "state": { ... },
  "summary": { ... },
  "attribution": { ... },
  "timestamp": "2025-01-23T14:30:00Z"
}

Response:

{
  "snapshotId": "snap_abc123"
}

Or:

{
  "id": "snap_abc123"
}

Load a snapshot

GET /snapshots/snap_abc123

Response:

{
  "snapshot": {
    "sessionId": "abc123",
    "state": { ... },
    "summary": { ... },
    "attribution": { ... },
    "timestamp": "2025-01-23T14:30:00Z"
  }
}

Or the snapshot object directly:

{
  "sessionId": "abc123",
  "state": { ... },
  ...
}

Handoff URLs

When data-handoff-url is configured, the SDK builds a complete handoff URL that includes the snapshot reference and all attribution data:

https://app.deepfathom.ai/signup
  ?df_snapshot=snap_abc123
  &partnerId=acme-security
  &referralCode=SPRING2025
  &utm_source=partner-site
  &utm_medium=embed
  &sessionId=sess_xyz789

This URL is included in onComplete, onLeadSubmit, and onShare events, so you can:

• Display it as a "Continue to Deep Fathom" button
• Send it in follow-up emails
• Track handoff conversions

Handoff URL parameters

Parameter	Description
df_snapshot	Snapshot ID (when service succeeds)
df_onramp	URL-encoded state (fallback when service unavailable)
partnerId	Your partner identifier
referralCode	Campaign/tracking code
sessionId	Assessment session identifier
utm_*	UTM parameters for analytics
source	Attribution source identifier

Loading priority

When a visitor arrives at a page with the configurator, snapshots are loaded in this order:

1. Query parameter (?df_snapshot=...) — Highest priority
2. URL hash (#df_onramp=...) — Fallback for stateless snapshots
3. Local storage — Previous session on same device
4. Fresh start — No snapshot found

This means shared links (with query params) always take precedence over local state.

Privacy considerations

Default behavior

• URL snapshots: Company name and other PII are redacted by default
• Service snapshots: Full data is preserved (your service controls access)

When to enable URL PII

Context	Recommendation
Production partner sites	Keep PII disabled (default)
Internal sales tools	Enable if needed for demos
Development/testing	Enable for debugging

Data included in snapshots

Data type	URL snapshot (default)	URL snapshot (PII enabled)	Service snapshot
Assessment responses	Yes	Yes	Yes
Company name	Redacted	Yes	Yes
Contact info	Redacted	Redacted	Yes
Attribution	Yes	Yes	Yes
Session ID	Yes	Yes	Yes

Troubleshooting

Snapshots not saving

1. Check endpoint URL — Verify data-snapshot-endpoint is correct and accessible
2. Check CORS — Your snapshot service must allow requests from the configurator origin
3. Check response format — Service must return { snapshotId: "..." } or { id: "..." }

Snapshots not loading

1. Check URL format — Parameter should be ?df_snapshot=ID or #df_onramp=DATA
2. Check service availability — GET request must return the snapshot data
3. Check data freshness — Very old snapshots may reference outdated assessment structure

URL snapshots are too long

• This is expected for complex assessments
• Enable service-based snapshots for clean URLs
• URL snapshots are compressed but can exceed 2KB for detailed assessments

Next steps

• Events reference — Capture snapshot events in your application
• Embedding guide — Configure snapshot endpoints