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

# Quickstart

> Make your first DialNexa v1 API calls: authenticate, create and publish an agent, trigger a call, and read the result.

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 [Authentication](/docs/api-reference/authentication) for details.
* Every request in this guide uses the v1 base URL:

```text theme={null}
https://api.dialnexa.com/v1
```

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

## Step 1: Verify your API key

Send any authenticated GET request to confirm the key works. Listing languages is a safe, read-only check:

```bash theme={null}
curl "https://api.dialnexa.com/v1/languages" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

A `200` response with a JSON array means you are authenticated. A `401 Unauthorized` means the key is missing, malformed, or revoked. Check that you sent the full `key_id:secret` value and see [Errors](/docs/api-reference/errors) for the standard error format.

Note the `id` of the language you want your agent to speak. You will use it in step 3.

## Step 2: List voices

Agents need a voice. List the catalog and pick one:

```bash theme={null}
curl "https://api.dialnexa.com/v1/voices?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The response wraps the records in a `voices` array with pagination fields. Copy the `id` of a voice you like. You can filter by `provider`, `gender`, or `language_id`; see [List Voices](/docs/api-reference/v1/voices/list) for all filters.

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

```bash theme={null}
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_1",
    "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. Save its `id`. The `{{customer_name}}` placeholder is a dynamic variable; you supply its value per call after publishing.

## Step 4: Publish version 1

New agents start as drafts. Publish version 1 before using it for a live call:

```bash theme={null}
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": 1,
    "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](/docs/api-reference/v1/agents/update) 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):

```bash theme={null}
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](/docs/api-reference/v1/calls/create) for destination validation rules.

## Step 6: Read the result

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

```bash theme={null}
curl "https://api.dialnexa.com/v1/calls/CALL_ID_FROM_STEP_5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The `status` moves from `initiated` to `in-progress`, then to a terminal state such as `completed`, `failed`, `busy`, or `no-answer`. For production integrations, prefer [webhooks](/docs/api-reference/v1/webhooks/create) over polling; see [Get Call Details](/docs/api-reference/v1/calls/get) 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`        |
| `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`  |
| `org_`   | Organization   | `org_A1B2C3D4E5F6G7`  |

Some catalog resources, such as voices and LLMs, return IDs without a prefix. Always treat IDs as opaque strings and copy them from API responses rather than constructing them.

## Next steps

* [Introduction](/docs/api-reference/introduction): the full API overview and key concepts.
* [Create Batch Call](/docs/api-reference/v1/batches/create): call a whole list of contacts from one file upload.
* [Create Webhook](/docs/api-reference/v1/webhooks/create): get notified when calls end instead of polling.
* [Pagination](/docs/api-reference/pagination): how list endpoints page their results.
* [Errors](/docs/api-reference/errors): the standard error format and how to handle it.