Extraction

Submit documents for extraction and retrieve structured results.

The Extraction endpoints turn a document into structured data. You choose how you want to wait for the answer: /extract/sync holds the connection open and returns the result in the response, /extract accepts the job and returns an ID you poll or receive a webhook for, and /extract/bulk does the same for many documents at once and groups them under a single identifier.

All three take the same rich parameter set — the document type, the model, the chart of accounts, the analysis toggles — so moving a working synchronous call to the asynchronous path is usually a change of URL and nothing else.

Generated endpoint reference

The generated reference is the source of truth for schemas and responses.

• Get all extractions in a multi-extraction group

• Get extraction details

• Extract document data (Async)

• Bulk document extraction (Async)

• Synchronous document extraction

This guide keeps the integration rules and known behavior the schema cannot express.

Send the document one of two ways: content as base64, or file_url as a URL the platform can reach. Give one of them, not both. The same either/or applies to the document type: use documentType for a single type, or documentTypes for multi-extraction — again, one of them.

Neither constraint is expressed in the spec's required list — every property is formally optional, and the obligations live only in the property descriptions. A request that satisfies the schema can still be rejected. See Conventions for the full set of these unenforced rules.

For what the parameters mean in product terms — document types, models, chart of accounts, confidence — see Document Extraction.

Get all extractions in a multi-extraction group, keyed by documentType.

GET /document-extractions/group/{extraction_group_id}

Requires the X-Api-Key header. See Authentication.

Path and query parameters

Parameter	In	Type	Required	Description
extraction_group_id	path	string	Yes

Responses

Status	Description	Schema
200	OK	GroupExtractionResponse
400	Bad Request	ValidationError
401	Authentication required — the X-Api-Key header is missing or invalid.
404	No extraction group exists with that ID.

Example

curl -X GET "https://api-docai-uat.uptiq.ai/document-extractions/group/{extraction_group_id}" \
  -H "X-Api-Key: $DOCAI_API_KEY"

Get extraction details

GET /document-extractions/{extraction_id}

Requires the X-Api-Key header. See Authentication.

Path and query parameters

Parameter	In	Type	Required	Description
extraction_id	path	string	Yes

Responses

Status	Description	Schema
200	OK	GetExtractionResponse
400	Bad Request	ValidationError
401	Authentication required — the X-Api-Key header is missing or invalid.
404	No extraction exists with that ID.

Example

curl -X GET "https://api-docai-uat.uptiq.ai/document-extractions/{extraction_id}" \
  -H "X-Api-Key: $DOCAI_API_KEY"

Extract document data (Async)

POST /extract

Requires the X-Api-Key header. See Authentication.

Request body — application/json, required: ExtractRequest

Property	Type	Required	Default	Description
additionalParams	AdditionalParams | null			Additional extraction parameters for fine-grained control
agentInstructions	string | null			Additional system-level instructions injected into the LLM system prompt
analysisDepth	string | null		"standard"	Depth of document analysis: 'quick' (skip classification if type provided) or 'standard' (full analysis). One of: quick, standard.
chartOfAccounts	object | array<object> | null			Chart of accounts mapping. Flat array for standard: [{accountId, accountName}]. Structured dict for BusinessFinancialStatement: {BalanceSheet: [...], ProfitAndLossStatement: [...]}.
chartOfAccountsUrl	string | null			URL to download chart of accounts JSON. Only used when chartOfAccounts is not provided directly.
content	string | null			Base64-encoded file content
custom_document_types	array<string> | null			Custom document type names to use for V2 classification instead of the built-in list
documentType	string | null			Document type. Mutually exclusive with documentTypes; one is required.
documentTypes	array<DocumentTypeEntry> | null			Multi-extraction document types. Mutually exclusive with documentType; one is required.
enableCaching	boolean | null		false	If true, store extraction result in cache for future requests
enableDocumentAnalysis	boolean | null		true	Run AI document analysis to categorize content before extraction (V2 only)
enableJudge	boolean | null		false	Enable LLM-as-Judge evaluation: a second LLM reviews extraction quality post-hoc
enablePageContent	boolean | null		false	Include page-wise OCR content and AI-generated summaries per page
enablePageSummaries	boolean | null		false	Deprecated — use enablePageContent instead
enableRawSections	boolean | null		false	Include raw OCR text sections with bounding boxes in the result (V2 only)
extractionFormat	object | null			Custom extraction JSON schema defining the output structure. Overrides the default DocumentConfig format.
extractionPrompt	string | null			Custom natural language prompt to guide LLM extraction behavior beyond the extractionFormat schema.
file_url	string | null			Public URL to file
form8825Address	string | null			Single property address (backward-compatible alias for form8825Addresses with one entry)
form8825Addresses	array<string> | null			Property addresses for Form 8825 direct deep extraction. Skips property identification and runs a native-PDF extraction per address.
formTypes	array<string> | null			Form types (for tax documents)
galleryIds	array<string> | null			Knowledge Search gallery IDs to tag the document into after extraction
includeLayout	boolean | null		false	Include document layout structure (tables, paragraphs, headings) in result
industry	string | null			Industry name to load default chart of accounts from database for supported document types
metadata	object | null			Arbitrary key-value metadata to attach to the extraction record
model	string | null		"gemini-3"	LLM model for extraction. One of: gpt-4.1, gpt-5.1, gemini-3, openrouter/z-ai/glm-5.2, openrouter/deepseek/deepseek-v4-pro.
overrideCache	boolean | null		false	If true, bypass cached extraction results and re-extract from scratch
query	string | null			Natural language question to answer after extraction completes. Enables async Q&A on the result.
quickExtract	boolean | null		false	Use Gemini native PDF extraction (bypasses Azure OCR). Faster but may have lower accuracy for complex layouts.
rawExtractionOnly	boolean | null		false	Skip LLM extraction entirely; return only OCR/layout data without structured extraction
subtype	string | null			Document subtype
tagInstructions	string | null			Tag classification instructions (only used when documentType is OtherWithMetadata)

Nested objects

AdditionalParams

Property	Type	Required	Default	Description
extractImages	boolean		false	When true, extract embedded images from well-formatted (digital) PDFs, store them in the storage bucket, and return signed URLs on result.extractedImages. Scanned/photo PDFs and non-PDF files are skipped with a message (imageExtraction.status). Signed URLs are valid for 7 days - consumers must fetch/copy within that window.
imageInstructions	string | null			Free-text instruction used to vision-tag and rank extracted images (e.g. 'property photos and map locations'). Requires extractImages=true. Matching images are ranked first (matchScore); images are never dropped.
returnFieldConfidences	boolean		false	When true, compute per-field confidence scores (inline + aggregate). Skips field confidence computation when false to reduce response size.

DocumentTypeEntry

Property	Type	Required	Default	Description
documentType	string	Yes		Document type for extraction
entity	string | null			Entity name for this extraction
entityId	string | null			Entity ID for this extraction
pageNumbers	array<integer> | null			Target page numbers (PDF)
sheetNames	array<string> | null			Target sheet names (Excel)

Responses

Status	Description	Schema
200	OK	ExtractResponse
202	Accepted — returned instead of 200 when the request uses documentTypes for a multi-extraction. The success code varies with the request, not just the endpoint.
400	Bad Request	ValidationError
401	Authentication required — the X-Api-Key header is missing or invalid.
500	Returned instead of 400 when the request body is missing or invalid. Known defect.

Example

curl -X POST "https://api-docai-uat.uptiq.ai/extract" \
  -H "X-Api-Key: $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
         "documentType": "BankStatements",
         "file_url": "https://example.com/statement.pdf"
       }'

Bulk document extraction (Async)

POST /extract/bulk

Requires the X-Api-Key header. See Authentication.

Request body — application/json, required: ExtractBulkRequest

Property	Type	Required	Default	Description
files	array<ExtractBulkRequestFile>	Yes		List of files to extract, each with content or file_url

Nested objects

ExtractBulkRequestFile

Property	Type	Required	Default	Description
additionalParams	AdditionalParams | null			Additional extraction parameters for fine-grained control
agentInstructions	string | null			Additional system-level instructions injected into the LLM system prompt
analysisDepth	string | null		"standard"	Depth of document analysis: 'quick' (skip classification if type provided) or 'standard' (full analysis). One of: quick, standard.
chartOfAccounts	object | array<object> | null			Chart of accounts mapping. Flat array for standard: [{accountId, accountName}]. Structured dict for BusinessFinancialStatement: {BalanceSheet: [...], ProfitAndLossStatement: [...]}.
chartOfAccountsUrl	string | null			URL to download chart of accounts JSON. Only used when chartOfAccounts is not provided directly.
content	string | null			Base64-encoded file content
custom_document_types	array<string> | null			Custom document type names to use for V2 classification instead of the built-in list
documentType	string | null			Document type. Mutually exclusive with documentTypes; one is required.
documentTypes	array<DocumentTypeEntry> | null			Multi-extraction document types. Mutually exclusive with documentType; one is required.
enableCaching	boolean | null		false	If true, store extraction result in cache for future requests
enableDocumentAnalysis	boolean | null		true	Run AI document analysis to categorize content before extraction (V2 only)
enableJudge	boolean | null		false	Enable LLM-as-Judge evaluation: a second LLM reviews extraction quality post-hoc
enablePageContent	boolean | null		false	Include page-wise OCR content and AI-generated summaries per page
enablePageSummaries	boolean | null		false	Deprecated — use enablePageContent instead
enableRawSections	boolean | null		false	Include raw OCR text sections with bounding boxes in the result (V2 only)
extractionFormat	object | null			Custom extraction JSON schema defining the output structure. Overrides the default DocumentConfig format.
extractionPrompt	string | null			Custom natural language prompt to guide LLM extraction behavior beyond the extractionFormat schema.
file_url	string | null			Public URL to file
form8825Address	string | null			Single property address (backward-compatible alias for form8825Addresses with one entry)
form8825Addresses	array<string> | null			Property addresses for Form 8825 direct deep extraction. Skips property identification and runs a native-PDF extraction per address.
formTypes	array<string> | null			Form types (for tax documents)
galleryIds	array<string> | null			Knowledge Search gallery IDs to tag the document into after extraction
includeLayout	boolean | null		false	Include document layout structure (tables, paragraphs, headings) in result
industry	string | null			Industry name to load default chart of accounts from database for supported document types
metadata	object | null			Arbitrary key-value metadata to attach to the extraction record
model	string | null		"gemini-3"	LLM model for extraction. One of: gpt-4.1, gpt-5.1, gemini-3, openrouter/z-ai/glm-5.2, openrouter/deepseek/deepseek-v4-pro.
overrideCache	boolean | null		false	If true, bypass cached extraction results and re-extract from scratch
query	string | null			Natural language question to answer after extraction completes. Enables async Q&A on the result.
quickExtract	boolean | null		false	Use Gemini native PDF extraction (bypasses Azure OCR). Faster but may have lower accuracy for complex layouts.
rawExtractionOnly	boolean | null		false	Skip LLM extraction entirely; return only OCR/layout data without structured extraction
subtype	string | null			Document subtype
tagInstructions	string | null			Tag classification instructions (only used when documentType is OtherWithMetadata)

AdditionalParams

Property	Type	Required	Default	Description
extractImages	boolean		false	When true, extract embedded images from well-formatted (digital) PDFs, store them in the storage bucket, and return signed URLs on result.extractedImages. Scanned/photo PDFs and non-PDF files are skipped with a message (imageExtraction.status). Signed URLs are valid for 7 days - consumers must fetch/copy within that window.
imageInstructions	string | null			Free-text instruction used to vision-tag and rank extracted images (e.g. 'property photos and map locations'). Requires extractImages=true. Matching images are ranked first (matchScore); images are never dropped.
returnFieldConfidences	boolean		false	When true, compute per-field confidence scores (inline + aggregate). Skips field confidence computation when false to reduce response size.

DocumentTypeEntry

Property	Type	Required	Default	Description
documentType	string	Yes		Document type for extraction
entity	string | null			Entity name for this extraction
entityId	string | null			Entity ID for this extraction
pageNumbers	array<integer> | null			Target page numbers (PDF)
sheetNames	array<string> | null			Target sheet names (Excel)

Responses

Status	Description	Schema
200	OK	ExtractBulkResponse
400	Bad Request	ValidationError
401	Authentication required — the X-Api-Key header is missing or invalid.

Example

curl -X POST "https://api-docai-uat.uptiq.ai/extract/bulk" \
  -H "X-Api-Key: $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
         "files": [
           {
             "documentType": "BalanceSheet",
             "file_url": "https://example.com/bs.pdf"
           },
           {
             "documentType": "ProfitAndLossStatement",
             "file_url": "https://example.com/pl.pdf"
           }
         ]
       }'

Synchronous document extraction

POST /extract/sync

Requires the X-Api-Key header. See Authentication.

Request body — application/json, required: ExtractSyncRequest

Property	Type	Required	Default	Description
additionalParams	AdditionalParams | null			Additional extraction parameters for fine-grained control
agentInstructions	string | null			Additional system-level instructions injected into the LLM system prompt
analysisDepth	string | null		"standard"	Depth of document analysis: 'quick' (skip classification if type provided) or 'standard' (full analysis). One of: quick, standard.
chartOfAccounts	object | array<object> | null			Chart of accounts mapping. Flat array for standard: [{accountId, accountName}]. Structured dict for BusinessFinancialStatement: {BalanceSheet: [...], ProfitAndLossStatement: [...]}.
chartOfAccountsUrl	string | null			URL to download chart of accounts JSON. Only used when chartOfAccounts is not provided directly.
content	string | null			Base64-encoded file content
custom_document_types	array<string> | null			Custom document type names to use for V2 classification instead of the built-in list
documentType	string | null			Document type. Mutually exclusive with documentTypes; one is required.
documentTypes	array<DocumentTypeEntry> | null			Multi-extraction document types. Mutually exclusive with documentType; one is required.
enableCaching	boolean | null		false	If true, store extraction result in cache for future requests
enableDocumentAnalysis	boolean | null		true	Run AI document analysis to categorize content before extraction (V2 only)
enableJudge	boolean | null		false	Enable LLM-as-Judge evaluation: a second LLM reviews extraction quality post-hoc
enablePageContent	boolean | null		false	Include page-wise OCR content and AI-generated summaries per page
enablePageSummaries	boolean | null		false	Deprecated — use enablePageContent instead
enableRawSections	boolean | null		false	Include raw OCR text sections with bounding boxes in the result (V2 only)
extractionFormat	object | null			Custom extraction JSON schema defining the output structure. Overrides the default DocumentConfig format.
extractionId	string | null			Existing extraction document ID for incremental instruction mode. When provided, runs instruction extraction on the stored document instead of standard extraction.
extractionPrompt	string | null			Custom natural language prompt to guide LLM extraction behavior beyond the extractionFormat schema.
file_url	string | null			Public URL to file
form8825Address	string | null			Single property address (backward-compatible alias for form8825Addresses with one entry)
form8825Addresses	array<string> | null			Property addresses for Form 8825 direct deep extraction. Skips property identification and runs a native-PDF extraction per address.
formTypes	array<string> | null			Form types (for tax documents)
galleryIds	array<string> | null			Knowledge Search gallery IDs to tag the document into after extraction
includeLayout	boolean | null		false	Include document layout structure (tables, paragraphs, headings) in result
industry	string | null			Industry name to load default chart of accounts from database for supported document types
mapToSchema	boolean | null		false	If true, instruction extraction results are mapped to the document type's JSON schema
mergeMode	string | null		"append"	How to merge instruction extraction results with existing data: append, overwrite, or replace. One of: append, overwrite, replace.
metadata	object | null			Arbitrary key-value metadata to attach to the extraction record
model	string | null		"gemini-3"	LLM model for extraction. One of: gpt-4.1, gpt-5.1, gemini-3, openrouter/z-ai/glm-5.2, openrouter/deepseek/deepseek-v4-pro.
overrideCache	boolean | null		false	If true, bypass cached extraction results and re-extract from scratch
query	string | null			Natural language query on the extraction result
quickExtract	boolean | null		false	Use Gemini native PDF extraction (bypasses Azure OCR). Faster but may have lower accuracy for complex layouts.
rawExtractionOnly	boolean | null		false	Skip LLM extraction entirely; return only OCR/layout data without structured extraction
subtype	string | null			Document subtype
tagInstructions	string | null			Tag classification instructions (only used when documentType is OtherWithMetadata)
targetFields	array<string> | null			Target field names for instruction extraction mode. Limits extraction to these fields.

Nested objects

AdditionalParams

Property	Type	Required	Default	Description
extractImages	boolean		false	When true, extract embedded images from well-formatted (digital) PDFs, store them in the storage bucket, and return signed URLs on result.extractedImages. Scanned/photo PDFs and non-PDF files are skipped with a message (imageExtraction.status). Signed URLs are valid for 7 days - consumers must fetch/copy within that window.
imageInstructions	string | null			Free-text instruction used to vision-tag and rank extracted images (e.g. 'property photos and map locations'). Requires extractImages=true. Matching images are ranked first (matchScore); images are never dropped.
returnFieldConfidences	boolean		false	When true, compute per-field confidence scores (inline + aggregate). Skips field confidence computation when false to reduce response size.

DocumentTypeEntry

Property	Type	Required	Default	Description
documentType	string	Yes		Document type for extraction
entity	string | null			Entity name for this extraction
entityId	string | null			Entity ID for this extraction
pageNumbers	array<integer> | null			Target page numbers (PDF)
sheetNames	array<string> | null			Target sheet names (Excel)

Responses

Status	Description	Schema
200	OK	ExtractSyncResponse
400	Bad Request	ValidationError
401	Authentication required — the X-Api-Key header is missing or invalid.
500	Returned instead of 400 when the request body is missing or invalid. Known defect.

Example

curl -X POST "https://api-docai-uat.uptiq.ai/extract/sync" \
  -H "X-Api-Key: $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
         "documentType": "BalanceSheet",
         "file_url": "https://example.com/balance-sheet.pdf",
         "model": "gemini-3"
       }'

Related pages

• Document Extraction — the same capability through the UI, including result review and corrections.

• Document Types — the registry of values accepted by documentType.

• Conventions — sync versus async, the status lifecycle, and the constraints the schema does not enforce.

• Errors — status codes, including the ones the spec omits.

• Quickstart: extract a document — a working call, end to end.