Adding Households in Batch

This guide walks you through creating a batch of households, either by entering them manually or importing from a spreadsheet.

Creating a New Batch

1. Go to Manage > Batches
2. Click Create
3. Give your batch a name (e.g., "Family Import" or "Household Migration")
4. Select the Households tab

Adding Households Manually

Click Add to open the household form. Fill in the required fields and any optional information.

Required Fields

Field	Description
Name	The household's name

General Information

Field	Description
Reference ID	Unique identifier for updates and matching
Tags	Add household tags
Custom Fields	Any custom fields configured for households

Primary Email

Field	Description
Email	Primary email address
Can Email	Allow email communication

Primary Phone

Field	Description
Phone	Primary phone number
Can Call	Allow phone calls
Can Text	Allow text messages

Primary Address

Field	Description
Address Line 1	Street address
Address Line 2	Suite, floor, etc.
City	City name
State	State or province
ZIP Code	Postal code
Country	Country name
Can Mail	Allow postal mail

Editing and Removing Rows

• Edit: Click anywhere on a row to open the form and make changes
• Delete: Click the trash icon on the right side of a row

Importing from Spreadsheet

For large household lists, importing from a spreadsheet is faster:

1. Click Import from Spreadsheet at the bottom of the batch
2. Select your CSV or Excel file
3. Map your columns to the correct fields (if needed)
4. Review the imported rows

See Importing from Spreadsheet for detailed instructions on the import process.

Supported CSV Columns

Below is the full list of columns supported when importing households from a CSV or Excel file.

Required

Column	Description
name	Household name

Contact Info

Column	Description
email	Primary email address
phone	Primary phone number

Address

Column	Description
line1	Street address line 1
line2	Street address line 2
city	City
state	State or province
zipcode	Postal/zip code
country	Country

Preferences

Column	Description
email_can_contact	Allow email communication (0 = no, 1 = yes)
phone_can_call	Allow phone calls (0 = no, 1 = yes)
phone_can_text	Allow text messages (0 = no, 1 = yes)
address_can_contact	Allow postal mail (0 = no, 1 = yes)

Other

Column	Description
reference_id	External or unique identifier for matching and updates
created_at	Creation date (YYYY-MM-DD format, defaults to current date)

Custom Fields (numbered, via column mapping)

Add custom field values using numbered columns:

Column	Description
household_custom_field_1	Value for the first household custom field
household_custom_field_2	Value for the second household custom field

Add more numbered columns (_3, _4, etc.) as needed.

Tags (numbered, via column mapping)

Apply tags using numbered columns:

Column	Description
household_tag_1	Tag name to apply to the household
household_tag_2	Second tag for the household

Add more numbered columns (_3, _4, etc.) as needed.

TIP

Custom fields and tags use numbered suffixes (_1, _2, etc.) and require the column mapping step during import. When you upload your file, map each numbered column to the correct field.

How Households Are Matched

When you upload the spreadsheet, each row is checked against your existing households. reference_id wins over email when both match.

• Row has reference_id matching an existing household → the existing household is updated.
• Row has an email matching an existing household's primary email (no reference_id match) → the existing household is updated.
• Neither matches → a new household is created.

If two or more rows in the same batch share a primary email (and none match an existing household), you'll see a warning like:

"Shares primary email with row 3 (no existing household in this organization). This row will be merged into that household; fields here may overwrite earlier values."

The rows are collapsed into a single new household when you process. Later rows' fields overwrite earlier ones. Use reference_id to keep same-email rows as distinct records.

TIP

Matching happens at upload time. Adding a household through the UI after uploading will not retroactively link batch rows to it. See Importing from Spreadsheet for the full matching flow.

Processing the Batch

When you're ready to finalize:

1. Review all household information
2. Click Process Batch
3. Confirm the action

Important

Batch processing cannot be undone. Once processed, each household becomes a permanent record. Double-check your data before processing.

After Processing

Once processed:

• Households appear in CRM > Households
• Communication preferences are set as specified
• Tags are applied to households
• Custom field values are saved

Tips and Best Practices

1. Include reference IDs - Essential for updating households via future imports
2. Set communication preferences - Respect household contact preferences
3. Use tags - Help organize records for future segmentation
4. Check for duplicates - Review for households that may already exist in your system
5. Validate email addresses - Ensure email formats are correct before importing
6. Test first - Import a small sample before the full file