CallingBox Python SDK

The official Python SDK for CallingBox – the API for AI phone calls.

Install

pip install callingbox

Quick Start

import callingbox

# Search and purchase a number (one-time setup)
available = callingbox.numbers.search_available(area_code="415")
number = callingbox.numbers.purchase(available[0].phone_number)

# Make a call – uses your oldest purchased number by default
call = callingbox.calls.create(
    to="+15551234567",
    prompt="Confirm appointment tomorrow 2pm",
    context={"patient": "Maria Lopez"},
    returns={"confirmed": "boolean"},
)

print(call.status)    # "initiated"
print(call.id)        # uuid

Example

There's a runnable quickstart in [examples/quickstart.py](examples/quickstart.py) that walks through the full flow — buying a number, making a call, polling for results:

export CALLINGBOX_API_KEY=sk_live_...
python examples/quickstart.py +15551234567

Authentication

Set your API key as an environment variable:

export CALLINGBOX_API_KEY=sk_live_...

Or pass it directly:

from callingbox import Callingbox

client = Callingbox(api_key="sk_live_...")
call = client.calls.create(to="+15551234567", prompt="Hello")

Choosing a Caller ID

By default, calls use your organization's oldest active purchased number. To use a specific number:

call = callingbox.calls.create(
    to="+15551234567",
    prompt="Confirm appointment tomorrow 2pm",
    from_="+15557654321",
)

The from_ parameter accepts any active E.164 number owned by your organization.

Managing Numbers

# List your numbers
numbers = callingbox.numbers.list()

# Search available numbers
available = callingbox.numbers.search_available(
    country_code="US",
    area_code="415",
    number_type="local",
    limit=10,
)

# Purchase a number
number = callingbox.numbers.purchase("+14155551234")

Retrieving Calls

# List recent calls
calls = callingbox.calls.list()

# Get a specific call
call = callingbox.calls.retrieve("call-uuid-here")
print(call.result)  # structured data extracted from the call

CLI

The SDK ships with an optional command-line interface. Install the extras:

pip install 'callingbox[cli]'

Log in once (the key is stored in ~/.config/callingbox/config.toml with mode 0600):

callingbox login
# or non-interactively:
callingbox login --api-key sk_live_...

Dispatch a call and wait for the structured result:

callingbox call \
  --to "+15551234567" \
  --prompt "Confirm appointment tomorrow 2pm" \
  --returns '{"confirmed": "boolean"}'

Add --transcript to also print what each side said once the call completes:

callingbox call \
  --to "+15551234567" \
  --prompt "Confirm appointment tomorrow 2pm" \
  --transcript

Other useful commands:

callingbox calls list --limit 20          # paginated; add --all to fetch every page
callingbox calls get <call-id>
callingbox numbers list
callingbox numbers search --area-code 415
callingbox numbers buy +14155551234
callingbox whoami                          # shows the active credentials source

Add --json to any command (or pipe the output) to get machine-readable JSON. Credential resolution order: --api-key flag > CALLINGBOX_API_KEY env > config file. Shell completions install with callingbox --install-completion.

Error Handling

from callingbox import AuthenticationError, BadRequestError, NotFoundError, APIError

try:
    call = callingbox.calls.create(to="+15551234567")
except BadRequestError as e:
    print(f"Invalid request: {e.message}")
except AuthenticationError:
    print("Check your API key")
except NotFoundError:
    print("Resource not found")
except APIError as e:
    print(f"API error [{e.status_code}]: {e.message}")