Worked examples

Each recipe below is a real sequence of Emboss API calls with the request you send and the answer you get. The same examples sit on every operation in the REST API description and the pay-per-call API description; the MCP connector's tools and the A2A agent's skills carry their own worked inputs. Ids are samples. File fields are sent as multipart file uploads.

Make a PDF fillable

Upload the form

POST /forms

Send:

{
  "file": "<the PDF form, sent as a file>",
  "retention": "ephemeral"
}

Answer:

{
  "form_id": "11111111-2222-3333-4444-555555555555",
  "library": null,
  "source_artifact_id": "22222222-3333-4444-5555-666666666666",
  "status": "processing"
}

Read its fields when it is ready

GET /forms/{form_id}

Answer:

{
  "artifact_id": "22222222-3333-4444-5555-666666666666",
  "error": null,
  "id": "11111111-2222-3333-4444-555555555555",
  "library": null,
  "retention": {
    "documents_deleted_after": "2026-10-10T14:32:00+00:00",
    "documents_deleted_at": null,
    "policy": "account_default"
  },
  "reused_layout": false,
  "schema_version": "2026-06-01",
  "source_artifact_id": "33333333-4444-5555-6666-777777777777",
  "status": "ready",
  "title": "W-9 Request for Taxpayer Identification",
  "warnings": []
}

Fill it from values

Start a session

POST /sessions

Send:

{
  "form_id": "11111111-2222-3333-4444-555555555555"
}

Set the answers

PUT /sessions/{sid}/fields

Send:

{
  "updates": [
    {
      "field_id": 1,
      "value": "Grace Hopper"
    }
  ]
}

Fill the PDF

POST /sessions/{sid}/fill

Answer:

{
  "session_id": "88888888-9999-aaaa-bbbb-cccccccccccc",
  "status": "completed"
}

Fill it from documents, reviewing every answer

Propose answers from your documents

POST /forms/{form_id}/prepare

Send:

{
  "context": [
    "<a supporting document, sent as a file>"
  ],
  "policy": "safe"
}

Answer:

{
  "job_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
  "status": "processing"
}

Read the proposal

GET /proposals/{proposal_id}

Answer:

{
  "attachments": [],
  "commit_token": null,
  "confirmations": [
    {
      "confidence": 0.72,
      "evidence": [
        "source.pdf p.1"
      ],
      "field_id": 2,
      "label": "Date of Birth",
      "value": "1906-12-09"
    }
  ],
  "error": null,
  "expires_at": "2026-09-22T18:00:00+00:00",
  "fields": [
    {
      "candidates": [],
      "confidence": 0.97,
      "evidence": [
        "source.pdf p.1"
      ],
      "field_id": 1,
      "label": "Full Name",
      "origin": "direct",
      "required": true,
      "state": "ready",
      "tiebreak": null,
      "value": "Grace Hopper"
    },
    {
      "candidates": [
        {
          "confidence": 0.72,
          "evidence": [
            "source.pdf p.1"
          ],
          "value": "1906-12-09"
        }
      ],
      "confidence": 0.72,
      "evidence": [],
      "field_id": 2,
      "label": "Date of Birth",
      "origin": null,
      "required": true,
      "state": "needs_confirmation",
      "tiebreak": null,
      "value": null
    }
  ],
  "form_id": "11111111-2222-3333-4444-555555555555",
  "mode": "two_call",
  "package_url": null,
  "policy": "safe",
  "proposal_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "questions": [],
  "requirements": {
    "attachments": [],
    "signatures": []
  },
  "status": "proposed",
  "summary": {
    "conflict": 0,
    "invalid": 0,
    "missing": 0,
    "needs_confirmation": 1,
    "ready": 1,
    "required_unresolved": 1
  }
}

Commit what you approved

POST /proposals/{proposal_id}/commit

Send:

{
  "confirm": [
    2
  ],
  "idempotency_key": null,
  "package": false,
  "policy": "safe",
  "values": [
    {
      "field_id": 1,
      "note": null,
      "value": "Grace Hopper"
    }
  ]
}

Follow the job to the filled PDF

GET /forms/with-context/{job_id}

Answer:

{
  "artifact_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
  "artifacts": [
    {
      "artifact_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
      "mime_type": "application/pdf",
      "role": "filled"
    }
  ],
  "error": null,
  "job_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
  "package_url": null,
  "pdf_url": null,
  "proposal_id": null,
  "receipt_url": null,
  "report": {
    "dropped": [],
    "filled": [
      {
        "confidence": "high",
        "id": 1
      },
      {
        "confidence": "high",
        "id": 2
      }
    ]
  },
  "result": null,
  "retention": {
    "documents_deleted_after": "2026-10-10T14:32:00+00:00",
    "documents_deleted_at": null,
    "policy": "account_default"
  },
  "session_id": "88888888-9999-aaaa-bbbb-cccccccccccc",
  "status": "ready"
}

Fill one copy per spreadsheet row

Match columns to fields

POST /forms/{form_id}/suggest-mapping

Answer:

{
  "mapping": {
    "Email": {
      "confidence": 0.88,
      "field_id": 2
    },
    "Full Name": {
      "confidence": 0.94,
      "field_id": 1
    }
  },
  "unmapped_columns": [
    "Internal Notes"
  ]
}

Start the batch

POST /forms/{form_id}/fill-batch

Send:

{
  "file": "<the spreadsheet, sent as a CSV file>",
  "mapping": "{\"Email\": {\"field_id\": 2}, \"Full Name\": {\"field_id\": 1}}"
}

Follow the batch

GET /forms/fill-batch/{batch_id}

Answer:

{
  "error": null,
  "failed": 0,
  "filled": 2,
  "results": [
    {
      "artifact_id": "55555555-6666-7777-8888-999999999999",
      "pdf_url": "/forms/fill-batch/44444444-5555-6666-7777-888888888888/rows/1/pdf",
      "row": 1,
      "status": "filled"
    },
    {
      "artifact_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
      "pdf_url": "/forms/fill-batch/44444444-5555-6666-7777-888888888888/rows/2/pdf",
      "row": 2,
      "status": "filled"
    }
  ],
  "retention": {
    "documents_deleted_after": "2026-10-10T14:32:00+00:00",
    "documents_deleted_at": null,
    "policy": "account_default"
  },
  "status": "complete",
  "total": 2
}

Pay per call, no account

Check the price

POST /pay/quote

Answer:

{
  "already_fillable": false,
  "card_minimum_usd": "0.50",
  "context_pages": 1,
  "expires": null,
  "methods": [
    "tempo",
    "stripe",
    "x402"
  ],
  "next": "POST /pay/<op> with the same file. The 402 challenge carries this exact price.",
  "pages": 1,
  "prices": {
    "fax": {
      "atomic": "30000",
      "cents": 3,
      "usd": "0.03"
    },
    "fill": {
      "atomic": "70000",
      "cents": 7,
      "usd": "0.07"
    },
    "fill-with-context": {
      "atomic": "80000",
      "cents": 8,
      "usd": "0.08"
    },
    "make-fillable": {
      "atomic": "50000",
      "cents": 5,
      "usd": "0.05"
    },
    "read": {
      "atomic": "10000",
      "cents": 1,
      "usd": "0.01"
    }
  }
}

Send the job

POST /pay/fill

Send:

{
  "pdf_url": "https://example.com/forms/building-permit.pdf",
  "values": {
    "Email": "grace@example.com",
    "Full Name": "Grace Hopper"
  }
}

First answer, the price to pay:

{
  "detail": "Payment required for this operation.",
  "job_id": "eeeeeeee-ffff-0000-1111-222222222222",
  "status": 402,
  "status_url": "https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE",
  "title": "Payment Required",
  "type": "https://paymentauth.org/problems/payment-required"
}

Send it again with the payment credential

POST /pay/fill

Answer:

{
  "job_id": "eeeeeeee-ffff-0000-1111-222222222222",
  "poll_after_seconds": 3,
  "quote_id": "eeeeeeee-ffff-0000-1111-222222222222",
  "status": "working",
  "status_url": "https://api.getemboss.ai/pay/jobs/eeeeeeee-ffff-0000-1111-222222222222?token=EXAMPLE"
}

Follow the job

GET /pay/jobs/{job_id}

Answer:

{
  "job_id": "eeeeeeee-ffff-0000-1111-222222222222",
  "quote_id": "eeeeeeee-ffff-0000-1111-222222222222",
  "quote_status": "executed",
  "result": {
    "artifact_id": "99999999-aaaa-bbbb-cccc-dddddddddddd",
    "download_url": "https://getemboss.ai/d/EXAMPLE",
    "files": [
      {
        "content_type": "application/pdf",
        "name": "building-permit-filled.pdf",
        "url": "https://getemboss.ai/d/EXAMPLE"
      }
    ]
  },
  "runs": 1,
  "status": "ready"
}

Send a fax

Fax the finished form

POST /fax

Send:

{
  "job_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
  "to": "+15025550123"
}

Answer:

{
  "artifact_id": "22222222-3333-4444-5555-666666666666",
  "destination_masked": "+1502******23",
  "job_id": "cccccccc-dddd-eeee-ffff-000000000000",
  "pages": 1,
  "price_cents": 3,
  "source_artifact_ids": [
    "22222222-3333-4444-5555-666666666666"
  ],
  "status": "working"
}

Follow delivery

GET /fax/{job_id}

Answer:

{
  "artifact_id": "22222222-3333-4444-5555-666666666666",
  "artifact_sha256": "285236fa25e49a62d43fffecac4f30a9799467fd0994db61bbbdb82fa9246925",
  "delivered_at": "2026-09-22T14:02:00+00:00",
  "job_id": "cccccccc-dddd-eeee-ffff-000000000000",
  "pages": 1,
  "price": {
    "amount": "0.03",
    "currency": "USD"
  },
  "provider": "telnyx",
  "status": "delivered",
  "submitted_at": "2026-09-22T14:00:00+00:00",
  "to_masked": "+1502******23",
  "type": "emboss.fax.receipt"
}