Orvelt Python SDK
Install and configure the Orvelt Python SDK, read typed results, handle errors, and upgrade the client.
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. The Developer quickstart creates a key and sends a first request; this page covers the Python client in detail.
Install
The Python package is not yet on PyPI. Install it from a checkout of orveltinc/python-sdk:
python -m pip install .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
| Group | Functions |
|---|---|
questions | list, create, update, delete |
opinions | list |
answers | list |
link | list, create, resend |
qr | display |
subscribers | count, invite |
The HTTP API reference also includes endpoints the SDK does not export.
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.
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
Client options
Create an Orvelt client and close its connections with a context manager:
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_urloverrides the defaulthttps://api.orvelt.com/v1; include/v1for staging or a local proxy.timeout_mssets a request timeout.clientandasync_clientaccept custom HTTPX-compatible transports.- Per-operation
http_headersadds request headers.
Every method has an async equivalent with an _async suffix. Use async with and await it inside your async service:
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
Create a separate Orvelt instance for each environment or organization. Each instance holds its own credentials; there is no shared global client.
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
Python has no useProject helper. Store the ID once and pass project_id explicitly:
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
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:
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="[email protected]",
customer_first_name="Alex",
customer_reference="ORDER-42",
)
emailed_at = result.emailed_atopinions.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.
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
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.
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)
raiseRetry 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:
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
TypeScript and Python ship together as one SDK release, with shared notes in the SDK changelog. 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.
Versions and ranges
Versions follow semantic versioning: 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:
python -m pip install .A prepared SDK release is not published until both packages have shipped.