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


## Related topics

- [Integrate with your CRM](/crm-integration.md)
- [n8n](/integrations/n8n.md)
- [Zapier](/integrations/zapier.md)