---
title: "Extract data with AI"
method: POST
path: "/extract"
---

# Extract data with AI

`POST /extract`

## Request

- Base URL: `https://marqpdf.com/v1`
- URL: `https://marqpdf.com/v1/extract`
- Auth: HTTP bearer

Read a PDF or an image (invoice, ID, statement, form) and return the fields you ask for as JSON in output.data (also saved as a .json output file). Name the fields, or pass a JSON Schema. A field the document doesn't contain comes back null. Runs on MarqPDF's model or one of your own (model). Counts as one operation when it succeeds.

## Request body

- object
  - `file` string, required: A file id from POST /files.
  - `fields` union[]: What to extract: names, or {name, type, description}.
    - union
      - string
      - object
        - `name` string, required
        - `type` 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'list'
        - `description` string
  - `schema` object: Instead of fields: a JSON Schema for the result (an object).
  - `instructions` string: Extra guidance, e.g. 'amounts in AED'.
  - `model` string: "marqpdf" (the default) or "provider/model" on a key you've added, e.g. "anthropic/claude-opus-5-5", "openai/gpt-5.1", "gemini/gemini-2.5-pro", "openrouter/…", "custom/…".
  - `wait` integer: Seconds to wait for the result before answering 202 with a job to poll. 0 = answer at once.
  - `webhook_url` string, uri: POSTed the finished job, signed with your webhook secret (MarqPDF-Signature).

## Response `200`

Finished: the job with its output

- Job
  - `object` 'job', required
  - `id` string, required
  - `operation` string, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `created_at` string, date-time, required
  - `started_at` string, nullable
  - `finished_at` string, nullable
  - `input` object
    - `files` string[]
    - `options` object
  - `output` object, nullable
    - `files` File[]
      - `object` 'file', required
      - `id` string, required
      - `name` string, required
      - `size` integer, required
      - `content_type` string, required
      - `pages` integer
      - `created_at` string, date-time, required
      - `expires_at` string, date-time, required
      - `source` 'upload' | 'url' | 'job', required
      - `job` string
      - `download_url` string, uri, required: Works without a key for an hour.
    - `text` string
    - `text_truncated` boolean
    - `note` string
    - `data` object: extract: the data
    - `model` string: AI operations: the model that answered
    - `steps` object[]: Workflows and the agent: each step
  - `error` object, nullable
    - `code` string
    - `message` string
  - `webhook_url` string, nullable
  - `webhook` object, nullable

## Other responses

- `202`: Still running: poll GET /jobs/{id} (also in Location)
- `400`: Invalid request
- `401`: Missing or invalid API key
- `402`: Free plan's monthly operations used
- `404`: Unknown file or operation
- `410`: File expired (kept 24 hours)
- `429`: Rate limit or job queue full (see Retry-After)
- `502`: The operation failed; the body also carries the job

---

[API](https://skmtc.dev/marqpdf/apis/marqpdf-api.md) · [All operations](https://skmtc.dev/marqpdf/apis/marqpdf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marqpdf/apis/marqpdf-api/revisions/9f614f17df46?raw)