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

<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 falls back to another workspace number, since that would surface the wrong caller ID to the recipient.
</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 is not synced to voice engine.`                                                                                   | The agent's assigned number hasn't finished syncing to the voice engine yet. |
| `400`  | `Phone number is not active.`                                                                                                   | 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`.                   |

<RequestExample>
  ```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"
      }
    }'
  ```
</RequestExample>

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