# Telleo API

> Start AI phone calls from your CRM, website or automation tool and get each call's outcome back.

- [Telleo API](https://docs.telleo.ai/introduction.md): Start AI phone calls from your own systems and get each call's outcome back.
- [Quickstart](https://docs.telleo.ai/quickstart.md): Create a key, find your agent, place a test call, then a real one.
- [Authentication](https://docs.telleo.ai/authentication.md): API keys, scopes, and keeping them safe.
- [Calls](https://docs.telleo.ai/concepts/calls.md): The life of a call, from request to outcome.
- [Agents and variables](https://docs.telleo.ai/concepts/agents-and-variables.md): Choose who calls, and fill their script with your data.
- [Outcomes](https://docs.telleo.ai/concepts/outcomes.md): What the agent sends back after a conversation.
- [Queue and limits](https://docs.telleo.ai/concepts/queue-and-limits.md): When your calls are dialled, and the guards that protect your contacts and your bill.
- [Test mode](https://docs.telleo.ai/concepts/test-mode.md): Build and test your integration without calling anyone.
- [Webhooks](https://docs.telleo.ai/webhooks/overview.md): Receive every call's result the moment it is ready.
- [Verify signatures](https://docs.telleo.ai/webhooks/verify-signatures.md): Check that a delivery really came from Telleo and was not changed.
- [Event payloads](https://docs.telleo.ai/webhooks/events.md): What each webhook delivery contains.
- [Connect your CRM](https://docs.telleo.ai/guides/crm-integration.md): Call new leads automatically and write every result back to the right record.
- [Call website enquiries](https://docs.telleo.ai/guides/website-forms.md): Ring a visitor back seconds after they submit your form.
- [Zapier, Make and n8n](https://docs.telleo.ai/guides/no-code.md): Connect Telleo to any tool that can send and receive HTTP requests, without writing a server.
- [Bulk calling](https://docs.telleo.ai/guides/bulk-calling.md): Queue up to 1,000 calls in one request and follow their progress.
- [Going live](https://docs.telleo.ai/guides/going-live.md): A checklist before your integration calls real people.
- [Errors](https://docs.telleo.ai/platform/errors.md): Every error has the same shape and a stable code.
- [Rate limits](https://docs.telleo.ai/platform/rate-limits.md): How many requests a key can make.
- [Idempotency](https://docs.telleo.ai/platform/idempotency.md): Retry requests without calling anyone twice.
- [Pagination](https://docs.telleo.ai/platform/pagination.md): Walk through long lists of calls.
- [Billing](https://docs.telleo.ai/platform/billing.md): What an API call costs.
- [Changelog](https://docs.telleo.ai/platform/changelog.md): Changes to the Telleo API.
- [API reference](https://docs.telleo.ai/api-reference/introduction.md): Base URL, authentication and conventions.
- [List calls](https://docs.telleo.ai/api-reference/calls/list-calls.md): Your calls, newest first. Filter by batch, by your `external_id`, or by creation time; page with `starting_after`.
- [Start a call](https://docs.telleo.ai/api-reference/calls/start-a-call.md): Queues a call to one number and dials it as soon as a line is free and calling hours allow. Returns the call at once (usually `queued` or `dialing`); the outcome arrives on your webhook, or poll `GET /calls/{id}`.
- [Get a call](https://docs.telleo.ai/api-reference/calls/get-a-call.md): The call's current status and, once it has ended, its duration, recording and outcome.
- [Cancel a call](https://docs.telleo.ai/api-reference/calls/cancel-a-call.md): Cancels a call that is still `queued`. A call that is already dialling or finished cannot be canceled.
- [Start a batch](https://docs.telleo.ai/api-reference/batches/start-a-batch.md): Queues up to 1,000 calls in one request. Each row is checked on its own: valid rows are queued, invalid rows come back in `rejected` with the row's `index`. Batch calls are dialled as lines free up, behind single calls.
- [Get a batch](https://docs.telleo.ai/api-reference/batches/get-a-batch.md): Progress of a batch: how many calls are in each status. List its calls with `GET /calls?batch_id=`.
- [List agents](https://docs.telleo.ai/api-reference/agents/list-agents.md): The agents you can name as `agent_id`: every agent that is turned on and can call out. Each lists the placeholders its script uses, so you know which `variables` to send.
- [Get the webhook](https://docs.telleo.ai/api-reference/webhook/get-the-webhook.md): Your webhook endpoint. The secret itself is not returned; `secret_hint` shows its ends.
- [Set the webhook](https://docs.telleo.ai/api-reference/webhook/set-the-webhook.md): Sets the one HTTPS endpoint that receives `call.completed` and `call.not_connected`. The first time, the response includes the signing `secret`; changing the URL later keeps the secret.
- [Remove the webhook](https://docs.telleo.ai/api-reference/webhook/remove-the-webhook.md): Stops sending events. Calls stay readable through the API.
- [Rotate the signing secret](https://docs.telleo.ai/api-reference/webhook/rotate-the-signing-secret.md): Replaces the signing secret and returns the new one once. Deliveries are signed with the new secret straight away, so update your server first or accept both secrets for a few minutes.
- [Send a test event](https://docs.telleo.ai/api-reference/webhook/send-a-test-event.md): Sends a signed `webhook.test` event to your endpoint now and tells you what it answered.
- [Callcompleted](https://docs.telleo.ai/api-reference/callcompleted.md): Sent once when a connected call is final, with its outcome. Verify `Telleo-Signature` before trusting it, answer 2xx within 10 seconds, and ignore an `id` you have already processed.
- [Callnot connected](https://docs.telleo.ai/api-reference/callnot_connected.md): Sent once when a call ends without connecting: `no_answer`, `busy`, `failed`, `canceled` or `expired` (see `data.status` and `data.status_reason`).

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.