Importing People

Import people in bulk by uploading a CSV file. This is the most efficient way to add many people at once or update existing profiles with new data.

---

Preparing your CSV file

Before importing, prepare your CSV file with the following:

Required columns

Your CSV must include at least one identifier column:

• ID - A unique external identifier for each person, or
• Email - A valid email address for each person

Optional columns

You can include any of these standard fields:

• first_name - Person's first name
• last_name - Person's last name
• email - Email address (if not using as identifier)

Custom attributes

You can add any additional columns for custom attributes. For example:

• subscription_tier
• signup_date
• total_orders
• favorite_category

Any column that isn't a standard field will be stored as a custom attribute.

---

CSV file format

Your CSV file should:

• Have a header row with column names
• Use commas to separate values
• Enclose values containing commas in quotes
• Use UTF-8 encoding
• Not exceed the maximum file size limit

Example CSV

id,email,first_name,last_name,subscription_tier,signup_date
user_001,[email protected],Alice,Smith,premium,2024-01-15
user_002,[email protected],Bob,Jones,free,2024-02-20
user_003,[email protected],Charlie,Brown,premium,2024-03-10

---

Downloading a sample file

Before creating your CSV, you can download a sample file to see the correct format:

1. Go to People and click Add people
2. Click Download sample sheet
3. Use this as a template for your own CSV file

---

Import process

Step 1: Upload CSV

1. Go to People and click Add people
2. Choose how you want to identify people:
   • ID - Use the id column as the identifier
   • Email - Use the email column as the identifier
3. Click to upload your CSV file or drag and drop it
4. Wait for the file to be processed

Step 2: Configure import settings

After uploading, configure how the import should handle your data:

Import name and description

• Import name - Give your import a name (defaults to the filename)
• Description - Optional description for your records

New profile data

Choose what to do with people who don't exist yet:

• Create new profiles - Add new people to your workspace
• Skip new profiles - Only update existing people, skip new ones

Existing profile data

Choose what to do with people who already exist:

• Update existing profiles - Update their attributes with new data
• Skip existing profiles - Leave existing people unchanged

Empty values

When updating existing profiles:

• Delete empty values - Remove attributes that are empty in your CSV
• Keep existing values - Preserve existing attribute values if CSV has empty values

Step 3: Preview and review

Before completing the import:

1. Review the preview table showing sample rows from your CSV
2. Check the summary:
   • Total records to import
   • Number of columns
   • Preview of first 10 records
3. Verify that your data looks correct

Step 4: Complete the import

1. Click Complete import to start the process
2. For large files, processing happens in the background
3. You'll receive an email notification when processing is complete
4. For smaller files, you'll see immediate results with a summary

---

Import results

After the import completes, you'll see:

• Total records processed - How many rows were imported
• New profiles created - Number of new people added
• Existing profiles updated - Number of people updated
• Errors - Any rows that couldn't be processed (with error details)

Handling errors

If some rows have errors:

• Review the error messages to understand what went wrong
• Fix the issues in your CSV file
• Re-import the corrected file

Common errors include:

• Missing required identifier (ID or email)
• Invalid email format
• Duplicate identifiers
• Data type mismatches

---

Large file imports

For very large CSV files:

• Processing happens in the background
• You'll receive an email when the import is complete
• You can continue working while the import processes
• Check the import status in your notifications

---

Importing to segments

You can also import people directly into a segment:

1. Go to the segment you want to add people to
2. Click Add people from the segment page
3. Follow the same import process
4. People will be imported and automatically added to the segment

---

Best practices

1. Validate your data first - Check for duplicate IDs/emails and invalid formats
2. Use consistent identifiers - Always use the same ID or email for the same person
3. Include email when possible - Enables email messaging capabilities
4. Test with a small file first - Import a few rows to verify your format
5. Keep backups - Save your original CSV files before importing
6. Review preview carefully - Check the preview table before completing the import
7. Handle errors promptly - Fix and re-import any rows with errors

---

CSV column mapping

The system automatically maps CSV columns to person fields. You can use common naming variations (e.g. firstName, First Name, email_address) as column headers—they are normalized internally.

CSV Column	Person Field	Notes
id	External ID	Required if using ID as identifier
email	Email	Required if using email as identifier
first_name	First Name	Optional
last_name	Last Name	Optional
Any other column	Custom Attribute	Stored as attribute with column name as key

For the complete list of accepted field names, format requirements (including E.164 for phone), and examples, see Person Field Mapping.

---

Updating existing people

When importing data for existing people:

• New attributes are added to their profile
• Existing attributes are updated with new values
• Empty values can delete attributes if configured
• The person's updated_at timestamp is refreshed

This ensures your person data stays synchronized with your source systems.

---

🎉 Import complete!
Your people have been imported and are now available in your workspace. You can view them in the People table, add them to segments, and include them in campaigns.