> ## 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
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.

> [!WARNING]
>
> 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}}`:

```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.`

## 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](https://dialnexa.com/docs/api-reference/webhooks/index.md)), 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](https://dialnexa.com/docs/api-reference/v1/webhooks/create.md) does not include `notes`.

```json theme={null}
{
  "phone_number": "+919876543210",
  "agent_id": "agent_abc123",
  "metadata": {
    "customer_name": "Priya Sharma"
  },
  "notes": {
    "crm_record_id": "rec_8812",
    "campaign_owner": "priya@example.com"
  }
}
```

`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](https://dialnexa.com/docs/api-reference/v1/calls/get.md) or process terminal events through [Webhooks](https://dialnexa.com/docs/api-reference/v1/webhooks/overview.md). 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](https://dialnexa.com/docs/api-reference/v1/calls/get.md) 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](https://dialnexa.com/docs/api-reference/v1/agents/list-phone-numbers.md)) 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](https://dialnexa.com/docs/api-reference/v1/agents/attach-phone-number.md), 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. A call whose agent version uses a retired LLM (or an enabled fallback LLM that is retired) is refused with `data.code` `LLM_RETIRED`; publish a version with a supported model.
* `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 DNC list is also refused with `403` (`This number is on your workspace's DNC list and cannot be called. ...`); the DNC 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.


## OpenAPI

````yaml POST /v1/calls
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/calls:
    post:
      tags:
        - Calls
      summary: Create Call
      description: >-
        Schedules a single outbound call. The call is queued and initiated when
        resources are available.
      operationId: createCall
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
            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:
                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: >-
                      Numeric agent version actually selected for this call. If
                      omitted in the request, the latest published version is
                      selected.
                required:
                  - id
                  - to_phone_number
                  - agent_id
              examples:
                success:
                  summary: Successful response
                  value:
                    id: call_abc123
                    agent_id: agent_2g7Xy3tY53gRlp
                    to_phone_number: '+919876543210'
                    agent_version_number: 1
        '400':
          description: >-
            Invalid request body or destination number, invalid
            metadata.agent_transfer_destinations, notes with more than 15 keys,
            the agent has no outbound number, phone_number_id is not one of its
            outbound numbers (PHONE_NUMBER_NOT_LINKED), or the agent has several
            outbound numbers and none was chosen (PHONE_NUMBER_REQUIRED, with
            phone_number_ids in data).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    message: 'Request validation failed: phone_number must be a string'
                phoneNumberNotLinked:
                  summary: 400 Bad Request
                  value:
                    message: >-
                      Request validation failed: Phone number phn_2g7Xy3tY53gRlp
                      is not an outbound number of agent agent_mgao6051Rk718Y.
                    data:
                      code: PHONE_NUMBER_NOT_LINKED
                phoneNumberRequired:
                  summary: 400 Bad Request
                  value:
                    message: >-
                      Request validation failed: Agent agent_mgao6051Rk718Y has
                      2 outbound numbers. Pass phone_number_id to choose which
                      one to dial from.
                    data:
                      code: PHONE_NUMBER_REQUIRED
                      phone_number_ids:
                        - phn_2g7Xy3tY53gRlp
                        - phn_8Kd2mQ4vX9pLs1
                llmRetired:
                  summary: Agent version uses a retired LLM
                  value:
                    message: >-
                      Request validation failed: This agent version uses GPT-4.1
                      Nano, which has been retired. Switch to a supported model
                      and publish a new version.
                    data:
                      code: LLM_RETIRED
                      llm_ids:
                        - meqtu4wiqv5haq
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    message: >-
                      API key is missing or invalid. You can generate this by
                      logging in into dashboard
        '402':
          description: >-
            The wallet has no spendable balance, or the workspace's monthly
            spend cap is reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 402 Payment Required
                  value:
                    message: >-
                      Insufficient balance. Please top up your billing wallet
                      before making a call..
                spendCapReached:
                  summary: Monthly spend cap reached
                  value:
                    message: >-
                      Monthly spend cap reached (₹5,000.00 of ₹5,000.00 used).
                      Raise it in Billing → Balance alerts, or it resets on 1
                      Nov.
        '403':
          description: >-
            The destination country or network prefix is not enabled for this
            workspace, or the workspace owner's KYC is not verified and the
            destination is not the owner's registered number (KYC rule not
            enforced for SIP numbers), or the destination number is on the
            workspace's DNC list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    message: >-
                      Country US Is Not Enabled For Outbound Calls From +91
                      Numbers. Enabled Countries: India (IN).
                dncBlocked:
                  summary: Number on the DNC list
                  value:
                    message: >-
                      This number is on your workspace's DNC list and cannot be
                      called. Remove it from Workspace Settings > Telephony >
                      DNC list to call it.
        '404':
          description: >-
            Agent not found in your organization, or it has no published version
            (or the requested agent_version_number is not published).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    message: >-
                      Agent mgao6051Rk718Y not found or doesn't belong to
                      organization 7Hk2pQ9rT1xY4z
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilteredErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    message: An unexpected error occurred. Please try again later.
      security:
        - bearer: []
components:
  schemas:
    CreateCallRequest:
      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: agent_2g7Xy3tY53gRlp
          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.
        phone_number_id:
          type: string
          example: phn_2g7Xy3tY53gRlp
          description: >-
            One of the agent's outbound numbers to call from. Required when the
            agent has more than one outbound number.
        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: crm
          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
    FilteredErrorResponse:
      type: object
      description: >-
        Error body on calls, batch calls, voices, languages and LLMs, which
        return only the message (and data for a coded refusal).
      properties:
        message:
          type: string
        data:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable refusal code.
          description: >-
            Present for a coded refusal: code and the details listed for that
            code.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - message
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.