# CSV & copy-paste import

Import contacts from a CSV file or by pasting rows from a spreadsheet: the file format and limits, the step-by-step wizard, how to update an existing import by re-uploading, and how to set marketing consent as you import.

**Language:** en
**Audience:** platform
**TLDR:** Upload a .csv file (up to 20 MB, UTF-8, header row first) or paste rows from Excel or any spreadsheet (up to 10,000 lines) under Data sources; the wizard detects the format, maps columns to attributes, resolves duplicates and finishes once you add at least one tag. Phones use international format (Default country fills missing prefixes). To refresh the import later, re-upload a file with the same key field.
**Translation key:** platform.data-sources.csv-copy-paste
**Search keywords:** Excel, upload list, no contacts yet, CSV, CSV import, import contacts, copy and paste, paste contacts, spreadsheet, update CSV, re-upload, delete absent, file format, UTF-8, phone format, import wizard, mapping, deduplication, tags, import consent, subscription status
**Related pages:** /platform/es/data-sources/csv-copy-paste, /platform/en/data-sources, /platform/en/data-sources/managing, /platform/en/consent, /platform/en/consent/subscription-attributes
**Docs index (every page):** https://docs.instasent.com/llms.txt
**This zone's index:** https://docs.instasent.com/platform/en/llms.txt
**This page:** https://docs.instasent.com/platform/en/data-sources/csv-copy-paste/ (HTML) · https://docs.instasent.com/platform/en/data-sources/csv-copy-paste.md (Markdown)
**Other language (es):** https://docs.instasent.com/platform/es/data-sources/csv-copy-paste.md

Uploading a CSV or pasting rows from a spreadsheet is the manual way to bring
contacts into a project. Both run through the same import wizard and produce a data
source you can refresh later. This page covers the file format, the wizard steps,
updating an existing import, and — important — how to set each contact's marketing
consent as you import.

## CSV file format

A few rules keep an import clean:

| Requirement   | Detail                                                                            |
| ------------- | --------------------------------------------------------------------------------- |
| File size     | Up to **20 MB**                                                                   |
| Encoding      | UTF-8 (auto-detected; a warning shows if the file isn't UTF-8)                    |
| Separator     | Auto-detected (the template uses `;`)                                             |
| First row     | Column headers                                                                    |
| Phone numbers | International format, mapped to `_phone_mobile` with a **Default country** picker |

The wizard auto-detects the encoding and separator, so in most cases you only have
to confirm. Phone numbers map to the `_phone_mobile` attribute; if some rows lack a
country prefix, the **Default country** picker fills it in.

Row counts are a **warning, not a hard limit**: at **100,000 or more** rows in a file
(or **5,000** in a paste) the panel flags the size, but the import can still run.

![The CSV import wizard mapping step, matching each source column to a contact attribute](/platform/en/data-sources/images/csv-copy-paste--1-mapping-step.png)
*The mapping step: each source column is matched to a contact attribute, with a preview of its values.*

## The import wizard

The wizard walks through up to five steps, some skipped automatically when they
don't apply:

#### 1. Upload

Choose the `.csv` file. The panel parses it, detects encoding and separator, and
previews the rows.

#### 2. Mapping

Map each column to an Instasent attribute — match an existing one, create a new
attribute, or ignore the column. See
[field mapping](/platform/en/data-sources/managing#field-mapping).

#### 3. Key field

Pick the identifier that decides who is who. Skipped if the project isn't active
yet.

#### 4. Merge

Resolve duplicates. Shown only when email or phone aren't unique in your data.

#### 5. Tags

Add at least one tag to finish; the tags label the contacts this import brings in.

Invalid rows are surfaced as warnings with a preview, not rejected outright — you
see what's wrong and decide whether to proceed.

## Updating an existing import

To refresh a previous CSV import, re-upload a file with the **same key field and
mapped fields**. This update wizard has three steps — select the source, upload the
new file, and configure the update:

- **Update existing** — contacts already present are updated. Always on.
- **Create new** — contacts not seen before are added. Always on.
- **Delete absent** — a toggle (**off** by default). When on, contacts missing from
  the new file are removed from the source.

You can keep existing tags or add new ones (up to 38 characters each).

> **Warning**: **Delete absent** removes contacts that aren't in the re-uploaded file from this
> source — and a contact left with no data from any other source is removed entirely,
> as when [deleting a source](/platform/en/data-sources/managing#deleting-a-data-source).
> Leave it off unless the new file is a complete, authoritative list.

## Copy and paste

Copy and paste uses the same wizard, but instead of a file you paste delimited text
(from Excel or a CSV) into a text area. The first row is the headers, just like a
file. The limit is **10,000 lines**, and the source is named
`copy-paste-YYYY-MM-DD.HH-mm` by default.

## Importing consent

An import can set each contact's **marketing consent**, not just their attributes —
and getting this right is essential, because an import can otherwise overwrite a
contact's real preference.

There are two ways to bring consent in:

- **A regular CSV** can map columns to the consent attributes directly, the same as
  any other attribute.
- **The dedicated marketing-preferences flow** is a purpose-built import for consent
  state. Its template (`unsubscribed_users.csv`) has the columns
  `_phone_mobile`, `_email`, `_is_subscribed_sms`, `_accepts_marketing_sms` and the
  matching `_email`, `_rcs` and `_whatsapp` variants.

In both cases the values are `true` / `false`, and an **empty cell means "no
change"** — it leaves the contact's existing value untouched rather than resetting
it. When a column isn't provided at all, the defaults apply:
`_accepts_marketing_*` defaults to **no preference** (`null`) and `_is_subscribed_*`
defaults to **subscribed** (`true`).

> **Warning**: Only set `_accepts_marketing_*` to **false** when the contact has **actively
> declined** marketing. "No data" or "never expressed a preference" must stay **no
> preference**, never `false`. Importing a blanket `false` opts people out who never
> declined. The full rules are in
> [Consent](/platform/en/consent/marketing-preference-vs-suppression).

For what each consent attribute means and how the values combine, see
[Subscription attributes](/platform/en/consent/subscription-attributes).

{/* VERIFY: the marketing-preferences template includes `_*_rcs` columns, but the backend doc states RCS shares the SMS consent attributes (no RCS-specific set). Confirm whether RCS columns are honoured or map onto the SMS attributes. */}

---

This is one page of the Instasent documentation. For the complete machine-readable index of every guide and API reference, fetch https://docs.instasent.com/llms.txt — start there for full context.