Extract fields from a Parse or document

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

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

POST

api

extract

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

{
  "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 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

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

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

Fields extracted. Check status for partial success.

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

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

enum<string>

required

The document envelope version.

Available options:

2.0

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

Integrate

API Reference

API endpoints

Extract fields from a Parse or document

Authorizations

Headers

Body

Response