This document outlines the format of the CSV files to establish data transfer between on-premise systems and Kolleno through SFTP. The objective of the data transfer is to provide Kolleno with all the necessary data such that Kolleno can manage AR effectively.
Please do NOT insert any NULL values or characters.
Make sure that all column names are lowercase and do not contain any spaces in the name.
File names cannot contain blank spaces. Use underscores to separate words. Each file name must start with its category (for example
customers_) followed by the date of the upload, e.g.customers_2026-10-29.csv. A full date-time (e.g.customers_2023-11-16T15:45:30.csv) also works, but some systems don’t allow colons in file names, so the date on its own is fine.Upload all CSV files to the csv_data_uploads folder. Files at the top level of your SFTP folder, or in any other folder, are not imported.
There are 3 possible requirements for each field:
Required: you must send the field and a value.
Optional (value): you must send the field but the value is optional.
Optional (value and field): you can decide if you want to send it. If you send, it will always overwrite any value entered by the user.
Do you also need to send journal entries? See Add a Journal Entries File to Your SFTP CSV Upload.
Additional data
If you’d like to bring in any additional data to use as columns or filters, add it as extra columns to the files listed below, following the same naming convention. This applies to every file except Credit Notes <> Invoices and Payments <> Invoices, which are relationship files and cannot hold extra data.
All data is imported as text (a string). For each additional field, if you would like it to be a custom field/column/filter, please raise support@kolleno.com what format it should be, e.g. date, number, currency or text, so we can set it up correctly.
Customers
File name should be “customers” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “customers_2023-11-16T15:45:30.csv”. Any extra data that would be beneficial on Kolleno can be provided as additional columns in the CSV.
If your customers file includes an email address column, Kolleno can also turn it into a contact for each customer and keep it in sync on every import. See Create contacts from email columns in your customers file.
Column | Requirement | Information |
id | Required | Unique among all customers. |
name | Required |
|
ref | Optional (value) | This will be displayed on the platform. |
currency_iso | Optional (value) | 3 letters ISO code such as “USD”. |
address_line_1 | Optional (value) |
|
address_line_2 | Optional (value) |
|
postal_code | Optional (value) |
|
city | Optional (value) |
|
state | Optional (value) |
|
country_iso | Optional (value) | 2 letters ISO code such as “US”. |
credit_limit_amount | Optional (value and field) | Decimal number |
Contacts
File name should be “contacts” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “contacts_2023-11-16T15:45:30.csv”. Any extra data that would be beneficial on Kolleno can be provided as additional columns in the CSV.
Column | Requirement | Information |
id | Required | Unique among all contacts. |
customer_id | Required | This is the “id” column in the “CUSTOMERS” file. |
first_name | Optional (value) |
|
last_name | Optional (value) |
|
email_address | Optional (value) | Max. 254 characters |
telephone_number | Optional (value) |
|
mobile_number | Optional (value) |
|
position | Optional (value and field) |
|
primary | Optional (value and field) | Set “true” or “false”. |
Invoices
File name should be “invoices” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “invoices_2023-11-16T15:45:30.csv”. Any extra data that would be beneficial on Kolleno can be provided as additional columns in the CSV.
Column | Requirement | Information |
id | Required | Unique among all invoices |
customer_id | Required | This is the “id” column in the “CUSTOMERS” file. |
ref | Required |
|
currency_iso | Required | 3 letters ISO code such as “USD”. |
amount | Required |
|
balance | Required |
|
date_invoice | Required | Format: YYYY-MM-DD |
date_due | Required | Format: YYYY-MM-DD |
Please use the same date format in every file. Dates should show only the year, month and day (e.g. YYYY-MM-DD), with no time.
Credit Notes
File name should be “credit_notes” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “credit_notes_2023-11-16T15:45:30.csv”. Any extra data that would be beneficial on Kolleno can be provided as additional columns in the CSV.
Column | Requirement | Information |
id | Required | Unique among all credit notes. |
customer_id | Required | This is the “id” column in the “CUSTOMERS” file. |
ref | Required |
|
currency_iso | Required | 3 letters ISO code such as “USD”. |
amount | Required |
|
balance | Required |
|
date_issued | Required | Format: YYYY-MM-DD |
Please use the same date format in every file. Dates should show only the year, month and day (e.g. YYYY-MM-DD), with no time.
Payments
File name should be “payments” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “payments_2023-11-16T15:45:30.csv”. Any extra data that would be beneficial on Kolleno can be provided as additional columns in the CSV.
Column | Requirement | Information |
id | Required | Unique among all credit notes. |
customer_id | Required | This is the “id” column in the “CUSTOMERS” file. |
ref | Required |
|
currency_iso | Required | 3 letters ISO code such as “USD”. |
amount | Required |
|
balance | Required |
|
date_paid | Required | Format: YYYY-MM-DD |
is_prepayment | Optional (value) | true/false |
is_overpayment | Optional (value) | true/false |
Please use the same date format in every file. Dates should show only the year, month and day (e.g. YYYY-MM-DD), with no time.
Credit Notes <> Invoices
File name should be “credit_notes_invoices” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “credit_notes_invoices_2023-11-16T15:45:30.csv”.
Column | Requirement | Information |
credit_note_id | Required | This is the “id” column in the “CREDIT NOTES” file. |
invoice_id | Required | This is the “id” column in the “INVOICES” file. |
amount_applied | Required |
|
Payments <> Invoices
File name should be “payments_invoices” followed by the date-time of upload in the format YYYY-MM-DDTHH:MM:SS separated by an underscore. Example: “payments_invoices_2023-11-16T15:45:30.csv”.
Column | Requirement | Information |
payment_id | Required | This is the “id” column in the “PAYMENTS” file. |
invoice_id | Required | This is the “id” column in the “INVOICES” file. |
amount_applied | Required |
|
SFTP Connection
Kolleno will provide the SFTP server. To facilitate access to the SFTP server, Kolleno requires an OpenSSH public key. Upon receipt, Kolleno will provide the credentials necessary (username and host) for connection, which can be used alongside the matching private key to access the SFTP server.
CSV data uploads can be uploaded to a folder within the SFTP server titled “csv_data_uploads”
Invoice PDFs can be uploaded to the "pdf" folder of the SFTP server with the naming convention “invoice_ref.pdf”. For example: “INV-123.pdf”.