Extract structured data

Extract needs a document and a schema. A schema describes the fields and types you want returned.

Extract directly from a document

Use direct Extract when you have a file and want structured data in one request. Direct Extract does not require a Parse ID. Set UNSTRUCTURED_API_KEY to your API key and replace the file path. To run the Python or TypeScript example, first install the Python SDK or TypeScript SDK.

export UNSTRUCTURED_API_KEY="your-api-key"

Python
TypeScript
cURL

from unstructured_transform_client import TransformClient

schema = {
    "type": "object",
    "properties": {"invoice_number": {"type": "string"}},
    "required": ["invoice_number"],
    "additionalProperties": False,
}

with TransformClient() as client:
    result = client.extract.from_document(input="document.pdf", schema=schema)
    print(result)

import { readFile } from "node:fs/promises";
import { TransformClient, isAccepted } from "unstructured-transform-client";

const client = new TransformClient();
const file = new File([await readFile("document.pdf")], "document.pdf");
const schema = {
  type: "object",
  properties: { invoice_number: { type: "string" } },
  required: ["invoice_number"],
  additionalProperties: false,
};

const outcome = await client.extract.fromDocument({ input: file, schema });
if (isAccepted(outcome)) {
  console.log("Extract job ID:", outcome.body.id);
} else {
  console.log(outcome.body.extractedData?.[0]?.data);
}

curl https://transform.unstructured.io/api/v2/extract \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -F "input=@document.pdf" \
  --form-string 'schema={"type":"object","properties":{"invoice_number":{"type":"string"}}}'

Extract from a completed Parse

Reuse a Parse when you want to extract different fields from content you already processed. Set PARSE_ID to its completed result’s id. The cURL example also requires jq.

export PARSE_ID="your-completed-parse-id"

Python
TypeScript
cURL

import os
from unstructured_transform_client import TransformClient

schema = {
    "type": "object",
    "properties": {"invoice_number": {"type": "string"}},
    "required": ["invoice_number"],
    "additionalProperties": False,
}

with TransformClient() as client:
    result = client.extract.run(parse_id=os.environ["PARSE_ID"], schema=schema)
    print(result)

import { TransformClient, isAccepted } from "unstructured-transform-client";

const client = new TransformClient();
const parseId = process.env.PARSE_ID;
if (!parseId) {
  throw new Error("Set PARSE_ID to a completed Parse result's id.");
}
const schema = {
  type: "object",
  properties: { invoice_number: { type: "string" } },
  required: ["invoice_number"],
  additionalProperties: false,
};

const outcome = await client.extract.run({ parseId, schema });
if (isAccepted(outcome)) {
  console.log("Extract job ID:", outcome.body.id);
} else {
  console.log(outcome.body.extractedData?.[0]?.data);
}

curl https://transform.unstructured.io/api/v2/extract \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -n --arg id "$PARSE_ID" '{parse_id: $id, schema: {"type":"object","properties":{"invoice_number":{"type":"string"}}}}')"

Use JSON for parse_id requests and multipart form data for input or file_id. Send one document source per request. If the document source is missing or the fields conflict, correct the request. See error codes and fixes. See Chain Parse and Extract for the complete sequence.

Read the result

For a completed HTTP 200 result, read extracted_data[i].data. The captured response contains invoice_number: "DEMO-001" and total: 10.0. HTTP 202 means the job continues. Keep the complete Location URL, including its query parameters, and follow request progress. Do not reconstruct an extraction retrieval URL from the job ID alone. See schema guidance and the endpoint reference.

​Extract directly from a document

​Extract from a completed Parse

​Read the result

Extract directly from a document

Extract from a completed Parse

Read the result