> ## 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.

# Add contacts & schedule calls

> Add contacts to telli from your CRM or other systems and schedule calls with them

<iframe width="560" height="315" src="https://www.loom.com/embed/150c954c421a467585f80cb83e8b1500?sid=bc65de9a-a402-44c3-94f0-ed728bfa8b4c" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen />

<br />

## Prerequisites

* A telli account with API access
* An API key from your telli dashboard (Settings > Developer)
* A CRM system, database, or automation platform (Zapier, Make, n8n) with contacts to sync
* Contact data including: first name, last name, and phone number (email and timezone are optional)

You can add contacts to telli programmatically using the API, enabling seamless integration with your CRM, database, or other systems.

## Add a single contact

Add one contact at a time using the `/v1/add-contact` endpoint:

```json theme={null}
POST /v1/add-contact

{
  "external_contact_id": "crm-12345",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+14155552671",
  "email": "john.doe@example.com",
  "timezone": "America/New_York",
  "contact_details": {
    "company": "Acme Corp",
    "notes": "Interested in product demo"
  }
}
```

See the [Add Contact endpoint documentation](/v1/endpoint/add-contact) for complete details.

## Add multiple contacts (batch)

Add multiple contacts efficiently using the `/v1/add-contacts-batch` endpoint:

```json theme={null}
POST /v1/add-contacts-batch

{
  "contacts": [
    {
      "external_contact_id": "crm-12345",
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": "+14155552671",
      "email": "john.doe@example.com"
    },
    {
      "external_contact_id": "crm-12346",
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+14155552672",
      "email": "jane.smith@example.com"
    }
  ]
}
```

See the [Add Contacts (Batch) endpoint documentation](/v1/endpoint/add-contacts-batch) for complete details.

## Schedule a single call

After adding a contact, you can schedule a call using the `contact_id` returned from the add contact response. Use the `/v1/schedule-call` endpoint:

```json theme={null}
POST /v1/schedule-call

{
  "contact_id": "6bd1e7e0-6d00-4c0b-ad5b-daa72457a27d",
  "agent_id": "d8931604-92ad-45cf-9071-d9cd2afbad0c"
}
```

See the [Schedule Call endpoint documentation](/v1/endpoint/schedule-call) for complete details.

## Schedule multiple calls (batch)

Schedule calls for multiple contacts at once using the `/v1/schedule-calls-batch` endpoint:

```json theme={null}
POST /v1/schedule-calls-batch

{
  "contacts": [
    {
      "contact_id": "6bd1e7e0-6d00-4c0b-ad5b-daa72457a27d",
      "agent_id": "d8931604-92ad-45cf-9071-d9cd2afbad0c"
    },
    {
      "contact_id": "7ce2e8f1-7e11-5d1c-be6c-ebb83568b38e",
      "agent_id": "d8931604-92ad-45cf-9071-d9cd2afbad0c"
    }
  ]
}
```

See the [Schedule Calls (Batch) endpoint documentation](/v1/endpoint/schedule-calls-batch) for complete details.

## Best Practices

1. **Use external\_contact\_id**: Always provide your CRM's contact ID to maintain the relationship
2. **Batch when possible**: Use batch endpoints for importing multiple contacts and scheduling calls
3. **Handle errors**: Check the response for any failed contacts in batch operations
4. **Store contact\_id**: Save the returned `contact_id` to link telli contacts back to your system and schedule calls
5. **Schedule after adding**: After adding contacts, immediately schedule calls using the returned `contact_id` to automate your workflow