Trigger a Call

POST

calls

Create a single outbound call

curl --request POST \
  --url https://api.dialnexa.com/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "phone_number": "+911234567890",
  "agent_id": "mgao6051Rk718Y",
  "metadata": {
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "priority": "high"
  },
  "agent_version_number": 2,
  "notes": {
    "customer_name": "John Doe",
    "follow_up_required": true,
    "source": "dashboard"
  }
}
'

import requests

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

payload = {
    "phone_number": "+911234567890",
    "agent_id": "mgao6051Rk718Y",
    "metadata": {
        "customer_name": "John Doe",
        "customer_email": "[email protected]",
        "priority": "high"
    },
    "agent_version_number": 2,
    "notes": {
        "customer_name": "John Doe",
        "follow_up_required": True,
        "source": "dashboard"
    }
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '+911234567890',
    agent_id: 'mgao6051Rk718Y',
    metadata: {
      customer_name: 'John Doe',
      customer_email: '[email protected]',
      priority: 'high'
    },
    agent_version_number: 2,
    notes: {customer_name: 'John Doe', follow_up_required: true, source: 'dashboard'}
  })
};

fetch('https://api.dialnexa.com/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/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([
    'phone_number' => '+911234567890',
    'agent_id' => 'mgao6051Rk718Y',
    'metadata' => [
        'customer_name' => 'John Doe',
        'customer_email' => '[email protected]',
        'priority' => 'high'
    ],
    'agent_version_number' => 2,
    'notes' => [
        'customer_name' => 'John Doe',
        'follow_up_required' => true,
        'source' => 'dashboard'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$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/calls"

	payload := strings.NewReader("{\n  \"phone_number\": \"+911234567890\",\n  \"agent_id\": \"mgao6051Rk718Y\",\n  \"metadata\": {\n    \"customer_name\": \"John Doe\",\n    \"customer_email\": \"[email protected]\",\n    \"priority\": \"high\"\n  },\n  \"agent_version_number\": 2,\n  \"notes\": {\n    \"customer_name\": \"John Doe\",\n    \"follow_up_required\": true,\n    \"source\": \"dashboard\"\n  }\n}")

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	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/calls")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+911234567890\",\n  \"agent_id\": \"mgao6051Rk718Y\",\n  \"metadata\": {\n    \"customer_name\": \"John Doe\",\n    \"customer_email\": \"[email protected]\",\n    \"priority\": \"high\"\n  },\n  \"agent_version_number\": 2,\n  \"notes\": {\n    \"customer_name\": \"John Doe\",\n    \"follow_up_required\": true,\n    \"source\": \"dashboard\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"+911234567890\",\n  \"agent_id\": \"mgao6051Rk718Y\",\n  \"metadata\": {\n    \"customer_name\": \"John Doe\",\n    \"customer_email\": \"[email protected]\",\n    \"priority\": \"high\"\n  },\n  \"agent_version_number\": 2,\n  \"notes\": {\n    \"customer_name\": \"John Doe\",\n    \"follow_up_required\": true,\n    \"source\": \"dashboard\"\n  }\n}"

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

{
  "id": "call_mfgsn90vwcozgb",
  "to_phone_number": "+911234567890",
  "agent_id": "agent_mfgsn90vwcozgb",
  "agent_version_number": 2
}

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. Use the /v1 version for new integrations. This endpoint remains available for existing integrations until then.

Initiates a single outbound call to the specified phone number using the given agent. The call starts as soon as 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.

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 Config 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": "agt_abc123",
  "metadata": {
    "customer_name": "Priya Sharma",
    "appointment_time": "3pm on Friday",
    "product": "Home Loan"
  }
}

In your prompt, you can then write: “Hi , calling to confirm your appointment.”

Authorizations

Authorization

string

header

required

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

Headers

x-organization-id

string

required

RSA encrypted organization ID (base64 format)

Example:

"BASE64_ENCRYPTED_ORG_ID_HERE"

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:

"mgao6051Rk718Y"

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

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": "dashboard"
}

Response

Call created 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

The version number of the agent used for this call.

Example:

2

Create an Outbound CallCreate a single outbound call through the v1 outbound-calls API.

Create a single outbound call

curl --request POST \
  --url https://api.dialnexa.com/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "phone_number": "+911234567890",
  "agent_id": "mgao6051Rk718Y",
  "metadata": {
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "priority": "high"
  },
  "agent_version_number": 2,
  "notes": {
    "customer_name": "John Doe",
    "follow_up_required": true,
    "source": "dashboard"
  }
}
'

import requests

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

payload = {
    "phone_number": "+911234567890",
    "agent_id": "mgao6051Rk718Y",
    "metadata": {
        "customer_name": "John Doe",
        "customer_email": "[email protected]",
        "priority": "high"
    },
    "agent_version_number": 2,
    "notes": {
        "customer_name": "John Doe",
        "follow_up_required": True,
        "source": "dashboard"
    }
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '+911234567890',
    agent_id: 'mgao6051Rk718Y',
    metadata: {
      customer_name: 'John Doe',
      customer_email: '[email protected]',
      priority: 'high'
    },
    agent_version_number: 2,
    notes: {customer_name: 'John Doe', follow_up_required: true, source: 'dashboard'}
  })
};

fetch('https://api.dialnexa.com/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/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([
    'phone_number' => '+911234567890',
    'agent_id' => 'mgao6051Rk718Y',
    'metadata' => [
        'customer_name' => 'John Doe',
        'customer_email' => '[email protected]',
        'priority' => 'high'
    ],
    'agent_version_number' => 2,
    'notes' => [
        'customer_name' => 'John Doe',
        'follow_up_required' => true,
        'source' => 'dashboard'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$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/calls"

	payload := strings.NewReader("{\n  \"phone_number\": \"+911234567890\",\n  \"agent_id\": \"mgao6051Rk718Y\",\n  \"metadata\": {\n    \"customer_name\": \"John Doe\",\n    \"customer_email\": \"[email protected]\",\n    \"priority\": \"high\"\n  },\n  \"agent_version_number\": 2,\n  \"notes\": {\n    \"customer_name\": \"John Doe\",\n    \"follow_up_required\": true,\n    \"source\": \"dashboard\"\n  }\n}")

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	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/calls")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+911234567890\",\n  \"agent_id\": \"mgao6051Rk718Y\",\n  \"metadata\": {\n    \"customer_name\": \"John Doe\",\n    \"customer_email\": \"[email protected]\",\n    \"priority\": \"high\"\n  },\n  \"agent_version_number\": 2,\n  \"notes\": {\n    \"customer_name\": \"John Doe\",\n    \"follow_up_required\": true,\n    \"source\": \"dashboard\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"+911234567890\",\n  \"agent_id\": \"mgao6051Rk718Y\",\n  \"metadata\": {\n    \"customer_name\": \"John Doe\",\n    \"customer_email\": \"[email protected]\",\n    \"priority\": \"high\"\n  },\n  \"agent_version_number\": 2,\n  \"notes\": {\n    \"customer_name\": \"John Doe\",\n    \"follow_up_required\": true,\n    \"source\": \"dashboard\"\n  }\n}"

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

{
  "id": "call_mfgsn90vwcozgb",
  "to_phone_number": "+911234567890",
  "agent_id": "agent_mfgsn90vwcozgb",
  "agent_version_number": 2
}

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

When to use this

Destination validation

Dynamic variables

Authorizations

Headers

Body

Response

​When to use this

​Destination validation

​Dynamic variables

Authorizations

Headers

Body

Response

When to use this

Destination validation

Dynamic variables