GUIDES

Quickstart

Push one certificate and read the result, in two calls. Everything on this page runs on a test key with nothing to configure first. The surface check comes back as soon as extraction finishes, and the verdict within 72 business-day hours on a live key.

The base URL is https://api.insuranceverified.ai/v1. Every path below is relative to it. The machine-readable contract is at /v1/openapi.yaml. Generate your client from that file.

  1. Get a test key

    Request an account for your organization and you receive a test key, prefixed ive_test_. Send it as Authorization: Bearer <key>. Every test key arrives with a sample consumer, consumer_ref: sample, that already holds a published starter requirement set.

    Test mode simulates outreach and marks every result test: true.

  2. Push a document

    POST /documents as multipart/form-data. The file field is files, repeated once per file, and files[] is accepted as an alias. Add an insured_ref of your choosing and a consumer_ref of sample. You get 201 Created back with one object: a transmission_id for the call, idempotent_replay, the engagement_id, and a documents[] array carrying an id, the content sha256, and content_bytes_deduplicated per file. The receipt carries no document status, because extraction runs after the response.

    Send an Idempotency-Key header. A replay returns this same body with idempotent_replay: true, and creates no second transmission.

    On a test key the whole lifecycle runs in about a minute: Insurance Verified reads the file, issues the surface check, opens the clocks, sends the question to a simulated agent of record, reads the answer, and issues the line verdicts and the roll-up. No email or call goes out. Add test_scenario to the push to choose the answer.

    test_scenario What the simulated agent does
    confirmed Confirms the line. The default
    refused Declines to confirm
    contradicted Reports the policy cancelled
    unclear Sends a vague reply that goes to reviewer triage
    silent Sends nothing. The clock runs out in five minutes and the line times out

    The first document creates the insured and its engagement against sample's requirement set. Read the whole verification back with the receipt's engagement_id.

    To open the clocks with no outreach running, create the engagement first with outreach: hold on POST /engagements. Release it later by posting outreach: auto on the same call.

  3. Read the surface check, in about a minute

    GET /insureds/{insured_ref}/verdicts?consumer_ref=sample returns the surface check once extraction has run. consumer_ref is required, and leaving it off returns 422. The body is {data, next_cursor}, newest first. Each entry carries kind: surface, a status, and rules[] naming what the paper claims against each rule.

    Branch on rules[].surface at this stage. rules[].result reads unverified with reason verification_pending until the source answers.

  4. Get the verdict

    Run the same call again later. A verdict carries kind: verified and scope: line, one per coverage line, as soon as that line resolves at the source: confirmed, refused, contradicted, or timed out. A roll-up for the whole engagement, scope: engagement, follows whenever it changes. GET /verdicts/{verdict_id} reads one by id and returns the bare object with no data wrapper.

    Branch on status and on rules[].result. A verified verdict carries no surface field, and result carries the outcome.

A line reads verified when a source behind the policy confirms it is in force with the stated terms, with proof attached. A certificate on its own reads claimed.

What the sample requirement set asks for

One rule. A compliant result against sample covers this rule only.

Rule Value Proof it demands
general_liability.limit_min.each_occurrence At least $1,000,000 A certificate, confirmed by the broker

The wording on a sample result reads "all 1 requirement". Publish your own consumer's rules before you read a pass as coverage.

Getting a request_id without a webhook

GET /insureds/{insured_ref}/requests?consumer_ref=sample lists the clocks on the engagement, newest first. Take a request_id from it, then call GET /requests/{request_id} for the detail or POST /requests/{request_id}/extend to add hours to the hard stop. The push receipt carries no request_id, because no clock is open when it returns.

Reading the whole verification

GET /engagements/{engagement_id} returns the whole verification in one object: identity, the requirement set it follows, the surface check, the verdict, per-line verdicts, the coverage lines with their clocks, the documents behind them, and the event trail. Poll it with the engagement_id from the push receipt.

What to configure next

Step Where Why
Push your real consumer's rules POST /​consumers/​{consumer_ref}/​requirement-sets Every result is measured against a requirement set. sample is ours
Choose how results reach you PUT /​delivery Webhook, scheduled batch file, or both
Send outreach from your own domain Settings, then Sending, in the portal Agents see your company as the sender. See Send from your own domain

Changelog

Date Change
2026-10-06 Spec 1.0.0-draft.13. The webhook envelope lists test. document.unreadable_fields and insured_contact.missing join the event schemas. close_reason lists surface_not_passed. Reason codes list policy_form_unconfirmed, policy_form_not_accepted, certificate_text_*, certificate_holder_mismatch, program_unverified, human_review_pending, and coverage_deleted_on_face. The /​outreach-identity operations are removed. The verdict status enum drops grace
2026-10-01 Photos pushed together are read as one packet. A page with no policy number goes to review, and a page marked not usable fires remediation.opened
2026-09-30 Programs and enrollments, insured aliases, and received_at and channel on POST /​documents
2026-09-28 Insured contact (name, email, phone) on PUT /​insureds/​{insured_ref}
2026-09-25 Delivery (webhooks and batch files) and the insured, coverage, and document reads go live
2026-09-23 Several requirement sets per consumer, named by key, with one engagement per requirement set
2026-09-15 GET /​documents/​{document_id} goes live. Requirement sets accept the SOP as text
2026-09-10 A low-confidence read gets a second read. document.unreadable_fields and document.not_insurance fire. Engagements on outreach: hold do not time out
2026-09-09 Engagements carry outreach: auto or hold
2026-09-08 Test mode for ive_test_ keys. GET /​verdicts/​{verdict_id}, GET /​insureds/​{insured_ref}/​verdicts, GET /​requests/​{request_id}, and POST /​requests/​{request_id}/​extend go live. One error envelope on /​v1
2026-09-04 The surface check reads each requirement as pass, fail, or not_yet
2026-09-02 Verdicts per coverage line, clock extensions, and the sample consumer on test keys

Versioning

Every path sits under /v1. The spec's info.version in /v1/openapi.yaml names the current revision, 1.0.0-draft.13. Within v1, new optional fields, endpoints, and event types can appear at any time. Ignore fields and events you do not know. An incompatible change ships as /v2 alongside /v1. When a new version ships, the prior version stays supported for 12 months and its retirement date is announced the same day.

Status

Insurance Verified reports service status on request. Email support@insuranceverified.ai.

Next

Implementation guideThe full build: your ids, the rules, the webhook, going live. How it worksThe two stages, who is who, and what Insurance Verified tracks.

Changelog  ·  Versioning and notice terms  ·  Status