Invoices CSV import API
invoices_v1
Import this template via API. Import accounts-receivable invoices from any CSV. Amounts parsed, due dates locale-detected, payment status enum-bounded.
30-second curl
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=invoices_v1" \ -F "file=@your_data.csv"
At a glance
- Pack
- Finance & Payments
- FHIR resource
- —
- Risk level
- medium
- Fields
- 7 (4 required, 0 validated)
Why it exists
Why this template?
The Invoices template is the canonical schema for accounts-receivable detail — the file an ERP export, an accounting-system dump, or a billing extract reduces to. Each row carries an invoice_number (required), a customer_id (required, the foreign key back to your CRM or ledger), an amount_due, a currency, a due_date parsed across locales, a status enum (paid / unpaid / overdue), and an optional tax_id for the counterparty. Finance and AR teams reach for it when migrating between accounting systems, when backfilling a warehouse with historical receivables for ageing analysis, and when feeding a dunning pipeline that chases overdue balances. It is `medium` risk because the row carries commercial counterparty and tax detail, so schema-only mode is the default ingress — raw invoice rows never leave the customer; only headers and clamped sample cells are processed to decide the mapping.
invoice_number, customer_id, amount_due, and currency are all required — an invoice without a counterparty or an amount is not an invoice. status lands in {paid, unpaid, overdue} or surfaces as an error in the dry-run. amount_due is number-typed and locale-tolerant (US "1,234.56", EU "1.234,56", Swiss "1'234.56"); due_date auto-detects ISO, US, and EU formats. tax_id is a free string because VAT-ID / Steuernummer / Partita IVA / NIF formats vary too widely to enum-bound. Hints cover DE / FR / IT / ES / EN so a multilingual ledger export does not escalate to the LLM.
Migration scenarios & common foreign headers
Migration scenarios for the Invoices template: porting an open-receivables ledger between accounting systems (Sage → Xero, DATEV → NetSuite) at fiscal close, backfilling a finance warehouse with years of invoices for AR-ageing and DSO analysis, feeding a dunning pipeline that escalates overdue balances, and consolidating receivables after a subsidiary acquisition. Foreign headers we routinely see: "Rechnungsnummer / Numéro de facture / Numero fattura / Número de factura / Kunde / Client / Cliente / Fälliger Betrag / Montant dû / Importo dovuto / Importe adeudado / Währung / Devise / Fälligkeitsdatum / Date d'échéance / Scadenza / Fecha de vencimiento / Status / Statut / Stato / Steuernummer / USt-ID / Numéro de TVA / Partita IVA / NIF". The cascade resolves all of these via the registered hints — no LLM call needed.
Canonical columns
Schema
The canonical column set, with the type each row carries, whether it is required, the field-level validators that fire on commit, and the multilingual header hints the cascade resolves against.
| Column | Type | Required | Validators | Hints |
|---|---|---|---|---|
| invoice_number | string | yes | — | rechnungsnummer · numéro de facture · numero fattura · invoice no · número de factura |
| customer_id | string | yes | — | kunde · client · cliente · customer |
| amount_due | number | yes | — | fälliger betrag · montant dû · importo dovuto · amount due · importe adeudado |
| currency | string | yes | — | währung · devise · valuta · moneda |
| due_date | date | — | — | fälligkeitsdatum · date d'échéance · scadenza · due date · fecha de vencimiento |
| status | enum | — | — | status · statut · stato · estado |
| tax_id | string | — | — | steuernummer · ust-id · numéro de tva · partita iva · tax id · nif |
The cascade
How AdaptivMapr maps your headers to this template
Five layers run in order, cheapest first. Layer 1 (Statistics) auto-accepts headers that have been mapped the same way across past uploads. Layer 2 (Heuristic) compares your header to the column name, the optional label, and every registered hint (DE / FR / IT / EN / ES) after a Unicode-and-punctuation-normalising pass. Layer 3 (Fuzzy) catches typos and reordered words. Layer 4 (Semantic) uses cached embeddings to catch the long tail of paraphrases. Layer 5 (LLM) only fires on genuinely ambiguous columns, constrained to the template’s allowed column set so it cannot invent a field. When a layer auto-accepts, the lower-cost layers below it never run — that is the cost lever.
REST · POST /v1/uploads
Pass the template_id; the cascade picks up the rest.
curl -X POST https://api.adaptivmapr.com/v1/uploads \ -H "Authorization: Bearer $ADAPTIVMAPR_API_KEY" \ -F "template=invoices_v1" \ -F "file=@your_data.csv"
The canonical template definition is read-only at GET /v1/templates/invoices_v1.
MCP · Cursor / Claude Desktop
Drop AdaptivMapr into your IDE. Schema-only calls are free and unlimited.
// In Cursor or Claude Desktop with the AdaptivMapr MCP server installed:
adaptivmapr.match_headers({
template: "invoices_v1",
headers: ["invoice_number", "customer_id", "amount_due", "currency"]
})MCP install instructions →Questions
FAQ — Invoices CSV import
Does the Invoices template deduplicate on invoice_number?
No. Deduplication is a downstream concern; the template guarantees a parseable invoice_number per row so your upsert key works. We surface duplicate numbers in the dry-run report so you can decide whether to skip, merge, or reject.
Can I extend the status enum (e.g. "partially_paid", "disputed")?
Yes — fork the template and edit enum_values. The canonical set is deliberately small (paid / unpaid / overdue) so cross-system AR reconciliation works without translation tables.
Is tax_id validated?
No — it is a free-text string because VAT-ID, Steuernummer, Partita IVA, and NIF formats differ per jurisdiction. Teams with strict downstream systems usually post-process it against a per-country validator.
How is invoice data protected during mapping?
Schema-only mode is the default: only headers and three clamped sample rows (≤80 chars each) are processed to decide the mapping. Full invoice rows never leave your environment unless you opt into full-data mode under an active subscription.