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

# Call The DialNexa API From Python

> Call the DialNexa API from Python services and workers using requests, covering payload construction, authentication, error handling, and retries.

The DialNexa API is reachable from any Python service using the standard `requests` library. There is no Python-specific SDK package yet, the recommended pattern is a thin wrapper module in your own codebase that centralizes the base URL, authentication header, and error handling. The example below mirrors the operations published in [`/api-reference/openapi.json`](https://dialnexa.com/docs/api-reference/openapi.json) and is a good starting point for production worker code.

## 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.
* **Operations tooling** that automates campaign and workflow management for your team.

For browser or mobile voice experiences, use the current [Web Calls](https://dialnexa.com/docs/calls/web-calls.md) path. Do not expose a DialNexa API key in browser or mobile code. The React and React Native SDK pages describe unreleased plans only.

## Trigger A DialNexa Outbound Call From Python

```python theme={null}
import os
import requests

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


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

    Returns {id, to_phone_number, agent_id, agent_version_number} on success.
    Raises requests.HTTPError on non-2xx responses so callers can decide
    whether to retry.
    """
    payload: dict = {
        "agent_id": agent_id,
        "phone_number": phone_number,  # E.164, for example +14155550123
        "metadata": metadata or {},  # required; {} when the prompt uses no variables
    }

    # Optional: which outbound number to dial from, when the agent has several.
    if phone_number_id:
        payload["phone_number_id"] = phone_number_id

    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()
```

Example usage:

```python theme={null}
create_call(
    agent_id="agent_123",
    phone_number="+14155550123",
    metadata={"campaign": "renewals", "customer_name": "Priya Sharma"},
    phone_number_id="phn_abc123",
)
```

## 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 [API fundamentals](https://dialnexa.com/docs/api-reference/api-fundamentals.md#authenticate-dialnexa-api-requests) 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. On `429`, wait for the seconds in `Retry-After`. Do not retry other 4xx responses, those indicate a payload that needs to be fixed, not a transient outage. Do not retry `POST /v1/calls` blindly: a retry can place a second call. See [API fundamentals](https://dialnexa.com/docs/api-reference/api-fundamentals.md#build-reliable-api-clients).
* **Handle webhook deliveries separately.** For inbound events from DialNexa, build a dedicated handler that verifies the signature. See [Verifying the signature](https://dialnexa.com/docs/api-reference/v1/webhooks/create.md#verifying-the-signature).

## Related pages

* [API Introduction](https://dialnexa.com/docs/api-reference/introduction.md): base URLs, authentication, request and response shape.
* [Trigger a Call](https://dialnexa.com/docs/api-reference/v1/calls/create.md): full OpenAPI schema for the operation above.
* [API fundamentals](https://dialnexa.com/docs/api-reference/api-fundamentals.md): authentication, error handling, pagination, and retries.
* [Dynamic Variables](https://dialnexa.com/docs/agents/dynamic-variables.md): injecting context into agent prompts via `metadata`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.