Migrate to the DialNexa v1 API

Migrate an existing DialNexa integration to the v1 API by mapping supported operations, checking schemas, testing side effects, and verifying production results.

To migrate to the DialNexa v1 API, use https://api.dialnexa.com/v1 as the base URL and rebuild each integration flow from the operations listed in this API reference. Do not assume that adding /v1 to an older request produces an equivalent operation. Confirm the current request schema, response schema, side effects, and retry guidance before changing production traffic.

Legacy unversioned routes with confirmed /v1 replacements were scheduled for deprecation on July 31, 2026. When deprecation is active, those routes return 410 Gone and include the replacement path in the response body. Some vendor callbacks and explicitly deferred routes can remain unblocked, but you should treat /v1 as the current integration surface.

Who this migration guide is for

Use this guide if you maintain an existing server-side integration and need to move it to the current public API. It is also useful when you are replacing a shared HTTP wrapper, regenerating a client from OpenAPI, or auditing requests that were written before your team standardized on /v1.

Before you migrate to the v1 API

• Create or identify a non-production DialNexa workspace for testing.
• Store a valid API key in a secrets manager or environment variable.
• Record every DialNexa operation your integration performs.
• Capture representative request bodies and the response fields your code reads.
• Identify state-changing or billable requests that must not be retried blindly.
• Decide how you will compare results between staging and production.

Map each workflow to a current resource

Use the resource pages below as the source of truth. If a capability is not listed in the current API Reference, do not infer or construct an undocumented route.

Capability	Current v1 resource	What to confirm
Create and manage agents	Agents	Required catalog IDs, draft versions, publishing, and phone-number assignment.
Start and inspect calls	Calls	Required metadata, destination validation, billing risk, and timeout reconciliation.
Run bulk calling jobs	Batch Calls	Recipient validation, queue behavior, lifecycle actions, and retry safety.
Inspect and control workflows	Workflows	Supported status actions, lead operations, and dashboard-only graph editing.
Manage knowledge bases	Knowledge Base	File requirements, indexing state, agent attachments, and deletion effects.
Manage phone numbers	Phone Numbers	Provider inventory, purchasing, SIP trunks, routing, and destructive deletion.
Select voices and models	Voices, Languages, LLMs, and Transcribers	Stable IDs, provider availability, language compatibility, and fallback options.
Register event notifications	Webhooks	Event names, HTTPS delivery, secret storage, and raw-body signature verification.

Migrate one operation at a time

1. Choose the current v1 operation

   Find the operation under Endpoints and confirm that it covers the business action your integration performs. Treat the operation page and its request panel as authoritative.

2. Rebuild the request

   Set the base URL to https://api.dialnexa.com/v1, keep the Bearer API key in the Authorization header, and construct the body from the current schema. Remove fields that are not accepted by the v1 request.

3. Update response handling

   Compare the documented success response and operation-specific errors with the fields your code expects. Update parsers, types, and persistence logic before sending live traffic.

4. Test retry behavior

   Follow the safety label on the endpoint page. Read operations can usually be repeated. State-changing, destructive, or billable operations require a verification read before retrying after a timeout.

5. Verify the result

   Confirm the HTTP response and the resulting DialNexa state. For calls and batches, also verify the outcome in Call History. For agents, workflows, knowledge bases, webhooks, and phone numbers, read the resource again or confirm it in the dashboard.

Verify the complete migration

Before routing all production traffic through the v1 integration:

1. Exercise every operation with representative staging data.
2. Confirm success responses, validation errors, authorization failures, and not-found behavior.
3. Test a timeout on each state-changing flow and verify before retrying.
4. Compare stored IDs, statuses, timestamps, and nested response fields with your existing assumptions.
5. Confirm webhook signatures against the raw request body.
6. Monitor production errors and duplicate side effects during the rollout.
7. Remove unused request code only after the v1 flow is stable.

Troubleshooting v1 migration issues

Problem	What to check
401 Unauthorized	Send the complete API key as Authorization: Bearer YOUR_API_KEY. Confirm the key is active in the correct workspace.
404 Not Found	Confirm the operation appears under Endpoints, the request includes /v1, and the resource belongs to the authenticated workspace.
410 Gone	The request used a legacy unversioned route that has a /v1 replacement. Read the replacement field and rebuild the request against that documented /v1 operation.
400 Bad Request	Compare the request with the current schema. Check required fields, accepted enums, ID formats, and unknown properties.
Response parsing fails	Compare your stored types with the documented response and regenerate types from OpenAPI when appropriate.
A capability is not listed	Use the dashboard for that action or contact DialNexa support. Do not construct an undocumented API route.
A timed-out request may have succeeded	Read or list the affected resource before retrying. This is especially important for calls, batches, purchases, and create operations.

Related pages

• API Introduction: base URL, request format, and response format.
• Authentication: Bearer API keys and webhook signature verification.
• Errors: standard error shapes and recovery steps.
• Reliability and retries: timeout, reconciliation, and retry guidance.
• Pagination: list response shapes and pagination parameters.
• Code examples: complete TypeScript and Python v1 workflows.