> ## 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`](/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.
* **Internal tooling** that automates campaign and workflow management for operations teams.

For browser or mobile voice experiences, use the current [Web Calls](/docs/calls/web-calls) 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,
    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()
```

Example usage:

```python theme={null}
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](/docs/api-reference/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](/docs/api-reference/errors).
* **Handle webhook deliveries separately.** For inbound events from DialNexa, build a dedicated handler that verifies the signing secret. See [Webhook secrets](/docs/api-access/webhook-secrets).

## Related pages

* [API Introduction](/docs/api-reference/introduction): base URLs, authentication, request and response shape.
* [Trigger a Call](/docs/api-reference/v1/calls/create): full OpenAPI schema for the operation above.
* [Errors](/docs/api-reference/errors): error format and codes returned by every endpoint.
* [Dynamic Variables](/docs/agents/dynamic-variables): injecting context into agent prompts via `metadata`.
* [Authentication](/docs/api-reference/authentication): how API keys are sent and verified.