PurchaseOrderOCRbyKoncile

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.

The two meanings side by side.
ERP purchase order APIPurchase order OCR API (PO parser)
What goes inA JSON recordA PDF, scan, fax or photo of a PO
What comes outA PO created, updated or listed in the ERPHeader fields and line items as JSON, each value with a confidence score
Typical jobCreate a PO, post a goods receipt, close an orderOrder entry from customer POs, checking supplier confirmations, three way matching
ExamplesOracle Fusion Procurement REST, Business Central purchaseOrders, SAP S/4HANAKoncile, 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.

Specimen PO CP-7731. Amounts in US dollars. The last column is what the quantity times the unit price really gives.
LineSKU and descriptionQtyUoMUnit priceLine total printedQty x price
1HX-1020 Hex bolt M10 x 50, box of 10012BX18.40220.80220.80
2WS-0310 Flat washer M10, box of 2006, handwritten over 8BX7.9563.6047.70
3AN-2290 Wedge anchor 3/8 in, pack of 254PK31.60136.40126.40
Subtotal printed420.80394.90
Sales tax 8.25%34.72
Total printed455.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.80

Line 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-Timestamp

Customer 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

From the Koncile API documentation, read on 3 November 2026.
ItemLimitWhat happens past it
Pages per document150Split longer files before upload
File formatsPDF, JPEG, PNGSpreadsheets and EDI files are already structured: no OCR needed
File size300 MB per PDF, 10 MB per PNG or JPEGRejected
Files per upload request1413 error; for batches, send files one by one or use the presigned direct upload
Upload rate1 per second, bursts of 5, per API key429 with a Retry-After header, no credit used
Polling reads2 per second, bursts of 20Same 429 behavior
Usage limitsDaily and monthly caps set by an admin, plan page cap402 with a message that says which limit
Trailing slashEndpoints 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

Questions to ask any vendor, ours included.
QuestionWhy it mattersKoncile's answer
Are line items separate typed fields, in order?A blob of table text pushes the parsing back to youYes, one array per column, one entry per line
Is there a confidence score on every value?It is what lets clean lines skip reviewYes, 0 to 1 on each value
Can you change the fields without retraining?Each business reads a PO slightly differentlyYes, template edited in plain language
Asynchronous with signed webhooks?Polling at scale wastes calls and hits rate limitsYes, HMAC-SHA256 signature
Are limits and errors published?You will hit them in production, not in the demoYes: pages, sizes, rates, status codes
Is the price per page public, with a free test?Volume pricing on request makes the business case guessworkYes, 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

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.