Create Call

POST

calls

Create Call

curl --request POST \
  --url https://api.dialnexa.com/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "agent_2g7Xy3tY53gRlp",
  "phone_number": "+919876543210",
  "agent_version_number": 1,
  "metadata": {}
}
'

import requests

url = "https://api.dialnexa.com/v1/calls"

payload = {
    "agent_id": "agent_2g7Xy3tY53gRlp",
    "phone_number": "+919876543210",
    "agent_version_number": 1,
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: 'agent_2g7Xy3tY53gRlp',
    phone_number: '+919876543210',
    agent_version_number: 1,
    metadata: {}
  })
};

fetch('https://api.dialnexa.com/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/calls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => 'agent_2g7Xy3tY53gRlp',
    'phone_number' => '+919876543210',
    'agent_version_number' => 1,
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/calls"

	payload := strings.NewReader("{\n  \"agent_id\": \"agent_2g7Xy3tY53gRlp\",\n  \"phone_number\": \"+919876543210\",\n  \"agent_version_number\": 1,\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/v1/calls")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"agent_2g7Xy3tY53gRlp\",\n  \"phone_number\": \"+919876543210\",\n  \"agent_version_number\": 1,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"agent_2g7Xy3tY53gRlp\",\n  \"phone_number\": \"+919876543210\",\n  \"agent_version_number\": 1,\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "call_abc123",
  "agent_id": "agent_2g7Xy3tY53gRlp",
  "to_phone_number": "+919876543210",
  "agent_version_number": 1
}

Billable - retry unsafe Queues a single outbound call to the specified phone number using the given agent. The call is created with status created and dialled shortly after; it connects when the recipient answers.

When to use this

Use this when you need to make a single, immediate call, for example when triggering a follow-up after a form submission, sending a verification call, or making a click-to-call request from your CRM.

This operation can place a real, billable call. It is not safe to retry blindly after a timeout. Before submitting another request, list recent calls for the agent and match to_number and called_time on your side.

Destination validation

phone_number must be a valid international phone number in E.164 format (including the country code). For non-SIP routes, the destination country and prefix must also be enabled in Workspace Settings > Telephony before the call is created. Invalid phone number formats return 400 Bad Request. Unsupported countries, unsupported prefixes, and workspaces with no enabled destination countries return 403 Forbidden.

Dynamic variables

Pass a metadata object to inject context into the agent’s prompt at call time. Reference these values in the prompt using {{variable_name}}:

{
  "phone_number": "+919876543210",
  "agent_id": "agent_abc123",
  "metadata": {
    "customer_name": "Priya Sharma",
    "appointment_time": "3pm on Friday",
    "product": "Home Loan"
  }
}

In your prompt, you can then write: Hi {{customer_name}}, calling to confirm your {{appointment_time}} appointment.

Notes

Pass an optional notes object to store your own data on the call. It is returned unchanged in payload.call.notes on every event of the organisation webhook registered in the dashboard (see Webhooks), so that handler can tie an event back to a record on your side without maintaining a map of DialNexa call IDs. The call-ended delivery sent to v1 webhook subscriptions does not include notes.

{
  "phone_number": "+919876543210",
  "agent_id": "agent_abc123",
  "metadata": {
    "customer_name": "Priya Sharma"
  },
  "notes": {
    "crm_record_id": "rec_8812",
    "campaign_owner": "[email protected]"
  }
}

notes accepts at most 15 top-level keys; nested values are unrestricted. More than 15 returns 400 Bad Request. If metadata contains agent_transfer_destinations, the value is checked with the same rules the dashboard applies to agent transfer targets, and an invalid value returns 400 Bad Request. The difference from metadata is what reads it. metadata is injected into the agent’s prompt as {{variables}} and changes what the agent says. notes is never shown to the agent; it is inert storage that only your webhook handler sees. Put anything the agent must not read, or must not be able to repeat aloud, in notes.

Verify the result

Store the returned id immediately. Fetch it with Get Call Details or process terminal events through Webhooks. A successful create response means the call was accepted for scheduling, not that the recipient answered.

Verify The Resolved Agent Version

Omit agent_version_number to use the latest published version. A version that does not exist or is not published returns 404 Not Found. The response’s numeric agent_version_number reports the version actually selected for the call. Do not subtract one from a draft version to guess the published version. Record the returned call ID and version, then inspect Get Call Details before retrying an uncertain request.

Choose The Outbound Number

The call is placed from one of the agent’s outbound numbers, and any of them works with any published version. Pass phone_number_id (a phn_ ID from List Agent Phone Numbers) to choose it. When the agent has exactly one outbound number you can omit it.

Situation	Response
The agent has several outbound numbers and `phone_number_id` is omitted	`400` with code `PHONE_NUMBER_REQUIRED` and the agent’s numbers in `data.phone_number_ids`
`phone_number_id` is not one of the agent’s outbound numbers	`400` with code `PHONE_NUMBER_NOT_LINKED`
The agent has no outbound number	`400`. Attach one, then retry.

Error bodies on this route have the shape { "message": "...", "data": { "code": "..." } }.

Errors and recovery

400 Bad Request: fix the E.164 number, missing metadata, the outbound number choice described above, or another invalid field.
402 Payment Required: the wallet has no spendable balance (Insufficient balance. ...), or the workspace’s monthly spend cap is reached (Monthly spend cap reached (₹X of ₹Y used). Raise it in Billing → Balance alerts, or it resets on <date>.). Add balance, or wait for the cap to reset on the 1st of the month (IST) or have it raised in the dashboard.
403 Forbidden: verify KYC (while it is pending, only the owner’s registered number can be called) and Telephony coverage. A number on the workspace’s DND list is also refused with 403 (This number is on your workspace's DND list and cannot be called. ...); the DND list is managed in the dashboard.
404 Not Found: verify the signed agent ID, and that the requested version exists and is published.
Network timeout or transient 5xx: list recent calls for the agent and match to_number and called_time before retrying.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

phone_number

string

required

Phone number to call (must include country code). Format: +[country code][phone number]

Example:

"+911234567890"

agent_id

string

required

Agent ID to use for the call. Must belong to the authenticated organization.

Example:

"agent_2g7Xy3tY53gRlp"

metadata

object

required

Metadata for the call including customer information and any additional context. This data will be available during the call for personalization.

Example:

{
  "customer_name": "John Doe",
  "customer_email": "[email protected]",
  "priority": "high"
}

agent_version_number

number

Specific agent version number to use (optional). If provided, must be a published version. If not provided, will use the latest published version.

Example:

2

phone_number_id

string

One of the agent's outbound numbers to call from. Required when the agent has more than one outbound number.

Example:

"phn_2g7Xy3tY53gRlp"

notes

object

Optional notes stored on the call log. Must be a JSON object with at most 15 top-level keys.

Example:

{
  "customer_name": "John Doe",
  "follow_up_required": true,
  "source": "crm"
}

Response

Call created and queued successfully.

string

required

Unique call ID for tracking. Use this ID to reference the call in other API endpoints.

Example:

"call_mfgsn90vwcozgb"

to_phone_number

string

required

The phone number that will receive the call.

Example:

"+911234567890"

agent_id

string

required

The ID of the agent used for this call.

Example:

"agent_mfgsn90vwcozgb"

agent_version_number

number

Numeric agent version actually selected for this call. If omitted in the request, the latest published version is selected.

Example:

2

Create Call

curl --request POST \
  --url https://api.dialnexa.com/v1/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "agent_2g7Xy3tY53gRlp",
  "phone_number": "+919876543210",
  "agent_version_number": 1,
  "metadata": {}
}
'

import requests

url = "https://api.dialnexa.com/v1/calls"

payload = {
    "agent_id": "agent_2g7Xy3tY53gRlp",
    "phone_number": "+919876543210",
    "agent_version_number": 1,
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_id: 'agent_2g7Xy3tY53gRlp',
    phone_number: '+919876543210',
    agent_version_number: 1,
    metadata: {}
  })
};

fetch('https://api.dialnexa.com/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/v1/calls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_id' => 'agent_2g7Xy3tY53gRlp',
    'phone_number' => '+919876543210',
    'agent_version_number' => 1,
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/v1/calls"

	payload := strings.NewReader("{\n  \"agent_id\": \"agent_2g7Xy3tY53gRlp\",\n  \"phone_number\": \"+919876543210\",\n  \"agent_version_number\": 1,\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/v1/calls")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"agent_2g7Xy3tY53gRlp\",\n  \"phone_number\": \"+919876543210\",\n  \"agent_version_number\": 1,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"agent_2g7Xy3tY53gRlp\",\n  \"phone_number\": \"+919876543210\",\n  \"agent_version_number\": 1,\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "call_abc123",
  "agent_id": "agent_2g7Xy3tY53gRlp",
  "to_phone_number": "+919876543210",
  "agent_version_number": 1
}

Overview

Endpoints

When to use this

Destination validation

Dynamic variables

Notes

Verify the result

Verify The Resolved Agent Version

Choose The Outbound Number

Errors and recovery

Authorizations

Body

Response

​When to use this

​Destination validation

​Dynamic variables

​Notes

​Verify the result

​Verify The Resolved Agent Version

​Choose The Outbound Number

​Errors and recovery

Authorizations

Body

Response

When to use this

Destination validation

Dynamic variables

Notes

Verify the result

Verify The Resolved Agent Version

Choose The Outbound Number

Errors and recovery