Quickstart: extract a document

One document in, structured fields out, in a single call.

Goal. Send a PDF to Document AI and get back structured fields — company name, dates, financial line items — without writing any polling logic.

This is the shortest path from a file to data. It uses the synchronous endpoint, which holds the connection open until extraction finishes. That makes it ideal for trying the API out and poor for production, for reasons the last section covers.

Before you start

• An API key. Settings → API Keys in the portal, as Owner or Admin — see Authentication.

• A document. This recipe uses a one-page balance sheet PDF.

• A client that will wait at least two minutes for a response.

export DOCAI_API_KEY='ak_…'

Step 1 — Choose a document type

Extraction is schema-driven: telling the platform what the document is determines which fields it looks for. Values come from the registry.

curl -s "https://api-docai-uat.uptiq.ai/listSupportedDocuments" \
  | jq -r '.documents[] | "\(.type)\t\(.category)"' | head

ACATAccountTransferForm         Account Transfer Document
AadhaarCard                     Identity Document
AccountReceivablesAgingReport   Financial Report
AccountsPayableAgingReport      Financial Report
ArticlesOfIncorporation         Corporate Document

We want BalanceSheet. If you do not know the type ahead of time, classify first.

Step 2 — Build the request

The document travels inside the JSON body, base64-encoded, so no multipart upload is involved.

python -c "
import base64, json
content = base64.b64encode(open('balance-sheet.pdf','rb').read()).decode()
json.dump({
    'documentType': 'BalanceSheet',
    'content': content,
    'model': 'gemini-3'
}, open('request.json','w'))
"

If your file already has a URL the platform can reach, send file_url instead of content and skip the base64 step. Send one or the other — never both.

Step 3 — Call the endpoint

Use Synchronous document extraction for the complete request and response schema.

curl -X POST "https://api-docai-uat.uptiq.ai/extract/sync" \
  -H "X-Api-Key: $DOCAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  -o response.json

This took 93 seconds for a single page. That is normal — the work is OCR plus model inference. Do not lower your timeout to "fix" it.

Step 4 — Read the result

{
  "_id": "8c1d47e9-2f36-4a85-b7c0-6e93a5d21fb8",
  "documentStatus": "Processed",
  "documentType": "BalanceSheet",
  "requestId": "b93c5f28-41a7-4e60-9d18-72c6ea035b1f",
  "status": "success",
  "result": {
    "extractedData": { },
    "extractionMetrics": { },
    "documentQuality": { },
    "layoutData": { },
    "tokenUsage": { },
    "ocrUsage": { }
  }
}

Check documentStatus — Processed means it worked. status: "success" refers to the API call, not the document, and will read success even for a document that failed to process.

The fields are under result.extractedData, each with its value and where it was found on the page:

jq '.result.extractedData.CompanyName' response.json

{
  "value": "Northwind Trading Co.",
  "bbox": [
    { "pageNumber": 1, "pageWidth": 8.5, "pageHeight": 11.0,
      "x1": 0.8256, "y1": 0.2805, "x2": 3.7036, "y2": 0.7508 }
  ]
}

The bbox coordinates are in inches, page-relative — enough to draw a highlight over the source document if you are building a review UI.

Step 5 — Judge whether to trust it

Do not treat every extraction as equally good. result.extractionMetrics grades the run:

{
  "accuracyScore": 85.67,
  "completenessScore": 66.67,
  "consistencyScore": 88.0,
  "formatScore": 100.0,
  "rulesChecked": 25,
  "rulesPassed": 22,
  "rulesFailed": 3,
  "totalExpectedFields": 6,
  "totalPopulatedFields": 4,
  "missingFields": [ ],
  "failedRules": [ ]
}

On our run, four of six expected fields were populated — hence completenessScore of 66.67 — because the test document was deliberately sparse. missingFields names exactly what was not found.

A sensible gate: auto-accept above a threshold on accuracyScore, route anything below it to human review. result.documentQuality.level (high, and a sharpness figure) tells you whether a poor result is the document's fault or the model's.

What it cost

{
  "creditReservation": { "cost": 0.03, "pages": 1, "operation": "extraction" },
  "tokenUsage":  { "total_tokens": 29375, "model": "gemini-3", "provider": "gemini" },
  "ocrUsage":    { "estimated_cost": 0.01, "page_count": 1, "provider": "azure" }
}

Useful for chargeback, and for noticing when a job runs away.

When it goes wrong

Symptom	Cause	Fix
401	Missing, expired or revoked key	Check Settings → API Keys
500 immediately	Missing or malformed body — not a server fault on this endpoint	Validate your JSON; see Errors
Client timeout	Waiting less than ~2 minutes	Raise the timeout, or use the async endpoint
documentStatus: Failed	The document could not be read	Check result.documentQuality; resubmitting an unreadable file will fail again
Empty extractedData	Wrong documentType for the document	Classify it first

Next steps

Do not build production on this endpoint. Ninety seconds of held connection does not survive a load balancer, a serverless timeout, or a user watching a spinner. Move to Extract asynchronously and poll, or better, Build an event-driven pipeline. The request body is identical — only the URL changes.

Related pages

• Extraction API — every parameter this request accepts.

• Document Extraction — the same capability in the UI, including result review.

• Conventions — envelopes, the lifecycle, and timing.