REFERENCE · DOCUMENTS
POST /v1/documents
Push one or more files for an insured. One call is one transmission and N documents. The response is a receipt, not a result: extraction runs after it returns.
PARAMETERS
| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| Idempotency-Key | string | no | Optional, and the preferred way to make a retry safe. Send one on every POST and PUT; a replay returns the original response with idempotent_replay true and creates nothing new. POST /documents also accepts an idempotency_key form field as an alias; the header wins when both are sent |
| files | file[] | yes | The file part, repeated once per file. `files[]` is accepted as an alias for callers whose HTTP client appends brackets to repeated parts |
| insured_ref | string | yes | Verifying entity's own id for the insured |
| consumer_ref | string | yes | Verifying entity's own id for the consumer |
| insured_name | string | no | Optional; used when the insured is new |
| parent_insured_ref | string | no | Optional |
| requirement_set | string | no | Optional; the consumer's requirement set (lineage key) this push's engagement follows. Requires consumer_ref. Omitted uses the consumer's single set, or the one named default; 422 if the consumer carries several and none is default. 404 if the key is unknown |
| document_ref | string | no | Optional |
| received_at | timestamp | no | Optional; when the document reached you (ISO 8601; no offset reads as UTC). 422 when unparseable or more than 5 minutes in the future. Shown as the Document's received_at and in the verification history. Informational: a line's clock starts at the later of the push reaching Insurance Verified and the engagement's surface check passing |
| channel | enum | no | Optional; how the document reached you. Shown as the Document's channel; omitted reads api |
| meta | object | no | Optional JSON |
| program_ref | string | no | Optional; attach a master policy document to a program |
| insured_state | string | no | Optional |
| test_scenario | enum | no | Test keys only. How the simulated agent of record answers for the lines in this push: confirmed (default) | refused | contradicted | unclear (escalates to review) | silent (the clock runs out). Rejected with a live key One of: confirmed, refused, contradicted, unclear, silent. |
| idempotency_key | string | no | Optional alias for the Idempotency-Key header, for clients that cannot set headers. The header is preferred and wins when both are sent |
RESPONSE
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| transmission_id | string | One push call. Quote it in support questions, and use it to tell two pushes of the same file apart |
| idempotent_replay | boolean | true when this body is a replay of an earlier call with the same Idempotency-Key. Nothing new was created |
| engagement_id | string | The verification this push feeds (0015). Set when insured_ref and consumer_ref were both sent; null otherwise. Poll GET /engagements/{engagement_id} for the surface check and the verdict as they land |
| engagement | object | The engagement, short form; null under the same condition as engagement_id |
| documents | object[] | One entry per file, in the order the files were sent |
| packet_document_id | string | Files pushed together are read together as one packet: when the push carried 2 or more photos, the packet document they were grouped into. Null otherwise |
Errors: 400, 401, 403, 409, 415, 422, 429, 500. Every error body carries error.code, error.message, and error.request_id.