Files and intake
Process an invoice email into a spreadsheet.
Capture invoice mail, store the source record, and append extracted invoice fields to a spreadsheet for finance review.
Token first
Make sure the agent has these scopes.
Create a new token or update the agent's current token before trying the calls below.
Required token scopes
email:read
files:read
files:write
workflows:write
work_routes:write
Outcome
What this gives you.
Invoice details become structured rows with source-message provenance instead of another manual data-entry step.
Use when
The operational shape.
- Vendor invoices arrive by email and should feed an invoice register or finance sheet.
- Your app or parser already has invoice fields and needs to write them into Gent's spreadsheet file.
- Invoice details are present in the message text and can be extracted by an workflow rule with LLM consent enabled.
API sequence
The calls to make.
01
Create the invoice register
POST/v1/files/
Create a spreadsheet file with persistent instructions for the invoice fields finance cares about.
Default example
Use this as the default shape for this step.
{
"name": "Vendor invoice register",
"file_type": "spreadsheet",
"scope": "inbox",
"inbox_id": "inb_finance",
"instructions": "Track vendor name, invoice number, invoice date, due date, amount, currency, payment terms, purchase order, and review status."
}
02
Append extracted invoice fields
POST/v1/files/{file_id}/rows/
Use this direct write when your app, parser, or operator has already extracted the invoice values.
Default example
Use direct row append when your parser, form workflow, or operator already has the invoice values. This path does not require Gent to parse the attachment.
{
"source_message_id": "msg_123",
"rows": [
{
"vendor": "Acme Supply",
"invoice_number": "INV-1042",
"invoice_date": "2026-06-14",
"due_date": "2026-07-14",
"amount": "980.00",
"currency": "USD",
"payment_terms": "Net 30",
"purchase_order": "PO-7731",
"review_status": "needs_review"
}
]
}
Minimal register row
Use this when you only need the fields required for reconciliation or export.
{
"source_message_id": "msg_123",
"rows": [
{
"vendor": "Acme Supply",
"invoice_number": "INV-1042",
"amount": "980.00",
"currency": "USD",
"review_status": "needs_review"
}
]
}
Multi-line invoice summary
Use this when your upstream parser returns useful line totals but you still want one spreadsheet row per invoice.
{
"source_message_id": "msg_123",
"rows": [
{
"vendor": "Acme Supply",
"invoice_number": "INV-1042",
"amount": "980.00",
"currency": "USD",
"line_items_summary": "Printer paper: 12 cases; Toner: 4 cartridges",
"review_status": "needs_review"
}
]
}
03
Automate rows from extracted fields
POST/v1/workflows/
Extract invoice fields, map them to spreadsheet columns, then append a row when required fields pass validation.
Default example
Field mapping is decided before activation. Runtime applies the saved mapping; if required fields are missing or uncertain, the workflow follows the configured review behavior.
{
"name": "Extract invoice rows from finance mail",
"trigger": "email_received",
"conditions": [
{"field": "to_address", "op": "eq", "value": "invoices@mail.example.com"},
{"op": "ai", "value": "The message text contains invoice details or a payment request."}
],
"writes": [
{
"source": {
"from": "trigger.attachment",
"extract": {"task": "extract_invoice", "engine": "ocr+llm"},
"map": {
"mode": "auto",
"fallback": {
"Vendor": "vendor_name",
"Invoice #": "invoice_number",
"Amount": "total_amount",
"Currency": "currency",
"Due Date": "due_date"
}
}
},
"target": {"type": "file.spreadsheet.rows", "file_id": "file_invoice_register"},
"contract": {"required": ["Vendor", "Invoice #", "Amount"]},
"policy": {"on_missing": "hold_for_review", "on_invalid": "hold_for_review"}
}
]
}
Webhook extraction handoff
Use this when attachment parsing happens in your own service and Gent should preserve the source message while your service appends the row.
{
"name": "Send invoice attachments to parser",
"trigger": "email_received",
"conditions": [
{"field": "to_address", "op": "eq", "value": "invoices@mail.example.com"},
{"field": "has_attachments", "op": "eq", "value": true}
],
"writes": [
{
"source": {"from": "event.payload"},
"target": {"type": "webhook", "url": "https://example.com/webhooks/invoice-parser", "event_type": "workflow.invoice_candidate"}
}
]
}
04
Route exceptions for review
POST/v1/work-routes/
Send missing, high-value, or exception invoices to finance before payment or downstream sync.
Default example
Use a route when missing fields, high amounts, or vendor exceptions should be approved before payment or sync.
{
"creator_inbox_id": "inb_finance",
"title": "Review invoice INV-1042",
"request_type": "approval",
"routing_mode": "parallel",
"completion": "required",
"failure_mode": "block",
"due_at": "2026-06-18T12:00:00Z",
"start": true,
"source": {
"type": "email",
"message_id": "msg_123",
"thread_id": "thr_123",
"subject": "Invoice INV-1042"
},
"recipients": [
{"kind": "email", "email": "finance@example.com"}
]
}
Controls
Review points.
- No new Gent feature is needed when invoice fields are supplied directly to the rows endpoint.
- Attachment-only PDF or image invoices need an extraction/OCR step before this can be fully automatic; until that lands, extract externally and append rows directly.
Related