Skip to main content
Every file ingested through the SFTP channel is an Excel workbook (.xlsx) with the same physical layout, regardless of category. This page is the authoritative reference for that layout: row structure, header matching, cell types, and the formatting mistakes that account for nearly all rejected rows.

​
File format

  • .xlsx only — the Office Open XML format. Legacy .xls and plain CSV files cannot be parsed by the workbook readers; re-save them as .xlsx.
  • First sheet only — the ingester reads the workbook’s first sheet and ignores all others. If your data lives on another tab, move it to position one.

​
Row structure

Row 1 is reserved for a human-readable banner (workbook title, version, instructions). It is never parsed — but it must exist. Headers in row 1 with data starting at row 2 is the single most common formatting error: the ingester will read your headers as a banner and your first data row as headers.
A workbook with no header row at all (fewer than two rows) is rejected outright.

​
Header normalization

Column headers in row 2 are normalized before matching:
  1. Leading and trailing whitespace is stripped.
  2. The text is converted to lowercase.
  3. Every run of non-alphanumeric characters (spaces, punctuation, symbols — however many in a row) is collapsed to a single underscore (_).
  4. Leading and trailing underscores are stripped.
This means the following headers are all equivalent: Fields are matched by normalized header name, never by position — you can reorder columns freely. Three consequences of name-based matching:
  • Unknown headers are ignored with a warning. Extra columns don’t break ingestion; they’re simply skipped. But note this cuts both ways — a misspelled required header is an unknown header, and the workbook will be rejected for the missing required one.
  • Duplicate headers reject the whole workbook. Two columns that normalize to the same field (e.g. First Name and first_name) are ambiguous; the error names both column positions.
  • Missing required headers reject the whole workbook. The error lists every missing header. This is a file-level failure — fix the header row and re-upload. See Upload Categories for which headers each category requires.
“Required column” means the header must be present in row 2. Whether an individual cell may be blank is a per-field rule — see the required/optional markers in the category reference.

​
Cell types and formats

​
Rows that are skipped on purpose

Two kinds of rows are silently skipped — they don’t count as errors:
  • Example rows. Rows whose identifier column starts with Ex. are treated as template examples. The identifier column depends on the category: File # for data workbooks, Subnetwork # for subnetworks, and the policy-number column (KYC Policy / KYB Policy) for policy workbooks. Use these to keep in-workbook guidance without affecting ingestion.
  • Blank rows. Rows missing their identifying values entirely — a data row with no file number and no subnetwork name, a subnetwork row with no subnetwork name, a policy row with no policy name — are treated as empty padding and skipped.

​
Formula cells

Workbooks are read using cached formula results, not live evaluation. If a cell contains a formula that has never been calculated and saved (typical when the file was generated programmatically and never opened in Excel), the ingester detects the uncached formula and rejects that row, listing the offending column names in the error — it will not silently treat the cell as blank. To avoid this: open and save the workbook in Excel with calculation enabled, or write literal values (or pre-computed cached values) when generating files programmatically.

​
Common mistakes

Header problems are structural — without the right headers the ingester can’t trust its reading of any row, so it fails fast with a list of what’s missing or duplicated. Cell-level problems are local — each data row is parsed and ingested independently, so a bad date in row 17 produces one row error while rows 3–16 and 18+ proceed normally.
The dashboard’s uploads view reports per-row outcomes, including the spreadsheet row number (counted as Excel displays it, banner and header included) and a human-readable message naming the offending column. Fix the rows and re-upload under a new filename — data rows upsert on natural keys, so corrected rows update rather than duplicate.
For the exact columns each category expects, continue to Upload Categories.