Extract fields from a Parse or document

Extract structured fields from a document or a completed Parse with a schema. Review required inputs, returned values, and pending responses.

POST /api/v2/extract

cURL

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"}}}'

200

Example

{
  "id": "7e3f0f72-4f99-4d6f-b42b-00cdaf7d54e6",
  "status": "completed",
  "profile": "balanced",
  "warnings": [],
  "markdown": null,
  "format_version": "2.0",
  "metadata": {
    "page_count": 1
  },
  "extracted_data": [
    {
      "data": {
        "invoice_number": "INV-1001"
      }
    }
  ],
  "elements": [],
  "source": {
    "file_id": "invoice-9eb6c914.pdf",
    "filename": "invoice.pdf",
    "mimetype": "application/pdf",
    "expires_at": "2026-09-18T18:34:26Z"
  }
}

Extract structured data directly from a document, or reuse a completed Parse. Choose the request format for your input:

Input	Content type	Body fields
A document	multipart/form-data	input: the file to upload. schema: a JSON Schema serialized as a JSON string.
A previously uploaded file	multipart/form-data	file_id: the uploaded file ID, instead of input. schema: a JSON Schema serialized as a JSON string.
A completed Parse	application/json	parse_id: the completed Parse ID. schema: a JSON Schema object.

For direct document extraction, send input and schema together. You do not need to upload or parse the document first. In the cURL example, -F "input=@document.pdf" uploads document.pdf as the input field.

To view the fields for each format, use the content-type selector beside Body: select multipart/form-data for document uploads or application/json for a completed Parse.

cURL

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"}}}'

Start with Parse your first document.

Chain Parse and Extract: pass a completed Parse ID as parse_id to reuse its content.

Authorizations

ApiKeyAuthBearerAuth

unstructured-api-key · string · header · required

API keys must be sent in this header.

Headers

Prefer · string

Wait up to this many seconds for completed extraction. When omitted the request waits up to 15 minutes, then returns 202 with the job to poll.

Body

application/jsonmultipart/form-data

A parse ID to extract from, and the shape to extract into.

parse_id · string · required

The ID of the parse to extract against. It is not parsed again.

Example:

"9eb6c914-02a5-4c5d-8490-a06476946a38"

schema · object · required

A JSON Schema. Subject to the same engine constraints as schema on the parse call: it must be a valid JSON Schema (drafts 6, 7, 2019-09 or 2020-12), required and additionalProperties are filled in automatically when omitted so they are not the caller's burden, and the serialized schema is limited to 1,048,576 bytes.

prompt · string

Optional free-text guidance that shapes how extracted fields are filled. Limited to 1,048,576 bytes when encoded as UTF-8.

Response

200

application/json

Fields extracted. Check status for partial success.

Parse operation metadata plus the canonical document, possibly before extraction has finished.

id · string · required

Underlying job id, for support and tracing.

status · enum<string> · required

Document processing or terminal status.

Available options: processing, completed, completed_with_warnings

profile · enum<string> | null · required

The effective profile used for raw-document partitioning.

Available options: balanced, best

markdown · string | null · required

Rendered Markdown projection when requested; null when elements are requested.

format_version · string · required

The document envelope version.

metadata · object · required

Public document-level metadata.

Show child attributes

extracted_data · object[] | null · required

Completed extraction results are available only after extraction has finished.

Show child attributes

elements · object[] · required

Public document elements.

Show child attributes

source · object | null · required

The associated original uploaded source file, when known.

Show child attributes

warnings · object[]

Notes about a result that still succeeded.

Show child attributes

failed_pages · object[]

Pages that could not be processed and have no elements in this result.

Show child attributes

degraded_pages · object[]

Pages that are in this result although some of their content could not be recognized.

Show child attributes