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

# Make a call

> POST /api/outbound-call — have one of your agents call a phone number.

<Note>
  `POST /api/outbound-call`
</Note>

Starts an outbound call. Trikon dials the number from your workspace's phone line and hands the conversation to the agent you name. The request returns as soon as the call is placed — it does not wait for the conversation to finish.

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY` — from **Settings → Developer API** once API access is enabled for the workspace.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

<ParamField body="to" type="string" required>
  The number to call, in international format: `+919845012345`.
</ParamField>

<ParamField body="agentId" type="string" required>
  The UUID of the agent that should handle the call. Open your agent in **AI Voice → My Agents** to copy the **Agent ID** shown next to the agent name at the top of the configuration page (e.g. `e320872e-1781-4fab-83da-1b009db7748d`).
</ParamField>

<ParamField body="enterprise" type="string" required>
  Your workspace slug, e.g. `acmeclinic`. It selects the phone line and credentials used for the call.
</ParamField>

<ParamField body="from" type="string" required>
  The Phone Number Record ID (UUID) of the specific phone line in your workspace to dial out from (e.g. `f47ac10b-58cc-4372-a567-0e02b2c3d479`). You can find this ID in **Settings → Phone Numbers & Telephony**.
</ParamField>

<ParamField body="name" type="string">
  The person's name. The agent uses it wherever your script says `{{customer_name}}`. Defaults to `Customer`.
</ParamField>

<ParamField body="metadata" type="object">
  Any extra values your script refers to. Each key becomes a placeholder — `amount_due` becomes `{{amount_due}}`.
</ParamField>

### Example

```bash theme={null}
curl -X POST https://voice.trikon.tech/api/outbound-call \
  -H "Authorization: Bearer $TRIKON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919845012345",
    "agentId": "8f2c1d34-5b6a-4c7e-9f10-2a3b4c5d6e7f",
    "enterprise": "acmeclinic",
    "from": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "Asha",
    "metadata": { "amount_due": "4500", "due_date": "12 October" }
  }'
```

## Response

<ResponseField name="success" type="boolean">
  `true` when the call was accepted by the carrier.
</ResponseField>

<ResponseField name="callUuid" type="string">
  Identifier for this call, useful when matching it to a row in **Call Logs**.
</ResponseField>

```json theme={null}
{
  "success": true,
  "callUuid": "9d1f6b2a-0c44-11f0-9c3e-0242ac120002"
}
```

## Errors

Failures come back with `success: false` and a human-readable `message`.

| Status | `message`                            | What to do                                                                |
| ------ | ------------------------------------ | ------------------------------------------------------------------------- |
| 400    | Missing required fields              | Ensure `to`, `agentId`, and `enterprise` are supplied in the request body |
| 400    | Invalid 'from' phone ID format       | Provide a valid Phone Number Record UUID for the `from` field             |
| 400    | Credentials missing                  | Add a phone number in **Settings → Phone Numbers & Telephony**            |
| 401    | Authentication failed (Unauthorized) | Check that your `Authorization: Bearer YOUR_API_KEY` header is valid      |
| 429    | Carrier rate limit exceeded          | Slow down call placement rate or reduce simultaneous active calls         |
| 500    | Internal server error                | Retry; if it persists, contact your Trikon contact with the timestamp     |

```json theme={null}
{
  "success": false,
  "message": "Credentials missing. Please configure them in Settings → Phone Numbers & Telephony."
}
```

## After the call

The recording, transcript, AI summary, and detected intent appear in [Call Logs](/user-guide/call-logs) in the app a short while after the call ends.

<Tip>
  Call yourself first. Hearing your own script over a real phone line catches problems that never show up in the browser playground.
</Tip>