# Extract typed fields from a PDF with a JSON Schema using Unsiloed

Unsiloed's Extract API pulls the fields you name in a JSON Schema out of a PDF. Each field comes back as a typed value with a score and, with citations on, the page and box it came from. A job costs $0.02 per page pay as you go, counted in pages of the PDF. Send `POST https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/v2/extract` with a bearer, pay the 402 price quote and retry, then poll `GET https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/extract/{job_id}` with the same bearer.

## At a glance

- **Endpoint:** `POST https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/v2/extract` to submit, `GET https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/extract/{job_id}` for the result
- **Body:** `file_url` (a PDF), `schema_data` (the JSON Schema as a string), `enable_citations: true`, optional `model` and `high_accuracy_mode`
- **Price:** $0.02 per page pay as you go, or $0.0125 from prepaid Credits. The result call draws nothing.
- **Payment:** a 402 is the price quote, which you pay and retry, over x402 or MPP (wallet rails settling in USDC). A card pays pay-as-you-go calls only from $0.50.
- **Credential:** an agent bearer token on the submit and on every result call
- **Response:** `job_id` with `status: "queued"`, then per field `value`, `score` and `citation`
- **Limits:** one PDF per job, given by `file_url`
- **Full purchase flow:** [buyer skill](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/SKILL.md)

## Write the JSON Schema

The schema is a root object with `properties`, `required` and `additionalProperties: false`. Each field's `description` tells the model what to look for, so describe where the value sits and what it looks like. Supported types are `string`, `number`, `integer`, `boolean`, `array`, `object` and `null`.

```json
{
  "type": "object",
  "properties": {
    "form_number": {"type": "string", "description": "Form number printed at the top left"},
    "tax_year": {"type": "string", "description": "Tax year the form covers"},
    "omb_number": {"type": "string", "description": "OMB control number"},
    "form_title": {"type": "string", "description": "Full title of the form"}
  },
  "required": ["form_number", "tax_year", "omb_number", "form_title"],
  "additionalProperties": false
}
```

For an invoice, the same pattern names fields such as `invoice_number`, `total` (`number`) and `line_items` (`array`).

## Extract the fields

1. Get an access token. The storefront issues an agent identity for free; register and exchange it as [auth.md](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/auth.md) shows. The token goes on the submit as well as on the result call, because a job paid without a credential on the submit could not be read afterwards.

2. Submit the PDF and the schema, encoded as one JSON string:

   ```bash
   curl -sS -X POST https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/v2/extract \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"file_url": "https://www.irs.gov/pub/irs-pdf/f1040.pdf", "model": "gamma", "enable_citations": true, "schema_data": "{\"type\":\"object\",\"properties\":{\"form_number\":{\"type\":\"string\",\"description\":\"Form number printed at the top left\"},\"tax_year\":{\"type\":\"string\",\"description\":\"Tax year the form covers\"},\"omb_number\":{\"type\":\"string\",\"description\":\"OMB control number\"},\"form_title\":{\"type\":\"string\",\"description\":\"Full title of the form\"}},\"required\":[\"form_number\",\"tax_year\",\"omb_number\",\"form_title\"],\"additionalProperties\":false}"}'
   ```

   The storefront answers `402` with `payment.amountUsd` for the PDF's pages: $0.04 for a two-page PDF. Nothing is charged yet.

3. Pay the quote and resend the identical request. On x402, the challenge is in the `payment-required` header and the proof goes in `x-payment`, next to `Authorization: Bearer`. On MPP, the proof takes `Authorization: Payment <credential>`, so the token moves to `ZC-Agent-Authorization: Bearer <token>`. A two-page form submitted this way paid $0.04, two pages at the Pay per page rate, by x402 and answered `200` with a job id and `"status": "queued"`.

4. Poll for the result with the same bearer:

   ```bash
   curl -sS https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/extract/$JOB_ID \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   Keep polling while `status` is `queued` or `processing`. The result call draws nothing from your wallet or credit.

## Read values, scores and citations

`result` has one key per schema field. The completed result for the blank two-page Form 1040, on the default model, trimmed:

```json
{
  "status": "completed",
  "result": {
    "form_number": {
      "value": "1040",
      "score": {"grounding_score": 0.98, "extraction_score": 0.998},
      "citation": {"bbox": [39, 23, 93, 47], "page": 1, "page_width": 612.0, "page_height": 792.0}
    },
    "tax_year": {"value": "2025", "score": {"…": "…"}, "citation": {"…": "…"}},
    "omb_number": {"value": "1545-0074", "score": {"…": "…"}, "citation": {"…": "…"}},
    "form_title": {"value": "U.S. Individual Income Tax Return", "score": {"…": "…"}, "citation": {"…": "…"}}
  }
}
```

- **`value`** is in the type the schema declared. Validate it against the same schema before use.
- **`score`** holds `grounding_score` and `extraction_score`; `extraction_score` can be `null`. Set a threshold for your workflow and send any field below it, or with a `null` score, to a person.
- **`citation`** gives `bbox` as left, top, right, bottom in PDF points, with `page`, `page_width` and `page_height`. Show the box next to the value so a reviewer can check it in one look.

## Choose a model

| Need | Setting |
| --- | --- |
| Fastest result | `model: "alpha"` |
| Balance of speed and thoroughness | `model: "beta"` |
| Thorough, recommended (the default) | `model: "gamma"` |
| Advanced tier | `model: "delta"` |
| Cross-check every value and re-verify uncertain fields, slower | `high_accuracy_mode: true` |

The 402 states the price before you pay.

## Boundaries

- Extract reads one PDF per job, given by `file_url`.
- The charge is taken when you pay the submit's 402, by page count. An unpaid 402 charges nothing, so it is safe to stop there.
- A card pays pay-as-you-go calls only from $0.50. Pay a short PDF by wallet, or draw it from Credits (minimum purchase $5, bought at `POST /plans/{planId}/purchase` with the plan id from `https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/manifest.json`).
- After a timeout on a paid submit, check the job before paying again.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` | The price quote | Pay and retry the same request, or stop |
| `401 bearer_required` | No agent credential on the call | Register at [auth.md](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/auth.md) and send the bearer on both calls |
| `401 invalid_token` | The access token expired or did not verify | Exchange the stored assertion for a fresh token |
| `404 task_not_found` on the result | The job is not visible to this credential | Submit with the same bearer you poll with |
| `settlement_failed` | The payment did not settle | Fix the wallet and send a fresh request |
| `429` | Too many requests | Wait the `retry_after` or `Retry-After` time, then poll again |

## Frequently asked questions

### Can Unsiloed extract invoice data to JSON?

Yes. Name the invoice fields in the JSON Schema, such as `invoice_number`, `total` and `line_items`, with a description for each. The result returns each one as a typed value with its score and, with `enable_citations` on, its page location.

### How much does a PDF extraction cost?

$0.02 per page pay as you go, times the PDF's page count, so a two-page PDF costs $0.04. Prepaid Credits bring the rate to $0.0125. The result call draws nothing.

### How long does an extraction job take?

Jobs usually finish within seconds to a few minutes. The two-page Form 1040 job reached `completed` about 15 seconds after it was created.

### Do I need an API key?

No. You need an agent bearer token, which the storefront issues for free, and a payment for each submit. Send the same bearer on the submit and on the result call.

## Keep reading

- [Buyer skill](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/SKILL.md): the full purchase flow
- [Identity](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/auth.md): register and exchange the bearer
- [How to pay](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/payment.md): x402, MPP, card and Credits
- [Error reference](https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/errors.md): every storefront error code

---

Updated 2026-11-06. All Unsiloed AI guides: https://agents.unsiloed.ai/guides.md. Storefront: https://agents.unsiloed.ai/zcj/fu5ckpqq8p4r/llms.txt.