---
title: "Add Contacts Batch"
method: POST
path: "/v1/add-contacts-batch"
---

# Add Contacts Batch

`POST /v1/add-contacts-batch`

Adds multiple contacts in a single request. Limited to 1000 contacts per request.

## Request body

- object
  - `contacts` Contact[], required — Array of contacts to add. Maximum 1000 contacts per request.
    - `external_contact_id` string, required — Your unique internal identifier for the contact
    - `external_url` string, uri — External URL linking to the contact in your CRM or external system
    - `salutation` string — Formal title or greeting (e.g. 'Mr.', 'Ms.', 'Herr', 'Frau'). If empty, will auto guess based on first name for German calls.
    - `first_name` string, required
    - `last_name` string, required
    - `phone_number` string, required — Contact's phone number in E.164 format (e.g. +4917642048466)
    - `email` string, email
    - `contact_details` object — Custom variables passed to the AI agent (should be discussed in advance). Please send variables in lowercase snake_case. This used to be called dynamic_variables, which still works but is deprecated and should be replaced with contact_details. Alternatively, you can send contact_details_<key> in the body instead of an object.
    - `timezone` string — IANA timezone identifier (e.g. Europe/Berlin). Defaults to account timezone if not set

## Response `200`

Contacts processed successfully

- object
  - `total_processed` integer — Total number of contacts processed
  - `total_success` integer — Number of contacts successfully added
  - `total_failed` integer — Number of contacts that failed to be added
  - `result` object[]
    - `external_contact_id` string — Your unique internal identifier for the contact
    - `status` 'success' | 'error' — Status of the contact addition
    - `contact_id` string, uuid — The telli contact ID (only present for successful additions)
    - `error` string — Error message (only present for failed additions)

## Other responses

- `400` — Invalid request
- `401` — Unauthorized - Invalid API key

---

[API](https://skmtc.dev/telli/apis/telli-api.md) · [All operations](https://skmtc.dev/telli/apis/telli-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/telli/telli-api/revisions/9815a3c63c75/schema)