Importing & Exporting Contacts

Synapse gives you several ways to get contacts into and out of your workspace. You can import contacts in bulk via the API, and export them as CSV or JSON files from the dashboard.

Importing Contacts via API

The bulk import endpoint lets you create or update up to 1,000 contacts per request. Each contact is identified by its external_id -- if a contact with that ID already exists, it will be updated instead of duplicated.

Required Fields

Every contact must have an external_id. All other fields are optional:

Field	Type	Max Length	Description
external_id	String	255	Your system's unique identifier for the contact (required)
email	String	255	Email address
phone	String	50	Phone number
first_name	String	255	First name
last_name	String	255	Last name
product_type	String	50	Product or plan type
subscription_status	String	20	One of: subscribed, unsubscribed, bounced, complained
timezone	String	50	IANA timezone (e.g., America/New_York)
locale	String	10	Language/locale code (e.g., en-US)
properties	Object	--	Custom key-value pairs
tags	Array	--	List of string tags

Conflict Handling

When an imported contact matches an existing external_id, you choose what happens:

Mode	Behavior
merge (default)	Shallow-merges properties and updates only the fields you provide. Existing fields you don't include are left unchanged.
skip	Leaves the existing contact untouched. Only new contacts are created.
replace	Overwrites the entire contact with the imported data.

What You Get Back

The API returns a summary of the operation:

Field	Description
total	Number of contacts in the request
created	How many were newly created
updated	How many existing contacts were updated
skipped	How many were skipped (due to conflict mode or errors)
errors	A list of per-item errors, each with the index, external_id, and error message

Tip

The bulk endpoint supports partial success. If 3 out of 1,000 contacts have validation errors, the other 997 will still be imported. Check the errors array to see which ones failed and why.

Warning

The import limit is 1,000 contacts per request. If you have more, split them into multiple requests. Your plan's total contact limit still applies -- if you're near your limit, only new contacts that fit within the limit will be created.

Looking for the API details? See API Reference for the full endpoint specification.

Exporting Contacts

You can export contacts from the dashboard in CSV or JSON format.

How to Export

Go to Contacts in the dashboard sidebar.
Select the contacts you want to export, or use filters to narrow down the list.
Click the Export button.
Choose your settings:

Option	Choices	Description
Format	CSV, JSON	The file format for the export
Scope	Selected, Filtered, All	Which contacts to include
Columns	All or specific	Choose which fields to include in the export
Include properties	Yes / No	Whether to flatten custom properties into individual columns

Export Behavior

Synapse handles exports differently depending on the size:

Contact Count	Behavior
5,000 or fewer	Instant download -- the file streams directly to your browser
More than 5,000	Background export -- you'll receive a job ID to check progress

For large exports, the system creates an async job. You can check the status and download the file once it's ready. Export files are available for 24 hours after creation.

Note

Exporting contacts requires the contacts:read permission. Owners, Admins, Developers, Marketing, and Operations roles all have this permission. Viewers cannot export contacts.

CSV Format for Imports

If you're preparing a CSV file to import via the API, here's the expected structure:

external_id,email,first_name,last_name,phone,product_type,subscription_status,timezone,locale

user_001,[email protected],Alice,Smith,+1-555-0100,premium,subscribed,America/New_York,en-US

user_002,[email protected],Bob,Jones,,starter,subscribed,Europe/London,en-GB

user_003,[email protected],Carol,,,free,subscribed,,

CSV Rules

The first row must be a header row with field names matching the schema above.
external_id is required for every row.
Empty cells are treated as null (the field will not be set or updated).
Custom properties and tags are not supported in CSV format -- use the JSON API for those.
Use UTF-8 encoding.
Strings containing commas should be wrapped in double quotes.

Tip

The easiest way to prepare a CSV is to export your existing contacts first. The exported CSV has the exact format Synapse expects, so you can use it as a template.

Bulk Actions

Beyond import and export, the dashboard supports bulk actions on selected contacts:

Action	Description
Delete	Permanently removes the selected contacts
Update status	Changes the subscription status (subscribed, unsubscribed, bounced, complained)
Export	Exports the selected contacts as a file

To use bulk actions:

Select contacts using the checkboxes, or use Select All to target all contacts matching your current filters.
Click the Bulk Actions menu.
Choose an action and confirm.

Warning

Bulk delete is permanent. There is no undo. Consider exporting contacts before deleting them if you might need the data later.

Next Steps

Managing Contacts -- search, filter, and organize your contacts
Contact Properties -- understand custom properties and how to use them
Building Segments -- create targeted groups from your contacts