Call The DialNexa API From Python

​

When to use this

• Backend workers that trigger outbound calls in response to CRM events, scheduled jobs, or upstream webhooks.
• Data pipelines that fetch DialNexa call logs and push them into a data warehouse.
• Internal tooling that automates campaign and workflow management for operations teams.

​

Trigger A DialNexa Outbound Call From Python

import os
import requests

API_KEY = os.environ["DIALNEXA_API_KEY"]
BASE_URL = "https://api.dialnexa.com/v1"


def create_call(
    agent_id: str,
    to_phone_number: str,
    from_phone_number: str | None = None,
    metadata: dict | None = None,
):
    """Trigger a single outbound call via DialNexa.

    Returns the call record as a dict on success. Raises requests.HTTPError
    on non-2xx responses so callers can decide whether to retry.
    """
    payload: dict = {
        "agent_id": agent_id,
        "to_phone_number": to_phone_number,
    }

    # Optional parameters from the current OpenAPI schema.
    if from_phone_number:
        payload["from_phone_number"] = from_phone_number
    if metadata:
        payload["metadata"] = metadata

    response = requests.post(
        f"{BASE_URL}/calls",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

create_call(
    agent_id="agent_123",
    to_phone_number="+14155550123",
    from_phone_number="+14155559876",
    metadata={"campaign": "renewals", "customer_name": "Priya Sharma"},
)

​

Recommended patterns

• Centralize the client. Wrap the snippet above in a single module (for example dialnexa_client.py) and import it from every job. Avoid scattering requests.post calls and headers across the codebase.
• Use environment variables for the API key. Never hard-code keys. See Authentication for the format.
• Set explicit timeouts. A 30 second timeout works for POST /v1/calls because the response is small and returns as soon as DialNexa accepts the call.
• Retry on transient failures only. Retry HTTP 502/503/504 and connection errors with exponential backoff. Do not retry 4xx responses, those indicate a payload that needs to be fixed, not a transient outage. See Errors.
• Handle webhook deliveries separately. For inbound events from DialNexa, build a dedicated handler that verifies the signing secret. See Webhook secrets.

​

Related pages

• API Introduction: base URLs, authentication, request and response shape.
• Trigger a Call: full OpenAPI schema for the operation above.
• Errors: error format and codes returned by every endpoint.
• Dynamic Variables: injecting context into agent prompts via metadata.
• Authentication: how API keys are sent and verified.