Mapping File

The mapping file is a YAML file passed with --map. It tells the CLI which CSV columns to read and which defaults to apply.

Minimal Mapping

columns:
  vatId: "VatId"

defaults:
  checkType: standard

columns.vatId is required. The check type is also required, either in YAML or on the command line.

Full Example

columns:
  vatId: "VatId"
  name: "CompanyName"
  street: "Street"
  zip: "PostalCode"
  city: "City"

customColumns:
  customer_number: "CustomerNumber"
  cost_center: "CostCenter"

input:
  delimiter: ";"
  encoding: "utf-8"
  hasHeader: true
  skipRows: 0
  quoteChar: "\""
  trimWhitespace: true

output:
  delimiter: ";"
  encoding: "utf-8"
  bom: true
  columns:
    - row
    - customer_number
    - vat_id
    - vat_id_status
    - checked_at

defaults:
  checkType: standard
  retryDuration: None
  pdf: false
  sign: false
  transliteration: false
  notify: false
  sendPdfByEmail: false

filter:
  skipEmptyVatId: true

folder:
  pattern: "*.csv"
  minAge: 0
  onDuplicate: skip
  retry: false

Top-Level Keys

Key	Type	Default	Description
columns	Object	empty	API validation field mappings.
customColumns	Object	empty	Local passthrough columns copied to the result CSV.
input	Object	see below	Input CSV parsing options.
output	Object	see below	Result CSV writing options.
defaults	Object	see below	Default check and API options.
filter	Object	see below	Row skip options.
folder	Object	see below	Folder mode options.

columns

Key	Type	Default	Description
vatId	String	required	Input column containing the VAT ID.
name	String	not set	Company name column.
street	String	not set	Street column.
zip	String	not set	Postal code column.
city	String	not set	City column.

Use header names when the CSV has a header. Use 1-based column indexes when --no-header or input.hasHeader: false is used.

customColumns

customColumns maps result CSV column names to input CSV columns.

customColumns:
  customer_number: "CustomerNumber"

These values are copied into the result CSV. They are not sent to the API and do not affect resume hashes.

Custom output names cannot be empty and cannot conflict with reserved result columns such as vat_id_status.

input

Key	Type	Default	Description
delimiter	String	auto-detected	Input CSV delimiter. If not configured by CLI or YAML, the CLI auto-detects it.
encoding	String	utf-8	Supported values: utf-8, windows-1252, iso-8859-1.
hasHeader	Boolean	true	Whether the CSV has a header row.
skipRows	Number	0	Rows to skip before the header or records.
quoteChar	Single character	"	Quote character used by the CSV parser.
trimWhitespace	Boolean	true	Trim whitespace around parsed fields.

output

Key	Type	Default	Description
delimiter	String	;	Result CSV delimiter.
encoding	String	utf-8	Supported values: utf-8, windows-1252, iso-8859-1.
bom	Boolean	true	Write a BOM for the output encoding.
columns	List	default result columns	Select result CSV columns or shortcuts.

defaults

Key	Type	Default	Description
checkType	standard or qualified	not set	Default check type. Required unless set by CLI option.
transliteration	Boolean	false	Enable transliteration.
pdf	Boolean	false	Request PDF output.
sign	Boolean	false	Digitally sign the PDF. Requires PDF output.
pdfDir	String	not set	Folder for saved PDFs.
pdfTimestamp	Boolean	false	Add timestamp to PDF file names.
companyVatId	String	not set	Own VAT ID used for validation.
notify	Boolean	false	Ask the API to send a notification email.
sendPdfByEmail	Boolean	false	Ask the API to send the PDF by email. Requires PDF output.
retryDuration	Duration	None	None, OneHour, TwoHours, FourHours, EightHours, TwentyFourHours.

filter

Key	Type	Default	Description
skipEmptyVatId	Boolean	true	Skip rows where the VAT ID is empty.
skipPattern	Regex string	not set	Skip rows where the VAT ID matches the regex.

Skipped rows are written to the result CSV with status SKIPPED.

folder

Key	Type	Default	Description
pattern	Glob	*.csv	Files selected from the folder root.
minAge	Number	0	Minimum file age in seconds before processing.
onDuplicate	skip, overwrite, rename	skip	Duplicate file handling for folder mode moves. skip keeps the existing destination, overwrite replaces it, and rename keeps both files with a timestamp.
retry	Boolean	false	Move failed CSV files from error back to the inbox for another attempt. Retried files start a new validation operation.
cleanupDoneAfterDays	Number	not set	Delete old files and state files from done.