# Exporting Contacts

Download your contacts as a CSV file.

SendBeam lets you export contacts to a CSV file at any time. Exports are generated on demand
and downloaded directly to your browser.

Exports contain every contact field plus tags, lists and custom fields, making them useful for
backups, migrations to other platforms, offline analysis, or sharing a list with a third-party
tool.

## Exporting from the Contacts page

To export every contact, or every contact matching a search or filter:

1. Navigate to **Contacts** in the left sidebar to open the contacts list.
2. Optionally narrow the list with the search box and the status, tag, list, source and
  date-added filters. Leave them all clear to export everyone.
3. Choose **Export CSV** from the **⋯** menu at the top of the page. A CSV of *all* contacts
  matching the current search and filters downloads — not just the page you are looking at.

> From your own code, `GET /api/v1/contacts/export?q=&status=&tag=&list=&source=&from=&to=`
> returns the same CSV (an API key with `contacts:export` — reading contacts and downloading
> them as a file are separate permissions, so a key with only `contacts:read` can look
> people up and page through them but cannot use this endpoint); `tag` and `list` take
> IDs, `from` and `to` are dates (YYYY-MM-DD). The same seven parameters filter
> `GET /api/v1/contacts`. For a complete copy of the whole workspace —
> lists, templates, campaigns and so on as well as contacts — an admin can download the JSON
> export from [Workspace settings → General → Your data](https://sendbeam.io/docs/admin/settings#your-data).
> 

## Exporting selected contacts

Use the checkboxes to select specific contacts on the page (see
[Bulk Actions](https://sendbeam.io/docs/contacts/bulk-actions) for details on selecting contacts),
then click **Export** in the bulk action toolbar that appears. Only the ticked
contacts are exported, with their tags and custom fields (list memberships are only in the full
export). If you choose **Select all matching** instead, the export uses the full
export with every column.

> Exports are generated fresh each time you request one. If you export now and export again in
> an hour after adding new contacts, the second file will include those additions.
> 

## CSV format and columns

Exported CSV files use standard comma-separated formatting with every value quoted, in UTF-8,
so they open in Excel, Numbers and Google Sheets. A value that begins with `=`,
`+`, `-` or `@` is prefixed with a single quote so the
spreadsheet shows it as text rather than running it as a formula.

The first row is a header row. The columns of the full export are:

- `email` — the contact's email address.
- `first_name` — first name, or empty if not set.
- `last_name` — last name, or empty if not set.
- `status` — subscription status: `subscribed`,
  `unsubscribed`, `bounced`, or `complained`.
- `source` — how the contact was added (e.g. `manual`, `import`, `form`, `api`).
- `tags` — the contact's tag names, separated by semicolons.
- `lists` — the names of the lists the contact belongs to, separated by semicolons.
- `created_at`, `subscribed_at`, `unsubscribed_at` — ISO 8601 timestamps.
- `custom.` — one column per custom field key found on any exported contact, for example `custom.company`.

The selected-rows export has the same shape without the `lists`,
`subscribed_at` and `unsubscribed_at` columns.

## When to use exports

Exports are useful in many common scenarios:

- **Backup** — take a copy of your contacts as a safety net before major changes
  such as bulk deletes or large imports.
- **Platform migration** — if you are moving to or from another email marketing
  tool, an export gives you a portable copy of your subscriber data.
- **Offline analysis** — import the CSV into a spreadsheet or data tool to run
  custom reports on your audience data.
- **Compliance requests** — if a subscriber requests a copy of their data under
  GDPR or similar regulations, search for them, select the row and export it to share with them.

> Exported CSV files contain personal data including email addresses. Store them securely and
> in accordance with your privacy policy. Do not share export files publicly or via unencrypted
> channels. Delete them once they are no longer needed.
>

---
Source: https://sendbeam.io/docs/contacts/exporting