This guide outlines the CSV/XLSX import formatting rules you need to follow before uploading files into the system. You’ll learn what structure your data should have, which fields are required, and how values should be formatted to be correctly recognized during import. Sticking to these rules helps prevent common issues like missing columns, invalid data types, or unexpected mapping errors. Use this article as a checklist to validate your file and ensure a fast, reliable import every time.
Currently application allows to upload data from two types of files:
CSV
XLSX
Your file must use a one of the standard separators. Otherwise, the file may be rejected.
Allowed options:
comma (,)
semicolon (;)
tab
Avoid:
Double commas (,,)
Commas in irregular places
Unusual separator characters
Encoding is the method used to represent text as digital data. It defines how letters, numbers, symbols, and special characters are stored and displayed by a system. Choosing the correct encoding is essential for preserving text accuracy, especially when working with multilingual content. If the wrong encoding is selected, characters may appear corrupted or unreadable, a problem often referred to as mojibake.
Among the most commonly used options, UTF-8 is the modern standard. It supports a vast range of characters from different writing systems and is widely recommended for international content because of its compatibility and flexibility.
Cyrillic (Windows-1251) is a legacy encoding commonly used for texts written in Cyrillic-based languages, especially in older Windows environments. Cyrillic (ISO-8859-5) is another older standard for Cyrillic text, although it is less common today than Windows-1251 or Unicode-based encodings.
For Central and Eastern European languages, Eastern Europe (Windows-1250) is often used in legacy Windows applications. It supports languages that use Latin scripts with additional diacritical marks, such as Polish, Czech, and Hungarian. Similarly, Eastern Europe (ISO-8859-2) is an older international standard designed for the same language group, though it has largely been replaced by Unicode in modern systems.
Finally, US ASCII is one of the oldest and most limited encodings. It includes only basic English letters, numbers, and punctuation marks, making it suitable only for simple plain-text content without accented or non-Latin characters.
In most modern use cases, UTF-8 is the safest and most universal choice, while legacy encodings remain useful mainly for compatibility with older files and systems.
Each column header should represent one attribute and each cell should contain only the value for that attribute.
If you leave extra values in a row that don’t match any attribute, the importer may attempt to merge values and treat them as a single field. This can lead to misleading validation errors (e.g., a “last_name too long” message even when the surname looks fine).
Checklist
Every column has a clear header (attribute name).
Every value belongs to an existing attribute (or one you plan to create).
No “extra” values placed after the last expected column.
Correct formatting matters because the import engine validates value types.
Before you create new attributes, see what types of attributes are available for use:
Type | Description | Example |
Boolean | It represents binary options: true / false. | Attribute "Marketing consent", value "True" |
Date | Field to store the information about a specific date. Format: ISO 8601. | Attribute "Birthday", value "1996-01-20" |
Datetime | Field to store time-specific details like sign-up or last activity information. It requires ISO 8601 format. | Attribute "Last seen", value "2016-08-03 12:00:00+00:00" |
Fixed choice | Set of possible options that limit the values for a specific field. Such attributes can also include "Allow multiple choices" variation. If this option is ON, you can out more than 1 value into cell, separating them by “|” symbol. | Attribute "Preferred language", value "English", "Polish", "Spanish" |
Floating-point number | Numerical data accommodating decimals, suitable for representing prices or statistical measures. | Attribute "Lifetime value", value "1000.59" |
Integer | Numerical data, includes only whole numbers. | Attribute "Total number of orders", value "9" |
JSON file format | It works for longer values that cannot be placed in other data formats. Not available for product events. | Attribute "Additional order information", value (valid JSON object): "key": "value" |
Number | Event only (!).This field is used for event attributes in specific. It covers both integer and floating-point number options. | Attribute "Points collected", value "15" |
String | Any string of characters limited by 255 elements. It is perfect for text-based information, including names, email addresses, or any other textual data. | Attribute "Subscription plan", value "Standard" |
You can read more about attributes here.
Some fields expect specific, predefined values. Make sure you use the correct format.
Attribute | Description | Required Values |
Gender (contact attribute) | Standard attribute you can update with your custom values. Empty by default. |
|
Phone number (contact attribute) | Standard attribute you can update with your custom values. Empty by default. Recommended format suitable for all providers: E.164 | E.164 format. Example: +44754123434 |
Status (deal attribute) | This field defines status of your deal. |
|
Status of the task (deal attribute) | These define your task status. |
|
Assigned to (contact attribute) | This defines which team member the contact is assigned to | Must match an existing team member ID or team member/group name (based on your system setup). |
Status (ticket attribute) | This field defines the status of the ticket. |
|
To know more about importing specific objects to the application, check a dedddicated section in our Knowledge Base: Data Import & Export
