Quickstart

This quickstart walks you through your first six DialNexa v1 API requests. In about ten minutes you will authenticate, pick a voice, create and publish an agent, place an outbound call, and read the call result. All you need is a terminal with curl and a DialNexa account.

Before you begin

Create an API key in the dashboard under Settings > API Keys. The key has the form key_id:secret and the full value is your Bearer token. See API fundamentals for details.
Every request in this guide uses the v1 base URL:

https://api.dialnexa.com/v1

To place a real call in step 5, the destination country must be enabled in Workspace Settings > Telephony, or you need a SIP/BYOC route.

Step 1: Verify your API key

Call Validate API Key. It is the purpose-built check: read-only, it creates nothing, and it tells you which workspace the key belongs to.

curl "https://api.dialnexa.com/v1/auth/validate" \
  -H "Authorization: Bearer YOUR_API_KEY"

A 200 response contains data.valid: true, the key’s data.key.id and data.key.name, and data.organization.id. Confirm that workspace ID is the one you meant to use, since a key from another workspace authenticates successfully and then acts on the wrong data. A 401 Unauthorized means the key is missing, malformed, unknown, expired, or revoked. An invalid key returns an error rather than a success response with valid: false. Check that you sent the complete key_id:secret value and see API fundamentals for the standard error format.

Step 2: List languages and voices

An agent needs a language and a voice. List both catalogs and copy one id from each.

curl "https://api.dialnexa.com/v1/languages" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.dialnexa.com/v1/voices?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

The voices response is a JSON array of voices with no pagination fields; it returns 20 voices unless you pass limit (maximum 50) and page. Copy the id of a voice you like. You can filter by provider, gender, or language_id; see List Voices for all filters. Pick a voice that supports the language you chose.

Step 3: Create an agent

An agent combines a voice, a language, and a prompt into a deployable entity. Only title, language_id, voice_id, and prompt_text are required:

curl -X POST "https://api.dialnexa.com/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Quickstart Agent",
    "language_id": "LANGUAGE_ID_FROM_STEP_2",
    "voice_id": "VOICE_ID_FROM_STEP_2",
    "prompt_text": "You are a friendly assistant for Acme Corp. Greet {{customer_name}} and confirm their appointment."
  }'

The response returns the new agent in data. Save data.id. The {{customer_name}} placeholder is a dynamic variable; you supply its value per call after publishing.

Step 4: Publish version 0

New agents start with a draft version 0. Publish version 0 before using it for a live call:

curl -X PATCH "https://api.dialnexa.com/v1/agents/AGENT_ID_FROM_STEP_3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version_number": 0,
    "is_published": true
  }'

Confirm the response shows the version as published. If the API says the version is already published, continue to the next step. See Update Agent for phone-number assignment and published-version rules.

Step 5: Trigger a call

Place a single outbound call with the agent. phone_number, agent_id, and metadata are required; metadata carries the dynamic variable values (send {} if the prompt uses none):

curl -X POST "https://api.dialnexa.com/v1/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "agent_id": "AGENT_ID_FROM_STEP_3",
    "metadata": { "customer_name": "Priya" }
  }'

phone_number must be in E.164 format, + followed by the country code and number. The response includes the call id. See Create Call for destination validation rules.

Step 6: Read the result

Fetch the call to see its status, duration, and outcome:

curl "https://api.dialnexa.com/v1/calls/CALL_ID_FROM_STEP_5" \
  -H "Authorization: Bearer YOUR_API_KEY"

The call is in flight while status is created, initiated, sent or received, and has ended once it is completed, did_not_pick, busy, no_answer, failed, cancelled or retry_expired. For production integrations, prefer webhooks over polling; see Get Call Details for polling guidance.

Resource ID prefixes

DialNexa IDs are prefixed strings that tell you what kind of resource you are holding:

Prefix	Resource	Example
`agent_`	Agent	`agent_abc123`
`voice_`	Voice	`voice_abc123`
`llm_`	LLM	`llm_abc123`
`webhook_`	Webhook	`webhook_c9v3nz8rq4pmxa`
`workflow_`	Workflow	`workflow_abc123`
`call_`	Call	`call_mfgsn90vwcozgb`
`kb_`	Knowledge base	`kb_def456`
`phn_`	Phone number	`phn_def456`
`batch_`	Batch call	`batch_abc123`
`lang_`	Language	`lang_abc123`
`trs_`	Transcriber	`trs_tr0deepnova3xx`
`lead_`	Workflow lead	`lead_abc123`

Workspace (organization), organization folder and knowledge base document IDs have no prefix, for example 5VjulLGsmWVQlD: data.organization.id from the key check above looks like this. Always treat IDs as opaque strings and copy them from API responses rather than constructing them.

Next steps

Introduction: the full API overview and key concepts.
Create Batch Call: call a whole list of contacts from one file upload.
Create Webhook: get notified when calls end instead of polling.
API fundamentals: authentication, pagination, errors, and production-safe retries.

Overview

Endpoints

Before you begin

Step 1: Verify your API key

Step 2: List languages and voices

Step 3: Create an agent

Step 4: Publish version 0

Step 5: Trigger a call

Step 6: Read the result

Resource ID prefixes

Next steps

​Before you begin

​Step 1: Verify your API key

​Step 2: List languages and voices

​Step 3: Create an agent

​Step 4: Publish version 0

​Step 5: Trigger a call

​Step 6: Read the result

​Resource ID prefixes

​Next steps

Before you begin

Step 1: Verify your API key

Step 2: List languages and voices

Step 3: Create an agent

Step 4: Publish version 0

Step 5: Trigger a call

Step 6: Read the result

Resource ID prefixes

Next steps