> For the complete documentation index, see [llms.txt](https://docs.insurgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurgrid.com/api-reference/webhook-events.md). # 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`](#policy-data-event-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`](#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: ```json { "topic": "client-submission", "data": { /* event-specific — see below */ } } ``` Both are verified the same way and follow the same delivery rules — see [Verify signatures](/guides/signing-verification.md) and [Delivery & de-duplication](/guides/delivery-dedup.md). 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](#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 ```json { "topic": "client-submission", "data": { "document_link": "https://files.insurgrid.com/dl/9f2a7b/declaration.pdf", "policy_type": "Personal Auto", "policy": { "provider": "Progressive", "policy_number": "912345678", "coverage_period": { "start_date": "2026-03-01", "end_date": "2027-03-01" }, "policy_term": "12 months", "annual_policy_premium": 1842.00, "payment_schedule": "monthly", "payment_method": "EFT", "policy_status": "active" }, "policyholder": { "entity_type": "individual", "first_name": "Jane", "last_name": "Roe", "full_name": "Jane Roe", "date_of_birth": "1989-04-12", "address": { "address_line_1": "12 Oak St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" }, "phone": "(555) 010-1234", "email": "jane.roe@example.com" }, "drivers": [ { "name": "Jane Roe", "date_of_birth": "1989-04-12", "driver_license_number": "TX-01234567", "driver_license_state": "TX", "relationship_to_policyholder": "self", "gender": "F", "marital_status": "single", "assigned_vehicles": ["1"] } ], "vehicles": [ { "vehicle_number": "1", "year": 2022, "make": "Toyota", "model": "RAV4", "vin": "JTMRFREV0ND123456", "usage": "commute", "annual_mileage": "9000", "garaging_address": { "address_line_1": "12 Oak St", "city": "Austin", "state": "TX", "postal_code": "78701" }, "coverages_details": { "liability": { "bodily_injury_per_person": "$100,000", "bodily_injury_per_accident": "$300,000", "property_damage": "$100,000" }, "comprehensive": { "deductible": "$500", "limit": "ACV" }, "collision": { "deductible": "$500", "limit": "ACV" } } } ], "discounts": [ { "type": "multi-policy", "description": "Bundled with homeowners", "percentage": 10 } ], "insurer_information": { "company_name": "Progressive", "company_phone": "1-800-776-4737", "claims_phone": "1-800-274-4499", "agent_name": "Sam Carter", "agent_phone": "(555) 220-9911" }, "prior_carrier": { "name": "GEICO", "policy_number": "88213-A", "expiration_date": "2026-02-28" } } } ``` #### 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 ```json { "topic": "client-submission", "data": { "document_link": "https://files.insurgrid.com/dl/4c1e9a/declaration.pdf", "policy_type": "Homeowners", "policy": { "provider": "State Farm", "policy_number": "HO-3345219", "coverage_period": { "start_date": "2026-05-15", "end_date": "2027-05-15" }, "policy_term": "12 months", "annual_policy_premium": 2140.00, "payment_schedule": "annual", "policy_status": "active" }, "policyholder": { "entity_type": "individual", "first_name": "Marcus", "last_name": "Lee", "full_name": "Marcus Lee", "address": { "address_line_1": "48 Birchwood Ln", "city": "Round Rock", "state": "TX", "postal_code": "78664", "country": "US" }, "phone": "(555) 402-7788", "email": "marcus.lee@example.com" }, "properties": [ { "property_id": "1", "location": { "address_line_1": "48 Birchwood Ln", "city": "Round Rock", "state": "TX", "postal_code": "78664" }, "ownership_status": "owned", "type": "single-family", "construction_type": "frame", "year_built": 2004, "square_footage": 2350, "roof_type": "composition shingle", "roof_year": 2019, "protection_class": "3", "coverages": [ { "type": "Dwelling", "limit": 420000, "deductible": 2500, "replacement_cost": true }, { "type": "Personal Property", "limit": 210000, "deductible": 2500 }, { "type": "Loss of Use", "limit": 84000 }, { "type": "Liability", "limit": 300000 } ], "deductibles": { "all_peril": 2500, "wind_hail": 5000 }, "mortgagee": [ { "name": "Wells Fargo Home Mortgage", "loan_number": "0099213456" } ] } ], "insurer_information": { "company_name": "State Farm", "company_phone": "1-800-782-8332", "claims_phone": "1-800-732-5246", "agent_name": "Priya Nair", "agent_phone": "(555) 617-2200" }, "prior_carrier": { "name": "Allstate", "policy_number": "AS-77213", "expiration_date": "2026-05-14" } } } ``` #### 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](#example-an-auto-policy) above | | Homeowners | `policy`, `policyholder`, `additional_insured`, `properties`, `policy_level_coverages`, `insurer_information`, `billing_information`, `prior_carrier` — see [full example](#example-a-homeowners-policy) 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](/intake-forms/builder-sessions.md#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 ```json { "topic": "form-submission", "data": { /* the full submission — see below */ } } ``` ### Example ```json { "topic": "form-submission", "data": { "form": { "id": 4412, "public_id": "f_9c2a7b1e4d", "name": "Apartment Intake — Acme Agency", "insurance_line": "commercial" }, "submission_id": 55231, "trace_id": "tr_5f3c9a2b7e14", "submitted_at": "2026-08-24T18:22:40Z", "agent": { "id": 88213, "name": "Jane Smith", "email": "jane@acme-agency.com" }, "contact": { "name": "Jane Roe", "email": "jane.roe@example.com", "phone": "(555) 010-1234" }, "answers": [ { "question_id": "b1c2-…", "label": "Full name", "type": "short_text", "value": "Jane Roe" }, { "question_id": "c3d4-…", "label": "Property address", "type": "address", "value": { "line1": "12 Oak St", "city": "Austin", "state": "TX", "zip": "78701" } }, { "question_id": "d4e5-…", "label": "Loss runs", "type": "file_upload", "value": [ { "filename": "losses.pdf", "content_type": "application/pdf", "url": "https://files.insurgrid.com/…" } ] }, { "question_id": "f6a7-…", "label": "Premises", "type": "data_table", "column_schema": [ { "key": "building", "type": "short_text" }, { "key": "units", "type": "number" } ], "value": [ { "building": "A", "units": 24 }, { "building": "B", "units": 18 } ] } ], "acord": { "is_acord_ready": true, "form_ids": ["125", "140", "126"], "archive_url": "https://files.insurgrid.com/…/acord-archive.zip" }, "metadata": { "partner_ref": "your-correlation-id" } } } ``` ### 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](#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](/intake-forms/forms.md#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}`](/intake-forms/submissions.md#get-one-submission) re-signs the links if you need them again later. *** ## Related * [Delivery & de-duplication](/guides/delivery-dedup.md) — retry behavior and de-dupe patterns (content hash for policy-data, `submission_id` for form-submission). * [Verify signatures](/guides/signing-verification.md) — the `x-signature` HMAC check, over the exact raw request bytes. * [Register your endpoint & choose an auth type](/guides/register-endpoint-auth-types.md) — signature, Bearer, Basic, or API-key delivery auth. * [Submissions API](/intake-forms/submissions.md) — re-fetch a `form-submission` payload on demand; same object shape. * [Forms API](/intake-forms/forms.md) — question types and `field_mapping` referenced by `answers[]`. * [Quickstart A — Receive policy data via webhook](/quickstarts/a-receive-policy-data.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.insurgrid.com/api-reference/webhook-events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.