SSP Integration Guide — receive insurance leads

Machine-readable version: /docs/ssp.md · Index for agents: /llms.txt

Overview

• SavItUp members explicitly choose a carrier and consent to sharing the fields shown on the consent screen, inside the SavItUp app, before any lead exists. A lead carries no phone number and no telephone-contact consent — members call carriers themselves, from the app.
• SavItUp delivers each lead to your HTTPS endpoint as a JSON POST — API-only, never email.
• You report each lead's outcome back to SavItUp (conversion feedback).
• Billing is a flat fee per delivered lead from a rate card agreed in advance. Conversion feedback informs your next rate card — never adjusts invoices.

Onboarding is done with the SavItUp team: support@savitup.com. You provide your endpoint URL, an Authorization header value, your field mapping, and your eligibility filters. SavItUp issues your API key(s) and your outcome-endpoint base URL.

1. Receiving leads (SavItUp → you)

• Transport: HTTPS POST, content-type: application/json, to your configured endpoint.
• Auth: your configured Authorization header value is sent verbatim on every delivery. Treat it as a shared secret.
• Timeout: respond within 30 seconds; any 2xx counts as accepted. Response bodies over 64KB are truncated in our logs.
• Idempotency: every lead carries a unique 16-character lowercase-alphanumeric leadId — deduplicate on it; retries resend the same lead with the same id.
• Retries: on non-2xx / timeout / connection error, SavItUp retries roughly every 4 minutes, 5 attempts total (~16 minutes), then marks the lead failed.
• Test leads: onboarding test deliveries always carry a top-level "test": true — never bill, store, or action them as real.

Field mapping

Your body shape is up to you: you provide a mapping of SavItUp canonical source paths to your destination paths.

{
  "contact.firstName": "applicant.first_name",
  "contact.email": "applicant.email",
  "lead.leadId": "external_ref"
}

There is no contact.phone to map: since 2026-09-24 a quote lead carries no phone number at any depth, so a mapping that requires one can never be satisfied.

Canonical lead (sample values, obviously fake — real leads share this shape)

{
  "leadId": "sample0000000001",
  "createdAt": "2026-01-15T12:00:00.000Z",
  "product": "auto",
  "state": "CO",
  "zip": "80202",
  "consent": { "profile": true },
  "contact": { "firstName": "Jamie", "lastName": "Rivera", "email": "jamie.rivera@example.com" },
  "addresses": [{ "line1": "742 Evergreen Ter", "city": "Denver", "state": "CO", "zip": "80202" }],
  "household": { "memberCount": 3 },
  "people": [
    { "firstName": "Jamie", "lastName": "Rivera", "age": 34 },
    { "firstName": "Alex", "lastName": "Rivera", "age": 32 }
  ],
  "cars": [{ "year": 2021, "make": "Toyota", "model": "RAV4" }],
  "currentPolicy": { "carrier": "Old Guard Mutual", "premium": 142.5 },
  "acquisition": { "channel": "sem", "method": "code" }
}

product is auto or home today. acquisition carries channel granularity only — no third-party identifiers.

Eligibility filters

{
  "lead.product": { "type": "single", "value": "auto" },
  "lead.state": { "type": "single", "value": "CO" },
  "people.0.age": { "type": "range", "min": 21, "max": 75 },
  "cars.0.year": "unknown"
}

"unknown" always passes; single requires an exact match; range requires min ≤ value ≤ max; a lead missing a filtered value fails that filter (fails closed).

2. Conversion feedback (you → SavItUp)

• Endpoint: POST {outcomeBaseUrl}/ssp/leads/{leadId}/outcome (base URL shared during onboarding).
• Auth: header x-savitup-key: <your API key> — issued and revocable by SavItUp, rate-limited per key.
• Body: { "result": "converted" | "not_converted" | "invalid", "reason": "optional, max 500 chars" }
• converted is final. invalid is accepted only within 48 hours (inclusive) of the last delivery attempt and may replace an earlier not_converted.
• Responses: 200 recorded · 400 bad input · 401 bad/revoked key · 404 unknown or not-your lead · 409 transition not allowed.

Feedback is a quality signal only: it informs your next rate card — it never re-prices issued invoices or statements.

3. Billing

• Flat fee per delivered lead from an effective-dated rate card per provider and acquisition-source tier, agreed prospectively.
• The fee is stamped at delivery time; monthly statements are never re-priced.
• Leads marked invalid within the 48-hour window are excluded from billing.
• Leads delivered with no active rate card are billed $0 and flagged.

4. Security expectations

• TLS 1.2+ everywhere. Lead submissions in the SavItUp app are gated by hardware device attestation (Apple App Attest).
• SavItUp never sends member PII over email — delivery and feedback are API-only.
• Keep your Authorization value and x-savitup-key secret; request rotation any time.

Contact

support@savitup.com — include “SSP integration” in the subject.