Extracting structured data

Extract structured data from any document into JSON, guided by your schema.

Extract takes a document and a JSON Schema, and returns the fields described by the schema as a structured object. You define what you want in the schema, the API finds it in the document: invoices, forms, ID documents, contracts, anything.

By default the call is synchronous: you send the request, the API blocks until the extraction is done, and the response comes back with the full result. For larger documents, opt into async mode with options.async = true: you get back a job ID, and you poll until done.

Full request/response schema for POST /api/v1/extract and GET /api/v1/extract/{job_id} lives in the API reference.

When to use Extract

	Input	Output	Best for
Search	Query string	Ranked text chunks	Finding passages across many documents
Parse	Document file	Markdown text	Converting a document to clean text
Extract	Document + JSON Schema	Structured object	Pulling typed fields from forms, invoices, contracts

Use Extract when you need machine-readable values out of a document, mapped to fields you've named.

Extract applies your schema independently to every page of the document: result.data comes back with one object per page. That makes it ideal for mechanical, repetitive document processing, where each page is a self-contained record (a stack of invoices, a batch of forms, a multi-page table) and you want the same fields pulled from every one.

If instead you need a single structured JSON for the whole document (synthesizing information spread across pages into one consolidated object), Extract is the wrong tool. Use the POST /api/v1/search endpoint inside your own agentic loop to retrieve the relevant passages, then have your model generate the structured output from them.

Sync extraction (small documents)

Sync mode handles documents up to 20 MB, 15 pages and returns the full result in one response.

const headers = {
  Authorization: `Bearer ${process.env.C212_API_KEY}`,
};

const response = await fetch("https://api.context212.com/api/v1/extract", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    document: "https://example.com/invoices/inv-2025-004.pdf",
    schema: {
      type: "object",
      properties: {
        invoice_number: { type: "string", description: "The invoice reference number" },
        total: { type: "number", description: "The total amount due" },
        due_date: { type: "string", description: "Due date in ISO format" },
      },
    },
  }),
});

const result = await response.json();
console.log(result.status); // → completed
console.log(result.result.data); // → [{ invoice_number: "INV-2025-004", total: 4750.0, due_date: "2025-12-01" }, ...]

You can also send a file via multipart/form-data instead of a URL:

import { readFileSync } from "node:fs";

const form = new FormData();
form.append("file", new Blob([readFileSync("invoice.pdf")]), "invoice.pdf");
form.append(
  "schema",
  JSON.stringify({ type: "object", properties: { invoice_number: { type: "string" } } }),
);

await fetch("https://api.context212.com/api/v1/extract", {
  method: "POST",
  headers,
  body: form,
});

In multipart requests, schema arrives as a JSON-encoded string and is decoded server-side.

Async extraction (large documents)

For documents up to 100 MB, 1000 pages, set options.async = true. The API returns a 202 Accepted immediately with a job ID.

const response = await fetch("https://api.context212.com/api/v1/extract", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    document: "https://example.com/large-report.pdf",
    schema: { type: "object", properties: { title: { type: "string" } } },
    options: { async: true },
  }),
});

const jobId = (await response.json()).id;
console.log(jobId);
// → ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4a

Poll GET /api/v1/extract/{job_id} until status is completed or failed. Recommended cadence: 1 s for the first 10 s, then 5 s, capped at 30 s.

let data;
while (true) {
  const r = await fetch(`https://api.context212.com/api/v1/extract/${jobId}`, {
    headers,
  });
  data = await r.json();
  if (data.status === "completed" || data.status === "failed") break;
  await new Promise((r) => setTimeout(r, 2000));
}

console.log(data.result.data);

Reading the response

Sync and async responses share the same shape:

{
  "id": "ext_0196e4b2a3c14d5e8f7a9b2c1d0e3f4a",
  "status": "completed",
  "created_at": "2026-03-31T10:00:00+00:00",
  "completed_at": "2026-03-31T10:00:04+00:00",
  "processing_time_ms": 3200,
  "document": {
    "filename": "invoice.pdf",
    "page_count": 3,
    "file_size_bytes": 245120,
    "mime_type": "application/pdf"
  },
  "result": {
    "data": [
      {"invoice_number": "INV-2026-001", "total": null},
      {"invoice_number": null,           "total": 1250.00}
    ],
    "pagination": {
      "page": 1,
      "page_size": 15,
      "total_items": 3,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "usage": {
    "pages_processed": 3
  }
}

result.data is one entry per page, each shaped like your schema. Fields that weren't found on a given page are null. When the document has more than 15 pages, result.data is paginated: request additional pages with ?page=N on the GET /api/v1/extract/{job_id} endpoint.

Common errors

Status	Cause
`400`	Missing document/file, unsupported format, or page limit exceeded
`401`	Missing or invalid API key
`404`	Extract job not found
`413`	File exceeds the size limit (20 MB sync, 100 MB async)
`422`	JSON Schema is malformed, uses unsupported features, or exceeds limits
`429`	Rate limit exceeded (6 requests/second per tenant)
`503`	Parsing backend is overloaded. Retry later

When to use Extract

Sync extraction (small documents)

Async extraction (large documents)

Reading the response

Common errors

On this page