> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to outbound dialing API

> Use the outbound dialing API to place outbound voice calls through a KoreVG channel, track them until they end, and terminate calls in progress.

These APIs let an application place outbound voice calls to customers and track them until they end. The API supports a proactive customer-engagement requirement:

* An external event or an app triggers a call.
* The voice agent conducts the conversation for answered calls.
* The calling app can monitor and act on the call.

A few specific use cases are:

* Remind user for an upcoming appointment.
* Verify user-placed orders.
* Send delivery notification or seek confirmation.
* Call as a follow-up of a user's contact request.

Pre-configured channels manage the telephony operations, infrastructure, and provider details. It makes the API simple to use by focusing on outcomes such as answered, busy, not answered, or failed calls. After a call is answered, it's handed over to an Artemis agent as a normal agent conversation. It uses idempotency to prevent unnecessary repeat calls.

## Prerequisites

* An outbound-capable KoreVG [voice channel](https://koreai.mintlify.site/agent-platform/channels.md#voice-channels).
* A project-bound Platform API key (`abl_…`). Send it in the `x-api-key` header.
* The `outbound_calls.initiate` scope on the key to [place](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-place) and [terminate](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-terminate) calls. The `outbound_calls.read` scope to look up, list, summarize, search, and stream calls.

## Call lifecycle

A call moves through these phases in order: `accepted`, `dialing`, `ringing`, `in_progress`, and `terminal`. A call that connects creates a session. When a call is `terminal`, its `outcome` shows how it ended: `completed`, `busy`, `rejected`, `no_answer`, `machine`, `failed`, `canceled`, or `expired`.

Placing a call returns at once with the phase `accepted`. Track the call by [looking it up](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-id), by [listing](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-listing) or [searching](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-search) the call log, or by subscribing to its [event stream](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-events).

## List of endpoints

All paths start with `/api/v1/project/{projectSlug}/{env}/outbound-calls`.

| Tasks | Help article | Purpose | Scope |
| :- | :- | :- | :- |
| Place | [Place outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-place) | Place an outbound call through a channel connection. The call returns once it's accepted. | `outbound_calls.initiate` |
| Track | [Look up a call by ID](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-id) | Get one call's phase, outcome, status history, and session ID. | `outbound_calls.read` |
| | [Events of outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-events) | Stream the status changes of one call as server-sent events. | `outbound_calls.read` |
| | [List outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-listing) | List the project's outbound calls with filters and cursor pagination. | `outbound_calls.read` |
| | [Search outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-search) | Find calls by the real destination number or SIP URI without putting it in a URL. | `outbound_calls.read` |
| Report | [Summarize outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-summary) | Get total, answered, in-flight, machine-detected, and per-outcome counts for a time window. | `outbound_calls.read` |
| Stop | [Terminate outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-terminate) | Hang up a call that hasn't ended. | `outbound_calls.initiate` |

## Behavior to know

* Each request to place a call needs an `idempotencyKey`. Repeating the same request returns the original call. Reusing the key with a different body returns `409`. Use one key per business event, such as one per booking, so a retry doesn't ring twice.
* Pass the values the agent's `ON_START` reads in `sessionMetadata`.
* Responses always mask the destination number. To find a call by number, use the search endpoint.
* A call that belongs to a different project returns `404`, not `403`.


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