Skip to main content

​
Overview

The DialNexa API is a REST API that lets you build, deploy, and monitor AI voice agents programmatically. Every action available in the DialNexa dashboard is also available through the API, so you can integrate voice AI directly into your own products and workflows.

​
Base URLs And Legacy API Support

The recommended base URL for current API requests is: 
https://api.dialnexa.com/v1
Legacy unversioned routes are still supported for existing integrations: 
https://api.dialnexa.com
Route familyBase URLStatus
Current v1 APIhttps://api.dialnexa.com/v1Use this for all new integrations.
Legacy unversioned APIhttps://api.dialnexa.comSupported until July 31, 2026. Start migrating to /v1 now.
For example, POST https://api.dialnexa.com/calls and POST https://api.dialnexa.com/v1/calls are both supported during the transition period. New code should use the /v1 route because the legacy unversioned API is scheduled for deprecation on July 31, 2026. All requests and responses use JSON, except for file upload endpoints which use multipart/form-data.

​
What you can build

  • Outbound calling: Trigger individual calls or bulk campaigns from your backend. Pass customer-specific data at call time and have the agent personalize every conversation.
  • Inbound handling: Assign an agent to a purchased phone number to automatically handle every incoming call.
  • Campaigns: Create and manage large-scale calling campaigns with full lifecycle controls, start, pause, resume, and cancel, while tracking progress in real time.
  • Workflows: Build multi-step calling sequences where a lead’s path through the workflow is determined by the outcome of each call.
  • Web calls: Embed a live AI voice call directly on your website or web app without requiring any phone number.
  • Webhooks: Subscribe to events (call completed, campaign finished, etc.) and receive real-time HTTP notifications on your server.

​
Key concepts

Agents are the core building block. An agent combines a voice, a language model, a system prompt, and telephony configuration into a single deployable entity. All calls, whether outbound, inbound, or browser-based, are handled by an agent. Dynamic variables let you personalize agents at call time. Any key in the metadata object passed when creating a call, or any column header in a leads file, becomes a {{variable_name}} that the agent can reference in its prompt. For example, if you pass {"customer_name": "Priya"}, the prompt can say Hello {{customer_name}}! and the agent will greet the caller by name. Campaigns and Batch Calls are both mechanisms for bulk outbound calling. Batch calls are simpler one-shot operations; campaigns add lifecycle management (pause, resume, cancel) and per-lead status tracking. Workflows are directed graphs where each node is an action (a call, a time delay, a conditional check) and each edge defines what happens next based on the outcome of that action.

​
Request format

Set the Content-Type header to application/json for all requests with a body: 
curl -X POST https://api.dialnexa.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agt_abc123", "to_phone_number": "+919876543210"}'

​
Response format

Successful responses return HTTP 200 or 201 with a JSON body. Errors return a standard error object: 
{
  "statusCode": 400,
  "message": "Validation failed: to_phone_number must be in E.164 format",
  "error": "Bad Request"
}
See the Errors page for a full list of error codes and how to handle them.

​
SDKs and tools

You can call the API directly with any HTTP client. For interactive testing, every endpoint in this reference includes a built-in request builder, fill in your API key and parameters, then send directly from the docs. AI agents and IDE assistants can also use the DialNexa docs MCP server to search the docs and read documentation files through MCP tools.