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

# Contacts

> Full visibility into your contact outreach

<iframe width="560" height="315" src="https://www.loom.com/embed/ac2b7b8a1d014ea9bb39340d00e2991e?sid=b91d5b39-ea5b-42a5-b7be-c2d51493a7f9" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />

The Contacts section gives you full visibility into each person your telli agent is trying to reach or has already interacted with.

## Add or Search Contacts

At the top, you can:

* Add new contacts manually
* Search existing contacts using filters or contact IDs

## Contact Status

Each contact is labeled with one of the following statuses:

* **New**: The contact has been added but hasn't been called yet
* **Pending**: The agent has attempted to reach the contact, but no successful interaction has occurred yet. The contact will be automatically called again
* **Reached**: The agent successfully reached the contact and had a conversation
* **Closed**: The contact is marked as done and will not be called again

You can filter by these statuses using the dropdown at the top left.

## Contacts Table

The contacts table shows your contacts along with their key information. You can customize which columns are visible using the **column picker** — including any [custom properties](/platform/contact-properties) you've defined for your account.

## Contact Details Panel

Clicking on any contact opens their detailed view. The panel is organized into sections:

* **System properties** — Core fields like phone number, email, timezone, and external ID
* **Custom properties** — Any [contact properties](/platform/contact-properties) you've defined, displayed with type-appropriate inputs (date pickers, dropdowns, checkboxes, etc.)
* **Call attempt history** — Full timeline of interactions with this contact

You can edit any property value directly in the panel and save your changes.

## Call Attempt History

Scroll down in the contact detail view to see the Call Attempt History. For each attempt, you'll find:

* Timestamp of the call
* Call direction (e.g. outgoing)
* Result (e.g. completed, failed, not reached)

This lets you trace the full communication history with one contact — the call details can be found in the [Conversation History](/platform/call-history) section.

## CSV Import

CSV import lets you add or update contacts from the Contacts page without using the API:

* Upload a `.csv` file
* Map every column to a telli system field, a custom property, or **Do not import**
* Review how many rows will create contacts, update existing contacts, or be skipped
* Import the file
* Optionally schedule calls for all successfully imported contacts

Limits:

* Maximum file size: `10MB`
* Maximum rows per file: `100,000`

Your CSV file must include a header row. These system fields are available in the import wizard:

| Column name    | Description                                                  | Required |
| -------------- | ------------------------------------------------------------ | -------- |
| `external_id`  | Your unique identifier for the contact in your own system    | Yes      |
| `first_name`   | Contact's first name                                         | Yes      |
| `last_name`    | Contact's last name                                          | Yes      |
| `phone_number` | Contact's phone number in E.164 format, for example `+4917…` | Yes      |
| `email`        | Contact's email address                                      | No       |
| `timezone`     | IANA timezone, for example `Europe/Berlin`                   | No       |
| `external_url` | Link to the contact in your CRM or another external system   | No       |

`external_id` is the primary import field. If you still use older CSV files with `external_contact_id`, telli can recognize that header during column mapping.

Here's an example of a valid CSV file:

```csv theme={null}
external_id,first_name,last_name,phone_number,email,timezone,lead_type
ID10001,Sarah,Smith,+491724222923,sarah.smith@test.com,Europe/Berlin,reactivated
ID10002,Michael,Scott,+4917682494115,test@test.com,America/New_York,new_lead
```

### Custom Properties in CSV

If you've defined [contact properties](./contact-properties), you can use them directly in CSV import:

* **Download the template** to get a CSV with all your custom properties already included as headers
* **Template headers use `Label (key)`** for custom properties, for example `Lead Type (lead_type)`
* **Automatic mapping** matches custom properties by key, label, or the `Label (key)` header format
* **Manual mapping** lets you assign any CSV column to an existing custom property
* **Create properties in the wizard** if a matching property does not exist yet

When you create a new property in the import wizard, these property types are available:

* Text
* Number
* Boolean
* Date
* Date & Time
* Phone Number
* Email

To import into an existing **Select** or **Multi-Select** property, map the CSV column to that property during the mapping step. For multi-select properties, separate multiple values in a single cell with commas.

### External ID

The external ID is a unique identifier from your system, such as a CRM lead ID or a database primary key.

telli uses this value to decide whether to create a new contact or update an existing one:

* If the external ID does not exist yet, telli creates a new contact
* If the external ID already exists, telli updates the existing contact instead of creating a duplicate
* If the same external ID appears multiple times in the same CSV, telli keeps one row for that external ID and uses the last valid row in the file

Rows with invalid data are skipped and shown as row-level errors during import.

### Scheduling Calls

After the import finishes, you can add all successfully imported contacts to the auto dialer. This step is optional.

* **Select an agent**: Choose which agent should call these contacts
* **Optional outbound number override**: If your account has multiple outbound numbers, you can choose which one to use
* **Schedule imported contacts in bulk**: telli schedules all successfully imported contacts from this import
* **Auto dialer behavior still applies**: If the selected agent's auto dialer is disabled, contacts are queued, but no calls are placed until it is enabled