Purchase order OCR API: send a PO file, get every line back as JSON
A purchase order OCR API takes a PO file (a PDF, a scan, a fax or a photo) and returns what is on it as structured data: the header once, every line item as a list. With Koncile it is two calls, one to upload the file and one to fetch the result, or one call and a webhook. Reading is the easy part to demo. What decides whether the integration holds is what your code does with low confidence values and with lines that do not add up, and this page shows both on a worked example.
Two different things called a purchase order API
Search for "purchase order API" and most results are ERP documentation: Oracle Fusion Cloud Procurement, Microsoft Dynamics 365 Business Central, SAP S/4HANA, Shopify. Those APIs create, read and update purchase order (PO) records that already live inside the system. They take structured JSON in. None of them reads a PDF.
A purchase order OCR API, also called a PO parser, works one step earlier. It takes the document a customer or a supplier sent you and turns it into the structured data an ERP API expects. A real integration often uses both: the OCR API reads the PO, your code checks it, and the ERP API creates the sales order or updates the purchase order.
| ERP purchase order API | Purchase order OCR API (PO parser) | |
|---|---|---|
| What goes in | A JSON record | A PDF, scan, fax or photo of a PO |
| What comes out | A PO created, updated or listed in the ERP | Header fields and line items as JSON, each value with a confidence score |
| Typical job | Create a PO, post a goods receipt, close an order | Order entry from customer POs, checking supplier confirmations, three way matching |
| Examples | Oracle Fusion Procurement REST, Business Central purchaseOrders, SAP S/4HANA | Koncile, Mindee, Veryfi, Parsio |
What a PO parser returns
Koncile returns two groups of fields. General fields appear once per document: PO number, date, buyer, vendor, ship to address, payment terms, currency, subtotal, tax, total. Line fields are arrays, one entry per line item in the order of the table: item number or SKU, description, quantity, unit of measure (UoM), unit price, line total. Every value carries a confidence_score between 0 and 1.
The fields come from a template, not from a fixed model. You start from the ready to use purchase order template in the library, or let the AI propose fields from a sample PO, then add, rename or remove fields and describe each one in plain language ("the quantity column, not the quantity ordered to date"). One template serves every layout of the same document type: you do not draw zones per customer or per supplier.
Two settings trip up most first integrations. Fields typed as Number use a decimal comma by default (1,2), and dates default to day first (DD/MM/YYYY). Both can be switched to the dot and the US date format in the settings. Decide before you write the parsing code, not after the first wrong total.
A worked example: one customer PO, three lines, two problems
Take a specimen order. A hardware distributor receives PO CP-7731 from its customer Cedar & Pine Hardware, as a scanned PDF. The buyer built the order in a spreadsheet, printed it, changed one quantity by hand from 8 to 6 boxes, and scanned the page. Here is what is printed on it.
| Line | SKU and description | Qty | UoM | Unit price | Line total printed | Qty x price |
|---|---|---|---|---|---|---|
| 1 | HX-1020 Hex bolt M10 x 50, box of 100 | 12 | BX | 18.40 | 220.80 | 220.80 |
| 2 | WS-0310 Flat washer M10, box of 200 | 6, handwritten over 8 | BX | 7.95 | 63.60 | 47.70 |
| 3 | AN-2290 Wedge anchor 3/8 in, pack of 25 | 4 | PK | 31.60 | 136.40 | 126.40 |
| Subtotal printed | 420.80 | 394.90 | ||||
| Sales tax 8.25% | 34.72 | |||||
| Total printed | 455.52 |
The printed subtotal is the sum of the printed line totals, so a check on the header alone passes: 220.80 + 63.60 + 136.40 = 420.80. The problems sit inside the lines. Line 3 is a plain error in the buyer's spreadsheet: 4 x 31.60 is 126.40, not 136.40. Line 2 is a hand correction that never reached the amount: 6 boxes cost 47.70, while the page still says 63.60 for the 8 boxes first typed. Shipped and invoiced as printed, the order is off by 25.90 dollars and nobody knows which quantity the customer really wants.
The request
# 1. Upload the PO (one file per request)
curl -X POST "https://api.koncile.ai/v1/upload_file/?folder_id=12&template_id=34" \
-H "Authorization: Bearer $KONCILE_API_KEY" \
-F "files=@CP-7731.pdf"
# {"task_ids": ["EOBdOSUX4Uv57YWsLYc4JQ"]}
# 2. Fetch the result (or let a webhook call you, see below)
curl "https://api.koncile.ai/v1/fetch_tasks_results/?task_id=EOBdOSUX4Uv57YWsLYc4JQ" \
-H "Authorization: Bearer $KONCILE_API_KEY"The upload returns one task ID per file. Processing is asynchronous: the task reads IN PROGRESS, then DONE, FAILED, or DUPLICATE when Koncile considers the document already received. The response below is shortened, with the dot and US date settings on.
The response
{
"status": "DONE",
"document_name": "CP-7731.pdf",
"General_fields": {
"PO number": {"value": "CP-7731", "confidence_score": 0.99},
"PO date": {"value": "10/27/2026", "confidence_score": 0.97},
"Buyer": {"value": "Cedar & Pine Hardware", "confidence_score": 0.98},
"Currency": {"value": "USD", "confidence_score": 0.99},
"Subtotal": {"value": "420.80", "confidence_score": 0.98},
"Tax": {"value": "34.72", "confidence_score": 0.97},
"Total": {"value": "455.52", "confidence_score": 0.98}
},
"Line_fields": {
"SKU": [{"value": "HX-1020", "confidence_score": 0.99},
{"value": "WS-0310", "confidence_score": 0.98},
{"value": "AN-2290", "confidence_score": 0.99}],
"Quantity": [{"value": "12", "confidence_score": 0.98},
{"value": "6", "confidence_score": 0.71},
{"value": "4", "confidence_score": 0.97}],
"Unit": [{"value": "BX"}, {"value": "BX"}, {"value": "PK"}],
"Unit price": [{"value": "18.40"}, {"value": "7.95"}, {"value": "31.60"}],
"Line total": [{"value": "220.80"}, {"value": "63.60"}, {"value": "136.40"}]
}
}Notice the 0.71 on the second quantity: the handwritten 6 over a typed 8 is exactly the kind of value the model is unsure about, and it says so.
Turning line fields into rows and checking them
Line fields come back as one list per column. The snippet below rebuilds one row per line, flags any value under a confidence threshold, recomputes quantity x unit price for each line and compares the sum with the printed subtotal. It is plain Python with no dependency.
def num(v):
# Number fields use a decimal comma by default: switch to a dot in the
# settings, or accept both as here.
return float(str(v).replace(",", "."))
def rows(doc):
"""Line_fields holds one list per column: rebuild one dict per line."""
cols = doc["Line_fields"]
n = max(len(v) for v in cols.values())
return [{k: (v[i] if i < len(v) else None) for k, v in cols.items()}
for i in range(n)]
def check(doc, min_conf=0.90, tol=0.01):
issues, total = [], 0.0
for i, r in enumerate(rows(doc), 1):
low = [k for k, f in r.items() if f and f.get("confidence_score", 1) < min_conf]
if low:
issues.append(f"line {i}: low confidence on {', '.join(low)}")
if not all(r.get(k) for k in ("Quantity", "Unit price", "Line total")):
issues.append(f"line {i}: missing value")
continue
q, p, t = (num(r[k]["value"]) for k in ("Quantity", "Unit price", "Line total"))
if abs(q * p - t) > tol:
issues.append(f"line {i}: {q:g} x {p:.2f} = {q * p:.2f}, printed {t:.2f}")
total += q * p
sub = num(doc["General_fields"]["Subtotal"]["value"])
if abs(total - sub) > tol:
issues.append(f"lines add up to {total:.2f}, printed subtotal {sub:.2f}")
return issues
for issue in check(doc):
print(issue)On PO CP-7731 it prints:
line 2: low confidence on Quantity
line 2: 6 x 7.95 = 47.70, printed 63.60
line 3: 4 x 31.60 = 126.40, printed 136.40
lines add up to 394.90, printed subtotal 420.80Line 1 goes straight to the ERP. Lines 2 and 3 wait for a person, who sees why: one quantity to confirm, one price calculation to raise with the customer before the order ships. Koncile's control layer can also run checks on its side (totals recomputed from the lines, lines matched to your catalog); whether you run them there or in your own code depends on your setup. The same rows feed the comparison of a PO with its delivery note and its invoice, described on our invoice matching software page.
Webhooks instead of polling
Polling fetch_tasks_results is fine for a test. In production, declare a webhook in the app: Koncile sends a POST to your URL when a document is done, in JSON or CSV, optionally limited to some folders or templates. With a signing secret (whsec_...), each request carries an HMAC-SHA256 signature of {timestamp}.{payload} in the X-Koncile-Signature header and the timestamp in X-Koncile-Timestamp. Verify both before trusting the body:
import hashlib, hmac, time
def from_koncile(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
if abs(time.time() - int(timestamp)) > 300: # older than 5 minutes: reject
return False
msg = f"{timestamp}.".encode() + raw_body # sign the raw bytes, not parsed JSON
expected = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
# headers: X-Koncile-Signature, X-Koncile-TimestampCustomer orders received by email follow the same path without code on your side: each customer PO sent to the account's integration address is imported, classified and extracted, then pushed by the webhook like an API upload. That is the usual setup for sales order automation.
Limits to know before you build
| Item | Limit | What happens past it |
|---|---|---|
| Pages per document | 150 | Split longer files before upload |
| File formats | PDF, JPEG, PNG | Spreadsheets and EDI files are already structured: no OCR needed |
| File size | 300 MB per PDF, 10 MB per PNG or JPEG | Rejected |
| Files per upload request | 1 | 413 error; for batches, send files one by one or use the presigned direct upload |
| Upload rate | 1 per second, bursts of 5, per API key | 429 with a Retry-After header, no credit used |
| Polling reads | 2 per second, bursts of 20 | Same 429 behavior |
| Usage limits | Daily and monthly caps set by an admin, plan page cap | 402 with a message that says which limit |
| Trailing slash | Endpoints end with / | 307 redirect |
Two parameters are worth knowing early. metadata passes up to 5,000 characters of JSON context you already hold (customer name, expected currency) to guide the extraction. doc_id attaches a file to a document already received, for a second page sent later or an amendment.
And the limits of the reading itself, said plainly. Tight handwriting, low resolution scans, phone photos taken at an angle and tables that run over several pages remain the first sources of error, on any OCR. Koncile does not create the order in your ERP: your code, or Make, n8n, Zapier or Power Automate, calls the ERP API with the checked lines. There are no native ERP apps. The official SDK exists for Python only; other languages call the REST API directly, documented in Swagger. An open source MCP server lets an AI agent call the same API.
How to choose a purchase order OCR API
| Question | Why it matters | Koncile's answer |
|---|---|---|
| Are line items separate typed fields, in order? | A blob of table text pushes the parsing back to you | Yes, one array per column, one entry per line |
| Is there a confidence score on every value? | It is what lets clean lines skip review | Yes, 0 to 1 on each value |
| Can you change the fields without retraining? | Each business reads a PO slightly differently | Yes, template edited in plain language |
| Asynchronous with signed webhooks? | Polling at scale wastes calls and hits rate limits | Yes, HMAC-SHA256 signature |
| Are limits and errors published? | You will hit them in production, not in the demo | Yes: pages, sizes, rates, status codes |
| Is the price per page public, with a free test? | Volume pricing on request makes the business case guesswork | Yes, 20 free credits, then from €0.20 per page |
Other APIs answer differently. Mindee has a dedicated purchase order OCR API with typed JSON, SDKs in six languages and a 14 day trial; comparing lines with your price list is code you write, which is the usual reason teams test a Mindee alternative. Veryfi offers a purchase order document type and a free plan of 100 documents a month. Amazon Textract returns tables and key values that you map to PO fields yourself; if that mapping is why you are leaving it, compare an AWS Textract alternative on the same POs. Email parsers such as Parsio or Parseur suit teams that start from the inbox rather than from code. Nanonets bills extraction as blocks inside workflows; if that pricing model is why you are looking elsewhere, compare a Nanonets alternative on your own POs. Prices and limits for each are in our ranking of the best purchase order OCR software.
Koncile's API comes with the account: 20 free credits without a card, one credit per page. The Advanced plan is €199 per month excluding tax for 1,000 credits, that is €0.20 per page, and the Pro plan brings it to €0.16 (pricing). The API key is created in the app settings (documentation).
Frequently asked questions
01What is a purchase order OCR API?
A web service that receives a purchase order file (PDF, scan, fax or photo) and returns its content as structured data: header fields once, line items as lists, usually in JSON. It replaces manual keying of POs in order entry, procurement or accounts payable systems.
02Is a PO parser the same as an ERP purchase order API?
No. An ERP purchase order API, such as Oracle Fusion Procurement or Business Central, creates and updates PO records that already exist as data. A PO parser reads the document and produces that data. Integrations often chain the two: parse, check, then post to the ERP.
03What does the Koncile API return for line items?
One array per column (SKU, description, quantity, unit, unit price, line total, or the fields you define), with one entry per line in table order, each with its confidence score. Rebuilding one row per line takes a few lines of code.
04How accurate is it?
Koncile publishes more than 99% accuracy on key fields of invoices and purchasing documents. On your own POs, the useful measure is how many lines fall under your confidence threshold or fail the arithmetic check, which is why a test on a sample of real orders matters more than a headline figure.
05Do I need a template per customer or supplier layout?
No. One template describes the fields of a document type, and the model finds them on any layout. You adjust the template when you want a new field or a different reading rule, not when a new customer sends a PO.
06Is the API synchronous?
No. The upload returns task IDs immediately; the result is fetched with fetch_tasks_results or pushed to your endpoint by a webhook when the document is done.
07Which files can I send?
PDF, JPEG and PNG: native PDFs, scans, faxes, photos and handwritten forms. Up to 150 pages per document, 300 MB per PDF and 10 MB per image, one file per request.
08How much does it cost?
One credit per page. An account starts with 20 free credits; the Advanced plan is €199 per month excluding tax for 1,000 credits (€0.20 per page) and the Pro plan brings it to €0.16 per page.
Sources
- Koncile API documentation: file uploading, task retrieval, webhooks, API status codes and rate limits (read on 3 November 2026).
- REST API for Oracle Fusion Cloud Procurement, purchase requisitions, Oracle (read on 3 November 2026).
- purchaseOrder resource type, Microsoft Learn, Business Central API v2.0 (read on 3 November 2026).
- Purchase order OCR API, Mindee product page (read on 3 November 2026).
Get an API key and parse your own POs
Create an account, send a few real purchase orders through the API, the scanned and handwritten ones included, and run the line check on what comes back. No card, no call.
Create a Koncile account, 20 free creditsTalk to an expert
20 free credits, no credit card. For professional use only.