Skip to content

Docs / All tools / Loop III: Assistant

doc.extract_fields

Extract fields such as invoice numbers, dates, amounts, and line items. Return the page and location of each value, and check the arithmetic.

25 credits. Per document. 0 when no field is found.

Example prompt

Send this to your AI app when Heelo is connected:

Extract the invoice number, total and due date from this PDF

Input fields

FieldTypeDescription
sourceRequiredobjectThe document: {data} as base64, or {asset_id} returned by doc.render_*.
end_user_idstringWhich of your end users an asset_id belongs to; must match the one it was rendered for.
schemaRequiredobjectFields to extract, as name -> type. Types: string, money, date, number, integer, boolean. A repeated group is a one-element list of an object, e.g. {"line_items": [{"desc": "string", "qty": "number", "amount": "money"}]}.
validationsarray of stringExtra checks as expression strings, e.g. "subtotal + tax == total". Added to the built-in defaults; field names refer to the schema.
modestringauto | fast | accurate, as for doc.extract_text.
include_confidencebooleanAlso return each field's confidence score, low_confidence_fields and calibration. Off by default: a score from label rules does not say if a value is right; compare the values with the document.
allow_llmbooleanAllow the paid fallback for fields the zero-cost pass could not fill.

Output fields

The fields in data when status is success.

FieldTypeDescription
fieldsobject
validationsarray of object
needs_reviewboolean
review_fieldsarray of string
review_reasonsarray of string
doc_kindstring
engine_usedstring
layout_sourcestring
cost_hintobject
calibrationobjectOnly with include_confidence.
unfilled_fieldsarray of string
low_confidence_fieldsarray of stringOnly with include_confidence. A hint, lowest first: fields with confidence below 0.80 or none. Every field is still confirmed.
untrustedboolean
extraction_idstring
reviewobjectThe review record this extraction opened (decide it with doc.review_decide; a write names it as review_id). Null when records are off for the caller.

Code

The call with the input fields that the tool needs. Replace each word in capitals, such as ASSET_ID. Set HEELO_API_KEY to your API key.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/doc.extract_fields/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {
        "source": {"asset_id": "ASSET_ID"},
        "schema": {"invoice_number": "string", "total": "money", "due_date": "date"},
    }},
    timeout=120,
)
response.raise_for_status()
print(response.json())