POST/v1/intelligent/parse

Parse natural language text into an EN 16931 invoice (AI)

Extract structured invoice data from free-form text (email body, chat message, OCR output, supplier description) and return an EN 16931 invoice JSON that is schema-identical to the `POST /v1/convert` input. If `ready_to_convert` is `true`, the caller can forward the `invoice` object directly to `/v1/convert` to obtain a compliant Peppol/XRechnung/Factur-X document. **Privacy pipeline:** all PII (names, companies, VAT IDs, IBANs, emails, phones, addresses) is anonymized via Microsoft Presidio + multilingual spaCy NER BEFORE the text leaves EU infrastructure. The exact text sent to the AI is returned in `anonymized_text` so the caller can audit it. After the model responds, placeholders are mapped back to the original values; if the mapping fails (model mangled a placeholder), the API returns `502 ANONYMIZATION_INTEGRITY_ERROR` rather than shipping corrupted data. **Strict-mode guarantee:** if the anonymization post-pass detects residual PII (typically a VAT ID, IBAN, email, or phone that slipped past NER), the request is aborted with `422 UNANONYMIZED_PII_DETECTED` **before** any AI call. The response lists the coarse categories that were detected so the caller knows what to redact. No raw PII values are included in the error body. **Quality signals:** `field_status` reports per-field extraction state (`extracted`, `inferred`, `default`, `missing`, `invalid`), `missing_fields` lists required fields that could not be extracted, and `confidence` gives an overall 0.0-1.0 score. **Legal notice:** AI-generated output. Always verify before submission. Required scope: `einvoice:parse`. Counted against your AI Parse quota.

Authentication

Requires API key via X-API-Key header.

Request body

textstringrequired

Natural language text describing an invoice

minLen 10 · maxLen 10000

contextanyoptional

Optional context hints

one of:
option 1:
seller_countryanyoptional

ISO 3166-1 alpha-2 country of the seller

one of:
option 1:
string
option 2:
null
buyer_countryanyoptional

ISO 3166-1 alpha-2 country of the buyer

one of:
option 1:
string
option 2:
null
currencyanyoptional

Expected currency code (ISO 4217)

one of:
option 1:
string
option 2:
null
languageanyoptional

Language of the input text (ISO 639-1)

one of:
option 1:
string
option 2:
null
option 2:
null

Example request

curl
curl -X POST \
  "https://einvoice.aethar.dev/api/v1/intelligent/parse" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"string"}'

Responses

200Successful Response
dataParseResultrequired

Structured result of AI-powered invoice parsing.

invoiceInvoice-Outputrequired

EN 16931 invoice — canonical JSON representation. This model is the single source of truth for invoice data flowing through the API. It is used as input to /v1/convert and as output from /v1/intelligent/parse (schema idempotency).

invoice_numberstringrequired

BT-1 Invoice number

maxLen 64

issue_datestring (date)required

BT-2 Invoice issue date

type_codestringoptional

BT-3 Invoice type code (UNTDID 1001). 380=Invoice

maxLen 4 · default "380"

currency_codestringrequired

BT-5 Invoice currency code (ISO 4217)

minLen 3 · maxLen 3

due_dateanyoptional

BT-9 Payment due date

one of:
option 1:
string (date)
option 2:
null
buyer_referenceanyoptional

BT-10 Buyer reference (mandatory for XRechnung)

one of:
option 1:
string
option 2:
null
purchase_order_referenceanyoptional

BT-13 Purchase order reference

one of:
option 1:
string
option 2:
null
project_referenceanyoptional

BT-11 Project reference

one of:
option 1:
string
option 2:
null
contract_referenceanyoptional

BT-12 Contract reference

one of:
option 1:
string
option 2:
null
vat_accounting_currencyanyoptional

BT-6 VAT accounting currency

one of:
option 1:
string
option 2:
null
tax_point_dateanyoptional

BT-7 Value added tax point date

one of:
option 1:
string (date)
option 2:
null
noteanyoptional

BT-22 Invoice note

one of:
option 1:
string
option 2:
null
preceding_invoice_referenceanyoptional

BT-25 Preceding invoice reference

one of:
option 1:
string
option 2:
null
sellerPartyrequired

Seller (BG-4) or Buyer (BG-7) party.

namestringrequired

BT-27/BT-44 Party name

maxLen 256

addressAddressrequired

Postal address (BG-5 Seller / BG-8 Buyer / BG-15 Delivery).

streetstringrequired

BT-35/BT-50 Address line 1

maxLen 256

street2anyoptional

BT-36/BT-51 Address line 2

one of:
option 1:
string
option 2:
null
citystringrequired

BT-37/BT-52 City

maxLen 128

postal_codestringrequired

BT-38/BT-53 Post code

maxLen 16

country_subdivisionanyoptional

BT-39/BT-54 Country subdivision

one of:
option 1:
string
option 2:
null
country_codestringrequired

BT-40/BT-55 ISO 3166-1 alpha-2

minLen 2 · maxLen 2

vat_idanyoptional

BT-31/BT-48 VAT identifier

one of:
option 1:
string
option 2:
null
tax_registration_idanyoptional

BT-32 Tax registration ID

one of:
option 1:
string
option 2:
null
legal_registration_idanyoptional

BT-30/BT-47 Legal registration ID

one of:
option 1:
string
option 2:
null
identifieranyoptional

BT-29/BT-46 Party identifier

one of:
option 1:
string
option 2:
null
identifier_schemeanyoptional

BT-29-1/BT-46-1 Scheme ID

one of:
option 1:
string
option 2:
null
electronic_addressanyoptional

BT-34/BT-49 Electronic address

one of:
option 1:
schemestringrequired

Electronic Address Scheme (EAS), e.g. EM, 0088, 0184

maxLen 8

idstringrequired

Electronic address value

maxLen 256

option 2:
null
contactanyoptional

BG-6 Seller contact

one of:
option 1:
nameanyoptional

BT-41 Contact name

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
phoneanyoptional

BT-42 Contact telephone

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
emailanyoptional

BT-43 Contact email

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
option 2:
null
buyerPartyrequired

Seller (BG-4) or Buyer (BG-7) party.

namestringrequired

BT-27/BT-44 Party name

maxLen 256

addressAddressrequired

Postal address (BG-5 Seller / BG-8 Buyer / BG-15 Delivery).

streetstringrequired

BT-35/BT-50 Address line 1

maxLen 256

street2anyoptional

BT-36/BT-51 Address line 2

one of:
option 1:
string
option 2:
null
citystringrequired

BT-37/BT-52 City

maxLen 128

postal_codestringrequired

BT-38/BT-53 Post code

maxLen 16

country_subdivisionanyoptional

BT-39/BT-54 Country subdivision

one of:
option 1:
string
option 2:
null
country_codestringrequired

BT-40/BT-55 ISO 3166-1 alpha-2

minLen 2 · maxLen 2

vat_idanyoptional

BT-31/BT-48 VAT identifier

one of:
option 1:
string
option 2:
null
tax_registration_idanyoptional

BT-32 Tax registration ID

one of:
option 1:
string
option 2:
null
legal_registration_idanyoptional

BT-30/BT-47 Legal registration ID

one of:
option 1:
string
option 2:
null
identifieranyoptional

BT-29/BT-46 Party identifier

one of:
option 1:
string
option 2:
null
identifier_schemeanyoptional

BT-29-1/BT-46-1 Scheme ID

one of:
option 1:
string
option 2:
null
electronic_addressanyoptional

BT-34/BT-49 Electronic address

one of:
option 1:
schemestringrequired

Electronic Address Scheme (EAS), e.g. EM, 0088, 0184

maxLen 8

idstringrequired

Electronic address value

maxLen 256

option 2:
null
contactanyoptional

BG-6 Seller contact

one of:
option 1:
nameanyoptional

BT-41 Contact name

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
phoneanyoptional

BT-42 Contact telephone

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
emailanyoptional

BT-43 Contact email

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
option 2:
null
deliveryanyoptional

BG-13 Delivery information

one of:
option 1:
dateanyoptional

BT-72 Actual delivery date

one of:
option 1:
string (date)
option 2:
null
locationanyoptional
one of:
option 1:
nameanyoptional

BT-70 Deliver to party name

...(deeper nesting omitted)
addressanyoptional
...(deeper nesting omitted)
option 2:
null
option 2:
null
paymentanyoptional

BG-16 Payment instructions

one of:
option 1:
means_codestringrequired

BT-81 Payment means type code (UNTDID 4461)

maxLen 4

means_textanyoptional

BT-82 Payment means text

one of:
option 1:
string
option 2:
null
termsanyoptional

BT-20 Payment terms

one of:
option 1:
string
option 2:
null
bank_accountanyoptional

BG-17 Credit transfer

one of:
option 1:
ibananyoptional

BT-84 IBAN

...(deeper nesting omitted)
bicanyoptional

BT-86 BIC/SWIFT

...(deeper nesting omitted)
bank_nameanyoptional

Bank name (informational)

...(deeper nesting omitted)
account_nameanyoptional

BT-85 Account name

...(deeper nesting omitted)
option 2:
null
payment_idanyoptional

BT-83 Remittance information

one of:
option 1:
string
option 2:
null
option 2:
null
linesarray<InvoiceLine-Output>required

BG-25 Invoice lines (at least one)

minItems 1

array of InvoiceLine-Output
idstringrequired

BT-126 Invoice line identifier

maxLen 32

descriptionstringrequired

BT-153 Item name

maxLen 512

quantitystringrequired

BT-129 Invoiced quantity

pattern /^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

unitstringrequired

BT-130 Unit of measure (UN/ECE Rec 20)

maxLen 8

unit_pricestringrequired

BT-146 Item net price

pattern /^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

net_amountstringrequired

BT-131 Invoice line net amount

pattern /^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

vat_categorystringrequired

BT-151 VAT category code (UN/ECE 5305)

maxLen 4

vat_rateanyoptional

BT-152 VAT rate as percentage

one of:
option 1:
string
option 2:
null
item_classificationanyoptional

BT-158 Item classification

one of:
option 1:
codestringrequired

BT-158 Item classification identifier

maxLen 32

schemestringrequired

BT-158-1 Scheme identifier (e.g. STI, CPV)

maxLen 8

option 2:
null
noteanyoptional

BT-127 Invoice line note

one of:
option 1:
string
option 2:
null
order_line_referenceanyoptional

BT-132 Referenced purchase order line

one of:
option 1:
string
option 2:
null
allowance_amountanyoptional

BT-136 Invoice line allowance amount

one of:
option 1:
string
option 2:
null
charge_amountanyoptional

BT-141 Invoice line charge amount

one of:
option 1:
string
option 2:
null
allowancesanyoptional

BG-20/BG-21 Allowances and charges

one of:
option 1:
array of DocumentAllowanceCharge-Output
is_chargebooleanrequired

True = charge (BG-21), False = allowance (BG-20)

amountstringrequired

BT-92/BT-99 Amount

pattern /^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

vat_categorystringrequired

BT-95/BT-102 VAT category code

maxLen 4

vat_rateanyoptional

BT-96/BT-103 VAT rate

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
reasonanyoptional

BT-97/BT-104 Reason

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
reason_codeanyoptional

BT-98/BT-105 Reason code

one of:
option 1:
...(deeper nesting omitted)
option 2:
...(deeper nesting omitted)
option 2:
null
country_extensionsanyoptional

Country-specific fields

one of:
option 1:
itanyoptional
one of:
option 1:
codice_destinatariostringrequired

SDI recipient code

minLen 7 · maxLen 7

codice_fiscale_selleranyoptional

Seller Codice Fiscale

...(deeper nesting omitted)
codice_fiscale_buyeranyoptional

Buyer Codice Fiscale

...(deeper nesting omitted)
regime_fiscalestringoptional

Tax regime code

maxLen 4 · default "RF01"

tipo_documentostringoptional

Document type code

maxLen 4 · default "TD01"

option 2:
null
deanyoptional
one of:
option 1:
leitweg_idstringrequired

Leitweg-ID (BT-10 routing ID for German B2G)

maxLen 64

option 2:
null
planyoptional
one of:
option 1:
nip_sellerstringrequired

Seller NIP

maxLen 10

nip_buyeranyoptional

Buyer NIP

...(deeper nesting omitted)
gtu_codesanyoptional

GTU goods/services type codes

...(deeper nesting omitted)
split_paymentbooleanoptional

MPP split payment flag

default false

option 2:
null
esanyoptional
one of:
option 1:
nif_sellerstringrequired

Seller NIF

maxLen 16

face_oficina_contableanyoptional

FACe routing code

...(deeper nesting omitted)
face_organo_gestoranyoptional

FACe routing code

...(deeper nesting omitted)
face_unidad_tramitadoraanyoptional

FACe routing code

...(deeper nesting omitted)
option 2:
null
franyoptional
one of:
option 1:
siret_selleranyoptional

Seller SIRET

...(deeper nesting omitted)
siret_buyeranyoptional

Buyer SIRET

...(deeper nesting omitted)
service_codeanyoptional

Chorus Pro service code

...(deeper nesting omitted)
option 2:
null
option 2:
null
field_statusobjectrequired

Per-field extraction status (dot-notation keys, e.g. 'seller.name')

ready_to_convertbooleanrequired

True if all required fields are present and valid — safe to send to /v1/convert

missing_fieldsarray<string>optional

Required fields that could not be extracted

array of string
string
confidencenumberrequired

Overall parse confidence (0.0-1.0)

min 0 · max 1

legal_noticestringoptional

Legal disclaimer — always present

default "AI-generated. Verify before submission."

anonymized_textstringrequired

Exact text that was sent to the AI model after PII anonymization. Sensitive identifiers (names, companies, VAT IDs, IBANs, emails, phone numbers, addresses) are replaced with format-preserving placeholders before the text leaves EU infrastructure. Use this field to audit what the AI actually saw.

detected_entity_countsobjectoptional

Per-entity-type counts of anonymized items (PERSON, LOCATION, VAT_ID, IBAN_CODE, EMAIL_ADDRESS, PHONE_NUMBER, COMPANY_NAME, …). Values only — no PII.

metadataMetadataSchemarequired
sourcesarray<SourceSchema>optional
array of SourceSchema
namestringrequired

Data source name

urlanyoptional

URL to the source

one of:
option 1:
string
option 2:
null
request_idstringrequired

Unique request identifier

rate_limitanyoptional
one of:
option 1:
object
option 2:
null
400The AI could not identify invoice data in the provided text.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
401Missing or invalid API key.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
403API key lacks the required scope for this endpoint.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
422Residual PII detected after anonymization (strict mode). The request is aborted before any AI call; the caller must manually redact the flagged categories (e.g. `vat_id`, `iban`, `email`, `phone`) and retry.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
429Daily rate limit exceeded for this API key.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
500Unexpected server error. Includes a request_id for support.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
502PII deanonymization integrity check failed — response refused for safety.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null
503Upstream AI provider is unavailable or the feature is not configured.
errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:
option 1:
string
option 2:
null
doc_urlanyoptional

Link to full documentation for this error code

one of:
option 1:
string
option 2:
null
fieldanyoptional

Field that caused the error (if applicable)

one of:
option 1:
string
option 2:
null
errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:
option 1:
array of object
object
option 2:
null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →