In this article, we will guide you through uploading a file of contacts to CloudTalk.
User Level:
Admin
⚠️ Contact import via CSV files may take some time. For the best results, we recommend allowing additional processing time during peak hours.
If timing is critical for your import, consider alternative methods such as using a CRM integration or CloudTalk’s API for real-time synchronization.
📘 Learn more: How do I import contacts into CloudTalk?
Data Preparation
A maximum of 8MB (typically ~ 80k contacts) is supported. Larger files will not upload.
When importing contacts from a file, we currently require a .csv format. There are various types of software that will allow you to save your data as a CSV. For the most common case of using Excel, you can go to File > Save as. Under the File Name field, select CSV format.
It's very important to set up your CSV file according to our CSV file template. In order to access this template, in your CloudTalk Dashboard account navigate to Contacts > List > Import Contacts in Bulk and then click Download template in bottom left corner. Note, that you can safely delete any unused columns from the template.If you only need to import basic details such as name, phone, and email, you can remove all other columns without any issues.
CSV File Requirements
It is highly recommended that you download and follow the template. Most importantly, make sure to:
Write all column names in lowercase (custom attributes may differ)
Avoid special fonts or stylized text (e.g., cursive, calligraphic, or decorative fonts) in contact names or other fields. These may prevent your file from uploading properly.
Fill in values for
nameandphoneoremailfor every contact.If your CSV file includes a
countrycolumn, the value must be provided as a two-letter ISO country code, not a full country name.For example:
US(United States)GB(United Kingdom)DE(Germany)AT(Austria)
Not following these requirements can lead to an unsuccessful import.
Important: Default Country Code
The default country set in your Account Settings determines which international code (+) will be automatically applied to uploaded phone numbers that do not already include one.
Before importing your file, please double-check that the selected country in Account > Settings > Default country code matches the country of the phone numbers in your CSV.
If the default country is different, your numbers may be imported with the wrong international prefix.
Example Columns in Your Spreadsheet
name and phone (number) are required columns which must have values for every entered contact.
name: the first and last name of the person
phone: the phone number(s) in E. 164 format
additional numbers separated by a colon
:ex.
+421905192483 : +421915111111
email: main email address. You can include multiple emails in thisrow, separated by a colon (:)
email2: additional email address. This field is kept for backward compatibility with the original system.
title: e.g. CEO, Sales Director
company: name of the company
address
favorite_agent: email address of a CloudTalk agent to assign as the contact’s favorite agent. If the email matches an existing agent, the agent is assigned. If no match is found, the import of this row will fail.
tags: one or more tags to assign to the contact. Multiple tags must be separated by a colon (for example:
coldlead:webinar:priority). Existing tags are reused; new tags are created automatically if they do not exist.custom attribute(s): these are any other additional fields you would like to create (see below)
Custom Attributes
In order to make sure the additional contact fields from your CSV file display properly on contacts, you will need to add these as custom attributes in your dashboard settings.
From the dashboard, navigate to Account > Settings.
In the General Settings tab, scroll to the Contacts section.
Here is where you can add your custom field names by selecting
+Add Custom Attribute. Make sure the names you enter here match the names on your CSV, in both spelling and case.
Importing Contacts From a File
When the CSV file is completed and saved in the correct format, it's ready to be imported.
Go to Contacts > List > Import Contacts in Bulk.
Upload the CSV file.
Tag your contacts: create a tag as a form of identification for the contacts you are importing. This tag is important for the Dialer campaigns and can be used for contact filtering.
Select
Confirmto start the import.
After uploading the file, the import appears in Contacts > Imported files, where you can track its progress and review results.
Imported Files
CloudTalk keeps a clear history of all CSV imports so you can easily track what happened, spot issues, and fix them without contacting Support.
When you open an import job, CloudTalk shows a detailed breakdown, including:
Total number of rows in the file
Number of contacts imported successfully
Number of contacts that failed (if any)
A row-by-row status with clear result messages. Each failed row includes a specific reason explaining why the contact could not be imported.
What Happens If an Import Fails
Global Import Errors
If the import fails before processing rows, you’ll see a global error message explaining the reason, such as:
File could not be loaded
Temporary service outage
File size exceeds 8 MB
Row error threshold reached
Partial Imports
CloudTalk no longer rejects the entire file because of one invalid contact.
Valid contacts are imported successfully
Invalid contacts are marked as Failed
If too many rows fail (the threshold is 1000 failed records), the import may stop to prevent incorrect data.
You can download the error report, fix only the failed rows, and re-upload them.
How to Fix Failed Rows
Open Contacts > Imported files
Click View details on the failed import
Review the failure reason for each contact
Download the error report (if available)
Fix only the failed rows in your CSV
Re-upload the corrected file
List of Failed Rows Errors & How to Troubleshoot Them
Error Name | Description | How to Fix |
| The number is not a valid local or international phone number. | Please insert a phone number that is following the E.164 Format (e.g., +42190812345). |
| The value provided is an invalid email. | Please insert a valid email format (e.g. [email protected]) |
| You are attempting to upload the contact without the phone number or email.
Either
| Review you contact and ensure that it has a phone number assigned in an International E.164 format. |
| Exceeded Maximum number of characters allowed for a column
Name: 150
Zip: 15 Title: 255 Company: 100 Industry: 100 Website: 100 Address: 255 City: 255
| Reduce the number of characters for this property to less than [Placeholder for whatever the limit for a given value type this is] |
| The provided number of characters is below the minimum character length.
Name: 1
Tag: 1 | The
All other fields (such as
If any optional field is left empty, no value will be imported for that field. |
| The value in the website column is not a valid website address. | Please review and re-upload a valid website address. |
| This is a generic error. The value in the column is invalid. | Please review the value for this contact and correct any obvious mistakes. If you’re unsure how to fix it, please contact our support team. |
If you’re still experiencing issues after fixing failed rows or want help with other specific import symptoms, check these troubleshooting guides:
CSV import stuck – explains why an import may remain in Processing for a long time, when it’s normal, and when to take action.
Upload of CSV file fails – walks through common formatting and structure problems (such as encoding, missing headers, or wrong delimiters) and how to resolve them.
Have more questions? Contact our Support team. We're always here to help!