Appearance

Bulk uploading records (xlsx) ​

Recognito accepts entity records as .xlsx files. For more than a handful of rows, this is the standard path. CSV isn't supported today — you export from your source system, save as Excel, then upload.

This page covers the file format, the upload flow, and the common pitfalls.

File format ​

The accepted format is .xlsx only. CSV files aren't accepted today. The columns in your spreadsheet need to match the entity's columns by header name.

The first row is the header row. Subsequent rows are data.

.xlsx only — no CSV

This catches a lot of customers by surprise. If your source data is CSV, the workaround is to open it in Excel or Google Sheets and save as .xlsx before uploading. The file extension is what matters; the underlying data is the same.

Preparing the file ​

For a Vendors entity with columns vendorId, vendorName, vendorAccount, taxId:

| vendorId  | vendorName       | vendorAccount | taxId       |
|-----------|------------------|---------------|-------------|
| V-100     | Acme Supplies    | 10-1234567    | LT123456789 |
| V-101     | Beta Logistics   | 10-2345678    | LT234567890 |
| V-102     | Gamma Industries | 20-3456789    | LT345678901 |

Header row exactly matches the entity's column names. Data rows fill the columns; empty cells are allowed.

Column name matching ​

The header row must match the entity's column names. If your upload comes back with errors about unmatched columns, the most likely cause is a header-row typo. Cross-check by opening the entity's record view and comparing column names.

Extra columns ​

Columns in your upload that aren't in the entity are typically ignored (TBD on exact behavior — confirm in your upload before mass-loading). Missing columns leave the corresponding cells empty.

Data types ​

Entity columns have one of four types: text, number, date, or select. For range matching (Less Than, More Than, etc.) on number columns, make sure your spreadsheet doesn't introduce formatting like comma separators (1,234.56 vs 1234.56). Excel sometimes adds these silently; check the saved file.

The upload flow ​

  1. Open the entity in Settings → Mapping → Entities.
  2. Click Import.
  3. Pick your .xlsx file.
  4. Confirm.

The system processes the file. For larger files, processing can take seconds to minutes.

Validating before upload ​

Before uploading a large file, sanity-check:

  • Header row matches the entity's columns.
  • No accidental blank rows. Excel sometimes leaves trailing blank rows that get imported as empty entity rows.
  • No duplicate identifiers in columns used as Context for definitions. The top-row-wins rule means duplicates can produce non-deterministic behavior.
  • Correct delimiters and number formatting. Particularly for numeric range columns.

For mission-critical uploads (a vendor master with 1,000+ rows), upload to a test project first and verify a few lookups before pointing the production project at it.

After uploading ​

Once the upload finishes:

  • Verify the row count. Compare with the source data.
  • Spot-check a few rows. Open the entity's record view and pick a few rows you know — confirm the values landed in the right columns.
  • Test a definition that uses the entity. Run a sample document through a workflow that touches the entity and confirm the lookups fire as expected.

If anything looks off, the safest path is to delete the uploaded rows and re-upload a corrected file, rather than patching individual rows in the UI.

The .xlsx round-trip for updates ​

For entities that need periodic updates (vendor master changes monthly, GL chart changes quarterly), the typical workflow is to prepare the updated spreadsheet in Excel or Google Sheets — adding new rows, correcting existing rows, removing deprecated rows — then import it via Import.

This round-trip is the operational reality for customers with frequently-changing reference data. The .xlsx-only constraint can be tedious if your source system can't readily produce Excel files, but it's what the product offers today.

When the API is a better fit ​

If you update entities frequently from a programmatic source — an ERP nightly sync, a CRM feed — the entity-records API is more ergonomic than the .xlsx round-trip. Recognito exposes GET, POST, PUT, and DELETE on a project's entity records; the API key needs the entity-records scope.

Two things to know before you build on it:

  • Updates and deletes match by search_by, not by ID. They affect every record matching the criteria you send — there's no update-one-by-id path. Use a search key that's guaranteed unique, or you can change more rows than you meant to.
  • The read endpoint has no pagination. It returns every record in the entity in one response, so it won't scale to very large tables without care.

See the API Reference for the exact request and response shapes. For one-off or occasional loads, the .xlsx upload above is still the simpler path.

What's next ​