Importing data through a CSV file is the fastest way to create or update your data in FreeAgent CRM. Our importer includes a template you can download to get your data ready, and it also includes a Field Mapping feature that allows you to match a column in your file to an existing field, in case they don't share the same name. You can also create fields right there in case you are missing one or more to get your data to FreeAgent CRM.
Note: Since FreeAgent CRM is fully customizable, the name of your apps could be different from those shown in this tutorial. Here are the descriptions of the most common Apps:
- Contacts: This app handles the contact information, it could also be called Leads, Customers, etc.
- Accounts: This app includes the information of the Account, Company, or Organization of the Contact. In some of the existing setups, this App could be deactivated.
- Opportunities: This is where you keep track of your Sales pipeline, meaning it could be called Sales or Deals. There are some cases in which this app is used with a different purpose in mind, like Projects.
Edition Qualifier: This feature is available in all FreeAgent Editions.
User Permissions: Role-based restrictions, If you are unable to import files, please reach out to your team's administrator.
Prerequisites: Before importing your data, make sure that you have completely configured your Apps. This is essential for the Template CSV file to include all the fields for your Apps.
To learn more about how to create your Apps, configure them, and create custom fields, please visit the following tutorials:
In this tutorial we will cover the following topics:
Getting your CSV Files Ready
The very first step needed to start the import process is to get your files ready. This involves a couple of steps.
Download CSV Template
You can start off by downloading the CSV template available for each of your apps. In the menu, click on the App's name to display the available options and then click Import [App Name]. Once you are in the right App, click the 'Import {App Name}' button on the top right corner.
In the import window, the option to download the template is located in the top light blue bar, and the download will begin right when you click 'Download our recommended templates'.
Note: You will need to repeat this process for each of your Apps, as the template CSV file includes the specific configuration for each of them.
Now that you have your template file, it's time to fill it with your data. At this time we recommend that you clean your data very well to make sure you import quality data. This clean up includes making sure that you are only adding relevant information for you and your team. Also that phone numbers, addresses, emails, etc.. are well-formatted. Your file shouldn't include any empty columns or rows.
It is worth mentioning two things:
1) the ID column should be empty if you are importing new data, however, if you are looking to import updates to your existing data, that column should include the record ID.
2) For those fields that are References to records within your Apps instead of having the Name of the record, it is necessary to use the record's ID. We will talk about this in more detail later.
Import Sequence
Given the existing relationships in the data, the import process should follow a specific order. The name of the Apps may vary based on your team's configuration but the order should be:
First, create your Accounts (or Organizations), then you will need to create your Contacts (Leads or Customers) and lastly your Opportunities (Deals or Sales).
It has to be done following this order, as we need to include the IDs to create the relationships. The same applies to any Custom app that includes a reference to another App as the IDs are needed to create those relationships as well.
To simplify this process, we recommend that you specify Unique fields for each of your Apps.
Unique Fields
The recommended unique fields for the most common Apps are:
| APP | RECOMMENDED FIELD |
| Contacts | Work Email |
| Accounts | Name |
| Opportunities | Name |
Please keep in mind that your Apps could have different fields, therefore you should use the one that makes the most sense for them.
Note: Once your Unique Field is setup you must use this instead of the record ID in your Import process. If Unique Field is not enabled, continue with record ID.
To learn more about unique fields, please visit this tutorial:
Unique Fields
First Steps
Download the template for your Apps and fill in the information you require. If you already have the information in another spreadsheet, we recommend that you organize your information based on the template, to make sure that you have all the fields in your app or create new in case you are missing some.
Note: When possible always use the field name as the column name in your file as it will help the mapping process.
There are different field types available in FreeAgent CRM, if you would like to learn more about them, please visit the following tutorial:
Field Types
Note: It is not necessary to fill out all the fields. In case you don't want to add information for a given field, then remove the column from the file before importing.
Date Time Format
Correctly configuring your date time format is an essential step in the preparation of your import file. FreeAgent uses the international standard (ISO 8601) for the import process. This format allows you to use one sequence to define a date and, when needed, time in a single cell.
The simplest way to remember formatting in this system is to always list your date and time values from largest to smallest.
Date: Year, Month, Day
Time: Hour, Minute, Second
Let's quickly add this format to Microsoft Excel, with largest to smallest values in mind. Navigate to Format Cells > Number > Custom. From here, copy and paste in the following format.
YYYY-MM-DD HH:MM:SS
Click 'Ok' to save and your format is all set for FreeAgent Date Time import. Let's quickly review.
| FORMAT | DESCRIPTION |
| YYYY-MM-DD | Date-only |
| YYYY-MM-DD HH:MM:SS | Date and time, with a space between the date and time. Time is in the 24-hour clock format |
| 00:00 | ISO standard for midnight time |
We'll use March 9th, 2022 at 3:15PM as an example
| 2022-03-09 | Date-only |
| 2022-03-09 15:15 | Date and time. Notice since we do not need to specify seconds, SS can be omitted. Date information is required at minimum for import. |
| 2022-03-09 15:15:30 | Date and time, including value for seconds |
Note: If your organization needs to utilize UTC, add your Z value directly after the time without a space. Z is the zone designator for the zero UTC offset.
Importing Accounts
Follow the recommendations in 'First Steps' section to get your file ready and once you are done, export it as a CSV file. Then go to Import Accounts, click the 'Import Accounts' button.
In the import window, click on the blue rectangle to select your file from your computer's file manager or drag and drop your file and click the 'Next' button.
Field Mapping
The next step is to verify that all the information on your file was Mapped correctly to the Fields in FreeAgent. If you used the template as a base for your file all the information should be mapped correctly. However, if a column wasn't mapped, it will show in red.
You will need to click on the arrow to display the available fields and select one that matches the column or simply select the 'Do Not Import' option if you want to skip it from the import process.
Once you have all your fields correctly mapped, click the 'Save' button.
Import Process
The import process will begin right away. As your CSV file is being processed you will see a 'Processes' column that will populate with the total records that have successfully imported. This is updated in intervals of 1000 during the Import.
The import process will be ready once the Status is 'Completed'.
You will now see the following columns: Processed / Added / Updated / Failed. The Added and Updated columns will show how many records were successfully Added and Updated, you will notice you can click on the value. Click on each column's number to generate a CSV of those records by column.
In the 'Failed' column you may notice some rows have failed to import. This means an import error has happened. To learn more about the most common errors when importing data, please visit the 'Understanding Import Errors' section of this tutorial.
Importing Contacts
Follow the recommendations in 'First Steps' section to get your file ready and once you are done, export it as a CSV file.
When importing your contacts, you can create a relationship between them and their account. Make sure that the Account Name field in your Account App is marked as 'Unique'. This will enable you to use the Account name to create this relationship.
Once you have your file ready, go to your Contacts app and click 'Import Contacts'. Then click the 'Import Contacts' button. In the import window, click on the blue rectangle to select your file from your computer's file manager or drag and drop your file and click the 'Next' button.
The next step is to verify that all the information on your file was Mapped correctly to the Fields in FreeAgent. Review the 'Field Mapping' section of the tutorial for more information.
The import process will begin right away. Review the 'Import process' section of this tutorial for more information.
Importing Opportunities
Follow the recommendations in 'First Steps' section to get your file ready and once you are done, export it as a CSV file.
When importing your opportunities, you can create relationships between them, the main point of contact, and the account.
Make sure that the Account Name field or the one you preferred, in your Account App is marked as 'Unique'. This will enable you to use that field to create this relationship.
In your Contacts App you will need to define a field as 'Unique' as well. The recommended one usually is 'Work Email', but you can use the field that works best for you, just make sure that you include it in your file so that the relationship is created.
Once you have your file ready, go to your Opportunities app and click 'Import Opportunities'. Then click the 'Import Opportunities' button. In the import window, click on the blue rectangle to select your file from your computer's file manager, or drag and drop your file and click the 'Next' button.
The next step is to verify that all the information on your file was Mapped correctly to the Fields in FreeAgent. Review the 'Field Mapping' section of the tutorial for more information.
The import process will begin right away. Review the 'Import process' section of this tutorial for more information.
Importing Lines
To prepare your CSV file, you can download the template available for your Line configuration as described in the "Download CSV Template" section of this tutorial.
The Parent ID column refers to the ID of the record that will contain the Lines. This is the 9 digit system code available for all records. This means that you will need to import the information of the Parent App first in order to be able to import your Lines.
If your Lines include references fields, you will need to use the record ID instead of the name.
Importing Images
Note: In order to import images for the Image field type, you will need to add the URL of the image. If your image is stored on your computer, you will need to upload it to a cloud service in order to get the image URL.
Uploading your image assets to your organization's Google Drive, Microsoft OneDrive, etc. will ensure that the URL you use in this field will continue to host your image, even when that file is updated in your cloud service.
If the image is in your organization's cloud and in a shared folder, make sure the folder it is stored in is set to public.
Understanding Import Errors
As your CSV is being imported, when an error is encountered in a row, this row will fail to Import. The import process will continue and an Error Description column will show the error(s) per row. At the end of the import process you will have the option to retrieve all the Failed rows in a CSV to review and remedy.
You will see Processed / Added / Updated / Failed columns in your Import. Click on 'Failed' to generate a new CSV containing all Failed rows and error description(s) shown conveniently in a new column.
The system will identify the first 1000 errors. If an import reaches that threshold, the import process will be cancelled. The resulting Failed CSV will show the rows that failed along with rows that were unprocessed before failure.
There is no size limit for the CSV file, so this will not be the cause of an import error or failure. However if an import process does not finish within 24 hours, it will automatically timeout. As a rule of thumb, 100K records will process in approximately 3 hours, depending on how many columns your file has. Use these guidelines to decide whether to split a very large file into smaller imports.
Let's look at each of the errors in detail.
Error Description Meanings
"Skipped." This does not signify an error in the row. It means the threshold for errors (1000) has been reached and the import process shut down before this row could be processed. Thus it was skipped.
"The reference value could not be found". This error is usually found in columns that map to Choice List or Reference fields. It means that the value used in that cell of the file doesn't exist in FreeAgent CRM.
In order to solve this error, make sure that the value in your file looks exactly the same as the options in FreeAgent CRM, they are Case Sensitive.
If the Choice or Reference doesn't exist, create it first and then try to import your file again.
"This is not a valid number". This field type expects a number, either an integer or a decimal.
"This is not a valid number: null". If the App you're importing to has any calculated fields and you import into a said calculated field, this error may result.
"This is not a valid date". The date field also expects a specific format. The date should include day, month, and year. The year should include 4 digits. The date should be formatted like this: YYYY-MM-DD e.g. 2020-06-04
"This is not a valid email address". When this error is found, it usually means that the email address is missing the '@' sign or the domain extension (.com, .net, .edu, etc...)
"This is not a valid phone number". The most common cause for this error is including the extension with the phone number. Extensions should be saved in a separate field. The phone number format can include '()' and/or '-'.
"This value violates unique field". This error means that your file contains duplicated information. For this to happen there needs to be a field in your App configured as "unique". The system will validate the information in the system and if the value already exists in any record of your App, it will show this error message.
Special Considerations
- To keep the field mapping process simple for you, make sure the column names are the same as field names. The Field Mapping will try to match column names in your spreadsheet to system field names.
- Beware of extra (blank) columns at the end of your file. These will cause errors.
- The first column should be as populated as possible, not sparse. This may also cause errors.
- Check and make sure all drop-down values exist. Case sensitive. This is true for any Choice List information as well as for Reference values.
- Avoid using the Create Field option when importing. It's best to create the fields before.
- & could get imported as &. So you may want to find/replace &s with and's.
- The importer will update records if the record value is found in the ID column, otherwise, it will create the record.
- Columns with missing headers will also cause the importer to fail.
- Calculated fields are not calculated on import. In order for the calculations to occur, the records need to be updated at least once.
- We recommend not to use apostrophes " ' " within your file, these sometimes cause errors during import.