Contacts
Importing contacts
API batches, CSV, sample data, export, and erasure.
There are three ways people enter a project. Pick one source of truth and keep IDs stable. Mixing anonymous CSV rows with later API upserts without externalId creates duplicates.
API (recommended)
POST /v1/projects/{projectId}/contact_ingestion
- Scope:
write - Up to 5,000 contacts per call; batches of a few hundred are easier
to retry
- Upsert on
externalId(your user id) or email - Properties use schema keys (
plan, not “Plan”)
See Contacts API and Contacts & events.
CSV
Data → Import uploads a spreadsheet for a one-off backfill.
- Include an email column.
- Map columns onto existing fields or allow a new field (it arrives as
proposed).
- Review the import result (created / updated / errors).
- Record consent separately if these
people should receive marketing mail. A CSV of customers is not consent evidence.
Large files are processed asynchronously. Stay on the import list until the job finishes; a partial failure should be retried only for the failed rows.
Sample dataset
New projects can load a sample dataset from Data to click through audiences and the editor before production sync exists. Replace it with real externalIds before any live send.
Export and erasure
Export downloads contacts you are allowed to see (GDPR-style portability). Erase on a contact profile permanently removes personal data and takes them off Contacts. An anonymous suppression remains so they are not emailed again if the same address comes back. Erasure is logged in the audit trail.