Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook events & payloads

InsurGrid pushes data to a URL you control — you never poll. There are two events, delivered as two distinct envelopes. Subscribe to either or both, on separate endpoint URLs if you like.

Event (topic)

Sent when

data carries

client-submission

A declaration page is extracted (policy-data flow).

A time-limited document link, the policy type, and the extracted policy fields.

form-submission

A consumer completes and submits an embedded form.

The full form response — every answer, file links, and any filled ACORD forms.

Both share the same outer shape:

{
  "topic": "client-submission",
  "data": { /* event-specific — see below */ }
}

Both are verified the same way and follow the same delivery rules — see Verify signatures and Delivery & de-duplication. In short: every request carries an x-signature header (HMAC-SHA256 of the raw request body); delivery is at-least-once, so de-duplicate — form-submission carries submission_id; the policy-data body has no dedicated id, so de-duplicate on a hash of the payload contents.

Policy-data event: client-submission

Fired when InsurGrid finishes extracting a submitted declaration page. data always carries document_link and policy_type, plus the extracted policy fields — which fields appear depends on policy_type.

Field sets vary by insurance line; the examples below are representative. InsurGrid extracts over twenty insurance lines, from a handful of source formats, and the exact field set for a given document depends on what that document actually contains. Rather than a single frozen schema, this page leads with two fully-worked, real-shape examples — auto and homeowners, the two most common lines — with complete field tables, then gives a compact map of what to expect from every other line. Treat the field tables as "the shape you'll usually see," not a contract that every field is always present.

Envelope

Field
Type
Meaning
Example

topic

string

The event type. Always "client-submission" for policy data.

"client-submission"

data.document_link

string (URL)

A time-limited link to the source declaration-page file. Fetch and store it promptly — see the warning below.

"https://files.insurgrid.com/dl/9f2a7b/declaration.pdf"

data.policy_type

string

A descriptive label for the insurance line, set per document (e.g. "Personal Auto", "Commercial Auto", "Homeowners", "Umbrella", "Other"). It is not a fixed code — don't hard-match on exact strings; use it as a hint and branch on the fields actually present. See Insurance line → field groups.

"Personal Auto"

data.*

object / array

The extracted policy fields. Set depends on policy_type.

—

document_link expires. It's a temporary download link. If you need the file, fetch and store it on your side promptly — don't save the link and expect it to work later.

Example: an auto policy

Auto field reference

Field
Type
Meaning
Example

policy.provider

string

Carrier that wrote the policy.

"Progressive"

policy.policy_number

string

The policy number.

"912345678"

policy.coverage_period.start_date / end_date

string (date)

Policy effective and expiration dates.

"2026-03-01"

policy.annual_policy_premium

number

Total annual premium.

1842.00

policy.payment_schedule

string

How the premium is billed.

"monthly"

policy.policy_status

string

Lifecycle state of the policy as of extraction.

"active"

policyholder.full_name

string

Named insured's full name.

"Jane Roe"

policyholder.address

object

Mailing address — address_line_1, city, state, postal_code, country.

{ "city": "Austin", "state": "TX" }

policyholder.phone / email

string

Contact details, when present on the declaration page.

"jane.roe@example.com"

drivers[]

array of object

Every listed driver — name, date_of_birth, driver_license_number, driver_license_state, relationship_to_policyholder, assigned_vehicles.

—

vehicles[]

array of object

Every scheduled vehicle.

—

vehicles[].vin

string

Vehicle identification number.

"JTMRFREV0ND123456"

vehicles[].year / make / model

number / string / string

Vehicle description.

2022, "Toyota", "RAV4"

vehicles[].garaging_address

object

Where the vehicle is principally kept.

{ "city": "Austin" }

vehicles[].coverages_details.liability

object

Per-person / per-accident bodily injury and property damage limits.

{ "bodily_injury_per_person": "$100,000" }

vehicles[].coverages_details.comprehensive / .collision

object

deductible and limit for each.

{ "deductible": "$500" }

discounts[]

array of object

Applied discounts — type, description, amount or percentage.

{ "type": "multi-policy", "percentage": 10 }

insurer_information

object

Carrier contact details — company_name, company_phone, claims_phone, agent_name, agent_phone.

{ "agent_name": "Sam Carter" }

prior_carrier

object

Previous carrier, when shown on the declaration page — name, policy_number, expiration_date.

{ "name": "GEICO" }

Auto policies can also carry additional_insured[], surcharges[], endorsements[], exclusions[], group_plan, and billing_information when the source document includes them.

Example: a homeowners policy

Homeowners field reference

Field
Type
Meaning
Example

policy.provider / policy_number

string

Carrier and policy number.

"State Farm", "HO-3345219"

policy.coverage_period.start_date / end_date

string (date)

Policy effective and expiration dates.

"2026-05-15"

policy.annual_policy_premium

number

Total annual premium.

2140.00

policyholder.full_name

string

Named insured's full name.

"Marcus Lee"

policyholder.address

object

Mailing address.

{ "city": "Round Rock" }

properties[]

array of object

Every insured property (usually one).

—

properties[].location

object

The property's address.

{ "address_line_1": "48 Birchwood Ln" }

properties[].ownership_status

string

owned, rented, leased, or other.

"owned"

properties[].construction_type

string

Building construction.

"frame"

properties[].year_built / square_footage

number

Building characteristics.

2004, 2350

properties[].roof_type / roof_year

string / number

Roof material and install/replacement year.

"composition shingle", 2019

properties[].coverages[]

array of object

Each coverage line — type (e.g. Dwelling, Personal Property, Loss of Use, Liability), limit, deductible, replacement_cost.

{ "type": "Dwelling", "limit": 420000 }

properties[].deductibles

object

Named deductibles — all_peril, wind_hail, hurricane, earthquake, flood.

{ "all_peril": 2500 }

properties[].mortgagee[]

array of object

Lienholder(s) on the property — name, loan_number.

{ "name": "Wells Fargo Home Mortgage" }

insurer_information

object

Carrier contact details — company_name, company_phone, claims_phone, agent_name, agent_phone.

{ "agent_name": "Priya Nair" }

prior_carrier

object

Previous carrier, when shown on the declaration page.

{ "name": "Allstate" }

Homeowners policies can also carry additional_insured[], policy_level_coverages[], and billing_information when the source document includes them.

Insurance line → field groups

InsurGrid extracts these insurance lines. Every one shares the same envelope (document_link, policy_type, plus policy fields) — this table tells you which top-level groups to expect in data for each line, so you know what to look for even for a line not fully worked out above.

Insurance line
Top-level field groups you can expect

Auto

policy, policyholder, additional_insured, drivers, vehicles, discounts, surcharges, endorsements, exclusions, insurer_information, prior_carrier, billing_information — see full example above

Homeowners

policy, policyholder, additional_insured, properties, policy_level_coverages, insurer_information, billing_information, prior_carrier — see full example above

Condo · renters · landlord · pet · personal marine/watercraft · powersports · general liability · other/uncommon lines

policy, policyholder, additional_insured, drivers, vehicles, discounts, surcharges, endorsements, exclusions, insurer_information (auto-shaped groups apply only where relevant, e.g. drivers/vehicles on a marine or powersports policy describe the operator and the craft/vehicle)

Personal umbrella

policy_information, contacts, coverages, underlying_policies, scheduled_exposures, drivers, endorsements, premium_breakdown, exclusions, territorial_coverage, business_activities, prior_coverage

Personal / small-business cyber

policy_information, contacts, coverages, endorsements, monetary_values

Flood

named_insured, insurer_information, agent_information, insured_information, policy_details, property_information, coverage_details, renewal_payment_information, mortgagee_information, additional_interests

Directors & officers (D&O)

policy, policyholder, additional_insureds, coverages, limits_and_retentions, premium_details, endorsements, exclusions, broker_information, locations, expiring_policy

Commercial package (CPP)

policy_information, contacts, coverage_parts_summary, coverages, business_operations, site_locations, mortgageholders, loss_payees, excluded_persons, endorsements, premium_breakdown, vehicles

Commercial auto

policy info, premium info, coverage limits, vehicles, drivers, business info (FEIN/NAICS/SIC), hired & non-owned auto exposure, form type & covered autos, endorsements

Business owner's policy (BOP)

policy info, premium info, property coverage (Section I: building/BPP/business income), liability coverage (Section II: the "Big 6" limits), built-in coverages, locations, additional insureds, endorsements

Commercial general liability (CGL)

policy info, premium info, coverage limits (the CGL "Big 6"), deductibles, locations & classifications, additional insureds, endorsements

Workers' compensation

policy info, premium info, Part 1 (workers' comp coverage), Part 2 (employers liability), classifications & payroll, experience modification, locations, other-states coverage, administrative details, audit provisions, endorsements

Commercial cyber

policy info, premium info, coverage limits, aggregate limit, retention / self-insured retention, business info, endorsements

Commercial flood

policy info, NFIP/program details, rating & pricing factors, premium info, coverage limits, increased cost of compliance (ICC), locations/buildings, mortgagees, claims history, endorsements

Commercial property (habitational)

policy info, premium info, coverage limits, property locations, additional info, endorsements

Commercial inland marine

policy info, premium info, coverages, scheduled items, additional insureds, endorsements

Commercial umbrella

policy info, premium info, coverage limits, underlying policies, form type & additional info

form-submission

Fired when a consumer completes and submits an embedded form (see Builder sessions → Embedding the fill form). Carries the entire response in one delivery — every answer, links to any uploaded documents, and filled ACORD forms. No follow-up API calls needed.

Envelope

Example

Field reference

Field
Type
Meaning
Example

form

object

Which form was submitted — id, public_id, name, insurance_line (personal / commercial).

{ "id": 4412, "insurance_line": "commercial" }

submission_id

integer

Unique id for this submission. De-duplicate on this.

55231

trace_id

string

Correlation id for this submission across InsurGrid systems — quote it when contacting support or matching logs.

"tr_5f3c9a2b7e14"

submitted_at

string (ISO-8601)

When the submission completed, UTC.

"2026-08-24T18:22:40Z"

agent

object

The agent this submission is attributed to — id, name, email.

{ "name": "Jane Smith" }

contact

object

The consumer's contact details, when captured — name, email, phone.

{ "email": "jane.roe@example.com" }

answers[]

array of object

Every answer, each with the question's question_id, label, type, and submitted value. See Answer value types.

—

acord

object

Present when the form maps to ACORD forms. is_acord_ready, form_ids, archive_url (a zip of the filled ACORD PDFs).

{ "form_ids": ["125", "140"] }

metadata

object

Any correlation values you supplied when the form link was generated, echoed back.

{ "partner_ref": "your-correlation-id" }

Answer value types

The type on each answer matches the question's type in Forms API → Question fields, and determines the shape of value:

Question type

value shape

Example

short_text, long_text, email, date

string

"Jane Roe"

number

number

24

dropdown, single_choice

string (the chosen option)

"Commercial"

multi_choice

array of string

["Fire", "Theft"]

address

object: line1, line2, city, state, zip, country

{ "city": "Austin", "state": "TX" }

file_upload

array of { filename, content_type, url }

[{ "filename": "losses.pdf", "url": "https://…" }]

data_table

array of row objects; columns described by the answer's own column_schema

[{ "building": "A", "units": 24 }]

File links. Each url under file_upload is a time-limited download link, as is acord.archive_url. Fetch and store the file on your side promptly — the link expires. Re-fetching the submission via GET /v2/submissions/{submission_id} re-signs the links if you need them again later.

Related

PreviousAPI reference
NextTesting & go-live