Skip to main content

​
Overview

The DialNexa API is a REST API that lets you build, deploy, and monitor AI voice agents programmatically. Use it to create agents, trigger calls, manage batch calls and workflows, work with catalog resources, manage webhooks, and connect phone numbers from your backend.

​
Base URLs And Legacy API Support

The recommended base URL for current API requests is:
Legacy unversioned routes are still supported for existing integrations:
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 when a v1 page exists 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 batch calls 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.
  • Batch calls: Upload a CSV or Excel file of leads, start outbound calls, and pause, resume, or cancel the batch.
  • Workflows: Build multi-step calling sequences where a lead’s path through the workflow is determined by call outcomes and workflow logic.
  • Phone numbers: Search Plivo inventory, purchase a provider number, link a bring-your-own SIP trunk, or delete a number you no longer use.
  • Webhooks: Subscribe to call and workflow-related events 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. Batch Calls are bulk outbound calling jobs created from a lead file. Use PATCH /v1/batch-calls/{id}/status to pause, resume, or cancel a batch. 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.

​
Make your first request

1

Get an API key

In the dashboard, open Settings > API Keys and create a key. Copy it immediately - it is shown only once. See Authentication.
2

List your agents

A 200 response returns an agents array. Agent listing is not paginated today.
3

Trigger a call

Publish the agent version, then take its agent_id and create a v1 call. Watch the result arrive in Call History.

​
Request format

Set the Content-Type header to application/json for all requests with a body:

​
Response format

Successful responses return HTTP 200 or 201 with a JSON body. Errors return a standard error object:
See the Errors page for a full list of error codes and how to handle them.

​
Tools

First-party SDK packages are not yet published - the HTTP API is the supported integration path, and it works with any HTTP client. The SDKs section has copy-paste HTTP patterns for TypeScript and Python, plus the status of the planned client SDKs. 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.