> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Call
> Create a single outbound call.
Billable - retry unsafe
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
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.
This operation can place a real, billable call. It is not safe to retry blindly after a timeout. Reconcile recent calls using stable metadata before submitting another request.
## 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}}`:
```json theme={null}
{
"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."*
## Verify the result
Store the returned `id` immediately. Fetch it with [Get Call Details](/docs/api-reference/v1/calls/get) or process terminal events through [Webhooks](/docs/api-reference/v1/webhooks/overview). A successful create response means the call was accepted for scheduling, not that the recipient answered.
## Errors and recovery
* `400 Bad Request`: fix the E.164 number, missing `metadata`, or another invalid field.
* `402 Payment Required`: add wallet balance before creating another call.
* `403 Forbidden`: verify KYC, workspace access, and Telephony Config coverage.
* `404 Not Found`: verify the signed agent ID and published version.
* Network timeout or transient `5xx`: list recent calls and match your metadata before retrying.
## OpenAPI
````yaml POST /v1/calls
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/calls:
post:
tags:
- Calls
- Calls V1
- V1
summary: Create Call
description: >-
Schedules a single outbound call. The call is queued and initiated when
resources are available.
operationId: CallsV1Controller_createCall
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCallDto'
examples:
request:
summary: Create an outbound call
value:
agent_id: agent_2g7Xy3tY53gRlp
phone_number: '+919876543210'
agent_version_number: 1
metadata: {}
responses:
'201':
description: Call created and queued successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCallResponseDto'
examples:
success:
summary: Successful response
value:
id: call_abc123
to_phone_number: '+919876543210'
agent_id: agent_2g7Xy3tY53gRlp
agent_version_number: 1
'400':
description: Invalid request body - missing required fields or validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: phone_number must be a valid E.164 phone number
error: Bad Request
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'402':
description: Payment required - insufficient billing wallet balance.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 402 Payment Required
value:
statusCode: 402
message: Insufficient billing wallet balance
error: Payment Required
'403':
description: Forbidden - KYC not verified or API key does not have access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: >-
Destination country or network prefix is not enabled for
this workspace
error: Forbidden
'404':
description: Agent or phone number not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 404 Not Found
value:
statusCode: 404
message: Agent or phone number not found
error: Not Found
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
CreateCallDto:
type: object
properties:
phone_number:
type: string
example: '+911234567890'
description: >-
Phone number to call (must include country code). Format: +[country
code][phone number]
agent_id:
type: string
example: mgao6051Rk718Y
description: >-
Agent ID to use for the call. Must belong to the authenticated
organization.
agent_version_number:
type: number
example: 2
description: >-
Specific agent version number to use (optional). If provided, must
be a published version. If not provided, will use the latest
published version.
metadata:
type: object
example:
customer_name: John Doe
customer_email: john@example.com
priority: high
description: >-
Metadata for the call including customer information and any
additional context. This data will be available during the call for
personalization.
notes:
type: object
example:
customer_name: John Doe
follow_up_required: true
source: dashboard
description: >-
Optional notes stored on the call log. Must be a JSON object with at
most 15 top-level keys.
required:
- phone_number
- agent_id
- metadata
CreateCallResponseDto:
type: object
properties:
id:
type: string
example: call_mfgsn90vwcozgb
description: >-
Unique call ID for tracking. Use this ID to reference the call in
other API endpoints.
to_phone_number:
type: string
example: '+911234567890'
description: The phone number that will receive the call.
agent_id:
type: string
example: agent_mfgsn90vwcozgb
description: The ID of the agent used for this call.
agent_version_number:
type: number
example: 2
description: The version number of the agent used for this call.
required:
- id
- to_phone_number
- agent_id
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````