Machine-only extraction over HTTP. One page image in, typed fields with per-field confidence out. Optional human escalation.
Machine extraction is AwaitVerify’s machine-only tier. Where verify_document() puts a human reviewer on every document, POST /api/v1/extract runs the extraction entirely by machine and returns per-field confidence scores — with an optional toggle to escalate low-confidence fields to AwaitVerify’s human reviewers before the response returns.Use it when you have document volume that doesn’t justify a human on every page, but you still want honest signals about which fields to trust.
Call it from the Python SDK (pip install awaithumans) with extract_document() / awaitExtract, or hit the HTTP endpoint directly — both are shown below.
POST https://api.awaithumans.dev/api/v1/extractAuthorization: Bearer <your API key>Content-Type: application/json
Get your API key from app.awaithumans.dev/keys — the same key you use for verify_document().One request carries one document page image, base64-encoded. image/png or image/jpeg, max 10 MB. Multi-page documents: rasterize each page and send one request per page.
The extracted fields, typed per doc_type. Every field is nullable. When the system can’t read a field, it abstains with null rather than guessing.
fields
Map of field path → {confidence, agreement, flags}. confidence and agreement are 0..1. flags is a list of strings (table below).
document_confidence
Aggregate confidence across the document’s fields, 0..1.
doc_type
Echo of the requested doc type.
pages
Pages processed in this request (currently always 1).
calibration
{version, calibrated}. Read the next section before using the scores.
usage
{pages, samples, cost_cents, balance_after_cents} — what this request processed and what it cost. samples is the number of extraction samples run for cross-model agreement.
Confidence scores are provisional — read this before thresholding
The calibration object tells you how to interpret the scores, and right now it says "calibrated": false. Here is what that means, honestly:While calibrated is false, confidence and agreement are provisional rank-orderings, not probabilities. They come from two signals:
K-sample cross-model agreement — we run the extraction multiple times (usage.samples) across models and measure how often the samples agree on each field.
Deterministic validators — where the document format allows it, we verify fields mechanically. For passports, that’s the ICAO 9303 MRZ check digits: if a check digit fails, the field’s confidence is capped near zero regardless of agreement.
A provisional confidence of 0.9 does not mean “90% chance the value is correct.” It means the field ranks higher than a field scored 0.7. Use provisional scores to rank fields for review and to drive the human_review toggle — do not hard-threshold them in your own pipeline (e.g. “auto-accept everything above 0.85”) as if they were error rates.calibrated: true turns on automatically once our labeled dev set is in place. At that point scores become calibrated probabilities and we publish threshold→error tables, so “reject below 0.85” becomes a statement with a known error rate. Until then, every field carries the PROVISIONAL_CALIBRATION flag as a machine-readable reminder.
Fields below the escalation threshold are verified by AwaitVerify human reviewers before the response returns. Verified fields carry the HUMAN_VERIFIED flag.
Machine rate + human rate on escalated pages.
"all"
Every field is human-verified.
Machine rate + human rate.
With human_review set to "low_confidence" or "all", the request blocks until human review completes — set your HTTP client timeout accordingly. With "off", responses are machine-fast.
from awaithumans import extract_document # alias: awaitExtractresult = await extract_document( document_path="./passport.png", doc_type="passport", human_review="off", # or "low_confidence" (default) / "all")result.data["passport_number"] # extracted value or Noneresult.fields["passport_number"].confidence # per-field scoreresult.fields["passport_number"].flags # e.g. ["PROVISIONAL_CALIBRATION"]result.calibration.calibrated # False until the fitted calibrator shipsresult.usage.cost_cents # what this call debited
extract_document_sync(...) is the blocking variant. Reads the
AWAITHUMANS_API_KEY and AWAITHUMANS_MANAGED_URL environment
variables, or pass api_key= / managed_url= explicitly. With
human_review on, the call blocks until review completes — the SDK
sizes its timeout accordingly.For several documents from one applicant, extract_envelope(documents=[...])
maps to the envelope endpoint.
Human-escalated pages (via human_review) additionally bill at the human verification rate — $0.80/page standard. usage.cost_cents on each response tells you exactly what the request cost, and usage.balance_after_cents what’s left. Billing draws from the same balance as verify_document(); top up at app.awaithumans.dev/billing.
Processing is ephemeral. Page images are deleted at response time — once you have the response, we no longer have the image. We retain only extraction metadata (timestamps, doc type, confidence statistics, usage); never field values, never images.One exception, bounded and controllable: quality-assurance sampling. A small percentage of extractions is reviewed by AwaitVerify’s human reviewers to calibrate the confidence scores, under a bounded 30-day retention window. You can disable QA sampling from your dashboard settings or by contract — when disabled, nothing is retained.
