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

# Make a call

> Initiate an outbound AI voice call via the Nedzo REST API. Specify the agent, phone number, and optional metadata to start an automated conversation.

> [!WARNING]
>
> This endpoint is deprecated. Use [Start a call](https://docs.nedzo.ai/api-reference/conversations/send-call.md) (`POST /v1/conversations/call`). It takes the same body and answers the same way, except for DND. A contact with Do Not Disturb (DND) on gets `403` there. Here it gets `400`, or `403` when the number is on the opt-out list, and the error text is not the same. This endpoint keeps working.

**agentId** `string` *required*

UUID of the agent to use for the call

**type** `string` *required*

Type of call target. Valid values: `contact`, `phoneNumber`

**variables** `object`

Custom variables to pass to the assistant. These override contact field values.

> [tab] Contact
>
> **contactId** `string` *required*
>
> UUID of the contact to call

> [tab] Phone Number
>
> **phoneNumber** `string` *required*
>
> Phone number to call (E.164 format, e.g., +14155551234)
>
> **firstName** `string`
>
> First name
>
> **lastName** `string`
>
> Last name
>
> **email** `string`
>
> Email address
>
> **businessName** `string`
>
> Business or company name
>
> **customFields** `object`
>
> Custom field values by field name. Field names must match existing custom field definitions.

> [!NOTE]
>
> The agent must have a phone number assigned in **Agent Builder > Settings** before you can make outbound calls. Calls fail with `400 Bad Request` if the agent has no number connected — Nedzo never falls back to another workspace number, since that would surface the wrong caller ID to the recipient.

> [!NOTE]
>
> Every call ends at the agent's **Max call duration** (set on the agent's **Settings** tab, 1 to 60 minutes, 30 by default). The cap covers the whole call, including any time after a transfer to a person. See [How Max call duration works](https://docs.nedzo.ai/agents/voice-agents.md#how-max-call-duration-works).

> [!NOTE]
>
> Outbound calls go live when your trial converts to a paid plan. Until then, `/v1/call` refuses the call with `402` and type `outbound-trial-gate`, and no call is placed. The one exception is a number verified in your workspace, such as your own phone, which you can call during the trial.

## Errors

| Status | Detail | Cause |
| - | - | - |
| `400` | `Agent does not have a phone number assigned. Please assign a number in Agent Builder > Settings before making outbound calls.` | The agent has no phone number connected. |
| `400` | `Phone number <number> is not active. Please activate it first.` | The agent's assigned number is in `pending` or another non-active status. |
| `400` | `Invalid call type` | `type` is something other than `contact` or `phoneNumber`. |
| `400` | `Contact is on the Do Not Disturb list and cannot be contacted` | A contact with this number has DND on, or the contact found by this email has DND on. No call was placed. |
| `400` | `The agent's number cannot place outbound calls. Assign a US or Canada number from Nedzo, or a verified caller ID.` | The agent's number can't make outbound calls. |
| `402` | `Outbound goes live when your trial converts. Go live now to start calling, texting, and emailing contacts.` | The account is on a trial. The `type` ends in `outbound-trial-gate`. |
| `402` | Varies | The account has no plan, its subscription is not active, or its wallet has no balance left. The `type` ends in `payment-required`. |
| `403` | `Recipient has Do Not Disturb (DND) on` | The number is on the opt-out list. No call was placed. |
| `403` | `Could not verify Do Not Disturb status` | Nedzo couldn't check the opt-out list, so it placed no call. Try again. |
| `403` | `Contact processing is restricted (GDPR Art.18)` | The contact's data is restricted. No call was placed. |
| `403` | `Your plan does not include calls.` | Your plan does not include calls. |
| `500` | `Could not look up the contact for this number. Please try again.` | Nedzo couldn't read the contacts on this number, so it placed no call. Try again. |
| `500` | `Could not look up the contact for this email. Please try again.` | Nedzo couldn't read the contact with this email, so it placed no call. Try again. |
| `500` | `Could not check this number against the Do Not Disturb list. Please try again.` | Nedzo couldn't check DND, so it placed no call. Try again. |
| `500` | `Could not check this contact against the Do Not Disturb list. Please try again.` | Nedzo couldn't check DND, so it placed no call. Try again. |

The other errors are the same as on [the new endpoint](https://docs.nedzo.ai/api-reference/conversations/send-call.md#errors).

```bash Call Contact theme={null}
curl -X POST https://api.nedzo.ai/v1/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "type": "contact",
    "contactId": "456e4567-e89b-12d3-a456-426614174000"
  }'
```

```bash Call Phone Number theme={null}
curl -X POST https://api.nedzo.ai/v1/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "123e4567-e89b-12d3-a456-426614174000",
    "type": "phoneNumber",
    "phoneNumber": "+14155551234",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "businessName": "Acme Inc",
    "customFields": {
      "Lead Source": "Website",
      "Company Size": "50-100"
    }
  }'
```

```json Response theme={null}
{
  "conversationId": "123e4567-e89b-12d3-a456-426614174000"
}
```

```json 402 Trial theme={null}
{
  "type": "https://api.nedzo.ai/errors/outbound-trial-gate",
  "title": "Payment Required",
  "status": 402,
  "detail": "Outbound goes live when your trial converts. Go live now to start calling, texting, and emailing contacts."
}
```


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