When you need to build your client address book from scratch — or add many consignors in one go — creating them one by one with the "+ NEW" dialog is slow. The CSV import lets you upload dozens (up to 500) of clients starting from a spreadsheet: you download a ready-made template, fill it with your data and upload it.
The complete bulk import flow: where the "IMPORT CSV" button lives, how to download and fill in
the template_clienti.csv template, which columns are required, how the platform handles
duplicates and row-by-row errors, and what happens to the clients right after the import. For the
general map of the section (table, filters, drawer) see the Clients
overview; to add a single client with VAT verification see
Add and invite a client.
Before you start
- A forwarder account with the ADMIN or OPERATOR role: importing clients — like adding them manually — requires one of these two roles.
- A spreadsheet (Excel, Google Sheets, LibreOffice) to fill in the template and save it as CSV.
- The CSV file can contain at most 500 data rows and weigh at most 5 MB.
The CSV import is the shortcut to populate the address book in bulk (migration from another management system, first load of your historical consignors). To add a single client — with the VAT number check on VIES and the automatic pre-fill of the company name — the "+ NEW" dialog described in Add and invite a client is more convenient.
1. Open the import dialog
From the Clients page (URL /company/{companyId}/trading-partners), click the "⤴ IMPORT CSV" button at the top right of the header, next to the lime "+ NEW" button.
The "Import customers from CSV" modal dialog opens, with the subtitle "Upload a CSV file to import customers in bulk".
2. Download the template and fill it in
Inside the dialog, at the top, click the green "Download CSV template" link: the browser immediately downloads the template_clienti.csv file, ready with the header row and two example rows.
Below the link, a preview table shows you the template columns with two example rows, so you immediately know what to write in each column. The twelve columns of the template_clienti.csv template are:
| Column | What it holds | Required |
|---|---|---|
ragione_sociale | Client company name | Yes |
paese_iva | VAT country code, e.g. IT | Yes |
partita_iva | VAT number, without the country prefix | Yes |
indirizzo | Street and number of the registered office | No |
citta | City of the registered office | No |
provincia | Province code, e.g. MI | No |
cap | Postal code | No |
paese | Country code of the address, e.g. IT | No |
nome_referente | Name of the contact person | No |
telefono_referente | Contact phone | No |
email_referente | Contact email | No |
note | Free text on the client record | No |
A row is imported only if the three columns ragione_sociale, paese_iva and partita_iva are
filled in. It's the same rule as the "+ NEW" dialog: there too the VAT number is mandatory,
because it is the client's unique identifier and is used to recognise and skip duplicates. All the
other columns (address, contact, notes) are optional: you can leave them empty and complete the
data later from the detail drawer.
- The column separator is the semicolon
;(it's the one the template is generated with). - Keep the header row with the column names: it's the row Truckscanner uses to understand the column order. Keep the column names exactly as in the template (ragione_sociale,paese_iva, …) — they are technical names and must not be translated. - Rows starting with the#character are ignored: you can use them for notes or comments inside the file. - Always save the file in.csvformat (UTF-8 encoding recommended). Other formats —.xlsx,.txt— are not accepted.
3. Upload the file and start the import
Once the template is filled in, go back to the dialog. You can drag the file onto the dashed area "Drag the CSV file here or browse", or click it to open your operating system's file picker. The area only accepts .csv files up to 5 MB.
As soon as the file is selected, the area turns into a row showing the file name and its size, and the "IMPORT" button at the bottom right becomes active.
Click "IMPORT". The button switches to the "IMPORTING…" state while the platform processes the file: for large files or files with many VAT numbers to check it may take a few seconds. Picked the wrong file? Click the X next to the name to remove it and upload another one.
4. Check the result
When the import finishes, a confirmation toast appears at the top right — for example "3 customers imported" — and inside the dialog a green box with the same count. If there are no errors, the dialog closes by itself after a couple of seconds.
The new clients appear immediately in the table and the counters of the tabs at the top update: every imported client enters as "Not invited" (in the Truckscanner column you see the "COLLABORATE ON TRUCKSCANNER" button), because the import only populates your address book and doesn't send any invitation.
What happens after the import
The clients uploaded via CSV are identical to those created with "+ NEW": you find them in the address book, you can open their detail drawer, edit them, link them to loads for the operational pickup and delivery notifications.
Two things to know:
- No email is sent. Unlike the invitation flow, the CSV import sends nothing to the clients: it only adds them to your internal address book. When you want a client to actively collaborate on Truckscanner, you invite them later with the "COLLABORATE ON TRUCKSCANNER" button on their row — the flow is described in Add and invite a client.
- Duplicates are skipped, not overwritten. If a CSV row has a VAT number already present in the address book, that client is neither created nor modified: it is counted among the "duplicates skipped". The import does not update existing clients.
Common problems
See also
- Clients overview — the full map of the section: table, filters, detail drawer, row actions.
- Add and invite a client — adding a single client with VAT verification, and how to invite them to collaborate on Truckscanner.
- For forwarders — overview