CSV File Import

If you wish to send packages to a large number of recipients, you can use the File Import function.

---

Create a Profile

Before importing the file, you must create an import profile.

1. Go to Profiles → Addresses or Shipments → press +
2. Choose Import Type → Addresses or Shipments
3. Add a Profile Name (e.g. Address book)
4. Choose Import File Type → CSV

The rest can remain as default.

5. Press Continue
6. Press Upload File

7. Press Process File
8. Map field names based on the header names of your CSV file

note

If your CSV file has no header row, the dropdown list will show Position 0, 1, 2, etc. The first column (A) of the spreadsheet corresponds to Position 0.

The Function column can remain untouched.

If needed, you can add a Transformation — created and used when data from the CSV file must be adapted for import. For example, use this when the country name in your file is "Switzerland" but the system requires ISO 3166-1 alpha-2 format ("CH").

When all mandatory (and optional) field names are entered, press Save.

---

Upload the CSV File

1. Go to File Imports
2. Press Import File in the top-right corner

3. Choose the Profile (the name you entered in step 1)
4. Upload the CSV file and press Import

5. Press Refresh

The imported information will appear in your address book or shipments.

---

Technical Requirements for CSV File

The system supports flexible CSV formats with automatic header detection and multiple encoding/delimiter options.

Character Encoding

Choose one of the supported encodings:

Encoding	Use Case	Notes
UTF-8	Recommended for all files	Universal support, handles all special characters
ISO-8859-1	Western European languages	German umlauts (ä, ö, ü), French accents
Windows-1251	Cyrillic characters	Ukrainian, Bulgarian

tip

Save your CSV as UTF-8 in Excel: File → Save As → CSV UTF-8 (Comma delimited)

Field Delimiters

Delimiter	Symbol	Excel Export (Region)	Use When
Semicolon	;	European Excel (DE/FR/IT)	Recommended for European locales
Comma	,	US/UK Excel	Data doesn't contain commas
Tab	\t	Manual export	Data contains many special characters
Pipe	|	Database exports	Technical integrations

warning

Your data must not contain the delimiter character, or it must be properly quoted.

---

CSV Header Format

Headers must start with a letter (A–Z, a–z) or underscore (_).

Allowed characters in headers (after the first character):

Character	Examples
Letters	A–Z, a–z
Numbers	0–9
Underscore	_
Hyphen	-
Dot	.
Space
Parentheses	( )
Forward slash	/
Colon	:
Ampersand	&
Comma	,

Not allowed as first character: Numbers, special symbols ($, #, @, !, etc.)

Valid header examples:

Name;Address1;PostalCode;Country
DokStatus;DokDat.;Order_Nr;Weight.KG
Customer Name;Street & Number;Date/Time;Status (Active)
recipient_name;recipient_address;tracking-number

Invalid header examples:

123;456;789          (starts with number)
$Amount;#ID;@Email   (special chars: $, #, @)
;Name;Address        (empty first column)

---

Header Auto-Detection

The system automatically detects whether the first row is a header by analysing:

• Header characteristics: contains at least one letter, not purely numeric, matches the allowed character pattern
• Data characteristics: second row contains numbers, emails, or significantly different text; length difference > 3 characters from header

First Row	Second Row	Detection Result
Name;Address;Weight	John Doe;Main St 1;2.5	Header detected
Customer;Order;Total	ACME Corp;12345;99.99	Header detected
123;456;789	111;222;333	No header (all numeric)
Active;Pending;Done	Active;Done;Pending	Ambiguous (similar text lengths)

---

CSV Configuration Parameters

Parameter	Type	Description	Example Values
columnDelimiter	String	Character separating fields	; , \t |
decimalSeparator	String	Decimal point for numbers	. (US) or , (EU)
multiValueDelimiter	String	Separator for multi-value fields	| ; ,
containsHeader	Boolean	Whether first row is a header	true / false

Decimal separator examples:

European format (comma as decimal):

Name;Weight;Price
Product A;2,5;19,99
Product B;1,8;15,50

US format (dot as decimal):

Name,Weight,Price
Product A,2.5,19.99
Product B,1.8,15.50

---

Creating CSV Files from Excel

1. Prepare your data:

   • First row = headers
   • No empty rows at the top
   • Consistent column count

2. Save as CSV:

   • European (semicolon): File → Save As → CSV (Semicolon delimited) *.csv
   • UTF-8: File → Save As → CSV UTF-8 (Comma delimited) *.csv
   • US (comma): File → Save As → CSV (Comma delimited) *.csv

3. Verify encoding:

   • Open the file in Notepad or TextEdit
   • Check that special characters (ä, ö, ü, é) display correctly

---

Common Issues & Solutions

Special characters display incorrectly

Problem: Müller appears as Müller

Solution: Save file as UTF-8 encoding. In Excel, use "CSV UTF-8" format instead of regular CSV. Verify in a text editor that special characters look correct.

---

Numbers are not recognised

Problem: 2,5 is treated as text instead of a number

Solution: Set decimalSeparator to match your file format.

• European: "decimalSeparator": ","
• US/International: "decimalSeparator": "."

---

Wrong delimiter

Problem: All data appears in the first column

Solution: Check the actual delimiter in your file. European Excel uses ;, US Excel uses ,. Set the correct columnDelimiter.

---

Header not detected

Problem: The system treats the header row as data

Solution: Ensure headers start with letters (not numbers). Explicitly set "containsHeader": true. Check that data rows are different from headers.

---

Empty rows or extra columns

Problem: Import fails or has unexpected columns

Solution: Remove empty rows at the top of the file. Ensure all rows have the same number of columns. Remove trailing delimiters.

---

Pre-Import Checklist

Before importing, verify:

• File encoding is UTF-8 (or appropriate for your language)
• Delimiter matches configuration (semicolon for Europe, comma for US)
• Headers start with letters (if using headers)
• No empty rows at the top
• Consistent column count across all rows
• Decimal separator matches your number format
• Special characters (ä, ö, ü, é) display correctly in a text editor
• No trailing spaces or delimiters
• File size is reasonable (< 25 MB recommended)