Chain Parse and Extract

Parse a document once, then pass its ID to Extract with a schema. Follow complete Python, TypeScript, and cURL examples to reuse parsed content.

Parse once, then extract fields from the same parsed document. Pass the completed Parse result’s id to Extract as parse_id. The second call reuses the parsed content without uploading or parsing the file again.

Use this flow when you want to inspect parsed content first or run multiple schemas against the same document. Use direct Extract when you already know your schema and want a single request that returns structured data.

Pass the Parse ID to Extract

Interface	Value from completed Parse	Extract parameter
HTTP	response.id	parse_id
Python	parsed.id	parse_id=parsed.id
TypeScript	parsed.body.id	parseId: parsed.body.id

A file_id identifies an uploaded file; a Parse ID identifies processed content. Keep the original Parse ID when you want another extraction. Extract returns its own result ID.

Chain two requests

Set UNSTRUCTURED_API_KEY to your API key and save your document as document.pdf. Install the Python SDK or TypeScript SDK before using those tabs. The cURL example uses zsh and requires jq.

The synchronous tab is the default path. Each request returns a completed result before the next line runs. Use the asynchronous tab when you need to return before processing finishes.

Synchronous (default)

Python

from unstructured_transform_client import TransformClient

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

with TransformClient() as client:
    parsed = client.parse.run(input="document.pdf")
    extraction = client.extract.run(parse_id=parsed.id, schema=schema)
    print(extraction.extracted_data)

TypeScript

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

const client = new TransformClient();
const schema = {
  type: "object",
  properties: { invoice_number: { type: "string" } },
  required: ["invoice_number"],
  additionalProperties: false,
};
const file = new File([await readFile("document.pdf")], "document.pdf");
const parsed = await client.parse.run({ input: file });
const extraction = await client.extract.run({
  parseId: parsed.body.id,
  schema,
});
console.log(extraction.body.extractedData);

cURL

# Run in zsh. Save the completed Parse response.
curl --fail-with-body -sS \
  https://transform.unstructured.io/api/v2/parse \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -F "input=@document.pdf" \
  -o parse.json

PARSE_ID=$(jq -er '.id' parse.json)
jq -n --arg id "$PARSE_ID" '{
  parse_id: $id,
  schema: {
    type: "object",
    properties: {invoice_number: {type: "string"}},
    required: ["invoice_number"],
    additionalProperties: false
  }
}' > extract-request.json

curl --fail-with-body -sS \
  https://transform.unstructured.io/api/v2/extract \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @extract-request.json \
  -o extract.json
cat extract.json

Asynchronous

Use this path when Parse should return before processing finishes. Each example submits Parse asynchronously, polls until it completes, then sends the completed Parse result ID to a blocking Extract request.

Python

import time

from unstructured_transform_client import TransformClient

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

with TransformClient() as client:
    accepted = client.parse.run(input="document.pdf", wait_seconds=0)
    job = client.jobs.get(accepted.id)
    while job.status in ("queued", "processing"):
        time.sleep(2)
        job = client.jobs.get(accepted.id)
    if job.status not in ("completed", "completed_with_warnings"):
        raise RuntimeError(job.error)

    extraction = client.extract.run(parse_id=job.result.id, schema=schema)
    print(extraction.extracted_data)

TypeScript

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

const client = new TransformClient();
const schema = {
  type: "object",
  properties: { invoice_number: { type: "string" } },
  required: ["invoice_number"],
  additionalProperties: false,
};
const file = new File([await readFile("document.pdf")], "document.pdf");
const accepted = await client.parse.run({ input: file, waitSeconds: 0 });
if (accepted.status !== 202) throw new Error("Parse did not return a job handle");

let job = await client.jobs.get(accepted.body.id);
while (job.status === "queued" || job.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await client.jobs.get(accepted.body.id);
}
if (job.status !== "completed" && job.status !== "completed_with_warnings") {
  throw new Error(`Parse stopped: ${job.status}`);
}
if (!job.result) throw new Error("Parse completed without a result");

const extraction = await client.extract.run({
  parseId: job.result.id,
  schema,
});
if (extraction.status !== 200) throw new Error("Extract did not complete");
console.log(extraction.body.extractedData);

cURL

# Run in zsh. This example requires jq.
API_BASE_URL="https://transform.unstructured.io"
curl --fail-with-body -sS \
  "$API_BASE_URL/api/v2/parse" \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -H "Prefer: wait=0" \
  -D parse-headers.txt \
  -F "input=@document.pdf" \
  -o parse-accepted.json

POLL_PATH=$(awk 'tolower($1) == "location:" {sub(/\r$/, "", $2); print $2; exit}' parse-headers.txt)
POLL_URL="${API_BASE_URL}${POLL_PATH}"
while :; do
  curl --fail-with-body -sS \
    "$POLL_URL" \
    -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
    -o parse-job.json
  STATUS=$(jq -r '.status' parse-job.json)
  case "$STATUS" in
    queued|processing) sleep 2 ;;
    completed|completed_with_warnings) break ;;
    *) cat parse-job.json; exit 1 ;;
  esac
done

PARSE_ID=$(jq -er '.result.id' parse-job.json)
jq -n --arg id "$PARSE_ID" '{
  parse_id: $id,
  schema: {
    type: "object",
    properties: {invoice_number: {type: "string"}},
    required: ["invoice_number"],
    additionalProperties: false
  }
}' > extract-request.json

curl --fail-with-body -sS \
  "$API_BASE_URL/api/v2/extract" \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @extract-request.json \
  -o extract.json
cat extract.json

To make Extract asynchronous too, send the same wait option on the Extract request and follow its returned job before reading the result. See Follow request progress, Python asynchronous Parse, and TypeScript asynchronous Parse for the retrieval patterns.

Run another schema against the same Parse

Keep the parsed document’s ID from the first operation. Send another Extract request with that ID and a different schema, such as one requesting total instead of invoice_number.

Each Extract request creates a separate extraction. Reusing the Parse avoids repeating the parsing step; it does not make extraction free or imply indefinite retention.

See the Extract endpoint, captured Extract response, and retention guidance.