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 name and phone or email for every contact.

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

Column	Description	Example
`name`	First and last name of the contact. This field must contain at least one character.	`Jane Smith`
`phone`	Phone number in E.164 format. You can include multiple phone numbers separated by a colon (`:`).	`+14155550123` `+14155550123:+12125550189`
`email`	Main email address. You can include multiple email addresses in this field, separated by a colon (`:`).	`[email protected]` `[email protected]:[email protected]`
`email2`	Additional email address. This field is kept for backward compatibility with the original system.	`[email protected]`
`title`	Job title of the contact.	`Head of Sales`
`company`	Name of the company the contact belongs to.	`Acme Corp`
`address`	Contact’s address.	`Main Street 1, San Francisco`
`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.	`[email protected]`
`tags`	One or more tags to assign to the contact. Multiple tags must be separated by a colon (`:`). Existing tags are reused; new tags are created automatically if they do not exist.	`coldlead:webinar:priority`
Custom attributes	Any additional fields you want to import. These must be created as custom attributes in Account Settings first, and the column names must match exactly.	`industry` → `Healthcare`

Country column (supported formats)

If your CSV file includes a country column, CloudTalk accepts multiple country formats to make imports easier.

You can use:

Two-letter country codes, for example: US, GB, DE
Three-letter country codes, for example: USA, FRA, DEU
Full country names in English, for example: United States, Germany, France
Common, unambiguous variants, for example: United States of America, Great Britain, Trinidad & Tobago

CloudTalk automatically normalizes common formatting differences, including:

uppercase and lowercase values
extra spaces before, after, or inside the value
using & instead of and (and vice versa)

If the country value cannot be recognized, the row will fail with a clear error message indicating an invalid country value.

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 Confirm to 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 (usually resolves on its own after a short time. If the issue persists or occurs multiple times within a few hours, CloudTalk Support can help investigate further)
File size exceeds 8 MB

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
An import with this outcome is shown with an orange "Completed" status, indicating that the import finished but some rows 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 value X in column Y is not a valid phone number.` `[phone, columnIndex]`	The number is not a valid local or international phone number.	Insert a phone number that is following the E.164 Format (e.g., +42190812345).
`The value X in column Y is not a valid email address.` `[email, columnIndex]`	The value provided is an invalid email.	Insert a valid email format (e.g. [email protected])
`The [columnName] value in column 1 is required.`	A required column is missing or empty.	Check for extra spaces in column headers and ensure required columns are correctly named and filled.
`The X value in column Y is required.` `[fieldName, columnIndex]`	You are attempting to upload the contact without the phone number or email. Either `Phone` or `Email` is a required field for CloudTalk to import this contact.	Review the contact and ensure that at least one valid identifier (phone number in E.164 format or email address) is provided.
`The provided X value in column Y exceeds the maximum length of N characters.` `[fieldName, columnIndex, max]`	Exceeded Maximum number of characters allowed for a column.	Shorten the value so it stays within the allowed character limit for this field.
`The provided X value in column Y must be at least N characters long.` `[fieldName, columnIndex, max]`	The provided number of characters is below the minimum character length.	The `Name` column must contain at least 1 character. This field is required. All other fields (such as `Company`, `Website`, `Title`, `Industry`, `Address`, `City`, `Zip`, etc.) are optional. If any optional field is left empty, no value will be imported for that field.
`The value X in column Y is not a valid website address.` `[columnName]`	The value in the website column is not a valid website address.	Please review and re-upload a valid website address.
`The value X in column Y is invalid.` `[displayFieldName, columnIndex]`	This is a generic error. The value in the column is invalid.	Review the value for this contact and correct any obvious mistakes. If you’re unsure how to fix it, please contact our support team.

Maximum character length

Field	Maximum characters
Name	150
Zip	15
Title	255
Company	100
Industry	100
Website	100
Address	255
City	255

If a value exceeds the maximum length, reduce the number of characters and re-upload the file.

All other fields are optional. If an optional field is left empty, no value will be imported for that field.

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!

How to Import Contacts into CloudTalk

Contact Merging

Introduction to CloudTalk Analytics

Upload of CSV File Fails

CSV Import Stuck