SFTP Import format

This page specifies every file your export sends to Monk. For how the integration works, see File integration (SFTP), and for how to connect and authenticate, see Connecting. If your ERP can’t produce these formats, talk to your Monk contact.

Folders and file names

	Monk-hosted SFTP	Your SFTP server
Where you upload	`/inbound`	The inbound folder you give Monk during setup
After processing	Monk removes the files from `/inbound`	Monk leaves the files where they are; your job removes them when it likes

Upload every file of a batch directly into the inbound folder, with no subfolders. Every file name is lowercase and starts with the batch’s timestamp and batch_id:

/inbound/
  20261019-060000_i000871_customers.csv
  20261019-060000_i000871_contacts.csv
  20261019-060000_i000871_invoices.csv
  20261019-060000_i000871_payments.csv
  20261019-060000_i000871_credit_memos.csv
  20261019-060000_i000871_invoice_lines.csv
  20261019-060000_i000871_inv-2026-0451.pdf
  20261019-060000_i000871_manifest.csv

CSV files are named <timestamp>_<batch_id>_<file>, where <file> is one of the names in Files you send. Leave out files you do not send.
<timestamp> is the manifest’s generated_at in UTC, as yyyymmdd-hhmmss, and is the same for every file in the batch.
Invoice PDFs are named <timestamp>_<batch_id>_<pdf_file>, where <pdf_file> is the value in that invoice’s pdf_file column. Upload a PDF only in the batch where it is new or changed, not in every batch.
<timestamp>_<batch_id>_manifest.csv is uploaded last. Monk processes nothing in the batch until it arrives.
A batch_id uses only lowercase letters, digits, and hyphens, and is never reused. File names are case-sensitive, so a name with uppercase letters is not picked up.

File conventions

CSV (RFC 4180), UTF-8, comma-delimited, with a header row using the exact column names in this guide. A byte-order mark at the start of a file is ignored; a file that is not valid UTF-8 rejects the batch. Fields may contain line breaks inside quotes, and rows in the manifest counts records, not lines.
A manifest can be at most 1 MiB, a CSV at most 100 MiB, and an invoice PDF at most 10 MiB. Monk rejects a larger file before reading its contents.
Do not open and re-save files in a spreadsheet such as Excel before uploading: it rewrites dates and strips leading zeros from IDs.
Monk reads columns by their header name, so columns can be in any order. Optional columns can be left out of the header. Omitting a column has the effect described for that column (for example, pause_invoices and invoice_via_portal keep the setting chosen in Monk). Conditionally required columns, such as exchange_rate, can be omitted only when no row in the file meets their condition.
Columns not in this guide are ignored and listed as warnings in the batch’s sync history, so you can export extra columns without breaking the import. A misspelled required column still rejects the batch, because the required column is missing.
Within a format_version, Monk only adds optional columns, so an export that works keeps working. A new required column, or a change to what a column means, comes with a new format_version.
Booleans as true or false, in lowercase. A required boolean is never blank.
Dates as YYYY-MM-DD.
Amounts as decimals in major units with a dot, such as 1234.50, with no currency symbols or thousands separators. Amounts are positive unless a column says otherwise.
Invoice amounts must be below 21,474,836.47 in Monk-supported currencies with 2 decimal places.
Currency as a Monk-supported ISO 4217 code with 2 decimal places in invoices.csv. Payments and credit memos are stated in the currency of the invoice they apply to. When a document’s currency differs from the entity’s functional currency, you can include exchange_rate: units of functional currency per one unit of document currency. Leave it blank if your export does not have it.
Amounts cannot have more than two fractional digits. Excess precision rejects the row.
IDs are your ERP’s internal identifiers: stable for the life of the record, never reused, unique within an entity_code, up to 255 characters, case-sensitive, and without : or |.
invoice_number is the number printed on the invoice, exactly as your customers see it. Monk matches it against payment references.
Send only posted documents. Leave out draft invoices, invoices awaiting approval, and payments that have not posted to your ledger, such as ones awaiting approval.
entity_code on every row identifies the legal entity or business unit. Monk maps each code to the right Monk organization during setup. Single-entity customers send one constant value. Entity codes use only letters, digits, and hyphens, and must stay unique when lowercased, because they appear in lowercase in Monk’s file names; Monk checks this when mapping them during setup.
Lists, such as tags, are pipe-separated: key-account|EMEA.

Batches and the manifest

Each export is a batch: a set of files followed by a manifest, named as in Folders and file names. Monk processes nothing until the manifest arrives and every file matches it. The manifest lists exactly the files you send, and every file it lists must arrive and match it. Every batch is a complete snapshot: every open invoice for the listed entities, plus invoices closed in the last 60 days, and everything related to them. A batch must also include every file needed by the products switched on for your connection. Leave a file out only when no product on for your connection uses it, such as contacts.csv for a Cash App-only connection. A batch that leaves out a needed file is rejected, even when its manifest matches the files that arrived. The manifest has one row per file in the batch, including invoice PDFs. The batch columns repeat on every row and must be identical; a manifest whose rows disagree rejects the batch. A rejected or incomplete batch blocks nothing. Fix the export and send it again as a new batch, with a new batch_id and generated_at.

format_version,batch_id,generated_at,entity_codes,file_name,rows,sha256
1,i000871,2026-10-19T06:00:00Z,US01|CA02,20261019-060000_i000871_invoices.csv,1843,9f2c...
1,i000871,2026-10-19T06:00:00Z,US01|CA02,20261019-060000_i000871_customers.csv,412,
1,i000871,2026-10-19T06:00:00Z,US01|CA02,20261019-060000_i000871_inv-2026-0451.pdf,,

Column	Required	Meaning
`format_version`	Yes	`1`
`batch_id`	Yes	The prefix of every file in the batch. Never reused: a batch Monk already processed under the same `batch_id` is ignored
`generated_at`	Yes	When your export ran, as an ISO 8601 timestamp with a time zone. Monk applies batches in `generated_at` order; a batch older than one Monk already applied for any entity it lists is skipped, because the newer snapshot replaced it
`entity_codes`	Yes	The entities this batch covers, pipe-separated, in any order. A batch never affects entities it does not list
`file_name`	Yes	One file in the batch
`rows`	For CSV files	Its row count, excluding the header. Blank for PDFs
`sha256`		Its SHA-256 checksum, when your scheduler can produce one

Files you send

File	Needed for	One row per
`customers.csv`	Collections, Cash App	Customer
`contacts.csv`	Collections	Contact
`invoices.csv`	Collections, Cash App	Invoice: every open invoice, plus invoices paid or cancelled in the last 60 days
`payments.csv`	Cash App	Payment application: one payment applied to one invoice, or cash left on account
`credit_memos.csv`	Cash App	Credit memo application: one credit memo applied to one invoice
`invoice_lines.csv`	Optional	Invoice line. If this file has rows, send at least one for every invoice or Monk rejects the batch. An absent or header-only file is valid.

Cash App needs each invoice’s full payment history. Cash App is switched on for your connection during setup. From then on, Monk computes every balance from the payments and credit memo applications you send, and every batch must include payments.csv and credit_memos.csv, with only the header row if there is nothing to send. Send all of them for each invoice in invoices.csv, including payments made before Monk was connected, not only recent ones. An application missing from a batch, on an invoice the batch includes, is treated as removed.

Products are switched on for your connection during setup. Every batch includes each file needed by a product that is on, with only the header row if there is nothing to send.

customers.csv

Column	Required	Description
`entity_code`	Yes
`customer_id`	Yes	ERP customer ID
`customer_name`	Yes	Name as it appears on payments; used to match bank payments
`legal_name`		Also used to identify who paid
`parent_customer_id`		Parent customer, if your ERP has hierarchies
`billing_address_line1`, `billing_address_line2`, `billing_city`, `billing_region`, `billing_postal_code`, `billing_country`		Country as ISO 3166-1 alpha-2
`tags`		Groupings your ERP already has, such as customer class, region, or segment, pipe-separated. Monk uses them to choose collection playbooks
`pause_invoices`		`true` pauses invoice sending and collections for this customer; `false` resumes them. If you include this column, every row needs `true` or `false`
`invoice_via_portal`		`true` when this customer receives invoices through their AP portal instead of by email. If you include this column, every row needs `true` or `false`

If you leave out pause_invoices or invoice_via_portal, Monk keeps the setting your team chose in Monk. If you send them, your ERP sets them, except for a customer whose setting your team changed in Monk: that change takes precedence over the file.

contacts.csv

Column	Required	Description
`entity_code`	Yes
`customer_id`	Yes
`contact_id`		ERP contact ID; if blank, the email address identifies the contact
`email`	Yes
`name`
`phone`		E.164 format, such as `+15551234567`
`title`
`invoice_id`		Set to send a specific invoice only to this contact

Send the complete contact list in every batch. A contact missing from it is removed. Monk treats every contact as a billing contact and addresses collection emails to it. The file has no role or recipient column. A customer with no contact that has an email gets no collection emails, so send at least one for every customer you want Monk to chase. Send only the contacts who should receive collection emails, such as your customer’s accounts payable contacts.

invoices.csv

Column	Required	Description
`entity_code`	Yes
`invoice_id`	Yes	ERP invoice ID
`invoice_number`	Yes	The number printed on the invoice; used to match bank payments
`customer_id`	Yes
`status`	Yes	`open` or `cancelled`. With Cash App off, an open invoice with an `open_balance` of 0 and a total above 0 is treated as paid
`invoice_date`	Yes
`due_date`	Yes
`currency`	Yes
`exchange_rate`
`total_amount`	Yes	After tax and discounts
`open_balance`	Yes	Amount still owed according to your ERP
`other_applied_amount`		Amount settled on this invoice in your ERP by anything other than the payments and credit memos in these files, such as a journal entry, a write-off without a payment, or AR/AP netting. Used when Cash App is on. Leave out write-offs your ERP loaded from Monk’s cash application file; Monk already has those
`po_number`
`memo`
`internal_note`		Internal note on the invoice. Never shown to your customer; may help Monk confirm a payment match
`project_reference`		Project or job code the invoice belongs to; may help Monk confirm a payment match
`project_name`		Project or job name; may help Monk confirm a payment match
`tags`		Groupings your ERP already has on invoices, such as invoice type or business line, pipe-separated. Monk uses them to choose collection playbooks
`pdf_file`		Lowercase file name of the invoice PDF, such as `inv-2026-0451.pdf`. See Invoice PDFs

If your ERP splits an invoice into installments, send one row per installment with its own invoice_id, the shared invoice_number, and that installment’s amounts and due date. Otherwise Monk treats the whole open balance as due on one date. Applications in payments.csv and credit_memos.csv refer to an installment by its invoice_id. Whether Monk sends the first invoice email or only follows up on invoices you have already delivered is a setting for the whole connection, chosen during setup. How Monk uses open_balance:

Collections only, Monk trusts open_balance and records the paid portion as settled in your ERP. Collections works; Cash App does not.
With Cash App on, Monk computes each balance from the payments and credit memos you send, plus other_applied_amount. Send other_applied_amount for anything else that settled part of the invoice in your ERP, such as a journal entry or a write-off without a payment; otherwise an invoice closed that way stays open in Monk, and keeps receiving collection emails. If Monk’s balance still disagrees with open_balance, Monk keeps its own balance and records the difference for review.
Missing invoices: an invoice that disappears from a batch stays as it was in Monk. Send a cancelled invoice with status cancelled, and keep paid and cancelled invoices in the file for 60 days from the date they were paid or cancelled, so Monk sees them close. If your ERP reverses an invoice with a credit memo instead of cancelling it, keep the invoice open and send the credit memo application in credit_memos.csv.

Invoice PDFs

Upload an invoice’s PDF, and list it in the manifest, only in the batch where it is new or changed. In later batches, keep the same pdf_file value on the invoice’s row without uploading the file again; Monk keeps the PDF it already has. To replace a PDF, upload the new one in a batch, under the same name or a new one. A blank pdf_file never removes a PDF Monk already has for the invoice; your team removes one in Monk. pdf_file names are unique within a batch, PDFs are at most 10 MiB, and a file that is not a PDF rejects the batch. If a pdf_file names a PDF Monk does not have, the invoice still imports, with a warning, and Monk shows the PDF as unavailable until a batch includes it.

payments.csv

Column	Required	Description
`entity_code`	Yes
`payment_id`	Yes	ERP payment ID
`voided`	Yes	`true` on every row of a payment voided or reversed in your ERP. Monk removes all of its applications. `false` otherwise
`unapplied`	Yes	`true` for cash left on account, with `invoice_id` blank. `false` for an application to the invoice in `invoice_id`. See Cash on account
`invoice_id`	When `unapplied` is `false`	Must be blank when `unapplied` is `true`
`applied_amount`	Yes	Amount applied to this invoice, or left on account, in the invoice’s currency
`payment_amount`	Yes	Full payment amount, repeated on each row of the payment; at least `applied_amount`
`payment_date`	Yes
`reference_number`		Check number, wire reference, or other reference recorded on the payment in your ERP, for your team’s audit trail
`payment_method`		How the customer paid, as your ERP names it, such as `check`, `wire`, or `card`
`memo`		Note recorded on the payment in your ERP
`exchange_rate`
`payer_customer_id`		When a different customer, such as a parent, paid
`discount_taken`		Early-payment discount taken on this invoice. Required when one was taken and Cash App is on. Blank when `unapplied` is `true`
`monk_payment_id`	For payments from Monk	The `monk_payment_id` from Monk’s cash application file, for payments you loaded from it

Echo the exact monk_payment_id for every payment loaded from Monk. If it is missing on an invoice with a retained, unechoed Monk payment, Monk leaves the ERP payment unapplied and warns not applied until Monk's payment is confirmed; send monk_payment_id in payments.csv. Monk does not guess which payment it represents. An ERP payment held because it duplicates a Monk payment is applied once that Monk payment is echoed. If a Monk payment is never echoed, Monk surfaces it in Sync Review as not_confirmed after three exports and in the unconfirmed-payments monitor. Keep a voided payment in every batch for 60 days after the void, with voided true on its rows, as you would a paid or cancelled invoice. An application that disappears from a batch without voided, on an invoice the batch still includes, such as one your team moved to another invoice, is treated as unapplied.

Cash on account

Monk only imports cash once it is applied to an invoice. Rows with unapplied true confirm cash that Monk itself left on account, through their monk_payment_id; Monk ignores other cash on account until your team applies it to an invoice, when it arrives as an ordinary application.

credit_memos.csv

Column	Required	Description
`entity_code`	Yes
`credit_memo_id`	Yes	ERP credit memo ID
`credit_memo_number`
`credit_memo_date`	Yes
`credit_memo_total`	Yes	Positive amount
`invoice_id`	Yes	The invoice this credit memo is applied to
`applied_amount`	Yes	Positive amount applied from this credit memo to this invoice
`applied_date`	Yes

Send only credit memos applied to an invoice. A credit memo not yet applied to anything is left out until your team applies it.

invoice_lines.csv

entity_code, invoice_id, line_type (product, tax, or discount), item_name, description, quantity (up to 3 decimals), unit_price, and line_amount. Monk identifies a line by its position among the invoice’s rows, as it does for NetSuite, so send each invoice’s lines in the same order in every batch, such as your ERP’s line number order. Lines and pdf_file are both optional. If you send neither for an invoice, Monk shows the invoice to your customer as a single line for total_amount.

Example

entity_code,invoice_id,invoice_number,customer_id,status,invoice_date,due_date,currency,exchange_rate,total_amount,open_balance,po_number,memo,tags,pdf_file
US01,10045,INV-2026-0451,C-881,open,2026-09-01,2026-10-01,USD,,12500.00,7500.00,PO-7731,,key-account,inv-2026-0451.pdf
CA02,20119,CA-88213,C-102,open,2026-09-15,2026-10-15,USD,1.3678,4200.00,4200.00,,,,

Validation

Check	If it fails
Manifest present, row counts and any checksums match	Monk waits at least 15 minutes for missing files, then reports the batch as incomplete
Required columns present and values match this format	Batch rejected with a row-numbered error report
`unapplied` agrees with `invoice_id` on every `payments.csv` row	Batch rejected with a row-numbered error report
`voided` is the same on every row of a payment	Batch rejected with a row-numbered error report
Only columns in this guide	Extra columns ignored and listed as warnings; the batch imports
Every `entity_code` is mapped to your organization	Batch rejected
A batch includes every file needed by the products on for your connection	Batch rejected
Every `pdf_file` names a PDF in this batch or one Monk already has for that invoice	That invoice imports with a warning; its PDF shows as unavailable
Applications reference invoices Monk knows	Those rows skipped and listed as warnings; the rest of the batch imports
Every `monk_payment_id` is one Monk issued to your organization	That payment imports as your ERP’s own payment, with a warning

Every batch appears in Monk’s sync history with the rows accepted and rejected, any warnings, and a downloadable error report. During setup, upload test batches to validate your export without importing anything.

Get Started

Core Concepts

Integrations

Webhooks

SFTP Import format

SFTP Import format

Folders and file names

File conventions

Batches and the manifest

Files you send

customers.csv

contacts.csv

invoices.csv

Invoice PDFs

payments.csv

Cash on account

credit_memos.csv

invoice_lines.csv

Example

Validation

​SFTP Import format

​Folders and file names

​File conventions

​Batches and the manifest

​Files you send

​customers.csv

​contacts.csv

​invoices.csv

​Invoice PDFs

​payments.csv

​Cash on account

​credit_memos.csv

​invoice_lines.csv

​Example

​Validation

SFTP Import format

Folders and file names

File conventions

Batches and the manifest

Files you send

customers.csv

contacts.csv

invoices.csv

Invoice PDFs

payments.csv

Cash on account

credit_memos.csv

invoice_lines.csv

Example

Validation