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

# Trigger Call

> Trigger a single outbound call to a contact.

## Request Body

**phone** `string` *required*

Phone number in E.164 format (e.g., `+14155551234`). Must start with `+` followed by country code and number.

**name** `string` *required*

Contact's display name. Maximum 128 characters.

**agentId** `string` *required*

The ID of the agent that will handle this call. Must reference an existing agent in your account.

**dynamicVariables** `object`

Optional key-value pairs injected into the agent's prompt. Maximum 20 entries. Keys max 64 characters. Every value must be a string, max 512 characters. The same values are returned in the call's webhooks as `data.dynamicVariables`.

Example: `{"company": "Acme Corp", "plan": "Enterprise"}`

**deferIfUnavailable** `boolean`

Optional. If `true`, a call that cannot be placed right now because the calling window is closed or the voice service is briefly unavailable is queued instead of refused. The response is then `202 Accepted` with `data.status` set to `"deferred"`, plus `reason`, `notBefore`, `deferredCallId` and `contactUID`. Must be a boolean.

**retryConfig** `object`

Optional retry configuration for failed call attempts.

**retryConfig properties**

**retryCount** `integer` *required*

Number of retry attempts (1–5).

**retryDelays** `array` *required*

Array of delay values in minutes before each retry attempt. Length must equal `retryCount`. Each value must be between 1 and 60.

## Response

**success** `boolean`

Indicates if the call was triggered successfully.

**data** `object`

**data properties**

**contactUID** `string`

Unique identifier for this contact/call. Use this to check status or cancel.

**campaignUID** `string`

The campaign this call was assigned to (API calls are grouped into internal campaigns).

```json 201 Created theme={null}
{
  "success": true,
  "data": {
    "contactUID": "contact_7f8a9b0c1d2e",
    "campaignUID": "campaign_3e4f5g6h7i8j"
  }
}
```

```json 400 Validation Error theme={null}
{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "phone",
      "message": "phone must be in E.164 format (e.g. +14155551234)"
    }
  ]
}
```

```json 402 Insufficient Credits theme={null}
{
  "success": false,
  "message": "Insufficient credits",
  "available": 2.5,
  "required": 5.0
}
```

```json 404 Agent Not Found theme={null}
{
  "success": false,
  "message": "Agent not found"
}
```

```json 202 Deferred theme={null}
{
  "success": true,
  "data": {
    "status": "deferred",
    "reason": "window",
    "notBefore": "2026-01-02T03:30:00.000Z",
    "deferredCallId": "dfc_example_123",
    "contactUID": "contact_7f8a9b0c1d2e"
  }
}
```

```json 429 Rate Limited theme={null}
{
  "success": false,
  "message": "Rate limit exceeded. Try again in 45 seconds."
}
```

```json 429 Concurrency Limit theme={null}
{
  "success": false,
  "message": "Concurrency limit reached maximum concurrent calls active"
}
```

```json 503 Voice Unavailable theme={null}
{
  "success": false,
  "message": "Voice service is temporarily unavailable. Please retry shortly.",
  "reason": "voice_unavailable"
}
```

## Error Codes

| Code | Meaning |
| - | - |
| 400 | Request body validation failed |
| 402 | Insufficient credits to start the call |
| 403 | The contact is on the Do Not Disturb list (the body has `"code": "CONTACT_ON_DND"`), or calling is not allowed at this time (outside the calling window) |
| 404 | The specified `agentId` does not exist in your account |
| 429 | Two different causes. **Rate limit:** more than 60 requests in a minute; the message says how many seconds to wait and the `Retry-After` header carries the same number. **Concurrency limit:** your account already has the maximum number of calls running at the same time; the message starts with "Concurrency limit reached" and there is no `Retry-After` header. Wait and retry with growing delays |
| 503 | Voice service or a pre-dial check is temporarily unavailable. The body has a `reason` (`voice_unavailable`, `dnd_unavailable` or `check_failed`). When the reason is `voice_unavailable`, a `Retry-After` header gives the seconds to wait |

The concurrent-call limit is set per account by Oktivo. It is not shown in the dashboard; ask Oktivo support for the current value.

> [!NOTE]
>
> This endpoint accepts both **API Token** (`okt_...`) and **JWT** authentication.


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