docs

Prepare and verify

View as Markdown

Split a fill from documents into two calls: prepare reads the documents and proposes a value for every field without writing anything, you read the proposal (GET /proposals/{proposal_id}) and settle what is open, and commit writes it. Fetch the commit's receipt and filled PDF here, and check any filled PDF against its form with verify. See the guide at /docs/prepare-commit-verify.

Prepare a proposal for a form you created

POST/forms/{form_id}/prepareBearer auth

Read supporting documents and propose a value for every field, without writing the PDF. Returns 202 with a job id; the finished job carries the proposal_id. Bills one context fill.

Parameters

NameInTypeRequiredDescription
form_idpathstringyesA form you created, status ready.
contextbodyfile (multipart, repeatable)noSupporting document(s) to read.
policybodystringnoOptional. safe (the default) treats high- and medium-confidence values as ready; strict treats only high-confidence ones as ready. Anything else is 400.
Idempotency-KeyheaderstringnoOptional. Retrying with the same key answers 200 with the original job instead of starting a new one. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

  • 200A replay of an earlier request with the same Idempotency-Key: the original job.
  • 202Accepted; the prepare job started.
  • 400policy is not safe or strict.
  • 401Missing or invalid API key.
  • 402No payment method on file and the monthly free context fills are used up, or the form and its documents are over the free tier's 5-page cap. The body's detail carries code, message and billing_url.
  • 404No such form, or owned by another key.
  • 409Form not ready.
  • 410The form's documents have been deleted under its retention policy.
  • 413Too many context files (max 5), file too large (max 10 MB), or request over 30 MB.
  • 422document_same_as_form: a context file is this form's own blank original. Nothing is charged.
  • 429Rate limit exceeded.
curl -X POST https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/prepare \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "context=@./w9-prior-year.pdf"
Response
{
  "job_id": "8c9d0e1f-2a3b-4c5d-9e6f-a1b2c3d4e5f6",
  "status": "processing"
}

Create a form and prepare a proposal

POST/forms/prepareBearer auth

Upload a flat PDF plus supporting documents: Emboss detects the fields and prepares a proposal in one call. Returns 202 with a job id; bills one creation and one context fill.

Parameters

NameInTypeRequiredDescription
filebodyfile (multipart)yesThe flat PDF.
contextbodyfile (multipart, repeatable)noSupporting document(s) to read.
policybodystringnoOptional. safe (the default) or strict. Anything else is 400.
retentionbodystringnoOptional. ephemeral or account_default; default account_default. See the Ephemeral processing guide.
Idempotency-KeyheaderstringnoOptional. Retrying with the same key answers 200 with the original job instead of starting a new one. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each request.

Status codes

  • 200A replay of an earlier request with the same Idempotency-Key: the original job.
  • 202Accepted; detection and the prepare job started.
  • 400Not a readable PDF, policy is not safe or strict, or a bad retention value.
  • 401Missing or invalid API key.
  • 402No payment method on file and the monthly free allowance is used up, or the request is over the free tier's 5-page cap. The body's detail carries code, message and billing_url.
  • 413Too many context files (max 5), file too large (max 10 MB), too many pages (max 100), or request over 30 MB.
  • 422The file field is missing, or document_same_as_form: a context file is the uploaded form itself. Nothing is charged.
  • 429Rate limit exceeded.
curl -X POST https://api.getemboss.ai/forms/prepare \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "file=@./w9.pdf" \
  -F "context=@./w9-prior-year.pdf"
Response
{
  "job_id": "8c9d0e1f-2a3b-4c5d-9e6f-a1b2c3d4e5f6",
  "status": "processing"
}

Get the receipt

GET/proposals/{proposal_id}/receiptBearer auth

The receipt of the proposal's newest commit: what was decided, by whom, on what evidence, the verification report, the second model's value check, and what the document still needs.

Parameters

NameInTypeRequiredDescription
proposal_idpathstringyesThe proposal.

Status codes

  • 200The receipt.
  • 401Missing or invalid API key.
  • 403A wrong proposal token.
  • 404No such proposal, or not yours, or no commit yet: "no receipt yet for this proposal".
curl https://api.getemboss.ai/proposals/3e714663-ff2c-45ac-ae11-3c7015facfef/receipt \
  -H "Authorization: Bearer sk_live_yourkey"
Response
{
  "receipt_version": "1",
  "emboss_version": "a1b2c3d4e5f6",
  "proposal_id": "3e714663-ff2c-45ac-ae11-3c7015facfef",
  "form_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "contract": { "schema_version": "1.0", "detector_version": "ffdnet-l-2026-08" },
  "policy": "safe",
  "mode": "two_call",
  "timestamps": { "proposed_at": "2026-10-06T18:31:49+00:00", "committed_at": "2026-10-06T18:40:02+00:00", "verified_at": "2026-10-06T18:40:04+00:00" },
  "fields": [
    { "field_id": 3, "label": "Name:", "value": "Acme Holdings LLC", "state": "ready", "origin": "document", "confidence": "high",
      "evidence": [{ "document_id": "d1", "document_name": "w9-prior-year.pdf", "page": 1, "method": "quote_check", "location": "Acme Holdings LLC" }], "note": null }
  ],
  "unresolved": { "fields": [], "attachments": [] },
  "verification": { "result": "complete", "checked_at": "2026-10-06T18:40:04+00:00", "issues": [], "adjustments": [],
    "counts": { "fields": 24, "written": 24, "required_unfilled": 0, "issues_blocking": 0, "issues_review": 0 } },
  "requirements": { "signatures": [], "attachments": [] },
  "files": { "filled_pdf": { "name": "filled.pdf", "bytes": 184320, "sha256": "285236fa25e49a62d43fffecac4f30a9799467fd0994db61bbbdb82fa9246925", "artifact_id": "99999999-aaaa-bbbb-cccc-dddddddddddd" } },
  "commits": [{ "n": 1, "at": "2026-10-06T18:40:02+00:00", "auto": false, "result": "complete", "values_supplied": 1 }],
  "retention": { "policy": "account_default", "documents_deleted_after": null },
  "checks": { "summary": { "ran": true, "checked": 24, "doubted": 0, "cost": 0.0021, "ms": 480 }, "fields": [] }
}

Download the proposal's filled PDF

GET/proposals/{proposal_id}/pdfBearer auth

The PDF the proposal's newest commit rendered. The response body is the raw %PDF bytes.

Parameters

NameInTypeRequiredDescription
proposal_idpathstringyesThe proposal.

Status codes

  • 200The PDF bytes (application/pdf).
  • 401Missing or invalid API key.
  • 403A wrong proposal token.
  • 404No such proposal, or not yours, or no commit yet: "no filled PDF yet for this proposal".
  • 410The form's documents have been deleted under its retention policy.
curl https://api.getemboss.ai/proposals/3e714663-ff2c-45ac-ae11-3c7015facfef/pdf \
  -H "Authorization: Bearer sk_live_yourkey" -o filled.pdf
Response
%PDF-1.7
…binary…

Verify a filled PDF

POST/forms/{form_id}/verifyBearer auth

Check a filled PDF you hold, however it was filled, against this form's contract. Returns the same report a commit gives: result, checked_at, issues, adjustments and counts. Bills one verify.

Parameters

NameInTypeRequiredDescription
form_idpathstringyesThe form the PDF is a copy of.
filebodyfile (multipart)yesThe filled PDF.

Status codes

  • 200The verification report.
  • 400Not a PDF ("file must be a PDF"), unreadable, or its widgets do not match this form's contract.
  • 401Missing or invalid API key.
  • 402No payment method on file and the monthly free verifications are used up, or the form is over the free tier's 5-page cap. The body's detail carries code, message and billing_url.
  • 404No such form, or owned by another key.
  • 409Form not ready.
  • 413File too large (max 10 MB).
  • 429Rate limit exceeded.
curl -X POST https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/verify \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "file=@./filled-by-hand.pdf"
Response
{
  "result": "review_required",
  "checked_at": "2026-10-06T18:40:04+00:00",
  "issues": [
    { "field_id": 9, "page": 0, "kind": "signature_missing", "detail": "Signature", "blocking": false }
  ],
  "adjustments": [],
  "counts": { "fields": 24, "written": 23, "required_unfilled": 0, "issues_blocking": 0, "issues_review": 1 }
}