# 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](https://api.getemboss.ai/internal/openapi.json) and the [pay-per-call API description](https://api.getemboss.ai/openapi.json); 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:

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

Answer:

```json
{
  "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:

```json
{
  "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:

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

### Set the answers

`PUT /sessions/{sid}/fields`

Send:

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

### Fill the PDF

`POST /sessions/{sid}/fill`

Answer:

```json
{
  "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:

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

Answer:

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

### Read the proposal

`GET /proposals/{proposal_id}`

Answer:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

First answer, the price to pay:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Answer:

```json
{
  "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:

```json
{
  "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"
}
```

## See also

- [Fill PDFs from your own data](https://getemboss.ai/use-cases/fill-pdfs-from-your-data)
- [Fillable PDF](https://getemboss.ai/glossary/fillable-pdf)
- [Authentication](https://getemboss.ai/docs/authentication)
- [Quickstart](https://getemboss.ai/docs/quickstart)
- [Pay per call](https://getemboss.ai/docs/pay-per-call)
- [Send a fax](https://getemboss.ai/docs/send-fax)
- [Forms](https://getemboss.ai/docs/reference/create-form)