DialNexa API fundamentals

DialNexa API fundamentals cover the four behaviors every production client needs: Bearer API key authentication, endpoint-specific pagination, structured error handling, and safe retry decisions. Use this page after the Quickstart and before sending real customer traffic.

Before you build a DialNexa API client

Create an API key in Settings > API Keys.
Use https://api.dialnexa.com/v1 as the base URL.
Keep API keys in server-side environment variables or a secrets manager.
Read the individual endpoint page before relying on its request, response, side-effect, or retry behavior.

Authenticate DialNexa API requests

An API key has a key ID and secret separated by a colon. Send the complete key_id:secret value as a Bearer token on every request.

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

A missing, revoked, expired, or malformed key returns 401 Unauthorized.

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Every operation under Endpoints supports Bearer API key authentication. Never send an API key from browser or mobile client code, commit it to source control, or include it in logs and screenshots.

Avoid common authentication mistakes

Send the full key_id:secret value, not only the key ID.
Use the Authorization: Bearer ... header, not x-api-key.
Keep /v1 in the configured base URL.
Use separate keys for development, staging, and production.
Rotate a key immediately after suspected exposure.

Webhook requests use a separate HMAC signature. See Webhooks for raw-body verification examples.

Paginate DialNexa list responses

DialNexa list endpoints do not use one universal response envelope. Most paginated endpoints accept page and limit, but their record keys, metadata fields, defaults, and maximums vary. Treat each endpoint page as the source of truth.

curl "https://api.dialnexa.com/v1/workflows?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoint	Records live in	Pagination fields
`GET /v1/workflows`	`data`	`meta.totalItems`, `meta.itemsPerPage`, `meta.totalPages`, `meta.currentPage`
`GET /v1/batch-calls`	`items`	Top-level `total`, `page`, and `limit`
`GET /v1/organization-phone-numbers`	`items`	Top-level `total`, `page`, and `limit`
`GET /v1/voices`	`voices`	Top-level `total`, `page`, `limit`, and `totalPages`
`GET /v1/user-webhooks`	`webhooks`	Top-level `total`, `page`, `limit`, and `totalPages`; default limit is `10`
`GET /v1/agents`	`agents`	None. The full list is returned.
`GET /v1/voices/s2s`	`voices`	None. The full list is returned.
`GET /v1/workflows/{workflowId}/leads`	`data`	Top-level `count`
`GET /v1/calls`	Root JSON array	Accepts `page` and `limit`, but returns no pagination metadata; documented maximum is `200`
`GET /v1/knowledge-base`	`items`	`meta.totalItems`, `meta.itemsPerPage`, `meta.totalPages`, `meta.currentPage`
`GET /v1/languages`, `GET /v1/llms`, `GET /v1/llms/fallback`, `GET /v1/transcribers`, and `GET /v1/transcribers/fallback`	Root JSON array	None. Each catalog is returned in full.

For an endpoint with meta.totalPages, continue until the current page reaches the reported total:

async function fetchAllWorkflows(apiKey: string) {
  const workflows = [];
  let page = 1;

  while (true) {
    const response = await fetch(
      `https://api.dialnexa.com/v1/workflows?page=${page}&limit=100`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    if (!response.ok) throw new Error(`List workflows failed: ${response.status}`);

    const { data, meta } = await response.json();
    workflows.push(...data);
    if (page >= meta.totalPages) break;
    page += 1;
  }

  return workflows;
}

For calls, stop when a page contains fewer records than the requested limit. Catalog endpoints return their complete lists and should not be paged.

Handle DialNexa API errors

Failed API requests return a structured error object. The message field can be a string or an array of validation messages.

{
  "statusCode": 400,
  "message": [
    "phone_number must be in E.164 format",
    "agent_id should not be empty"
  ],
  "error": "Bad Request"
}

Field	Type	Meaning
`statusCode`	integer	HTTP status code for the failure
`message`	string or array	Human-readable error details, including field-level validation messages
`error`	string	Short HTTP status name, such as `Bad Request` or `Not Found`

Common HTTP status codes

Code	Meaning	What to do
`400 Bad Request`	The body or query failed validation.	Fix required fields, formats, enums, or unknown properties.
`401 Unauthorized`	The API key is missing, invalid, expired, or revoked.	Send the complete active key as a Bearer token.
`403 Forbidden`	The key lacks permission, or Telephony Config blocks the destination.	Check workspace access and destination settings.
`404 Not Found`	The resource does not exist, belongs to another workspace, or the route is retired.	Confirm the resource ID and use a documented `/v1` endpoint.
`409 Conflict`	The operation conflicts with current resource state.	Read the resource and choose a valid next action.
`422 Unprocessable Entity`	An endpoint reports semantic validation failure.	Handle this only where the endpoint contract documents it.
`429 Too Many Requests`	A gateway or service rate limit was reached.	Retry with backoff and honor `Retry-After` when present.
`500 Internal Server Error`	DialNexa encountered an unexpected failure.	Retry safe reads; verify writes before deciding whether to retry.

Always check response.ok before using a response body:

async function dialNexaRequest(path: string, init: RequestInit = {}) {
  const response = await fetch(`https://api.dialnexa.com/v1${path}`, init);
  const body = await response.json();

  if (!response.ok) {
    const message = Array.isArray(body.message)
      ? body.message.join(", ")
      : body.message;
    throw new Error(`DialNexa ${body.statusCode}: ${message}`);
  }

  return body;
}

Build reliable API clients

A timeout does not prove that a request failed. Repeating a write can create a duplicate resource, purchase another number, or place another call.

The current v1 contract does not define a platform-wide idempotency header or one universal rate limit. Do not invent an idempotency header or hard-code a global request limit.

Operation class	Examples	Automatic retry decision
Read only	List agents, get call, list voices	Safe after network errors, `429`, and transient `5xx` responses.
State transition	Publish agent, pause workflow, resume batch	Read the resource first and retry only if the transition did not happen.
Resource creation	Create agent, webhook, knowledge base, purchase phone number	Search or list by stable business data before creating again.
Billable external action	Create call, create batch call	Never retry blindly. Reconcile recent calls or batches first.
Destructive action	Delete agent, knowledge base, phone number, or webhook	Read first and treat a later `404` as a possible completed deletion.

Set connection and total request timeouts that fit your application. For retry-safe requests, use capped exponential backoff with jitter and honor Retry-After when the response includes it.

async function getWithRetry(url: string, apiKey: string, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: AbortSignal.timeout(15_000),
    });

    if (response.ok) return response.json();
    if (response.status !== 429 && response.status < 500) {
      throw new Error(`Non-retryable response: ${response.status}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : Math.min(30_000, 500 * 2 ** attempt) + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("Retry budget exhausted");
}

For calls, attach a stable correlation value in metadata, save the returned DialNexa call ID, and reconcile recent calls after an ambiguous timeout.

Verify your API client

Before production traffic:

Confirm an authenticated list request returns 200.
Test each list parser against the endpoint’s actual response envelope.
Verify string and array error messages are both handled.
Confirm 4xx failures are not retried automatically.
Simulate a transient read failure and confirm backoff is capped.
Simulate a timed-out write and confirm the client reads or reconciles before retrying.
Redact API keys, secrets, phone numbers, and sensitive metadata from logs.

Troubleshoot API client behavior

Problem	What to check
Every request returns `401`	Confirm the client sends the complete API key in `Authorization: Bearer YOUR_API_KEY`.
A list parser returns no records	Check whether records live in `data`, `items`, a resource-specific key, or the root array.
A former unversioned route returns `404`	Find the supported operation under Endpoints and rebuild the request against its documented `/v1` path and schema.
A write may have happened twice	Stop retries, list or read the affected resource, and reconcile with your stable business data.
Requests retry indefinitely	Set a maximum attempt count, cap the delay, and classify responses before retrying.

Quickstart: make and verify your first request.
TypeScript and Python examples: copy complete integration workflows.
Webhooks: verify signatures and process events.
AI coding agent integration: generate a repository-specific implementation plan and code changes.

Overview

Endpoints

Code Examples And SDK Status

Before you build a DialNexa API client

Authenticate DialNexa API requests

Avoid common authentication mistakes

Paginate DialNexa list responses

Handle DialNexa API errors

Common HTTP status codes

Build reliable API clients

Verify your API client

Troubleshoot API client behavior

​Before you build a DialNexa API client

​Authenticate DialNexa API requests

​Avoid common authentication mistakes

​Paginate DialNexa list responses

​Handle DialNexa API errors

​Common HTTP status codes

​Build reliable API clients

​Verify your API client

​Troubleshoot API client behavior

​Related pages

Before you build a DialNexa API client

Authenticate DialNexa API requests

Avoid common authentication mistakes

Paginate DialNexa list responses

Handle DialNexa API errors

Common HTTP status codes

Build reliable API clients

Verify your API client

Troubleshoot API client behavior

Related pages