Push documents

Push each insurance file you receive. Insurance Verified reads it and merges what it states into the insured's coverage lines. Push it against an insured_ref and a consumer_ref of your own choosing, and push every version you receive, old certificates included.

What one call does

POST /documents is multipart/form-data with files, insured_ref, and consumer_ref. Repeat files once per file, and files[] is accepted as an alias. One call is one transmission and one document per file.

The response is 201 Created with one object:

Field	What it is
transmission_id	This push call. One call is one transmission, whatever the file count, and the transmission is the retry unit
idempotent_replay	true when the body is a replay of an earlier call with the same Idempotency-Key. Nothing new was created
engagement_id, engagement	The verification this push feeds: present when insured_ref and consumer_ref were both sent, null otherwise. GET /​engagements/​{engagement_id} returns the surface check, the verdict, and everything behind them
documents[]	One entry per file, in the order sent: id, the content sha256, and content_bytes_deduplicated

The receipt carries no document status and no request_id. Extraction runs after the call returns.

Optional field	What it is for
insured_name	The insured's display name. Used only when the insured is new
insured_state	The insured's two-letter state, which where state conditions read. Stored only when the insured is new
entity_kind	Stored on a new insured. Default business
parent_insured_ref	An insured that already exists under your key, set as the parent of a new insured. A parent's line can count toward the child's rules when its extends_to_children is true
requirement_set	The consumer's requirement set (its key) this push's engagement follows. Needs consumer_ref. Left off, the consumer's single set applies, or the one named default. Several sets with none named default is a 422. An unknown key is a 404
meta	A JSON object stored on the transmission and returned under meta on GET /​documents/​{document_id}
refs	A JSON object of your own ids, stored on the transmission
test_scenario	Test keys only: how the simulated agent of record answers for the lines in the push. confirmed (default), refused, contradicted, unclear, or silent. A live key gets 422

Nothing in meta or refs changes what extraction reads.

Deduplication and merging

Insurance Verified stores file bytes by sha256. content_bytes_deduplicated: true on a receipt entry means identical bytes were already stored. The push still gets its own transmission and document id, and the document reuses the earlier reading of those bytes. Pushing the same bytes twice without repeating the Idempotency-Key gives you a second transmission and a second document id.

Across documents, one insured's line with the same coverage type, policy number, and carrier is one coverage line. A line with no policy number, or of type other, does not merge. When a document of a stronger document_class arrives, its values replace the line's, and the line takes its class. A weaker document only fills values the line is missing. The line's verification state carries across the merge. The strength order is coi, endorsement, dec_page, policy.

Each value that both the line and the new document state, and that differs, raises contradiction.detected with the attribute, both values, and the sources, and the line gets the contradiction_open flag. A limit that moved between two versions of the same policy raises one on limits.

A file that holds several documents stays one document with doc_type: packet and a parts[] list: doc_type, page_start, and page_end for each part. A coverage line takes its class from the strongest part that states it.

Files pushed together are read together as one packet. When one push carries 2 or more photos (image/jpeg, image/png, image/webp, image/heic), the receipt's packet_document_id names a packet document (kind: packet), and each photo's parent_document_id names that packet. Insurance Verified reads the packet once, with every photo in upload order, and page_start and page_end in its parts[] count photos. The packet's coverage lines list the packet and every photo as sources. PDFs in the same push, and a photo pushed alone, stay standalone documents with kind: file.

A coverage read with no policy number and no carrier starts no coverage line. When the insured has one line of that coverage type, the page fills only the values that line is missing. Otherwise the page goes to Insurance Verified's reviewers, who also finish the read when a policy number, carrier, limit, expiration date, or additional insured is missing or unclear. An auto policy form the paper does not state goes to the source during verification, and the rule reads unverified with reason policy_form_unconfirmed. While the review is open, GET /engagements/{engagement_id} lists kind: escalated_to_iv in outstanding[] and the matching rules read pending_review. A reviewer enters the values (returned in the coverage line's corrections[]), attaches the page to a line, or marks it not usable. A page marked not usable fires remediation.opened with ask: complete_declarations_packet, and outstanding[] lists the item. Your system asks the insured for the paper. Uninsured and underinsured motorist, medical payments, personal injury protection, towing, rental reimbursement, hired and non-owned auto, and pollution on the same auto policy are stored on that auto_liability line as meta.parts.

Status

GET /documents/{document_id} returns the document with status, an outcome read from it, doc_type, parts[], the latest extraction summary, the coverage_lines it backs, the requests on those lines, the engagement it fed (engagement_id, requirement_set), every engagement those requests serve (engagements[]), the transmission's channel and received_at, and integrity. GET /documents?insured_ref=… lists an insured's documents, newest first.

integrity.state	What it means
clear	No finding above a note is in force
under_review	A check found something Insurance Verified reviews. The surface check is unchanged
not_relied_on	The document is left out of the surface check. The rules it fed read unverified with reason document_held. Ask the agent for a new copy from the agency

integrity.findings[] lists each finding in force, worst first, as severity (needs_a_look, do_not_rely) and title.

status	outcome	What it means
received	pending	Stored and not yet read. Poll again
classified	not_insurance	Read, and it is not an insurance document. document.not_insurance fires and no surface check follows
extracted	extracted	Read. Coverage lines and the surface check follow
escalated	needs_review	A reviewer has it: extraction errored, or the file could not be read as sent
failed	failed	Defined in the enum. No path sets it today
in_packet	packet_page	One photo of a packet. Read the packet named by parent_document_id

You can also read the outcome from the surface check: GET /insureds/{insured_ref}/verdicts?consumer_ref=… returns a kind: surface verdict once extraction has built lines and the engagement has a published requirement set.

Request ids first appear on document.extracted, as request_id on each coverage line, and are null for a line with no open request yet. Without a webhook, list them with GET /insureds/{insured_ref}/requests?consumer_ref=….

Limits

Each file can be up to 25 MB. A larger file returns 413, and an empty file returns 422. The API accepts PDF, PNG, JPEG, WEBP, GIF, HEIC, HEIF, and TIFF, read from the content type declared on each file part. A part sent as application/octet-stream is accepted when its bytes are a PDF or one of those images. Any other type returns 415 in the same call, and nothing is stored.

Extraction reads every accepted type. A TIFF is read as one page per frame, and a HEIC or HEIF photo is converted before the read. A file that cannot be converted, such as a damaged scan, is set to escalated and raises document.failed with a remediation.

Send an Idempotency-Key header on the call. A replay returns the original transmission and document ids with idempotent_replay: true, so a retry creates no second transmission. An idempotency_key form field is accepted as an alias for clients that cannot set headers, and the header wins when both are sent.

A validation failure is a 422 carrying the standard error envelope, and error.message names the field.

Upload from the portal

On Upload packet in the portal, you can leave the insured name blank for a new insured. Insurance Verified takes it from the certificate once the document is read. A new insured can also carry an optional contact name, email, and phone, which Insurance Verified uses to reach the insured for a call or a three-way call with the carrier. Empty contact fields are filled from the certificate when it lists them.

Next