> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Build Python voice apps with the Vobiz SDK - outbound calls, SIP trunking, VobizXML, and Flask webhook handlers for 130+ countries including India.

The official Python SDK for the Vobiz Voice API. Make outbound calls, manage SIP trunks, handle phone numbers, and build dynamic call flows using VobizXML - all seamlessly integrated into your Python applications.

**Source code and reference:** [vobiz-ai/Vobiz-Python-SDK](https://github.com/vobiz-ai/Vobiz-Python-SDK)

## Installation

Clone the repository and install the dependencies locally:

```bash theme={null}
git clone https://github.com/vobiz-ai/Vobiz-Python-SDK.git
cd Vobiz-Python-SDK
pip install -e .
```

## Quick start

Make an outbound call:

```python theme={null}
import vobiz

client = vobiz.RestClient()

response = client.calls.create(
    from_="+911234567890",                          # your Vobiz DID number
    to_="+919876543210",                            # destination number
    answer_url="https://your-server.com/answer",    # server returning VobizXML
    answer_method="GET",
)

print("Call UUID:", response.request_uuid)
```

When the destination party answers, Vobiz makes a synchronous HTTP request to your `answer_url` to ask for instructions on what to do next.

## Authentication

Vobiz uses your **Auth ID** and **Auth Token**. Find both in the [Vobiz Console](https://console.vobiz.ai).

We recommend exposing these as environment variables:

```bash theme={null}
export VOBIZ_AUTH_ID=MA_XXXXXXXXXX
export VOBIZ_AUTH_TOKEN=your_token_here
```

```python theme={null}
import vobiz

# Reads VOBIZ_AUTH_ID and VOBIZ_AUTH_TOKEN from your environment
client = vobiz.RestClient()
```

Or pass credentials explicitly:

```python theme={null}
client = vobiz.RestClient(auth_id="MA_XXXXXXXXXX", auth_token="your_token")
```

## Receiving calls (Flask server)

When an outbound call connects (or an inbound call arrives), Vobiz requests your `answer_url` to interpret the VobizXML instructions. Below is a Flask implementation:

```python theme={null}
from flask import Flask, request, Response
from vobiz import vobizxml

app = Flask(__name__)

@app.route('/answer', methods=['GET', 'POST'])
def answer():
    call_uuid = request.values.get('CallUUID')
    from_num = request.values.get('From')
    to_num = request.values.get('To')

    print(f"Incoming call {call_uuid}: {from_num} → {to_num}")

    response = vobizxml.ResponseElement()
    response.add_speak(
        "Hello! You have reached our Python application.",
        voice="WOMAN",
        language="en-US",
    )
    response.add_hangup()

    return Response(response.to_string(), status=200, mimetype='application/xml')

if __name__ == '__main__':
    app.run(port=5001)
```

## VobizXML

The Python SDK exposes a tightly integrated `vobizxml` module to construct robust IVR systems without manually formatting XML. It handles escaping and schema validation automatically.

```python theme={null}
from vobiz import vobizxml

response = vobizxml.ResponseElement()

gather = response.add_gather(
    action="https://your-server.com/gather-result",
    input_type="dtmf speech",
    execution_timeout=15,
)
gather.add_speak("Welcome to Acme Corp. Press 1 or say Sales.")
gather.add_play("https://your-server.com/audio/menu.mp3")

xml_string = response.to_string(pretty=True)
print(xml_string)
```

## Common operations

### Phone numbers and account capacity

```python theme={null}
# Purchase a new number out of the public inventory
client.phone_numbers.purchase_from_inventory(e164="+911234567890", currency="INR")

# Fetch your account live balance
balance = client.accounts.get_balance(auth_id="YOUR_AUTH_ID", currency="INR")
print(balance.available_balance, balance.currency)
```

### Call detail records (CDR)

```python theme={null}
cdrs = client.cdrs.list(
    start_date="2026-01-01",
    end_date="2026-01-31",
    page=1,
    per_page=20,
)
for cdr in cdrs.data:
    print(cdr['call_id'], cdr['duration'], cdr['status'])
```

## Resources

* [GitHub repository](https://github.com/vobiz-ai/Vobiz-Python-SDK)
* [Vobiz Console](https://console.vobiz.ai)
* [API documentation](/introduction)
* [VobizXML reference](/xml/response)