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

# AI Agent Calls

> Use the Zeeg API to trigger immediate or scheduled AI agent outbound phone calls, including how to pass call context and handle responses.

Zeeg's AI Agent can make outbound phone calls on your behalf. Use the API to trigger calls immediately or schedule them for a specific time. This guide walks you through both scenarios.

## Prerequisites

Before you begin, make sure you have the following in place:

* An AI agent created, published, and enabled in your [Zeeg dashboard](https://app.zeeg.me)
* The agent's UUID (found in the agent settings)
* An API token with the `outbound-calls:write` scope

## Triggering an Immediate Call

Send a `POST` request to start a call right away. The AI agent will dial the specified phone number and use the provided context to drive the conversation.

**Endpoint**

```
POST https://api.zeeg.me/v2/agents/{agentUuid}/outbound-calls
```

**Required fields**

| Field         | Type   | Description                                           |
| ------------- | ------ | ----------------------------------------------------- |
| `phoneNumber` | string | Phone number in E.164 format (e.g., `+4915112345678`) |
| `email`       | string | Contact's email address                               |
| `fullName`    | string | Contact's full name                                   |

**Optional fields**

| Field            | Type   | Description                                                                             |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `additionalData` | string | Extra context for the AI agent to use during the call                                   |
| `scheduledTime`  | string | Schedule the call for later (see [Scheduling a Future Call](#scheduling-a-future-call)) |

<Info>
  Phone numbers must be in **E.164 format** — a `+` followed by the country code and subscriber number with no spaces or dashes. For example: `+4915112345678` (Germany) or `+14155551234` (US).
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "phoneNumber": "+4915112345678",
      "email": "alex.mueller@example.com",
      "fullName": "Alex Mueller",
      "additionalData": "Follow up on demo request from March 28. Interested in the Enterprise plan."
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={
          "phoneNumber": "+4915112345678",
          "email": "alex.mueller@example.com",
          "fullName": "Alex Mueller",
          "additionalData": "Follow up on demo request from March 28. Interested in the Enterprise plan.",
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        phoneNumber: "+4915112345678",
        email: "alex.mueller@example.com",
        fullName: "Alex Mueller",
        additionalData:
          "Follow up on demo request from March 28. Interested in the Enterprise plan.",
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

<Tip>
  Use `additionalData` to give your AI agent relevant context about the person being called — prior interactions, the reason for the call, or specific talking points. This makes conversations more personalized and effective.
</Tip>

## Scheduling a Future Call

To schedule a call for a later time, include the `scheduledTime` field in the same request. The value must be a future datetime in `YYYY-MM-DD HH:mm:ss` format.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "phoneNumber": "+4915112345678",
      "email": "alex.mueller@example.com",
      "fullName": "Alex Mueller",
      "scheduledTime": "2026-04-10 14:30:00",
      "additionalData": "Quarterly check-in call. Discuss renewal options."
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
      headers={
          "Authorization": "Bearer YOUR_TOKEN",
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={
          "phoneNumber": "+4915112345678",
          "email": "alex.mueller@example.com",
          "fullName": "Alex Mueller",
          "scheduledTime": "2026-04-10 14:30:00",
          "additionalData": "Quarterly check-in call. Discuss renewal options.",
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.zeeg.me/v2/agents/YOUR_AGENT_UUID/outbound-calls",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        Accept: "application/json",
      },
      body: JSON.stringify({
        phoneNumber: "+4915112345678",
        email: "alex.mueller@example.com",
        fullName: "Alex Mueller",
        scheduledTime: "2026-04-10 14:30:00",
        additionalData:
          "Quarterly check-in call. Discuss renewal options.",
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

A successful request returns the created call object with a `201` status code.

```json theme={null}
{
  "id": 42,
  "status": "pending",
  "agentId": "YOUR_AGENT_UUID",
  "phoneNumber": "+4915112345678",
  "email": "alex.mueller@example.com",
  "fullName": "Alex Mueller",
  "additionalData": "Follow up on demo request from March 28. Interested in the Enterprise plan.",
  "scheduledTime": null
}
```

**Status values**

| Status      | Description                 |
| ----------- | --------------------------- |
| `pending`   | Call is queued or scheduled |
| `completed` | Call finished successfully  |
| `failed`    | Call could not be completed |

## Error Handling

| Status | Error                       | Description                                                   |
| ------ | --------------------------- | ------------------------------------------------------------- |
| `400`  | Agent is not active         | The agent must be published and enabled in the dashboard      |
| `403`  | Missing scope               | Your API token does not have the `outbound-calls:write` scope |
| `404`  | Agent not found             | No agent exists with the provided UUID                        |
| `422`  | Invalid phone number format | The phone number is not in valid E.164 format                 |
| `422`  | Scheduled time in the past  | `scheduledTime` must be a future datetime                     |

## Integration Example

You can combine this API with workflow automation tools to trigger calls based on external events. For a step-by-step walkthrough using n8n, see the guide:

<Card title="Build a Workflow with n8n and Zeeg" icon="diagram-project" href="https://zeeg.me/en/help/articles/14038528-how-to-build-a-workflow-with-n8n-and-zeeg">
  Automate outbound calls by connecting Zeeg's AI Agent API to n8n workflows.
</Card>