> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/serve/call-center-outbound-api.md).

# Call Center Outbound API

Use the call center outbound API from an external system to have the Agent bound to a number place a call, then query its status with the call records API.

External systems can initiate outbound calls through the API. The Agent bound to the specified SIP number handles the conversation. For example, after obtaining a customer's consent, a customer service system can submit a callback request and save the returned call record ID to check whether the call connects and when it ends.

First, configure the SIP trunk, number, and Agent in the admin console by following [Phone Support (Call Center)](https://docs.maiagent.ai/build/choose-channel/call-center) in the user manual. This page covers API integration; the admin console steps are covered in the manual.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* The organization has call center access enabled, and the caller is the organization owner or a member with call center permissions.
* Use a SIP number ID from the current organization. Its trunk must have outbound calling enabled, an outbound route configured, and a sync status of synced.
* The number is bound to a valid Agent that supports voice, and the Agent has an API conversation platform.

Authentication, API URLs, and JSON field formats follow the [API Conventions](https://docs.maiagent.ai/tech/en/api-integration/api-conventions.md). The paths below use `/api/v1/`, and JSON uses camelCase.

## Start an Outbound Call <a href="#start-outbound-call" id="start-outbound-call"></a>

```http
POST /api/v1/sip-numbers/{sipNumberId}/outbound-call/
```

`{sipNumberId}` is the ID of the SIP number used to place the call, not the destination phone number. The request body contains only the destination number:

| Field      | Required | Description                                                                                                                                   |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `toNumber` | Yes      | Destination number in E.164 format or as a SIP user part; 1–32 characters, allowing digits, English letters, and `+`, `*`, `#`, `.`, `_`, `-` |

The Agent is determined by the SIP number's existing binding and is not selected separately in this request. The system creates a conversation and an outbound call record, then initiates dialing.

A successful request returns `201 Created` with a call record object. Save its `id` first; the initial status is `initiated`, and the direction is `outbound`.

{% hint style="warning" %}
`201 Created` means that the outbound call has been initiated. It does not mean that the recipient has answered or that the call has finished. Your integration should continue querying the call record; do not treat a successful response as confirmation that the customer has been reached.
{% endhint %}

## Query the Call Result <a href="#query-call-result" id="query-call-result"></a>

Query using the returned call record `id`:

```http
GET /api/v1/calls/{callId}/
```

This query also requires call center permissions and only returns call records for Agents in the current organization that have not been deleted. Track the outcome using these fields:

| Field                               | Purpose                                                      |
| ----------------------------------- | ------------------------------------------------------------ |
| `id`                                | Save as the call tracking identifier in the external system  |
| `status`                            | Current call status; see the table below                     |
| `direction`                         | Calls created through this flow have the value `outbound`    |
| `chatbot`, `conversation`           | Identifiers of the Agent and conversation used for this call |
| `fromNumber`, `toNumber`            | Originating and destination numbers                          |
| `answeredAt`, `endedAt`, `duration` | Answer time, end time, and call duration in seconds          |
| `disconnectReason`                  | Disconnect reason recorded by the system                     |

| Status        | Meaning     |
| ------------- | ----------- |
| `initiated`   | Initiated   |
| `ringing`     | Ringing     |
| `in-progress` | In progress |
| `completed`   | Completed   |
| `failed`      | Failed      |
| `busy`        | Busy        |
| `no-answer`   | No answer   |
| `canceled`    | Canceled    |

`initiated`, `ringing`, and `in-progress` indicate an ongoing call; all other statuses are terminal. The external system can stop tracking the call once it reaches a terminal status.

## Handle Failures When Starting a Call <a href="#handle-start-failure" id="handle-start-failure"></a>

The request is rejected before initiation if outbound calling is disabled, the trunk has not synced, no valid Agent is available, or the API conversation platform is missing. Correct the configuration before retrying. For the standard validation error format, see [API Conventions: Error Responses](https://docs.maiagent.ai/tech/en/api-integration/api-conventions.md#errors).

If dispatching the dialing request fails, the outbound endpoint returns `400`. Each request to the initiation endpoint may create a new call. Check existing call records before retrying to avoid duplicate callbacks.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/serve/call-center-outbound-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
