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
| Field | Type | Description |
|---|---|---|
sourceRequired | object | The document: {data} as base64, or {asset_id} returned by doc.render_*. |
end_user_id | string | Which of your end users an asset_id belongs to; must match the one it was rendered for. |
schemaRequired | object | Fields 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"}]}. |
validations | array of string | Extra checks as expression strings, e.g. "subtotal + tax == total". Added to the built-in defaults; field names refer to the schema. |
mode | string | auto | fast | accurate, as for doc.extract_text. |
include_confidence | boolean | Also 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_llm | boolean | Allow the paid fallback for fields the zero-cost pass could not fill. |
Output fields
The fields in data when status is success.
| Field | Type | Description |
|---|---|---|
fields | object | |
validations | array of object | |
needs_review | boolean | |
review_fields | array of string | |
review_reasons | array of string | |
doc_kind | string | |
engine_used | string | |
layout_source | string | |
cost_hint | object | |
calibration | object | Only with include_confidence. |
unfilled_fields | array of string | |
low_confidence_fields | array of string | Only with include_confidence. A hint, lowest first: fields with confidence below 0.80 or none. Every field is still confirmed. |
untrusted | boolean | |
extraction_id | string | |
review | object | The 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())// Node.js 18 or newer, in an ES module.
const response = await fetch("https://toolsprimitives.uk/v1/tools/doc.extract_fields/invoke", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HEELO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
input: {
"source": {
"asset_id": "ASSET_ID"
},
"schema": {
"invoice_number": "string",
"total": "money",
"due_date": "date"
}
},
}),
signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());