API Documentation

Authentication

POST https://auth.embeddedinsurance.com/oauth2/token

The EI API uses the OAuth 2.0 client credentials grant. Exchange your client_id and client_secret for a short-lived Bearer token (default expires_in is 3600 seconds), then send it in the Authorization header of every API call. Tokens can be cached and reused until they expire — there's no need to fetch a new one per request.

Your credentials are delivered via a secure one-time link during partner onboarding.

Server-side only. Never put your client credentials in browser code, mobile apps, or public repos. The Embedded Component and any other front-end usage should call your own backend, which proxies to EI using server-held credentials.

Request Body (x-www-form-urlencoded)

Field	Type		Description
client_id	string	required	Your partner client ID
client_secret	string	required	Your partner client secret
grant_type	string	required	Always `client_credentials`

Response

200Returns access_token, token_type, and expires_in

401Invalid credentials

Request

POST https://auth.embeddedinsurance.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

Authorization: Bearer <access_token>

Embedded Component

A drop-in React widget that surfaces a personalized auto insurance offer directly inside your application — on a dashboard, account page, or post-purchase screen — without sending the customer to a separate site for the initial offer.

Distributed as @ei-tech/embedded-component on npm. You wire it up by giving it a leadId and two async callbacks — getContent and getUrl — that proxy to your backend. The component takes care of polling, rendering the right offer variant, and handing off to the EI microsite when the customer clicks through.

When to use what. Reach for the Embedded Component when you want to keep the customer inside your app for the initial offer impression. Use Get Quote Link or Get Quote Share Link when a hard redirect to the EI quoting microsite is the right experience — typically once the customer has shown intent.

Credentials stay on your server. The browser only talks to your two proxy routes; your EI client_id and client_secret never leave your backend.

How it works

Mount. The component immediately calls getContent(leadId), which hits a route on your backend (e.g. GET /api/embedded-content/:leadId).
Proxy. Your backend authenticates with EI via POST /oauth2/token, then forwards the request to GET /auto/v1/leads/:id/embedded-content and returns the JSON.
Render. The component picks the variant from layout — one of none, content, content-cta, image-content, or image-content-cta — and renders the corresponding offer.
Poll while pending. If the response sets "continuePolling": true, the component re-runs getContent every pollingInterval ms (default 5000), up to maxPollingAttempts iterations (default 50), until polling is turned off or the cap is hit.
Hand off. When the customer clicks the CTA, the component calls getUrl(leadId); your backend proxies POST /auto/v1/leads/:id/get-link and the component opens the returned single-use URL in a new tab.

Component props

Prop	Type		Description
leadId	string	required	The EI lead ID returned by Create Lead
getContent	(leadId) => Promise<Content>	required	Async fetch of the content payload from your backend proxy
getUrl	(leadId) => Promise<string>	required	Async fetch of the one-time microsite URL when the customer clicks the CTA
theme	'dark' \| 'light'	optional	Visual theme. Defaults to `dark`
pollingInterval	number	optional	Milliseconds between content polls. Defaults to `5000`
maxPollingAttempts	number	optional	Cap on poll iterations. Defaults to `50`

Content payload

The JSON your backend returns from GET /auto/v1/leads/:id/embedded-content is what the component renders. The layout field chooses the variant; the rest of the fields populate that variant. EI controls the copy and imagery server-side, so partners typically don't need to inspect the payload — just forward it through.

layout	Renders	Required fields
none	Nothing	-
content	Heading + subheading + footer	`mainHeading`, `subHeading`, `footerText`
content-cta	Text with a CTA button	Above + `buttonText`
image-content	Image + text	`mainHeading`, `subHeading`, `footerText`, `imageUrl`, `imageAlt`
image-content-cta	Image + text + CTA	All of the above + `buttonText`

CTA layouts also accept these optional fields for fine-grained control: ctaHeadline, buttonAriaLabel, buttonDisabled, buttonLoading, buttonBackgroundColor, buttonTextColor. Every payload — regardless of layout — can include continuePolling (boolean) to control the polling loop described above.

Install

npm install @ei-tech/embedded-component

Requires React 18 or higher. Import the bundled stylesheet once in your app entry: import '@ei-tech/embedded-component/styles';

1. Server-side proxy (two routes)

// Express example - keep this on your backend

async function getEIToken() {
  const r = await fetch('https://auth.embeddedinsurance.com/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.EI_CLIENT_ID,
      client_secret: process.env.EI_CLIENT_SECRET,
      grant_type: 'client_credentials'
    })
  });
  return (await r.json()).access_token;
}

// Drives getContent - proxies the embedded-content payload
app.get('/api/embedded-content/:leadId', async (req, res) => {
  const token = await getEIToken();
  const r = await fetch(
    `https://api.embeddedinsurance.com/auto/v1/leads/${req.params.leadId}/embedded-content`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  res.json(await r.json());
});

// Drives getUrl - proxies the one-time microsite link
app.get('/api/quote-link/:leadId', async (req, res) => {
  const token = await getEIToken();
  const r = await fetch(
    `https://api.embeddedinsurance.com/auto/v1/leads/${req.params.leadId}/get-link`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ partnerBrand: process.env.EI_PARTNER_BRAND })
    }
  );
  const { url } = await r.json();
  res.json(url);
});

2. Render the component

import { EmbeddedInsurance, Content } from '@ei-tech/embedded-component';

const getContent = async (leadId: string): Promise<Content> => {
  const r = await fetch(`/api/embedded-content/${leadId}`);
  if (!r.ok) throw new Error('Failed to load content');
  return r.json();
};

const getUrl = async (leadId: string): Promise<string> => {
  const r = await fetch(`/api/quote-link/${leadId}`);
  if (!r.ok) throw new Error('Failed to get link');
  return r.json();
};

export function Dashboard({ leadId }: { leadId: string }) {
  return (
    <EmbeddedInsurance
      leadId={leadId}
      getContent={getContent}
      getUrl={getUrl}
      theme="dark"
    />
  );
}

Example content payload

{
  "layout": "image-content-cta",
  "mainHeading": "Your Quote is Ready!",
  "subHeading": "Click to view your personalized insurance details.",
  "buttonText": "View Now",
  "imageUrl": "https://cdn.example.com/quote.svg",
  "imageAlt": "Insurance Quote",
  "footerText": "Insurance by Embedded Insurance Agency, LLC.",
  "continuePolling": false
}

Create Lead

POST /auto/v1/leads

Submit a new auto insurance lead to EI. At a minimum you need to send the primary applicant's contact details, address, and one vehicle. EI returns a lead id immediately; quoting then runs asynchronously and progress is delivered to your webhook endpoint.

Test vs. production data. EI treats every submission as production data by default. To send a lead that should not be quoted or routed to a carrier, set "isTest": true at the root of the request body. The same base URL and credentials are used for both — the flag is the only switch.

Applicant (required)

Field	Type		Description
firstName	string	required
lastName	string	required
dateOfBirth	string	required	Format: `YYYY-MM-DD`
address	object	required	`address1`, `city`, `state` (2-letter), `zip` (5-digit). `address2` optional.
phoneNumber	string	required	E.164 format: `+1XXXXXXXXXX`
email	string	required	Applicant's email address. Each applicant within a lead must have a distinct email.
gender	string	optional	`Male` · `Female` · `Non-Binary`
maritalStatus	string	optional	`Single` · `Married` · `Divorced` · `Widowed` · `Separated` · `Domestic Partner`
residenceOwnershipType	string	optional	`Own` · `Rent` · `Other`
monthsAtAddress	integer	optional
priorAddress	object	optional	Same structure as `address`
licenseNumber	string	optional
licenseState	string	optional	2-letter state abbreviation
yearsLicensed	integer	optional
educationLevel	string	optional	`HighSchool` · `BachelorsDegree` · `MastersDegree` · and more
income	array	optional	Array of income objects: `employmentType`, `employerName`, `jobTitle`, `monthsAtEmployer`, `annualIncome`

Co-applicants (optional)

Object with numeric string keys "1"–"9". Each shares the same optional fields as applicant, plus:

Field	Type		Description
relationshipToApplicant	string	optional	`Spouse` · `Parent` · `Child` · `Relative` · `Cohabitant` · `Other`

Vehicles (required - at least one)

Object with numeric string keys "1"–"9". Vehicle 1 is required.

Field	Type		Description
make	string	required
model	string	required
year	string	required	4-digit year as string
vin	string	optional	17-character VIN
trim	string	optional
estimatedAnnualMileage	integer	optional
isFinanced	boolean	optional
lien	object	optional	`lienHolder`, `monthlyPayment`, `originalAmount`, `payoffAmount`, `remainingTerm`

Root fields

Field	Type		Description
orgId	string	required	Your organization ID provided by EI
isTest	boolean	optional	Set `true` for test requests
partnerExternalId	string	optional	Your internal reference ID for this lead
partnerData	object	optional	Arbitrary key-value metadata to pass through
insuranceGrade	string	optional	Single letter `A`–`I` representing your lead-quality grading. EI works with each partner during onboarding to define the meaning of each grade — separate documentation is provided. Safe to omit if you don't yet have a grading model.

Response

200Lead accepted. Returns the lead id and a status of PENDING.

400Validation error or duplicate lead

401Missing or invalid Bearer token

Lead status lifecycle

Status	Meaning
PENDING	The lead has been accepted and is being processed. Quoting, verification, and any downstream work happens in the background — listen for webhook events to follow progress.
COMPLETED	All asynchronous processing for the lead has finished. The lead's quotes (if any) and verification results are final.

Request

POST /auto/v1/leads
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "applicant": {
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-01-15",
    "address": {
      "address1": "123 Main St",
      "city": "Boston",
      "state": "MA",
      "zip": "02108"
    },
    "phoneNumber": "+16175551234",
    "email": "john.doe@example.com",
    "gender": "Male",
    "maritalStatus": "Married"
  },
  "coapplicants": {
    "1": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1982-06-20",
      "relationshipToApplicant": "Spouse"
    }
  },
  "vehicles": {
    "1": {
      "vin": "1HGCM82633A123456",
      "make": "Toyota",
      "model": "Camry",
      "year": "2020"
    }
  },
  "orgId": "your-org-id",
  "insuranceGrade": "A"
}

Response

{
  "id": "bea82fae-e1b7-5bc5-810b-c38694e66aef",
  "status": "PENDING"
}

Get Lead

GET /auto/v1/leads/:id

Fetch the latest snapshot of a lead — its current lifecycle status plus any quotes that have been generated so far. Polling this endpoint is supported but webhooks are the recommended way to stay in sync; use Get Lead for ad-hoc reads (e.g. an internal admin view or a recovery path).

Path Parameters

Field	Type		Description
id	string (UUID)	required	The lead ID returned by Create Lead

Response

200The lead object with its current status and any available quotes

404Lead not found for the supplied ID

Request

GET /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef
Authorization: Bearer <access_token>

Response

{
  "id": "bea82fae-e1b7-5bc5-810b-c38694e66aef",
  "status": "PENDING",
  "partnerExternalId": "your-ref-123"
}

Update Lead

POST /auto/v1/leads/:id

Re-submit a lead with corrected or expanded information and trigger a fresh quote. Send only the fields you want to change — anything you omit is left untouched. When the new quote is ready you'll receive a quote webhook.

The body's id must match the path's :id. This is a deliberate belt-and-braces check to avoid accidentally updating the wrong lead when wiring this endpoint up.

Path Parameters

Field	Type
id	string (UUID)	required

Request Body

Field	Type		Description
id	string (UUID)	required	Lead ID (must match path param)
address	object	optional	Updated address
drivers	object	optional	Keyed `"1"`–`"9"`, updated driver info
vehicles	object	optional	Keyed `"1"`–`"9"`, updated vehicle info

Response

200Updated lead with refreshed quotes

400Validation error

Request

POST /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "id": "bea82fae-e1b7-5bc5-810b-c38694e66aef",
  "address": {
    "address1": "456 New Ave",
    "city": "Boston",
    "state": "MA",
    "zip": "02109"
  },
  "vehicles": {
    "1": {
      "vin": "1HGCM82633A123456",
      "make": "Toyota",
      "model": "Camry",
      "year": "2020"
    }
  }
}

Get Quote Link

POST /auto/v1/leads/:id/get-link

Returns a single-use URL that directs the applicant to the Embedded Insurance quoting microsite, pre-populated with their lead data.

Each link is consumed the first time it's opened — after that it can't be reused. Generate a fresh link every time you need to send the applicant back to the microsite. If you need a link that survives multiple opens (for email, SMS, or sharing), use Get Quote Share Link instead.

Path Parameters

Field	Type
id	string (UUID)	required

Request Body

Field	Type		Description
partnerBrand	string	required	Your partner brand identifier provided by EI

Response

200Returns url - a one-time redirect link

Request

POST /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef/get-link
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "partnerBrand": "your-brand"
}

Response

{
  "url": "https://quote.embeddedinsurance.com/..."
}

Get Quote Share Link

POST /auto/v1/leads/:leadId/quote/get-share-link

Returns a multi-use URL to the quoting microsite that's safe to send to the applicant directly — e.g. by email or SMS. The link stays valid for a configurable window and can be opened more than once during that window.

The default TTL is 60 minutes, but EI configures this per partner. Talk to your EI contact during integration planning if you need a longer or shorter window for your channel.

Path Parameters

Field	Type
leadId	string (UUID)	required

Request Body

Field	Type		Description
partnerBrand	string	required	Your partner brand identifier
returnUrl	string	optional	Where to send the applicant after they finish the quoting flow
partnerExternalId	string	optional	Your internal reference for this lead — echoed back on related webhooks

Response

200Returns url and expiresInSeconds — the remaining lifetime of the link

Request

POST /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef/quote/get-share-link
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "partnerBrand": "your-brand",
  "returnUrl": "https://yoursite.com/thank-you",
  "partnerExternalId": "your-ref-123"
}

Response

{
  "url": "https://quote.embeddedinsurance.com/share/...",
  "expiresInSeconds": 3600
}

Get Quote Content

GET /auto/v1/leads/:id/embedded-content

Returns the content payload used to render the inline offer inside the Embedded Component. Your backend proxies this endpoint and forwards the JSON straight to the component's getContent callback. The layout field on the response selects which variant the component renders; see the Content payload table for the full set of layouts and fields. Set continuePolling: true on the response while quoting is still in flight — the component will poll this endpoint again until you return false.

Path Parameters

Field	Type		Description
id	string (UUID)	required	The lead ID returned by Create Lead

Response

200Content payload — passed through to the Embedded Component

Request

GET /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef/embedded-content
Authorization: Bearer <access_token>

Response

{
  "layout": "image-content-cta",
  "mainHeading": "Your Quote is Ready!",
  "subHeading": "Click to view your personalized insurance details.",
  "buttonText": "View Now",
  "imageUrl": "https://cdn.example.com/quote.svg",
  "imageAlt": "Insurance Quote",
  "footerText": "Insurance by Embedded Insurance Agency, LLC.",
  "continuePolling": false
}

Get Verification Link

POST /auto/v1/leads/:id/verify/get-link

Returns a single-use link to the EI verification microsite, where the applicant can confirm their existing coverage so EI can quote against it.

The link is consumed the first time it's opened. Use this endpoint for in-session redirects from your app; use Get Verification Share Link for anything you intend to send via email or SMS.

Path Parameters

Field	Type
id	string (UUID)	required

Request Body

Field	Type		Description
partnerBrand	string	required	Your partner brand identifier
returnUrl	string	optional	Where to send the applicant after verification finishes
partnerExternalId	string	optional	Your internal reference — echoed back on the resulting verification webhook

Response

200Returns url — a one-time verification link

Request

POST /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef/verify/get-link
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "partnerBrand": "your-brand",
  "returnUrl": "https://yoursite.com/thank-you",
  "partnerExternalId": "your-ref-123"
}

Response

{
  "url": "https://verify.embeddedinsurance.com/..."
}

Get Verification Share Link

POST /auto/v1/leads/:leadId/verify/get-share-link

Returns a multi-use verification link safe to send to the applicant directly — e.g. by email or SMS. The link stays valid for a configurable window.

The default TTL is 60 minutes, configurable per partner. Talk to your EI contact during integration planning if your channel needs a different window.

Path Parameters

Field	Type
leadId	string (UUID)	required

Request Body

Field	Type		Description
partnerBrand	string	required	Your partner brand identifier
returnUrl	string	optional	Where to send the applicant after verification finishes
partnerExternalId	string	optional	Your internal reference — echoed back on the resulting verification webhook

Response

200Returns url and expiresInSeconds — the remaining lifetime of the link

Request

POST /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef/verify/get-share-link
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "partnerBrand": "your-brand",
  "returnUrl": "https://yoursite.com/thank-you",
  "partnerExternalId": "your-ref-123"
}

Response

{
  "url": "https://verify.embeddedinsurance.com/share/...",
  "expiresInSeconds": 3600
}

Create Lead Event

POST /auto/v1/leads/:id/events

Record a partner-side lifecycle event against a lead — the inverse of the webhook flow. Use this to tell EI about state changes that happen on your side (for example, the applicant successfully authenticating in your app). The supported event types are intentionally narrow today; new types are added as EI and partners agree on what's useful to signal.

Path Parameters

Field	Type
id	string (UUID)	required

Request Body

Field	Type		Description
type	string	required	Event type. Supported values: APPLICANT_AUTHENTICATED

Request

POST /auto/v1/leads/bea82fae-e1b7-5bc5-810b-c38694e66aef/events
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "type": "APPLICANT_AUTHENTICATED"
}

Response

{
  "ok": true,
  "eventId": "evt_123456789"
}

Common Errors

These status codes are returned consistently across the API. Endpoint-specific errors are documented inside each endpoint's section.

400The request body failed validation or was malformed

401The Bearer token is missing, expired, or invalid

403The credentials are valid but not permitted to perform this action

404The lead, quote, or other resource doesn't exist for your partner

500Unexpected server error — safe to retry with backoff

Error responses use a JSON body with a machine-readable error code and a human-readable message. Always log the message — it usually pinpoints exactly which field caused the failure.

Example Error

{
  "error": "invalid_request",
  "message": "Missing required field: applicant.firstName"
}

Webhooks - Overview

EI delivers lifecycle events for your leads to an HTTPS URL you provide during onboarding. Each event arrives as an HTTP POST with a JSON body, signed so you can confirm it came from EI. Webhooks are the recommended way to track quoting and verification progress — Get Lead is for ad-hoc reads, not polling loops.

Headers (every event)

Header	Value
Content-Type	`application/json`
X-Webhook-Signature	Hex-encoded HMAC-SHA256 of the raw request body, signed with the webhook secret EI shared with you during onboarding. See Verifying Signatures.

Common envelope

All event bodies share these fields:

Field	Type	Description
id	string	Unique event ID
leadId	string	The lead this event relates to
partnerCode	string	Your EI partner code
partnerExternalId	string	Optional - the ID you supplied via Create Lead
eventType	string	One of `verification` · `quote` · `needs_insurance`
eventTime	string	ISO 8601 timestamp
idempotencyKey	string	Stable identifier for this logical event. Retries of the same event re-use the same key — store the first one you see and treat duplicates as a no-op.

Acknowledge receipt by responding with any 2xx status within a few seconds. Anything else (non-2xx, timeout, connection error) is treated as a delivery failure and may be retried by EI, so make your handler idempotent — store idempotencyKey the first time you process an event and short-circuit on duplicates.

Minimal handler

// Express - keep the raw body so the signature check works
app.post('/webhooks/ei',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig  = req.headers['x-webhook-signature'];
    const body = req.body.toString('utf8');

    if (!verifyWebhookSignature(process.env.EI_WEBHOOK_SECRET, sig, body)) {
      return res.status(401).end();
    }

    const event = JSON.parse(body);
    // dedupe on event.idempotencyKey, then handle by event.eventType
    res.sendStatus(200);
  }
);

Verifying Signatures

Every webhook is signed with HMAC-SHA256 over the raw request body, using a secret EI shares with you during onboarding. Reject any request that doesn't verify — without this check, anyone who knows your URL can forge events.

Read the X-Webhook-Signature header.
Compute HMAC-SHA256(secret, rawBody) as a hex string.
Compare the two using a constant-time equality check.

Use the raw request body - re-serializing parsed JSON will change byte ordering and break the check.

Node.js

import crypto from 'node:crypto';

const createWebhookSignature = (secret, body) => {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(body);
  return hmac.digest('hex');
};

export const verifyWebhookSignature = (secret, signature, body) => {
  if (!signature) return false;
  const expected = createWebhookSignature(secret, body);
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected,  'hex'),
    );
  } catch {
    return false;
  }
};

Verification Events

POST eventType: verification

Delivered once verification finishes for a lead — either successfully (status completed) or with a structured failure reason (status failed). The payload tells you what coverage we found and includes references to any uploaded documents (ID cards, declarations pages).

Status values

completed failed

Completed - fields

Field	Type	Description
insuranceVerification.id	string	Verification record ID
insuranceVerification.source	string	`id-card` · `third-party`
policyInfo.carrier	string	Verified carrier name (optional)
policyInfo.policyType	string	Always `auto`
policyInfo.policyNumber	string	Optional
policyInfo.vehicles[]	array	`vin`, `year`, `make`, `model` - all optional
policyInfo.namedInsureds[]	array	`firstName`, `lastName`, `isPrimary`
media[]	array	`documentType` (`insurance-id-card` · `declarations`), `url`, `description`, `contentType`, `size`, `createdAt`, `expiresAt`
verificationConfidence	number	Optional - confidence score from 0.00 to 1.00

Failed - failure reasons

_tag	Description
NoActiveAutoPoliciesFound	No active auto policies were found for the insured
NoVehicleMatchesFound	No auto policies with matching vehicles were found
RetrieveError	An error occurred while retrieving verification data

Media URLs are short-lived. Each entry in media[] is a pre-signed link with an expiresAt. If you need to retain the asset, download it to your own storage before the link expires — refetching the event later won't refresh the URL.

Completed

{
  "id": "evt_abc123",
  "leadId": "lead_987654321",
  "partnerExternalId": "partner_app_456",
  "partnerCode": "ACME",
  "eventType": "verification",
  "eventTime": "2024-01-15T10:30:00.000Z",
  "status": "completed",
  "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "insuranceVerification": {
    "id": "verification_123",
    "source": "id-card",
    "policyInfo": {
      "carrier": "Progressive",
      "policyType": "auto",
      "policyNumber": "POL123456789",
      "vehicles": [
        { "vin": "1HGBH41JXMN109186", "year": "2023", "make": "Honda", "model": "Accord" }
      ],
      "namedInsureds": [
        { "firstName": "Jane", "lastName": "Doe", "isPrimary": true }
      ]
    },
    "media": [
      {
        "documentType": "insurance-id-card",
        "url": "https://storage.googleapis.com/ei-media/insurance-cards/id-card-123.jpg",
        "description": "Insurance identification card",
        "contentType": "image/jpeg",
        "size": 512000,
        "createdAt": "2024-01-15T10:25:00.000Z",
        "expiresAt": "2024-01-22T10:25:00.000Z"
      }
    ],
    "verificationConfidence": 0.95
  }
}

Failed

{
  "id": "evt_def456",
  "leadId": "lead_987654321",
  "partnerCode": "ACME",
  "eventType": "verification",
  "eventTime": "2024-01-15T10:35:00.000Z",
  "status": "failed",
  "idempotencyKey": "f6e5d4c3-b2a1-0987-fedc-ba9876543210",
  "insuranceVerification": {
    "id": "verification_124",
    "source": "third-party",
    "failureReasons": [
      { "_tag": "NoActiveAutoPoliciesFound", "message": "No active auto policies found" }
    ]
  }
}

Quote Events

POST eventType: quote · status: completed

Delivered when a quote is successfully generated for a lead.

Fields

Field	Type	Description
quote.id	string	Quote ID
quote.carrier	string	Insurance carrier the quote is with
quote.totalPremiumCents	integer	Total premium in cents (optional)
quote.savingsAmountCents	integer	Savings vs current policy in cents
quote.savingsMonthlyCents	integer	Monthly savings in cents
quote.savingsAnnualCents	integer	Annual savings in cents (rounded to nearest $10)
quote.currentPaymentMonthlyCents	integer	Current monthly payment in cents
quote.newPaymentMonthlyCents	integer	New monthly payment in cents

The savings and current-payment fields (savingsAmountCents, savingsMonthlyCents, savingsAnnualCents, currentPaymentMonthlyCents, newPaymentMonthlyCents) are only populated when EI can compare the new quote against prior coverage — i.e. when the lead has both a quote and a successful verification result. For "cold" quotes (no prior policy on file) you'll get just totalPremiumCents; don't render savings UI unconditionally.

With prior insurance

{
  "id": "evt_ghi789",
  "leadId": "lead_987654321",
  "partnerExternalId": "partner_app_456",
  "partnerCode": "ACME",
  "eventType": "quote",
  "eventTime": "2024-01-15T11:15:00.000Z",
  "status": "completed",
  "idempotencyKey": "12345678-abcd-ef01-2345-6789abcdef01",
  "quote": {
    "id": "quote_456",
    "carrier": "Geico",
    "totalPremiumCents": 120000,
    "savingsAmountCents": 30000,
    "savingsMonthlyCents": 2500,
    "savingsAnnualCents": 30000,
    "currentPaymentMonthlyCents": 12500,
    "newPaymentMonthlyCents": 10000
  }
}

Cold quote

{
  "id": "evt_jkl012",
  "leadId": "lead_987654321",
  "partnerCode": "ACME",
  "eventType": "quote",
  "eventTime": "2024-01-15T11:15:00.000Z",
  "status": "completed",
  "idempotencyKey": "abcdef01-2345-6789-abcd-ef0123456789",
  "quote": {
    "id": "quote_457",
    "carrier": "Allstate",
    "totalPremiumCents": 150000
  }
}

Needs Insurance Event

POST eventType: needs_insurance

Delivered when a user signals — inside the insurance verification app — that they need a new auto policy rather than verifying an existing one. Treat this as a hand-off: the user has effectively opted into being quoted, so this is the right moment to kick off your quoting flow.

Fields

Field	Type	Description
source	string	Always `insurance_verification_app`

All other fields come from the common envelope.

Event

{
  "id": "evt_mno345",
  "leadId": "lead_987654321",
  "partnerExternalId": "partner_app_456",
  "partnerCode": "ACME",
  "eventType": "needs_insurance",
  "source": "insurance_verification_app",
  "eventTime": "2024-01-15T09:00:00.000Z",
  "idempotencyKey": "11112222-3333-4444-5555-666677778888"
}

Get Health

GET /auto/v1/health

Lightweight liveness probe for the API. No authentication required, no side effects — safe to hit from uptime monitors, synthetic checks, or as a pre-flight from your backend before the first authenticated call after a deploy.

Response

200API is healthy

5xxService degraded or unavailable

Request

GET https://api.embeddedinsurance.com/auto/v1/health

Response

{
  "status": "ok"
}

Embedded Insurance API - Auto

How a typical integration flows

Authentication

Embedded Component

Create Lead

Get Lead

Update Lead

Get Quote Link

Get Quote Content

Get Verification Link

Create Lead Event

Common Errors

Webhooks - Overview

Verifying Signatures

Verification Events

Quote Events

Needs Insurance Event

Get Health