> ## 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 an [accepted format](/phone-number-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

## Deleting Contacts and Personal Data

Deleting a contact removes all personal data telli stores about that person, not only the contact record. Use it to fulfil deletion requests under the GDPR or when you no longer need a contact. Deletion is available on every plan and does not require the [data retention](/platform/data-retention) feature.

You can delete contacts in four ways:

* **Single contact**: Open the contact in the details panel and click **Delete Contact**
* **Several contacts at once**: Select the contacts in the table and choose **Delete** in the selection bar
* **Charlie**: Ask [Charlie](/platform/charlie) to delete an exact contact, then confirm the deletion in the app
* **API**: Call [Delete Contact](/v2/endpoint/delete-contact)

All four ways run the same deletion process and delete the same data.

### What gets deleted

| Data               | What telli does                                                                                                                                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contact record     | Name, phone number, email, salutation, gender, timezone, external ID and external URL, custom properties, and all other contact data are removed. An anonymized placeholder remains so that call statistics stay consistent. |
| Call recordings    | All audio files of every call with the contact are deleted from telli's storage.                                                                                                                                             |
| Transcripts        | Raw and refined transcripts, transcript excerpts stored in the call details, and transcripts kept for speech-recognition quality review are deleted.                                                                         |
| Call analysis      | Summaries, call outcomes, collected data, call scores, notes, feedback comments, transfer targets, and dynamic variables of every call are deleted.                                                                          |
| Call records       | Phone numbers and all other personal data on every call with the contact are removed. An anonymized call record with technical metadata such as duration, status, timestamps, and agent remains for reporting and billing.   |
| SMS conversations  | Message contents of every conversation with the contact are removed, and the contact's phone number is removed from the conversation.                                                                                        |
| Workflow runs      | Running workflows triggered by the contact or its calls are stopped, and the stored contact and call data of all runs is deleted.                                                                                            |
| Auto dialer        | Active enrollments of the contact are canceled.                                                                                                                                                                              |
| Telephony provider | telli deletes the call and message records its telephony provider holds for calls and SMS with the contact.                                                                                                                  |

Deletion is irreversible. telli never deletes records in your CRM or other connected systems; it only removes the CRM ID and URL stored in telli. Deleted contacts and their calls no longer appear in the telli app or API.

### Before you delete

* A contact can't be deleted while a call with it is in progress or is still being processed after it ended. Wait for the call to finish, then try again.
* Owners and admins can also delete the recording of a single call in the [Conversation History](/platform/call-history) without deleting the contact.
* To delete contacts, call data, recordings, or transcripts automatically after a set time, configure [data retention](/platform/data-retention). Data retention runs the same deletion process, is available on Enterprise plans, and is not required for manual deletion.


## Related topics

- [Update Contact](/v1/endpoint/update-contact.md)
- [Get Contact](/v1/endpoint/get-contact.md)
- [Delete Contact](/v1/endpoint/delete-contact.md)