Importing Members

Need to add many members at once? The CSV import lets you bulk-create or update members from a spreadsheet, including their contact info, labels, notification preferences, and form data.

CSV Import (UI)

1. Go to People → Members
2. Click the Import button
3. Select your CSV file
4. Choose a role for any newly created members
5. Review the import preview
6. Click Confirm to import

CSV Format

Your file must be a standard CSV with headers in the first row. At minimum, each row needs one of: email, phone, or external_id.

csv

Column Reference

Including Form Data

To populate form records during import, add columns using dot notation: form.{data_type_slug}.{field_slug}.

csv

The data type and field slugs must match what's configured in your workspace under Knowledge → Forms.

Limits

• Maximum 10,000 rows per import
• Maximum 10 MB file size

Bulk Import via API

For automated or recurring imports, use the API endpoint directly:

bash

The API streams progress as NDJSON so you can track large imports:

json

To find the newMemberRoleId, list your roles at GET /api/v2/w/{workspace_uuid}/member-roles or check People → Roles in the admin.

For creating individual members with associated data records in one call, see the Importing Members developer guide which covers the /create-signup endpoint.

Duplicates and Update-vs-Create

The import matches existing members by email or phone number:

• New member — If no match is found, a new member is created with the role you selected
• Existing member — If a match is found, the member's fields are updated with the values from the CSV (blank cells are skipped, not cleared)
• Role preserved — Existing members keep their current role; the selected role only applies to new members

This means you can safely re-import the same file after making edits — existing members get updated, and new rows create new members.

Using External IDs

If your members originate from another system (CRM, EHR, etc.), populate the external_id column with your system's user ID. This makes it easy to:

• Look up members by your system's ID via the API
• Keep members in sync across repeated imports
• Track which members correspond to records in your other systems

Validation Errors and Troubleshooting

Common Errors

Tips

• Check your encoding — Save CSV files as UTF-8 to avoid garbled characters
• Trim whitespace — Leading/trailing spaces in emails or phone numbers cause validation failures
• Preview first — The import UI shows a preview before committing; review it for unexpected data in the wrong columns
• Export then edit — If updating existing members, export your current member list first (GET /api/v2/w/{workspace_uuid}/members/export), edit the CSV, then re-import

Best Practices

• Start small — Test with 5-10 rows before importing thousands
• Use external IDs — They make re-imports and API lookups much easier
• Normalize phone numbers — Always use E.164 format (+ followed by country code and number, no spaces or dashes)
• Create labels first — Set up any labels you reference in the CSV before importing
• Set up forms first — If including form data columns, make sure the data types and fields exist in your workspace
• Keep a backup — Save your original CSV before editing, in case you need to start over