> ## Documentation Index > Fetch the complete documentation index at: https://docs.monk.com/llms.txt > Use this file to discover all available pages before exploring further. # SFTP Import format > Columns, batches, and validation for the files you send to Monk over SFTP # SFTP Import format This page specifies every file your export sends to Monk. For how the integration works, see [File integration (SFTP)](https://docs.monk.com/integrations/sftp), and for how to connect and authenticate, see [Connecting](https://docs.monk.com/integrations/sftp#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 `__`, where `` is one of the names in [Files you send](#files-you-send). Leave out files you do not send. * `` 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 `__`, where `` 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. * `__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](#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](#files-you-send) 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`. ```csv theme={null} 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. | > [!NOTE] > > **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](#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](#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](https://docs.monk.com/integrations/sftp-export-format.md), 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 ```csv theme={null} 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.