POST/v1/intelligent/preview

Preview the anonymized text the AI would see (no AI call)

Run the full PII anonymization pipeline on the supplied text and return the scrubbed version — exactly what would be sent to the AI model if you called `POST /v1/intelligent/parse` with the same input. This endpoint does **not** call the AI model, so it incurs no inference cost and does not count against your AI Parse quota. Use it to verify which identifiers (names, companies, VAT IDs, IBANs, emails, phones, addresses) are detected and masked before committing to a paid parse. The anonymization pipeline uses Microsoft Presidio with multilingual spaCy NER plus custom recognizers for EU VAT IDs and company legal forms. Supported languages: `en`, `de`, `pl`, `fr`, `it`, `es`, `nl`. Pass `language` to force a specific pipeline; otherwise the service auto-detects from the text. **Strict-mode guarantee:** `/preview` mirrors `/parse` — if the anonymization post-pass finds residual PII, the request is rejected with `422 UNANONYMIZED_PII_DETECTED` listing the coarse categories that must be manually redacted before retry. No AI call is ever made from `/preview`. Required scope: `einvoice:parse`.

Authentication

Requires API key via X-API-Key header.

Request body

textstringrequired

Natural language text to preview anonymization for

minLen 1 · maxLen 10000

languageanyoptional

Optional ISO 639-1 language hint (en, de, pl, fr, it, es, nl)

one of:

option 1:

string

option 2:

null

Example request

curl

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

Responses

200Successful Response

dataPreviewResultrequired

Preview of what the AI model would see after anonymization.

anonymized_textstringrequired

Text with all detected PII replaced by format-preserving placeholders

detected_entity_countsobjectoptional

Per-entity-type counts (no PII values)

language_usedstringrequired

Language pipeline used for NER (auto-detected if not provided)

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

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

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). `/preview` aborts with the same code as `/parse`; no AI call is made. Manually redact the flagged categories (e.g. `vat_id`, `iban`, `email`, `phone`) and retry.

errorErrorDetailrequired

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

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

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 →