CSV Import FAQs
What file type can I import?
Only .csv files. Save your spreadsheet as CSV before you start.
Is there a row limit?
Yes. Each import can have up to 50,000 rows. Split larger files into more than one import.
Do my column names need to match the Apricot field names?
No. You match your columns to Apricot fields during Step 2. Columns you do not map are ignored, so you do not need to delete them from your file.
What date formats are accepted?
YYYY-MM-DD, MM-DD-YYYY, MM/DD/YYYY, and YYYY/MM/DD. A date that could be read two ways (for example, 01-02-2026) is read as month first.
What format do other common fields need?
| Field type | Accepted format | Notes |
|---|---|---|
| Date | YYYY-MM-DD, MM-DD-YYYY, MM/DD/YYYY, or YYYY/MM/DD | A date that could be read two ways (for example, 01-02-2026) is read as month first. Also applies to Dropdown Date fields. |
| Phone (US) | ###.###.#### | No country code. Enter 560.358.3574, not 1.560.358.3574. |
| Phone (Global) | Digits only, 10–23 digits | No leading +. |
| Social Security Number | 9 digits in any common format | Dashes, dots, and spaces are removed automatically. |
| Social Insurance Number (CA) | 9 characters | Canadian SIN format. |
| National Insurance Number (UK) | 9 characters, upper case | Example: AB123456C. |
| Zip Code (US) | 5 digits | Do not include ZIP+4. |
| Postal Code (CA) | A1A 1A1 |
|
| Postcode (UK) | UK postcode format | Example: SW1A 1AA. |
| State (US) | 2-letter code | CA, not California. |
| Province (CA) | 2-letter code | ON, not Ontario. |
| Currency | Number with up to 2 decimal places | Symbols and commas are removed automatically. |
| Website | Full URL with https:// | Example: https://example.com. |
| | Standard email format | Example: name@example.com. |
Field type questions
Why did my dropdown or checkbox value fail?
Some field types store each option as a label (what the user sees) and a code. Your CSV must use the code. To see the allowed values for a form, go to the Imports home page and open the form from the forms list.
| Field type | What to enter in your CSV |
|---|---|
| Dropdown, Radio Buttons, Multi-Select, Checkbox | The option value exactly as it appears in the form. Case matters. |
| Milestone | The short code (up to 2 characters), not the milestone name. |
| Likert Scale | The numeric code, not the label. |
| Masked Dropdown, Masked Radio Buttons, Masked Checkbox | The backend value (the part the user does not see). Case matters. |
How do I enter more than one value in a field?
Separate values with a pipe (|): value1|value2|value3. This applies to Multi-Select, Checkbox, Masked Checkbox, and User List fields.
-
Do not put spaces around the pipe. value1 | value2 will fail.
-
Do not repeat a value. value1|value1 will fail.
How do I import Name and Address fields?
Each part needs its own column.
| Field type | Columns needed | Notes |
|---|---|---|
| Name | first, last (and optionally middle) | If the field is required, both first and last need values. Each part is limited to 64 characters. |
| Address | line1 (and optionally line2) | If required, line1 needs a value. |
| Address Lookup | line1, line2, neighborhood, city, state, county, zip, country | Only the parts marked required on the form need values. |
Why is a field greyed out in the mapping list?
For Date, Dropdown Date, and Numeric fields, Apricot turns the field off if more than 50% of the values in your column do not match the expected format. Fix the column in your file and start a new import.
Why is a field missing from the mapping list?
It is probably deactivated on the form. Deactivated fields are hidden. An Apricot Administrator needs to reactivate the field on the form first.
Updating records
What do I need to update existing records?
Your file must include a column with the Apricot record IDs. It must also include values for every required field on the form — not just the fields you are changing. If a required field is missing from your file, that row will fail even if the field already has a value in Apricot.
Which record IDs do I need?
| Action | Your CSV must include |
|---|---|
| Create a T1 record | No record ID needed |
| Create a T2 record | The T1 record ID it should attach to |
| Update a T1 record | The T1 record ID |
| Update a T2 record | The T1 record ID and the T2 record ID |
Record IDs are assigned by Apricot. If you do not have them, export the records from Apricot before you import.
Programs and validation
Can I assign records to more than one program?
Not in one import. You can assign records to one program per import. If records belong to several programs, run a separate import for each additional program.
What happens if I leave a required field blank?
It depends on the form:
-
If the form does not allow draft records, the row cannot be imported until the value is added.
-
If the form allows draft records, the row imports as a draft record. You can complete and publish it later.
Why did a row fail after I already submitted the import?
Validation runs in two passes. The first pass happens before you submit, in Step 4. The second pass runs while Apricot processes the import in the background. If any rows fail the second pass, open the import from the import history list to review and resubmit them.
Legacy import tool
Can I manage a legacy import from the new tool?
No. Both tools show import history, but an import started in the legacy tool can only be managed from the legacy tool, and an import started in the new tool can only be managed from the new tool.
When should I still use the legacy import tool?
Use the legacy tool if you need to:
-
Revert or undo a completed import
-
Import program enrollments
-
Run bulk imports, use SFTP, or set up automated, scheduled imports
-
Import into field types the new tool does not yet support: linking fields (Link, Target Link), Append Only text, Dynamic Dropdown and Dynamic Checkbox, Smart List, file uploads, client photos, images, signatures, and calculated fields
Why did my Apricot import fail validation | How do I separate multiple values in an Apricot CSV import | What date format does Apricot import accept | How do I import Name and Address fields in Apricot | Why is a field greyed out in Apricot import | Can I import into more than one program in Apricot | When should I use the legacy import tool in Apricot | How do I update existing records in Apricot with a CSV