# Orvelt Python SDK

URL: /docs/developers/python-sdk

The Orvelt Python SDK (`orvelt-business`, Python 3.10+) exposes 12 selected operations from the Business REST API. It is generated from the same contract as the [HTTP API](/docs/api-reference). The [Developer quickstart](/docs/developers) creates a key and sends a first request; this page covers the Python client in detail.

## Install [#install]

The Python package is not yet on PyPI. Install it from a checkout of [orveltinc/python-sdk](https://github.com/orveltinc/python-sdk):

```bash
python -m pip install .
```

## Functions [#functions]

Operations use the same single-word resource and action names as the API. For example, `link.create` calls `POST /project/{projectId}/link`.

### Resource groups [#resource-groups]

| Group | Functions |
| --- | --- |
| `questions` | `list`, `create`, `update`, `delete` |
| `opinions` | `list` |
| `answers` | `list` |
| `link` | `list`, `create`, `resend` |
| `qr` | `display` |
| `subscribers` | `count`, `invite` |

The [HTTP API reference](/docs/api-reference) also includes endpoints the SDK does not export.

### Pass parameters as one flat object [#pass-parameters-as-one-flat-object]

Pass keyword arguments in snake_case, including `project_id` on every call. Requests still use the API's camelCase field names.

```python
import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.opinions.list(project_id="PROJECT_ID", page=1, limit=20)
```

## Configure the client [#configure-the-client]

### Client options [#client-options]

Create an `Orvelt` client and close its connections with a context manager:

```python
import os
from orvelt_business import Orvelt

with Orvelt(
    business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"],
    server_url=os.environ.get("ORVELT_API_BASE_URL", "https://api.orvelt.com/v1"),
    timeout_ms=10_000,
) as client:
    page = client.opinions.list(
        project_id="PROJECT_ID",
        http_headers={"x-request-id": "REQUEST_ID"},
    )
```

- `server_url` overrides the default `https://api.orvelt.com/v1`; include `/v1` for staging or a local proxy.
- `timeout_ms` sets a request timeout.
- `client` and `async_client` accept custom HTTPX-compatible transports.
- Per-operation `http_headers` adds request headers.

Every method has an async equivalent with an `_async` suffix. Use `async with` and await it inside your async service:

```python
import asyncio
import os
from orvelt_business import Orvelt

async def main():
    async with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
        page = await client.opinions.list_async(project_id="PROJECT_ID")
        print({"count": len(page.result.opinions)})

asyncio.run(main())
```

### Use separate clients [#use-separate-clients]

Create a separate `Orvelt` instance for each environment or organization. Each instance holds its own credentials; there is no shared global client.

```python
import os
from orvelt_business import Orvelt

with Orvelt(
    business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"],
    server_url=os.environ.get("ORVELT_API_BASE_URL", "https://api.orvelt.com/v1"),
) as client:
    page = client.opinions.list(project_id="PROJECT_ID")
```

### Bind a project ID [#bind-a-project-id]

Python has no `useProject` helper. Store the ID once and pass `project_id` explicitly:

```python
import os
from orvelt_business import Orvelt

project_id = os.environ["ORVELT_PROJECT_ID"]
with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.opinions.list(
        project_id=project_id,
        external_user_id="customer-42",
        visibility="public",
    )
```

## Read results and errors [#read-results-and-errors]

The Python SDK returns typed Pydantic models and raises HTTP errors rather than returning a `{ data, error }` envelope. Non-paginated operations return their typed response directly:

```python
import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    result = client.link.create(
        project_id="PROJECT_ID",
        customer_email="customer@example.com",
        customer_first_name="Alex",
        customer_reference="ORDER-42",
    )
    emailed_at = result.emailed_at
```

`opinions.list`, `answers.list`, and `link.list` return a page wrapper with the typed response in `.result`. Call `.next()` (or `await page.next()` for async calls) to fetch another page; it returns `None` after the last page. Filters, credentials, and page size carry over. See [Pagination](/docs/developers/pagination).

[Errors](/docs/developers/errors) lists every status and code. Log only the status, error code, and counts you need; keep customer records, opinion text, delivery links, credentials, and raw error objects out of logs.

### Throw on errors [#throw-on-errors]

HTTP failures always raise subclasses of `orvelt_business.errors.OrveltError`; there is no `throwOnError` setting. Inspect `status_code` and `headers` to decide how to recover. Invalid response shapes raise `ResponseValidationError`; transport failures raise HTTPX errors.

```python
import logging
import os
from orvelt_business import Orvelt, errors

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    try:
        page = client.opinions.list(project_id="PROJECT_ID")
        print({"count": len(page.result.opinions)})
    except errors.OrveltError as error:
        logging.error("Business API request failed: HTTP %s", error.status_code)
        raise
```

### Retry transient failures [#retry-transient-failures]

GET requests retry connection failures and HTTP `429`, `500`, `502`, `503`, and `504` with bounded backoff. Pass `retries=None` to disable read retries for an operation:

```python
import os
from orvelt_business import Orvelt

with Orvelt(business_api_key=os.environ["ORVELT_BUSINESS_API_KEY"]) as client:
    page = client.opinions.list(project_id="PROJECT_ID", retries=None)
```

Mutations do not retry by default, including link issuance, invitations, and rotating QR display. Do not replay these automatically: the first attempt may have succeeded.

## Upgrade the SDK [#upgrade-the-sdk]

TypeScript and Python ship together as one SDK release, with shared notes in the [SDK changelog](/changelog?product=sdk). The notes identify each package's changes and versions; breaking changes say what to update. Business app and HTTP API changes are released separately under [Business releases](/changelog?product=business).

### Versions and ranges [#versions-and-ranges]

Versions follow [semantic versioning](https://semver.org): patch releases are fixes only, minor releases add functions or options without breaking existing calls, and major releases contain breaking changes.

For upgrades, check out the Python version named in the shared SDK release notes and reinstall it:

```bash
python -m pip install .
```

A prepared SDK release is not published until both packages have shipped.