Skip to main content
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
  • 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
FieldTypeDescription
phoneNumberstringPhone number in E.164 format (e.g., +4915112345678)
emailstringContact’s email address
fullNamestringContact’s full name
Optional fields
FieldTypeDescription
additionalDatastringExtra context for the AI agent to use during the call
scheduledTimestringSchedule the call for later (see Scheduling a Future Call)
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).
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."
  }'
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.

​
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. 
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."
  }'

​
Response

A successful request returns the created call object with a 201 status code. 
{
  "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
StatusDescription
pendingCall is queued or scheduled
completedCall finished successfully
failedCall could not be completed

​
Error Handling

StatusErrorDescription
400Agent is not activeThe agent must be published and enabled in the dashboard
403Missing scopeYour API token does not have the outbound-calls:write scope
404Agent not foundNo agent exists with the provided UUID
422Invalid phone number formatThe phone number is not in valid E.164 format
422Scheduled time in the pastscheduledTime 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:

Build a Workflow with n8n and Zeeg

Automate outbound calls by connecting Zeeg’s AI Agent API to n8n workflows.
Last modified on April 4, 2026