Outbound calls are initiated via the DialNexa REST API. Each call requires a source number, a destination number, and an agent version. You can pass dynamic variables to personalize the agent’s behavior for each call, and monitor results in Call History.
Prerequisites
- A DialNexa API key. Find yours in Settings > API Keys.
- A phone number in your workspace to use as the caller ID. See Purchase a Phone Number.
- A published agent version. Outbound calls require a published version.
- The destination number must be reachable and allowed by the selected route. For international numbers, KYC and Telephony Config must be ready. See International Calling.
API Endpoint
POST https://api.dialnexa.com/v1/calls
Required Fields
| Field | Type | Description |
|---|
from_number | string | The DialNexa phone number to call from, in E.164 format (e.g., +14155550100). Must be an active number in your workspace. |
to_number | string | The destination phone number in E.164 format. |
agent_version_id | string | The ID of the published agent version to run on this call. |
Optional Fields
| Field | Type | Description |
|---|
variables | object | Key-value pairs injected into the agent’s prompt at call time. Use this to personalize the call with caller name, account data, or any context your agent references. |
metadata | object | Arbitrary key-value pairs stored on the call record. Not passed to the agent. Useful for correlating calls with your internal IDs. |
Example Request
curl -X POST https://api.dialnexa.com/v1/calls \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+14155550100",
"to_number": "+16505550199",
"agent_version_id": "av_01hx...",
"variables": {
"customer_name": "Alex Rivera",
"appointment_date": "June 3rd at 2 PM",
"account_id": "acct_7842"
},
"metadata": {
"crm_contact_id": "cont_99123"
}
}'
Response
A successful request returns HTTP 201 with a call object:
{
"call_id": "call_01hy...",
"status": "queued",
"from_number": "+14155550100",
"to_number": "+16505550199",
"agent_version_id": "av_01hx...",
"created_at": "2026-05-23T10:15:00Z"
}
call_id uniquely identifies the call. Use it to look up the call record, retrieve the transcript, or check outcome in Call History.
Call Status Values
| Status | Meaning |
|---|
queued | Call accepted and waiting for an available outbound slot |
ringing | Dialing the destination number |
in_progress | Call connected and agent is active |
completed | Call ended normally |
failed | Call could not be connected |
no_answer | Destination did not answer |
busy | Destination line was busy |
voicemail | Call reached a voicemail system |
Using Variables
Variables let you pass call-specific context to the agent at runtime. In your agent’s prompt, reference variables with double curly braces:
You are calling {{customer_name}} about their appointment on {{appointment_date}}.
variables object replace the placeholders. Variables not referenced in the prompt are silently ignored.
Variable keys are case-sensitive. customer_name and Customer_Name are treated as different variables. Match the case used in your prompt exactly.
Monitor Calls
After triggering a call:
- Open Call History in the DialNexa dashboard.
- Find the call by
call_id, destination number, or timestamp.
- Click the call record to view: real-time status, transcript (once complete), post-call analysis, and any metadata you attached.
For bulk outbound operations with scheduling and retry logic, use Batch Calling instead of individual API calls.
Error Responses
| HTTP Status | Cause |
|---|
400 | Missing required field or invalid format |
401 | Invalid or missing API key |
403 | from_number not in your workspace, agent version not published, or the destination is blocked by Telephony Config, such as unsupported country or unsupported prefix |
409 | Workspace concurrency limit reached. See Concurrency and Limits. |
Rate Limits
API calls to POST /calls are rate-limited per workspace. If you need higher throughput for bulk dialing, use the Batch Calling endpoint, which handles queuing and retry internally.
