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

Quickstart B — Share a form and receive submissions

Get a published form in front of customers, and get the completed submissions back.

Once a form is published it has a link. Send that link to a customer and they can fill the form in — that's the whole of sharing it.

What happens next is the part worth setting up. Every completed form shows up in your InsurGrid dashboard automatically. If you also want the submission delivered to your own systems — every answer, the contact details, any uploaded files, and the filled ACORD PDFs — you register a webhook endpoint, and InsurGrid posts each one to you as it arrives.

This page covers both halves. About 20 minutes for the webhook half; sharing the link takes a minute.

What you'll need

  • An InsurGrid account with at least one published form.

  • For the webhook half: an HTTPS address InsurGrid can reach, that accepts POST. A deployed server is simplest — if you're working on your laptop, it isn't reachable from the internet, so put a tunnel in front of it (how).

Staging
Production

API

https://phoenix-staging.insurgrid.com

https://phoenix.insurgrid.com

Form links

https://link-staging.insurgrid.com

https://link.insurgrid.com

Part one — share the form

Get the link

Every published form has a shareUrl. It's in the dashboard's Forms section, or fetch it:

curl 'https://phoenix-staging.insurgrid.com/api/v1/forms' \
  -H 'Authorization: Bearer YOUR_API_KEY'
https://link-staging.insurgrid.com/jane-smith/form/f_9c2a7b1e4d/apartment-intake-acme

⚠️ shareUrl is null until the form is published. Drafts and archived forms have no link at all. Publish first, with PUT /api/v1/forms/{id}/publish.

The first segment is the slug of the agent who created the form, and that's who submissions through this link are credited to. It appears again as agent in every webhook.

Give it to people

It's an ordinary web address, so use it however suits you — email or text it to a customer, put it behind a button on your website, print it as a QR code. InsurGrid hosts the page; nothing needs registering beforehand.

Showing it inside your own page

If you'd rather the form appeared within your product than on a page of its own, put the link in an <iframe> and add ?embed=1. That flag strips InsurGrid's header and page furniture, so only the form shows — no InsurGrid branding around it.

Give the frame a height that suits your layout — the form doesn't message your page, so there's nothing to listen for and nothing to resize against. Everything else works exactly as it does through a plain link.

Part two — receive the submissions

When someone completes the form, the response lands in your InsurGrid dashboard straight away. That happens for every account with nothing to set up — you can read the answers, download any files, and review the submission there.

To get the same submission into your own systems, register a webhook endpoint. InsurGrid then posts each completed submission to your server as a form-submission event, carrying the contact details, every answer, links to any uploaded files and, for ACORD-mapped forms, a download of the filled PDFs.

The rest of this page is that setup.

Register your endpoint

In the InsurGrid webhooks dashboard:

  1. Add your endpoint — a publicly reachable HTTPS URL that accepts POST. Each account has one.

  2. Choose your events — tick form-submission · intake & ACORD. You can receive client-submission (policy data) on the same endpoint too.

  3. Choose how InsurGrid authenticates to you — see below.

  4. Send a test event to check your handler before real traffic arrives.

How InsurGrid proves it's InsurGrid

You pick this per endpoint; it isn't fixed:

Option
What your endpoint receives

Default signature

Every request signed by InsurGrid. No setup needed.

Custom signature

An HMAC-SHA256 signature of the body, in a header you name, signed with a secret you provide.

API key

Your key, in a header or query parameter you name.

Bearer token

Authorization: Bearer <token>

Basic auth

Authorization: Basic <credentials>

We recommend Custom signature, API key or Bearer token, so your server can reject anything it can't verify.

A staging secret never validates a production event, and vice versa.

Acknowledge first, work second

Return any 2xx as soon as the event arrives — the body is ignored. Do the slow work after you've responded.

Anything else — another status, a timeout, no response — counts as a failed delivery and is retried. You can also resend any event from the dashboard.

Two behaviours to design for:

  • Events can arrive more than once. Use data.submission_id to skip ones you've handled.

  • Order isn't guaranteed. If sequence matters, sort on data.submitted_at.

What the event looks like

Every event has the same envelope — check topic first, since one endpoint can receive several kinds:

Inside data

Field
Type
What it is

submission_id

integer

Unique id for this submission. Your de-duplication key.

trace_id

string | null

The form session that produced it. Quote it if you contact support.

submitted_at

string

When it was submitted, UTC ISO 8601.

form.id

integer

Form id.

form.public_id

string

The public id used in links and embeds.

form.name

string

Form name.

form.insurance_line

string

personal or commercial.

form.external_user_id

string | null

Your own user id, if the form was created through the Forms API with one.

agent

object

Who it's credited to: id, name, email. Name and email can be null.

contact

object

The submitter's name, email, phone. Filled from questions carrying a field_mapping — see the warning below. Any can be null.

answers

array

One entry per question. See below.

acord

object

ACORD output. See below.

⚠️ contact only fills if the questions are tagged. InsurGrid reads it from questions carrying a field_mapping of FullName, Email or Phone — never from a question's type or label. A form built through the API with its own steps, and no tags, delivers contact: {name: null, email: null, phone: null} on every submission, with the answers still present in answers[]. See Keeping the contact block populated.

Answers

answers lists every question on the form, in order — including ones nobody answered, which carry value: null.

Field
What it is

question_id

Stable id. Map on this, not label — labels get edited, ids don't.

label

The question text as shown to the submitter.

type

The question type.

value

The answer. Shape depends on type.

columns

data_table only — the table's columns (id, label, type).

Type

value

short_text, long_text, email

string

number

number

date

date string

dropdown, single_choice

string — the option they picked

multi_choice

array of strings

address

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

data_table

array of rows, each keyed by column id

file_upload

array of { filename, content_type, url }

⚠️ File links are public and permanent — treat them as sensitive. The url on a file_upload answer, and acord.archive_url, are unsigned links to a public bucket. They don't expire, and anyone who has the URL can download the file without authenticating. Since these are documents your customer uploaded, don't paste one into a ticket, a chat, an email or a log you wouldn't paste the document itself into.

Download and store what you need when the event arrives: there is no endpoint to re-fetch a submission, and a file's url is null once the document is no longer available.

ACORD

Field
What it is

acord.is_acord_ready

true when the form is mapped to ACORD forms.

acord.form_ids

The ACORD numbers filled from this submission, e.g. ["125", "140"]. Empty when not ACORD-ready.

acord.archive_url

A ZIP of the filled PDFs. Present only when ACORD-ready and the archive built — treat as optional.

A complete example event

Handling a repeat delivery

Next steps

PreviousIntake Forms
NextQuickstart C — Build forms via the API