Insurance Documents by API: Fill, Sign, Write Back

A platform automating its insurance document path is answering three questions, and most vendor pages answer only the middle one. Where do the fields on the document come from? What does "prefilled" mean when the policyholder disagrees with a value? And what returns to your policy record when they sign?

The signature is the easy part. The document path around it is where integrations get rebuilt a year later.

Where do the fields come from?

Three routes, and the right one depends on who authored the PDF.

You place them by hand. Someone opens a template builder and positions each field on the page. This is fine for a handful of governed document types and wrong at the scale of an insurance form library.

You embed tags in documents you generate. If your platform renders the PDF, a policy jacket or a quote packet or a producer agreement, then you control the source and you can put handlebars-style tags into it as you generate. Roles and fields are created where the tags sit, with no coordinate math. Verdocs calls this Dynamic Tagging. It is the right route for anything your system produces.

You upload a fillable PDF exactly as it is. Many insurance documents are already forms: text boxes, checkboxes, dropdowns, and signature areas defined inside the file using the AcroForm standard. Verdocs inspects the PDF on upload, maps each widget to a field type, and creates the fields for you. Text becomes a textbox, Btn becomes a checkbox or radio, Ch becomes a dropdown, and text fields named like dates, signatures, or initials become those field types. Reset and Print buttons are ignored. If detection fails, the upload still succeeds and the document is stored without generated fields.

Two gates control this, and both are per organization and off by default: process_tags scans for text tags, process_acroforms detects form widgets. They are independent, and AcroForm detection runs only when no text tags were found, so a document carrying both follows the tag path. If you inherit a Verdocs organization and wonder why an uploaded form arrives with no fields, that default is usually the answer.

What about ACORD forms?

This is the reason the third route matters in insurance.

ACORD has published the insurance industry's standard forms since its first paper form in 1971, and states that its forms are "now available in a variety of formats, including printable PDF, electronic fillable, and eForms" (acord.org, checked September 2026). The electronic fillable ones are AcroForm PDFs. The fields on an ACORD 125 or an ACORD 25 are already defined, by ACORD, inside the file.

So you do not rebuild them. You upload the form as you hold it today and the fields come across, with labels derived from the PDF's own internal field names.

Two limits are worth knowing before you scope the work, because neither is obvious and both change the estimate.

Every detected field lands on one signer role. An AcroForm PDF does not encode which signer owns which widget, so all detected fields are assigned to a single Recipient role. For a form one applicant signs, that is exactly right. For a packet where the producer signs one section and the insured signs another, you rename and split roles afterward, through the builder or the Roles and Fields APIs. Budget it as a one-time setup step per template, not as per-envelope work. If you need multiple signers declared in the source document from the start, Dynamic Tagging is the better fit.

It is a PDF feature. A Word document has no AcroForm widgets to find, so DOCX workflows use Dynamic Tagging instead. DOCX uploads do work; they convert to PDF, and the signed artifact is a PDF either way.

And one thing vendor pages tend to leave out: ACORD's own forms page states that you must subscribe to an eligible Forms program to download ACORD Forms. Field detection solves the file. It does not address your right to distribute the form. Work out which side of that line your platform sits on before you ship a form library to your agencies.

What does "prefilled" actually mean?

It means default values, not locked values, and the difference decides how much support volume you inherit.

Supply defaults when you create the envelope, or update fields before signing begins. They appear to the signer as starting values. Unless a field is marked read-only, the signer can change them.

That distinction is a product decision, not a configuration detail. A prefilled value the policyholder can correct is a data-quality feature: you are showing them what you believe and letting them fix it, which is how you find out the mailing address changed. A locked value is a control: you are asserting something the signer cannot argue with.

Get it backwards in either direction and it costs you. Lock the mailing address because it came from your system and you have converted a correction into a support ticket. Leave a calculated premium editable and you have let someone change the number they are agreeing to. Read-only belongs on account numbers, calculated totals, and system-generated clauses. Nearly everything the policyholder knows better than you does not.

What comes back, and when?

Webhooks, not polling. The point of embedding signing is that your record stays current without anyone watching a queue.

Handle these at a minimum: recipient_submitted, recipient_declined, envelope_completed, and recipient_auth_fail if you use recipient verification. Plan for sent, viewed, expired, canceled, and voided as the integration matures.

The two most often skipped are the two that matter most in insurance. A decline is a workflow, not an error: somebody has to know the endorsement was refused. And an authentication failure on a high-stakes document is a real operational event. A policyholder who cannot clear knowledge-based authentication on a settlement release has not gone away; they are now a phone call, and your system should know that before they make it.

Three implementation notes that will save you a rewrite:

• Delivery is at-least-once. Make your consumer idempotent and key on the envelope id. You will receive the same event twice eventually.
• Answer quickly. Deliveries expect a 2xx within a few seconds, so acknowledge first and do the work after.
• Verify the caller. Require an HMAC signature on the raw JSON body, or OAuth client credentials if you already issue machine tokens to partners. Reject anything that fails, and rotate the secret on the same schedule as your other production credentials.

When the envelope completes, the signed PDF, the signing certificate, and the audit trail come back through the API, into the claim or policy file they belong to. That is the half of "integration" that decides whether anyone has to log into a second system, and it is worth testing before you commit.

Do you need a template at all?

Not always. You can create an envelope directly from an uploaded PDF or DOCX, define recipients and fields in the same request or through tags in the document, and send immediately. That suits one-off documents and systems that already produce the final PDF server-side.

Templates earn their place when business users need a repeatable, governed document type: the renewal packet that has to look the same every time and that somebody other than an engineer maintains. Most insurance platforms end up with both, generating some documents and governing others.

One practical constraint while you design: upload documents through the document endpoints rather than inlining binary data in JSON, and expect plan-level envelope quotas and per-file upload caps.

What to ask before you build

1. Can I upload our existing fillable forms without rebuilding them? If the answer needs a professional services engagement, price that in.
2. What happens to a form with two signers? Ask specifically how roles get assigned, and whether that is per template or per envelope.
3. Which events fire, and is delivery at-least-once? If the vendor cannot answer the second half, your consumer will be written wrong.
4. How is a webhook authenticated? A shared secret in a query string is not an answer.
5. Does the signed PDF, the certificate, and the audit trail come back through the API? Into your system, not just into a portal someone can log into.
6. Can I send a test envelope today? A sandbox key in minutes tells you more than a capability matrix.

Where this leaves you

The document path is three decisions: where fields come from, what the signer can change, and what returns to your record. Answer them in that order and the signing component is close to the least interesting part of the build.

That component still has to render inside your product rather than redirect out of it, which is a separate argument covered in iframes versus native components. The workflow context sits on the insurance platform page, and if you build the system agencies run on, eSignature for agency management systems goes at the AMS case directly. The component API in React is in embed signing in a React app.