Skip to main content

Alleo Python SDK

Official Python SDK for the Alleo Customer API.

Install

pip install alleo
# or
uv add alleo

Requires Python 3.10+.

Quickstart — sync

from alleo import AlleoClient

with AlleoClient(access_key="...", secret_key="...") as client:
    companies = client.list_companies()
    for company in companies:
        print(company.id, company.name)

    # Iterate every employee across all pages lazily.
    for employee in client.list_employees_iter(company_id=companies[0].id, is_active=True):
        print(employee.id, employee.email)

Credentials can also come from the environment:

export ALLEO_ACCESS_KEY=...
export ALLEO_SECRET_KEY=...
# optional

Then:

with AlleoClient() as client:
    ...

Quickstart — async

import asyncio
from alleo import AsyncAlleoClient

async def main():
    async with AsyncAlleoClient() as client:
        companies = await client.list_companies()
        async for emp in client.list_employees_iter(companies[0].id):
            print(emp.id, emp.email)

asyncio.run(main())

Creating and updating employees

from alleo import AlleoClient, EmployeeCreate, EmployeeEdit

with AlleoClient() as client:
    new_emp = client.create_employee(
        company_id=42,
        body=EmployeeCreate(
            email="jane.doe@acme.com",
            first_name="Jane",
            last_name="Doe",
            language="en",
            company_group_id=1,
        ),
    )

    # PATCH — only the set fields are sent.
    client.update_employee(42, new_emp.id, EmployeeEdit(last_name="Doe-Smith"))

    client.deactivate_employee(42, new_emp.id)

Bodies also accept plain dicts.

Error handling

from alleo import AlleoClient, ConflictError, RateLimitError, ValidationError

with AlleoClient() as client:
    try:
        client.create_employee(42, {"email": "dup@acme.com", "first_name": "D", "last_name": "U"})
    except ConflictError as e:
        # 409 — duplicate email. e.message = server's "detail", e.response_body has the full body.
        ...
    except ValidationError as e:
        # 400 or 422. For 422 the message is a flattened "loc: msg" line per field.
        ...
    except RateLimitError as e:
        # Raised only after the SDK has exhausted its automatic retries.
        # e.retry_after has the server's last Retry-After in seconds.
        ...

All errors derive from AlleoError. See src/alleo/errors.py for the full taxonomy.

Rate limits

After every call, the last observed rate-limit headers are available on the client:

print(client.last_rate_limit)  # RateLimit(limit=600, remaining=599, reset_seconds=60)

The SDK retries 429 automatically (respecting Retry-After) up to max_retries=3 before raising RateLimitError.

Blueprint version

This SDK targets blueprint_version = "1". If the server publishes a v2 blueprint, upgrade to a matching SDK major version.

License

MIT — see LICENSE.

Release files for alleo 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alleo 0.1.1
File Size Uploaded
alleo-0.1.1.tar.gz 64.0 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for alleo 0.1.1
File Interpreter ABI Platform
alleo-0.1.1-py3-none-any.whl Python 3 none any Details

Total release size: 78.5 kB

Release files / alleo-0.1.1.tar.gz

Download URL alleo-0.1.1.tar.gz
Size 64.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a3b2cfd576af8b95249113f34fd01acfca947b674c4c324d1cdef3de64a5f43f
BLAKE2b-256 checksum
How to use checksums
db22e5c8a865b444b27ad6b1c764b810576f9209410a57c550e3bce05116be62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / alleo-0.1.1-py3-none-any.whl

Download URL alleo-0.1.1-py3-none-any.whl
Size 14.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
69fd616ac8bf6f16ed0e7c9ee8b32036828890ffc36357c765bc58334f4c0771
BLAKE2b-256 checksum
How to use checksums
07ff76d53062a858790b1bc6320bc54d3ff1c6cabfbe553f230db4f95c8625e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page