Initiate Outbound Call

POSThttps://api.nexyantra.live/v1/calls

Purpose & Architecture

Immediately dispatch an autonomous conversational AI phone call to a customer's mobile or landline number with injected CRM variables.

CRM & Business Use Cases

Instant lead qualification (under 15 seconds after webform submission in HubSpot/Salesforce), automated EMI and overdue payment collections reminders, delivery schedule confirmations, or post-service CSAT verification without human agent intervention.

Prerequisites & Constraints

Agent must be created and belong to the same tenant as your Bearer API key (cross-tenant calls return 403 Forbidden).
Destination phone number must be formatted in strict E.164 with international country code (e.g. +919876543210).
Compliant calling windows configured on the agent (e.g., TRAI 09:00 - 21:00 recipient local time) are strictly enforced. Calls placed outside allowed hours reject immediate dial with 409 Conflict.
Tenant account must have active carrier balance or minute quota.

Headers

Header	Type	Required	Description
Authorization	string	Required *	Bearer authentication token. Format: Bearer nxk_live_... Constraint: Must be a valid active API key scoped to your tenant
Content-Type	string	Required *	Payload serialization standard. Constraint: Required for POST requests

Request Body Parameters

Field	Type	Required	Description & Formatting Guidelines
agent_id	string (UUID)	Required *	Target voice agent UUID configured in your tenant. Determines the prompt, voice model, language, and behavior. Format: Valid active agent UUID
phone	string (E.164)	Required *	Destination customer phone number with international country code. Format: +<country_code><number>, e.g. +919876543210
caller_id	string (E.164)	Optional	Purchased carrier DID phone number to display as calling identity. If omitted, uses agent default DID. Format: Must be assigned to tenant in Numbers section
user_context	object (JSON)	Optional	Dynamic CRM variables injected into the agent system prompt (e.g., customer_name, due_amount, account_id). Format: Key-value map of strings or numbers
dial	boolean	Optional	Whether to dispatch carrier dial command immediately (true) or register call session state only (false).(Default: true) Format: true \| false

Response Attributes (201 OK)

session_idstring (UUID)

Unique call correlation ID used across telephony, webhooks, and analytics.

dialedboolean

Indicates whether the telecom carrier dial command was dispatched.

dial_resultobject

Carrier dispatch outcome containing carrier call_sid and initial queue status.

calling_windowobject

Contains enforcement status, whether the window is currently open, and next_open ISO timestamp.

Expected Error Codes & Handling

Status	Reason	Condition	Resolution
400	Bad Request	Malformed JSON payload or missing required body.	Check JSON syntax and required fields.
401	Unauthorized	Missing, invalid, or revoked Bearer API key.	Supply header: Authorization: Bearer nxk_live_...
403	Forbidden	The agent_id specified belongs to a different company/tenant.	Ensure agent was created under your tenant.
404	Not Found	The requested agent_id does not exist.	Check /v1/agents for valid agent UUIDs.
409	Calling Window Closed	Call attempt occurred outside compliant local business hours.	Schedule call after next_open ISO timestamp.
422	Validation Error	Invalid phone number formatting or schema validation error.	Ensure phone starts with + followed by country code.
429	Rate Limit Exceeded	More than 60 requests sent in a 60-second sliding window.	Throttle requests or implement exponential backoff.