Test mode

Push a certificate on a test key and you read the surface check in about a minute and the verdict in about three, against the scenario you pick. The base URL is https://api.insuranceverified.ai/v1, and every call below sends Authorization: Bearer ive_test_.... Only an ive_test_ key accepts test_scenario. A live key that sends it gets 422. Test events reach the webhook you configure with the test key, with test: true, or you poll the reads in steps 3 and 4.

1. Define what you require

   POST /consumers/{consumer_ref}/requirement-sets takes structured rules in a JSON body. Add publish: true and applies_to: "new" to publish the version in the same call.

   curl -X POST https://api.insuranceverified.ai/v1/consumers/acme/requirement-sets \
     -H "Authorization: Bearer ive_test_..." \
     -H "Content-Type: application/json" \
     -d '{
       "rules": [{
         "coverage_type": "general_liability",
         "requirement": {"kind": "limit_min", "label": "each_occurrence", "min": 1000000},
         "document_class_required": "coi",
         "verification_required": "broker",
         "severity": "hard"
       }],
       "publish": true,
       "applies_to": "new"
     }'
   

   You get 201 with version, status, rules[] carrying the rule_key assigned to each rule, and compile_errors. A version with compile_errors stays a draft.

   Add key to the body to file this version under a different requirement set. The default is default. A consumer needs more than one only when different insureds follow different rules.

   The second way takes the customer's SOP as prose. Send it as source_text in the JSON body, or as a PDF or DOCX in a multipart source_document field.

   curl -X POST https://api.insuranceverified.ai/v1/consumers/acme/requirement-sets \
     -H "Authorization: Bearer ive_test_..." \
     -H "Content-Type: application/json" \
     -d '{"source_text": "Vendors carry commercial general liability of at least $1,000,000 per occurrence, evidenced by a certificate confirmed by the broker."}'
   

   That returns a draft: status: draft, the parsed rules[], parse_confidence keyed by rule_key, and an ambiguities list naming each place the SOP is too loose to enforce literally. publish on this path returns 422. Read the draft, then publish it with POST /consumers/{consumer_ref}/requirement-sets/{version}/publish and a body of {"applies_to": "new", "grace_period_days": 14}.

   Skip this step to use consumer_ref=sample, which every account ships with. It holds one published rule: general liability each occurrence at least $1,000,000, certificate required, broker verification.

2. Push a certificate

   POST /documents as multipart/form-data. test_scenario picks how the simulated agent of record answers for the lines in this push.

   curl -X POST https://api.insuranceverified.ai/v1/documents \
     -H "Authorization: Bearer ive_test_..." \
     -H "Idempotency-Key: test-run-1" \
     -F files=@coi.pdf \
     -F insured_ref=driver-1042 \
     -F consumer_ref=sample \
     -F test_scenario=confirmed
   

   201 Created returns one object: transmission_id, idempotent_replay, engagement_id, and documents[] with an id, sha256, and content_bytes_deduplicated per file. Store the id. Extraction runs after the response, so the receipt carries no document status.

3. Check the file was read

   GET /documents/{document_id} returns the document with status, the extraction attempt, coverage_lines[], requests[], the engagement_id it fed, and test: true. Branch on outcome.

   curl https://api.insuranceverified.ai/v1/documents/{document_id} \
     -H "Authorization: Bearer ive_test_..."
   

   outcome	What to do
   pending	The file is not read yet. Poll again on the next tick
   not_insurance	The file is not an insurance document. No surface check and no verdict follow for it. Ask the insured for the certificate
   extracted	Coverage lines are built. The surface check follows within a tick
   needs_review	A reviewer has the file: extraction errored, or the file could not be read as sent. Wait, or ask the insured for a PDF

4. Read the result

   GET /insureds/{insured_ref}/verdicts with consumer_ref required and current=true for the verdicts in force now: one surface check, one roll-up, one per resolved line.

   curl "https://api.insuranceverified.ai/v1/insureds/driver-1042/verdicts?consumer_ref=sample&current=true" \
     -H "Authorization: Bearer ive_test_..."
   

   Or read the whole verification in one call: GET /engagements/{engagement_id} (the engagement_id from the push receipt) returns the surface check, the verdict, and everything behind them together.

   The surface check arrives about a minute after the push:

   { "kind": "surface", "scope": "engagement", "status": "compliant", "test": true,
     "rules": [{ "rule_key": "general_liability.limit_min.each_occurrence",
                 "surface": "pass", "result": "unverified", "severity": "hard",
                 "reasons": ["verification_pending"] }] }
   

   The verified verdict follows within about one to three minutes:

   { "kind": "verified", "scope": "line", "status": "compliant", "test": true,
     "rules": [{ "rule_key": "general_liability.limit_min.each_occurrence",
                 "result": "pass", "severity": "hard",
                 "verification_state": "verified", "reasons": [] }] }
   

   On kind: surface, read rules[].surface (pass, fail, not_yet, pending_review, not_applicable) and the surface status (compliant, pending, non_compliant). On kind: verified, read rules[].result (pass, fail, gap, unverified, not_applicable). A passing surface check carries result: unverified with reason verification_pending, so a client that branches on result at stage one reads it as a non-pass. wording.* is display copy and changes without a version bump. Do not parse it.

The five scenarios

The clock under a test key targets 3 wall-clock minutes with a hard stop at 5, and the simulated reply lands in the same tick as the send. No email or call goes out.

confirmed is the default when you leave test_scenario off. The newest test push behind a line sets the scenario for that line.

What you see, what it means

Test rows are kept and readable, are not billed, and are not returned to a live key. The same code against an ive_live_ key runs the real clocks, 48 business-day hours to target and 72 to the hard stop, and real outreach to the agent of record.

Next