> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retellai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose contacts

> Upload a call list CSV or auto-enroll contacts into an outbound campaign with Retell AI: filter contacts, map file columns, and call new matches automatically.

A Standard campaign calls a fixed list: contacts you select with a filter, or a CSV or XLSX file you upload. An Auto-enroll campaign calls every contact that matches your conditions at launch, and every contact that comes to match them later.

You choose contacts on the campaign's **Contacts** tab. You pick the campaign type when you create the campaign (see [Standard and Auto-enroll campaigns](https://docs.retellai.com/dialer/overview.md#standard-and-auto-enroll-campaigns)). After you choose contacts, click **Continue** to set up the [compliance checks](https://docs.retellai.com/dialer/compliance-checks.md) that screen each contact before its first dial.

Every campaign contact is a record in your workspace [Contacts](https://docs.retellai.com/features/contacts.md), keyed by phone number.

## Standard campaigns

A Standard campaign gets its contacts in one of two ways, never both:

* **Filter** the contacts already in your workspace.
* **Upload** one CSV or XLSX file. The upload adds the file's rows to your workspace Contacts, and the campaign calls exactly those contacts.

**Upload CSV or XLSX** is hidden while a filter exists. To switch from a filter to a file, open **Filter contacts**, remove every row, and click **Continue**.

### Filter your contacts

**1. Open the filter**

On the **Contacts** tab, click **Filter contacts**.

**2. Add conditions**

In each row, pick a field, an operator, and a value. Click **Add filter** for another row. A contact must match every row.

**3. Apply**

Click **Continue**. The table lists every matching contact, 20 per page.

![Contacts tab of a Standard campaign with the description that contacts matching your filters are included by default and you can uncheck any you don't want to dial. A Filter contacts button sits at the top right. The table lists checked rows with columns Phone, Name, Contact ID, Related Conversations, Latest Conversation, External ID, and a Company custom field.](https://mintcdn.com/retellai/vuwPMEb2Qq5g6X0u/images/dialer/dialer-contacts-standard.png?fit=max\&auto=format\&n=vuwPMEb2Qq5g6X0u\&q=85\&s=f79b67bcac06987987eea11459d7924b)

A Standard campaign's Contacts tab, listing the contacts that match its filter.

You can filter on these fields:

| Field | Operators | Notes |
| - | - | - |
| **Phone number** | equals, does not equal, contains, starts with, ends with | Numbers are stored in E.164 format. To match an area code, use **starts with** `+1415`, not `415` or `(415)`. |
| **Do not call** | equals `true` or `false` | A contact with no value counts as `false`. |
| **Tags** | is any of | Listed once your workspace has tags. |
| Text custom fields | equals, does not equal, contains, starts with, ends with | |
| Number custom fields | equals, does not equal, greater than, greater than or equal, less than, less than or equal | |
| Boolean custom fields | equals `true` or `false` | |
| Selector custom fields | is any of | |

Conditions follow these rules:

* **All conditions must match.** There's no OR between rows. To accept several values of one field, use **is any of** on a Tags or Selector field.
* **Text matching is case-sensitive.** `Mission` doesn't match `mission`.
* **A missing value never matches.** A contact with no value in a field fails every condition on that field, including **does not equal**. **Do not call** is the exception.
* **Some fields aren't available.** You can't filter on first name, last name, or Date and Datetime fields.
* **Phone number, Do not call, and Tags take one row each.** A custom field can take several rows, for example `balance_due` greater than `100` and less than `500`.

[Auto-enroll campaigns](#auto-enroll-campaigns) use the same conditions.

### Upload a CSV or XLSX file

**1. Pick the file**

On the **Contacts** tab, click **Upload CSV or XLSX** and choose a file. If a workbook has more than one sheet, select the worksheet to import. The preview shows the row count. Click **Continue**.

**2. Map the columns**

Select the columns to import and map each one to a contact field. A column whose header matches a field name, such as `first_name`, maps automatically. Map exactly one column to **Phone Number**. To store a column that has no field yet, create one from the mapping list.

**3. Set the default country**

Under **Phone number formatting**, choose the country for numbers that don't include a country code. It defaults to the United States.

**4. Confirm**

Click **Confirm**. The dashboard checks every value first. If one doesn't fit its field, you see "Invalid value · Row N" with the column and the expected format. Fix the file, map the column to another field, or unselect it. Then the import runs, and the table fills in when it finishes.

The file must meet these requirements (as of October 2026):

| Requirement | Value |
| - | - |
| File type | `.csv` or `.xlsx` |
| File size | Up to 50 MB |
| Rows | Up to 50,000 data rows. The dashboard doesn't count rows up front. A larger file fails after you confirm, with "1 contact failed to import", and nothing imports. |
| Header | The first row holds the column names. Each selected column needs a unique name. |
| Phone number | Exactly one column, mapped to **Phone Number**. A row whose phone number is missing or can't be read doesn't import. Extensions such as `x123` are dropped. |
| Mapped columns | Up to 200 |

Each value must match the type of the contact field it maps to:

| Contact field type | Accepted values |
| - | - |
| Text | Any text |
| Number | A number, such as `42` or `19.99` |
| Boolean, including **Do Not Call** | `true`, `false`, `1`, or `0`, in any case |
| Date or Datetime | `2026-11-12`, `11/12/2026`, `2026/11/12`, or an ISO 8601 timestamp such as `2026-11-12T15:30:00Z` |
| Selector | Exactly one of the field's options, with the same capitalization |

An empty cell, or one that reads `null`, is skipped. Retell checks the values again when it runs the import. A row that fails that check is skipped, and the result banner counts it as failed.

Here's a short file for a dental reminder campaign. The last two rows show phone numbers without a country code, which the default country fills in:

```csv theme={"dark"}
phone_number,first_name,last_name,clinic,balance_due
+14155550101,Ada,Lovelace,Mission,0
(415) 555-0102,Alan,Turing,Sunset,45.50
4155550103,Grace,Hopper,Mission,120
```

With `clinic` mapped to a Text field, the agent's prompt can say `Hi {{first_name}}, this is Bright Smile Dental at our {{clinic}} office.` See [Use contact fields in the agent's prompt](#use-contact-fields-in-the-agents-prompt).

#### What the upload changes in your Contacts

The upload is a normal [contact import](https://docs.retellai.com/features/contacts.md#import-from-csv-or-xlsx), so it writes to your workspace Contacts:

* **Rows match by phone number.** A number that already has a contact updates that contact. A new number creates one. Numbers are formatted first, so `(415) 555-0102` and `+14155550102` are the same contact.
* **Blank cells don't clear values.** An existing contact keeps any value your file leaves empty, and any field you don't map.
* **Do Not Call can be set but not cleared.** `true` marks the contact as [do-not-call](https://docs.retellai.com/build/do-not-call.md). `false` never removes an existing mark. Clear it on the [Contacts](https://docs.retellai.com/features/contacts.md) page instead.
* **The contacts stay.** Replacing the file or deleting the campaign doesn't remove contacts that an upload created or updated.
* **Each upload adds a hidden tag.** Retell tags every contact in the file with a new tag that the dashboard doesn't show, and the campaign filters on it. A workspace can hold up to 1,000 contact tags, so heavy re-uploading can reach the limit.
* **Running Auto-enroll campaigns see the changes.** An uploaded contact that matches an Auto-enroll campaign's conditions enrolls in that campaign too. See [When contacts enroll](#when-contacts-enroll).

Only one contact import runs at a time per workspace. If another is running, wait for it to finish.

Uploading needs CRM write access, the permission to edit workspace Contacts. Admins and Developers have it. Members don't, and a custom role has it only if it includes CRM write permission. **Upload CSV or XLSX** is disabled without it, with "You need CRM write access to do this." To get it, ask an Admin to change your role:

1. Go to **Settings** → **Workspace** → **Users**.
2. Open the menu on your row and click **Edit Roles**.
3. Pick **Developer**, **Admin**, or a custom role with CRM write permission.

See [access control](https://docs.retellai.com/accounts/access-control.md) for what each role can do.

To use a different file, click **Edit upload** and replace it. Replacing the file restores any rows you excluded. To go back to a filter, remove the file in **Edit upload**.

### Exclude contacts

Every matching contact is included by default. To leave one out, uncheck its row. There's no select-all, so to drop many contacts, narrow the filter or the file instead. Click **Restore excluded** to bring every excluded contact back.

### When the list is fixed

Until launch, the list is a live filter. Contacts that are created or updated to match appear in the table, and the count changes.

At launch, Retell takes a snapshot. Every contact that matches at that moment, minus the ones you excluded, enrolls in the campaign. For a scheduled campaign, the snapshot happens when you launch, not at the start time. Contacts that match later never join a Standard campaign. To keep adding contacts, use an [Auto-enroll campaign](#auto-enroll-campaigns).

Each phone number enrolls once. A number that appears in several rows of your file is one contact, so it's called once, and the later row's values win. If the earlier row had a value that the later row leaves blank, whether it survives depends on where the rows fall in the file. Keep one row per number so you know which values the agent gets.

A campaign can hold up to 100,000 contacts (as of October 2026). Launch stops with one of these messages:

| Message | What to do |
| - | - |
| "Choose contacts before launching this campaign." | Add a filter or upload a file. |
| "Add contacts before launching this campaign." | Change the filter or file. It matches no contacts. |
| "The campaign exceeds the 100,000 contact limit." | Narrow the filter, or split the list across two campaigns. |

## Auto-enroll campaigns

An Auto-enroll campaign's **Contacts** tab opens **Setup Trigger**, which has three parts:

* **When to enroll**: contacts enroll automatically when they're created or updated.
* **Who to enroll**: your conditions. Click **Add filter** to add a row. They work exactly like the [Standard campaign filter](#filter-your-contacts).
* **Enrollment**: a live count, such as "1,240 contacts match right now." That's how many contacts would enroll if you launched now, before compliance checks.

An Auto-enroll campaign needs at least one condition to launch.

![Setup Trigger with three connected cards. When to enroll reads: Contacts enroll automatically when they're created or updated. Who to enroll has two condition rows, Where Country is any of United States, and And Form equals Outbound Sales, with an Add filter button. Enrollment reads: 1,284 contacts match right now.](https://mintcdn.com/retellai/vuwPMEb2Qq5g6X0u/images/dialer/dialer-auto-enroll-trigger.png?fit=max\&auto=format\&n=vuwPMEb2Qq5g6X0u\&q=85\&s=e31b532d7b29ec90b4c33d9b8e8bfce5)

Setup Trigger for an Auto-enroll campaign with two conditions.

For example, a home-services company syncs web leads from its CRM with the tag `web-lead`. Its Auto-enroll campaign uses one condition, **Tags** is any of `web-lead`, so each new lead enrolls as soon as it syncs. The campaign's Interested outcome [writes](https://docs.retellai.com/dialer/sequences.md) `qualified` to a `lead_status` contact field. A second Auto-enroll campaign with the condition `lead_status` equals `qualified` then enrolls the lead for a follow-up with a different agent.

### When contacts enroll

At launch, every contact that matches enrolls. After launch, Retell checks a contact against your conditions when the contact is created, and when an update changes a field your conditions use. These changes count:

* Edits on the [Contacts](https://docs.retellai.com/features/contacts.md) page or through the API.
* Contact imports, including uploads to a Standard campaign.
* [CRM sync](https://docs.retellai.com/integrations/crm-overview.md).
* Field writes after a phone call or SMS chat, such as [Post Call Extraction](https://docs.retellai.com/features/post-call-analysis-overview.md) mappings and campaign outcomes that save to a contact field.
* [Backfills from past conversations](https://docs.retellai.com/features/contacts.md#backfill-fields-from-past-conversations), which can enroll many contacts at once.

Web calls and web chats have no phone number, so they never create or update a contact.

> [!WARNING]
>
> Every phone call or SMS chat with a new number creates a contact. If a brand-new contact meets your conditions, as it does with **Do not call** equals `false` on its own, the campaign enrolls and calls every new number your agents talk to. Base conditions on a tag or a field you set on purpose.

A new match enrolls right away with the stage **Validating**. Its compliance checks usually run within about 5 minutes, and then it's scheduled for its first attempt in its calling window. If the screening provider is unavailable, Retell retries, and the contact can stay in **Validating** for up to a day before it fails.

### Enrollment rules

* **Once per campaign, ever.** A contact that finished, stopped, or failed in a campaign never enrolls in that campaign again, even if it matches again. To call it again, use a new campaign.
* **No removal when a contact stops matching.** A contact stays enrolled after its fields change. To end its calls, use **Stop contact** on the [campaign page](https://docs.retellai.com/dialer/overview.md#monitor-a-campaign).
* **Overlapping campaigns both call.** If a contact matches two campaigns, it enrolls in both, and both call it. Keep the conditions of related campaigns mutually exclusive, for example with different tags.
* **Paused campaigns keep enrolling.** Scheduled, running, and paused campaigns enroll new matches. A paused campaign dials them after you resume it. A stopped campaign enrolls no one.
* **The campaign doesn't end on its own.** It runs until you stop it.
* **Up to 100,000 enrollments** (as of October 2026). The count includes every contact that ever enrolled, including contacts that failed a compliance check. After that, new matches don't enroll. Launch is blocked if more than 100,000 contacts match at launch.
* **Conditions lock at launch.** To change them, [duplicate the campaign](https://docs.retellai.com/dialer/overview.md#pause-stop-duplicate-or-delete) with **Settings + contacts**, edit the copy's conditions, and launch it. **Just settings** starts the copy with no conditions.
* **There's no exclusion list.** To keep contacts out, add a condition that rules them out.

## Use contact fields in the agent's prompt

Each call or SMS in a campaign passes the contact's fields to the agent as [dynamic variables](https://docs.retellai.com/build/dynamic-variables.md):

* `{{first_name}}`, `{{last_name}}`, and `{{do_not_call}}`
* `{{contact_memory}}`, when the contact has [contact memory](https://docs.retellai.com/features/contact-memory.md)
* One variable per custom contact field, named after the field, such as `{{clinic}}` or `{{balance_due}}`. A Date or Datetime field arrives as a timestamp in milliseconds, so store any date the agent reads aloud, such as an appointment time, in a Text field.

The phone number is in `{{user_number}}`, like on any outbound call.

Retell reads the contact again before each attempt. A field that changes between attempts, from a new upload, a CRM sync, or an earlier call's outcome, reaches the next attempt. A campaign has no dynamic variables of its own, so store anything the agent needs per contact in a contact field.

If a contact has no value for a field, its variable is missing. Write prompts that read correctly without it. See [Handling missing variables](https://docs.retellai.com/build/dynamic-variables.md#handling-missing-variables).

## FAQ

> [accordion] Do I need a time zone column in my file?
>
> No. By default, a campaign dials each contact during the calling window in the contact's local time, worked out from the area codes of US and Canadian numbers. Other numbers use the sequence's fallback time zone. See [Build a sequence](https://docs.retellai.com/dialer/sequences.md#timezone).

> [accordion] Will uploading a file overwrite my existing contacts?
>
> Only the fields you map, and only where the cell has a value. Blank cells and unmapped fields keep their current values. A `false` in the **Do Not Call** column never clears an existing do-not-call mark. See [What the upload changes in your Contacts](#what-the-upload-changes-in-your-contacts).

> [accordion] My call list has more than 50,000 rows. How do I use it?
>
> A Standard campaign takes one uploaded file. Split the list into files of up to 50,000 rows and import each one from **Actions → Upload CSV or XLSX** on the [Contacts](https://docs.retellai.com/features/contacts.md) page, adding the same tag to every file. Then filter the campaign on **Tags** is any of that tag. One campaign holds up to 100,000 contacts.

> [accordion] Why does my filter match fewer contacts than I expect?
>
> Check the [condition rules](#filter-your-contacts). Text matching is case-sensitive, phone numbers need the `+` and country code, every condition must match, and a contact with no value in a field never matches a condition on that field.

> [accordion] Can I add contacts to a Standard campaign after launch?
>
> No. Its list is fixed at launch. Launch another Standard campaign for the new contacts, or use an Auto-enroll campaign for a list that keeps growing.

> [accordion] Can the same contact be in two campaigns?
>
> Yes. Campaigns don't check each other, so a contact in two campaigns is called by both. The one exception is a copy made with **Contacts not yet contacted**, which skips numbers the original campaign already reached. Within one campaign, a contact enrolls only once. See [Enrollment rules](#enrollment-rules).

Related: [Dialer overview](https://docs.retellai.com/dialer/overview.md), [Compliance checks](https://docs.retellai.com/dialer/compliance-checks.md), [Build a sequence](https://docs.retellai.com/dialer/sequences.md), [Caller ID and pacing](https://docs.retellai.com/dialer/phone-numbers.md), and [Contacts](https://docs.retellai.com/features/contacts.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.