> ## 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.

# Start a call

> Place an outbound AI voice call with an agent, to a contact or a phone number.

Place an outbound call with an agent. The response gives the `conversationId` at once, and the call is placed in the background. Read the result with [Get a conversation](/api-reference/conversations/get) once the call ends.

Every plan with calls can use this endpoint. It takes the same body as [Make a call](/api-reference/calls) (`POST /v1/call`), which it replaces.

<Warning>
  Every call checks Do Not Disturb (DND) first. If the contact has DND on, or the number is on the opt-out list, the call is refused with `403` and no call is placed.
</Warning>

<ParamField body="agentId" type="string" required>
  UUID of the agent to use for the call
</ParamField>

<ParamField body="type" type="string" required>
  Type of call target. Valid values: `contact`, `phoneNumber`
</ParamField>

<ParamField body="variables" type="object">
  Custom variables to pass to the assistant. These override contact field values.
</ParamField>

<Tabs>
  <Tab title="Contact">
    <ParamField body="contactId" type="string" required>
      UUID of the contact to call
    </ParamField>
  </Tab>

  <Tab title="Phone Number">
    <ParamField body="phoneNumber" type="string" required>
      Phone number to call (E.164 format, e.g., +14155551234)
    </ParamField>

    <ParamField body="firstName" type="string">
      First name
    </ParamField>

    <ParamField body="lastName" type="string">
      Last name
    </ParamField>

    <ParamField body="email" type="string">
      Email address
    </ParamField>

    <ParamField body="businessName" type="string">
      Business or company name
    </ParamField>

    <ParamField body="customFields" type="object">
      Custom field values by field name. Field names must match existing custom field definitions.
    </ParamField>
  </Tab>
</Tabs>

<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 uses another number in the workspace, because the person would see the wrong caller ID.
</Note>

<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](/agents/voice-agents#how-max-call-duration-works).
</Note>

<Note>
  Outbound calls go live when your trial converts to a paid plan. Until then, this endpoint 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.
</Note>

## 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` | `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` | `Contact has Do Not Disturb (DND) on` | A contact with this number has DND on, the contact found by this email has DND on, or the number is on the opt-out list. No call was placed. |
| `403` | `Contact processing is restricted (GDPR Art.18)` | The contact's data is restricted. 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` | `Your plan does not include calls.` | Your plan does not include calls. |
| `404` | `Agent not found` | The agent is not in the workspace, or it was deleted. |
| `404` | `Contact not found` | The contact is not in the workspace. |
| `429` | Varies | The plan's concurrent call limit is reached, or the account is over its write rate. No call was placed. Read `Retry-After`. |
| `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. |
| `503` | `Could not check the concurrent call limit. Please retry shortly.` | Nedzo couldn't count the calls in progress. No call was placed. Read `Retry-After`. |
| `503` | `We couldn't check this workspace's limits just now. Try again in a moment.` | Nedzo couldn't check the workspace's limits. No call was placed. |

<RequestExample>
  ```bash Call Contact theme={null}
  curl -X POST https://api.nedzo.ai/v1/conversations/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/conversations/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"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```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."
  }
  ```
</ResponseExample>


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