> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://virtuous.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://virtuous.ferndocs.com/_mcp/server.

# Python SDK

## Installation

```bash
pip install virtuous
```

## Usage

```python
from virtuous import Virtuous

client = Virtuous(token="YOUR_API_KEY")

# List contacts with auto-pagination
contacts = client.contacts_and_individuals.search_contacts(
    search="John",
    skip=0,
    take=25,
)
for contact in contacts:
    print(contact)

# Get a specific contact
contact = client.contacts_and_individuals.get_a_contact(contact_id="12345")
```

## Auto-pagination

All list endpoints support auto-pagination. The SDK handles `skip`/`take` parameters automatically:

```python
all_gifts = client.giving.query_gifts(
    groups=[{"column_name": "Amount", "operator": "GreaterThan", "value": "100"}],
)
for gift in all_gifts:
    print(gift)
```

## Retries

The SDK automatically retries failed requests with exponential backoff. You can configure retry behavior:

```python
client = Virtuous(
    token="YOUR_API_KEY",
    max_retries=5,
)
```

## Error handling

```python
from virtuous import VirtuousError

try:
    contact = client.contacts_and_individuals.get_a_contact(contact_id="invalid-id")
except VirtuousError as e:
    print(e.status_code)
    print(e.message)
```

## Async support

```python
from virtuous import AsyncVirtuous

client = AsyncVirtuous(token="YOUR_API_KEY")

contacts = await client.contacts_and_individuals.search_contacts(search="John")
async for contact in contacts:
    print(contact)
```

## GitHub repository

View the source and contribute: [virtuous-python-sdk](https://github.com/fern-demo/virtuous-python-sdk)