Chain Parse and Extract

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. Compile the TypeScript examples before you run them. Requests without a Prefer header wait up to 15 minutes by default. HTTP 200 returns a completed result; HTTP 202 returns a pending job handle. These examples poll pending jobs until their results are ready. TypeScript requests a 30-second wait to fit the SDK’s 60-second client timeout and Node’s 300-second header limit. The Python and cURL synchronous examples use the service’s default wait.

Synchronous (default)
Asynchronous

Python
TypeScript
cURL

import time
from unstructured_transform_client import TransformClient

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

def completed_result(client, response):
    if response.status in ("queued", "processing"):
        job = client.jobs.get(response.id)
        while job.status in ("queued", "processing"):
            time.sleep(2)
            job = client.jobs.get(response.id)
        if job.status not in ("completed", "completed_with_warnings") or job.result is None:
            raise RuntimeError("Job did not complete with a result")
        return job.result
    if response.status not in ("completed", "completed_with_warnings"):
        raise RuntimeError("Request did not complete")
    return response

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

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

const client = new TransformClient({ timeoutMs: 60_000 });
type Submission = Awaited<ReturnType<typeof client.parse.run>> | Awaited<ReturnType<typeof client.extract.run>>;
async function completedResult(response: Submission) {
  if (!isAccepted(response)) return response.body;
  let job = await client.jobs.get(response.body.id);
  while (job.status === "queued" || job.status === "processing") {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    job = await client.jobs.get(response.body.id);
  }
  if ((job.status !== "completed" && job.status !== "completed_with_warnings") || !job.result) {
    throw new Error("Job did not complete with a result");
  }
  return job.result;
}
const schema = {
  type: "object",
  properties: { invoice_number: { type: "string" } },
  required: ["invoice_number"],
  additionalProperties: false,
};
const file = new File([await readFile("document.pdf")], "document.pdf");
// Override the service default to fit Node's transport and client timeout limits.
const parsed = await completedResult(await client.parse.run({ input: file, waitSeconds: 30 }));
const extraction = await completedResult(await client.extract.run({
  parseId: parsed.id,
  schema,
  waitSeconds: 30,
}));
console.log(extraction.extractedData);

# Run in zsh. Follow any pending job before using its result.
API_BASE_URL="https://transform.unstructured.io"
completed_result() {
  local response="$1" headers="$2"
  local reference="$(awk 'tolower($0) ~ /^location:/ {sub(/^[^:]*:[[:space:]]*/, ""); sub(/\r$/, ""); print; exit}' "$headers")"
  if [[ -z "$reference" ]]; then reference="$(jq -r '.poll_url // empty' "$response")"; fi
  if [[ -z "$reference" ]]; then
    jq -e '.status == "completed" or .status == "completed_with_warnings"' "$response" >/dev/null
    return
  fi
  local poll_url
  case "$reference" in
    http://*|https://*) poll_url="$reference" ;;
    *) poll_url="${API_BASE_URL}${reference}" ;;
  esac
  while :; do
    curl --fail-with-body -sS "$poll_url" \
      -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" -o job.json || return 1
    case "$(jq -r '.status' job.json)" in
      queued|processing) sleep 2 ;;
      completed|completed_with_warnings) jq -e '.result | objects' job.json > "$response"; return ;;
      *) return 1 ;;
    esac
  done
}
curl --fail-with-body -sS \
  https://transform.unstructured.io/api/v2/parse \
  -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
  -F "input=@document.pdf" \
  -D parse-headers.txt \
  -o parse.json

completed_result parse.json parse-headers.txt || exit 1
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 \
  -D extract-headers.txt \
  -o extract.json
completed_result extract.json extract-headers.txt || exit 1
cat extract.json

Each example submits Parse without waiting and polls until it completes. It then submits Extract and polls any pending Extract job.

Python
TypeScript
cURL

import time

from unstructured_transform_client import TransformClient

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

def completed_result(client, response):
    if response.status in ("queued", "processing"):
        job = client.jobs.get(response.id)
        while job.status in ("queued", "processing"):
            time.sleep(2)
            job = client.jobs.get(response.id)
        if job.status not in ("completed", "completed_with_warnings") or job.result is None:
            raise RuntimeError("Job did not complete with a result")
        return job.result
    if response.status not in ("completed", "completed_with_warnings"):
        raise RuntimeError("Request did not complete")
    return response

with TransformClient(timeout_seconds=960) 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 = completed_result(client, client.extract.run(parse_id=job.result.id, schema=schema))
    print(extraction.extracted_data)

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

const client = new TransformClient({ timeoutMs: 60_000 });
type Submission = Awaited<ReturnType<typeof client.parse.run>> | Awaited<ReturnType<typeof client.extract.run>>;
async function completedResult(response: Submission) {
  if (!isAccepted(response)) return response.body;
  let job = await client.jobs.get(response.body.id);
  while (job.status === "queued" || job.status === "processing") {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    job = await client.jobs.get(response.body.id);
  }
  if ((job.status !== "completed" && job.status !== "completed_with_warnings") || !job.result) {
    throw new Error("Job did not complete with a result");
  }
  return job.result;
}

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 completedResult(await client.extract.run({
  parseId: job.result.id,
  schema,
  waitSeconds: 30,
}));
console.log(extraction.extractedData);

# Run in zsh. This example requires jq.
API_BASE_URL="https://transform.unstructured.io"
completed_result() {
  local response="$1" headers="$2"
  local reference="$(awk 'tolower($0) ~ /^location:/ {sub(/^[^:]*:[[:space:]]*/, ""); sub(/\r$/, ""); print; exit}' "$headers")"
  if [[ -z "$reference" ]]; then reference="$(jq -r '.poll_url // empty' "$response")"; fi
  if [[ -z "$reference" ]]; then
    jq -e '.status == "completed" or .status == "completed_with_warnings"' "$response" >/dev/null
    return
  fi
  local poll_url
  case "$reference" in
    http://*|https://*) poll_url="$reference" ;;
    *) poll_url="${API_BASE_URL}${reference}" ;;
  esac
  while :; do
    curl --fail-with-body -sS "$poll_url" \
      -H "unstructured-api-key: $UNSTRUCTURED_API_KEY" -o job.json || return 1
    case "$(jq -r '.status' job.json)" in
      queued|processing) sleep 2 ;;
      completed|completed_with_warnings) jq -e '.result | objects' job.json > "$response"; return ;;
      *) return 1 ;;
    esac
  done
}
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)
case "$POLL_PATH" in
  http://*|https://*) POLL_URL="$POLL_PATH" ;;
  *) POLL_URL="${API_BASE_URL}${POLL_PATH}" ;;
esac
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 \
  -D extract-headers.txt \
  -o extract.json
completed_result extract.json extract-headers.txt || exit 1
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.

Integrate

API Reference

API endpoints

Chain Parse and Extract

Pass the Parse ID to Extract

Chain two requests

Run another schema against the same Parse

​Pass the Parse ID to Extract

​Chain two requests

​Run another schema against the same Parse

Pass the Parse ID to Extract

Chain two requests

Run another schema against the same Parse