Import Data Guidelines

A complete guide to importing transactions, vendors, users, and banks — including file formats, required fields, and AI extraction.

Overview

How importing works from start to finish

The Import Data tool lets you bring large amounts of information into the system at once — instead of entering records one by one. You can import transactions to create payment batches, vendors to set up payees, users to onboard your team, or bank configurations to connect financial institutions.

Importing works in three steps: Upload your file, Preview how it will be processed (and catch any errors before anything is saved), then Confirm to apply the changes.

Upload File

Choose your CSV, Excel, JSON, XML, PDF, or image file

Preview

Review matched fields and catch errors before saving

Confirm

Apply the import — records are created or updated

File Formats

Supported formats and when to use each one

Download a template from the Import page to get a pre-formatted file with sample data and the correct column names already filled in.

CSV — Comma-Separated Values

Best for spreadsheet exports from accounting systems

Recommended

A plain-text file where each row is a record and columns are separated by commas. The first row must be the header row with column names. Exported directly from Excel, QuickBooks, or any accounting software.

csv — transaction example

payee_name,amount,transaction_date,vendor_code,memo
Acme Corp,1500.00,2026-05-15,ACME-001,Q1 consulting
Riverside Printing,250.00,2026-05-15,,May flyers
City Utilities,425.50,2026-05-14,,Electric bill

Column names are flexible — common alternatives are recognized automatically
Dollar signs and commas in amounts are stripped automatically
Empty optional fields are fine — just leave them blank

Excel (.xlsx)

Native Excel workbook format

Works exactly like CSV but as a native Excel file. The first row of the first worksheet is treated as the header row. Other sheets in the workbook are ignored. Column names and data handling work identically to CSV.

Use the Download Template button on the Import page to get an Excel template with color-coded required fields (blue) and optional fields (gray), plus an Instructions sheet.

JSON

For API exports and developer-friendly formats

JSON files can be either a top-level array of objects, or an object with a wrapper key containing the array. Both flat and wrapped formats are accepted.

json — flat array

[
  {
    "payee_name": "Acme Corp",
    "amount": 1500.00,
    "transaction_date": "2026-05-15",
    "vendor_code": "ACME-001",
    "memo": "Q1 consulting"
  },
  {
    "payee_name": "Riverside Printing",
    "amount": 250.00,
    "transaction_date": "2026-05-15"
  }
]

json — wrapped object (also accepted)

{
  "data": [
    { "payee_name": "Acme Corp", "amount": 1500.00, "transaction_date": "2026-05-15" }
  ]
}

Accepted wrapper keys: data, items, records, transactions, rows

XML

For ERP and enterprise system exports

XML files exported from ERP systems (SAP, Oracle, etc.) are supported. The system looks for repeated record elements within a root container.

xml — transaction example

<?xml version="1.0" encoding="UTF-8"?>
<transactions>
  <transaction>
    <payee_name>Acme Corp</payee_name>
    <amount>1500.00</amount>
    <transaction_date>2026-05-15</transaction_date>
    <vendor_code>ACME-001</vendor_code>
    <memo>Q1 consulting</memo>
  </transaction>
  <transaction>
    <payee_name>Riverside Printing</payee_name>
    <amount>250.00</amount>
    <transaction_date>2026-05-15</transaction_date>
  </transaction>
</transactions>

PDF & Images (JPG, PNG)

Transaction imports only — uses AI extraction

AI-Powered

Transaction imports also accept PDF files and images. The AI reads the document — whether it's an image of a check, check register report, or a payment summary — and extracts the transaction data automatically. No column mapping required, but make sure the document contains the Payee Name, Amount, and Date.

AI extraction is best-effort. Always review the Preview screen carefully before confirming a PDF or image import. Complex layouts or poor scan quality may reduce accuracy.

Transaction Import

Create payment batches from your check run or payment file

Transaction imports create a payment batch ready for review and approval. Each row in your file becomes one payment. The system matches each payee name to a vendor in your account — if no match is found, the row is flagged in the Preview screen.

Column names are flexible. company_name, vendor_name, and payee are all accepted in place of payee_name. Similarly, check_date and date are accepted for transaction_date. The system normalizes them automatically.

Field Name	Required	Description	Example
`payee_name`	✱ Required	The name of the company or person you are paying. This becomes the vendor match during import. Also accepted: payee, vendor_name, company_name, company	`Acme Corp`
`amount`	✱ Required	Payment amount in dollars. Commas and dollar signs are stripped automatically. Also accepted: payment_amount, check_amount, total	`1500.00`
`transaction_date`	✱ Required	Date of the payment. ISO format (YYYY-MM-DD) recommended. Also accepted: date, check_date, payment_date, effective_date	`2026-05-15`
`vendor_code`	Optional	Your internal vendor code. Speeds up vendor matching when provided. Also accepted: code, vcode, payee_code	`ACME-001`
`check_number`	Optional	Check or wire reference number for your records.	`10042`
`reference_number`	Optional	Invoice or external reference number. Also accepted: reference, ref, invoice, invoice_number	`INV-2026-0099`
`memo`	Optional	Free-text memo or description for the payment. Also accepted: description, note, notes, comment	`Q1 consulting services`

Vendor Import

Bulk-create or update your vendor / payee master list

Vendor imports set up the payees your organization sends money to. Only name and payment_type are required — banking details can be collected later via an automated bank-info request sent directly to the vendor's contact email.

Include at least one contact (name + email) so the system can automatically send a bank information request to vendors who don't have routing and account numbers yet.

Field Name	Required	Description	Example
`name`	✱ Required	Legal vendor or payee name.	`Acme Corporation`
`payment_type`	✱ Required	Default payment method. Must be one of the supported values. Accepted: ACH, FedNow, RTP, RequestForCheck	`ACH`
`code`	Optional	Your unique internal vendor code. Used to match vendors on future imports.	`ACME-001`
`address_line1`	Optional	Street address.	`123 Main St`
`address_line2`	Optional	Suite, floor, or department.	`Suite 400`
`address_city_state_zip`	Optional	City, state, and ZIP code.	`Austin, TX 78701`
`routing_number`	Optional	Bank routing number (ABA, 9 digits). Collected via bank-info request if not provided.	`021000021`
`account_number`	Optional	Bank account number. Encrypted at rest.	`123456789`
`account_type`	Optional	Checking or Savings.	`Checking`
`contact1_name`	Optional	Primary contact full name (used for bank info requests).	`Jane Smith`
`contact1_email`	Optional	Primary contact email address.	`jane@acme.com`
`contact1_mobile_phone`	Optional	Primary contact mobile phone.	`512-555-0100`
`contact1_work_phone`	Optional	Primary contact work phone.	`512-555-0101`
`contact2_name`	Optional	Secondary contact full name.	`Bob Jones`
`contact2_email`	Optional	Secondary contact email address.	`bob@acme.com`
`contact2_mobile_phone`	Optional	Secondary contact mobile phone.	`512-555-0102`
`contact2_work_phone`	Optional	Secondary contact work phone.	`512-555-0103`
`status`	Optional	Vendor status at import time. Accepted: Active, Hold, Inactive, New, NeedBankInfo, WaitingApproval	`Active`

Payment Type values

ACH — Standard ACH bank transfer (1–3 business days)
FedNow — FedNow instant payment (seconds, 24/7)
RTP — The Clearing House Real-Time Payment
RequestForCheck — System mails a physical check on your behalf

User Import

Onboard your team members with the right roles

User imports add team members to the system. Each user receives a welcome email with instructions to set their password. Role assignment determines what actions each user can take.

Field Name	Required	Description	Example
`email`	✱ Required	User's email address. Used for login and notifications. Must be unique.	`jane.smith@company.com`
`name`	✱ Required	User's full display name.	`Jane Smith`
`role`	✱ Required	System role that controls permissions. Accepted: Admin, Approver, Processor	`Approver`
`phone`	Optional	Mobile phone number for SMS notifications.	`512-555-0100`
`department`	Optional	Department or team for organizational grouping.	`Finance`
`title`	Optional	Job title.	`CFO`

Role permissions

AdminFull access — manage users, vendors, banks, approve payments

ApproverReview and approve/reject payment batches

ProcessorCreate batches and import transactions; cannot approve their own batches

Bank Configuration Import

Connect originating financial institutions

Bank imports configure the financial institutions that originate your ACH and payment files. Each bank requires at minimum a name, ODFI routing number, and transmission method. SFTP connection details are required when the transmission method is SFTP.

Bank imports require Admin role. Incorrect routing numbers or SFTP credentials can prevent payments from being delivered. Double-check with your bank before importing.

Field Name	Required	Description	Example
`name`	✱ Required	Name of the bank or financial institution.	`First National Bank`
`odfi_routing`	✱ Required	ODFI routing number (9 digits). This is the originating bank's ABA number.	`021000021`
`transmission_method`	✱ Required	How ACH files are delivered to the bank. Accepted: SFTP, Manual, API	`SFTP`
`sftp_host`	Optional	SFTP server hostname.	`sftp.firstnational.com`
`sftp_port`	Optional	SFTP port (default 22).	`22`
`sftp_username`	Optional	SFTP login username.	`ach_upload`
`sftp_remote_path`	Optional	Remote directory path for file uploads.	`/ach/incoming`
`company_id`	Optional	ACH Company ID assigned by the bank (up to 10 characters).	`1234567890`
`company_name`	Optional	ACH Company Name as it appears on NACHA files (up to 16 characters).	`ACME CORP`
`default_payment_type`	Optional	Default payment rail for this bank.	`ACH`

AI Extraction

How the system reads PDFs, images, and unstructured files

When you upload a PDF or image file (JPG or PNG) for a transaction import, the system uses AI to read and extract payment data automatically — no manual column mapping needed.

What it can read

•Check run summary reports
•Scanned payment vouchers
•Invoice lists and remittance advice
•Bank-generated payment summaries
•Screenshots of spreadsheets
•Multi-page PDFs

Limitations to be aware of

•Poor scan quality reduces accuracy
•Handwritten documents may not extract correctly
•Very large PDFs may time out
•Totals/subtotal rows may be included — review carefully
•Always verify the Preview screen before confirming

How it works, step by step

1
You upload a PDF or image file on the Import page.
2
The system first tries to extract text directly from the PDF. If the file is a scanned image or the text extraction doesn't find transactions, AI vision is used to visually read the document.
3
The AI identifies rows that look like payment transactions — payee name, amount, and date — and converts them to structured data.
4
The Preview screen shows every extracted row. Rows the system is uncertain about are flagged. You can review and remove any incorrect rows before confirming.
5
Only after you click Confirm are any records created in the system.

AI extraction is also used as a fallback for CSV and Excel files when the column names don't match any known format. In that case, the AI reads the header names and maps them to the correct fields automatically.

Tips & Troubleshooting

Common issues and how to resolve them

My file uploaded but shows 0 transactions

Check that the required columns (payee_name, amount, transaction_date) are present and spelled correctly. Download the template to see the expected column names. Also confirm the file has at least one data row below the header.

Amounts are importing as 0 or being skipped

Make sure amounts are numbers (not text). Currency symbols and commas are stripped automatically, but cells formatted as text in Excel may not parse correctly. Re-format the column as Number in Excel before exporting.

Vendors are showing as 'Not matched' in the preview

The system matches payee names to your vendor list by name similarity. If the name in the file is different from the vendor name in the system, it won't match. You can still confirm the import — unmatched transactions are imported with the payee name as-is and can be linked later. Providing a vendor_code in your file improves match accuracy significantly.

My Excel file isn't being read correctly

Make sure the data starts in the first row of the first worksheet and that row one is the header row. Remove any merged cells, title rows above the headers, or decorative formatting. Use the Download Template button as a starting point.

PDF extraction missed some rows

For best results, use PDFs with selectable text rather than scanned images. If extraction is incomplete, consider exporting to CSV or Excel from the source system instead. You can also add missing transactions manually after the batch is created.

I'm getting a 'missing required fields' error

The file must include payee_name (or an alias like company_name), amount, and transaction_date for transactions. For vendors, name and payment_type are required. Check the field tables above for all required fields and accepted aliases.

The import succeeded but some records were skipped

The result screen shows a count of skipped rows. Common reasons: amount was zero or negative, payee name was blank, or a duplicate record was detected. Skipped rows are listed in the result details.

What file size is supported?

Files up to 10 MB are supported. For very large files, split them into smaller batches of 500–1,000 rows each for best performance.

Still having trouble? Go back to Import and use the Download Template button to start from a correctly formatted file.