decidalo_client.py

This repository contains two async Python clients for decidalo:

Use the Import Client when you need to push data into decidalo (e.g. syncing users from an HR system). Use the App Client when you need to read data from decidalo (e.g. finding people with specific skills).

Installation

pip install decidalo-client

Import Client (DecidaloClient)

The Import Client wraps the decidalo V3 Import API (Swagger UI). It is used for bulk-importing data into decidalo using an API key.

import asyncio
from decidalo_client import DecidaloClient, DecidaloAPIError, DecidaloAuthenticationError

async def main() -> None:
    async with DecidaloClient(api_key="your-api-key") as client:
        # Get all users
        users = await client.get_users()
        for user in users:
            print(f"{user.displayName} ({user.email})")

        # Get all projects
        projects = await client.get_all_projects()
        for project in projects:
            print(f"{project.properties.name.value}")

if __name__ == "__main__":
    asyncio.run(main())

Error Handling

import asyncio
from decidalo_client import DecidaloClient, DecidaloAPIError, DecidaloAuthenticationError

async def main() -> None:
    async with DecidaloClient(api_key="your-api-key") as client:
        try:
            users = await client.get_users()
        except DecidaloAuthenticationError as e:
            print(f"Authentication failed: {e.message}")
        except DecidaloAPIError as e:
            print(f"API error {e.status_code}: {e.message}")

if __name__ == "__main__":
    asyncio.run(main())

Import Client Features

• Async HTTP client built on aiohttp
• Type-safe request/response models using pydantic, generated from the OpenAPI spec of the Import API
• Every public method of DecidaloClient wraps exactly one API operation (see API Coverage): path, query parameters, request body and response type follow the spec, and the keyword arguments are the snake_case names of the query parameters (e.g. created_on_or_after for CreatedOnOrAfter)
• Query parameters of format date take a datetime.date, those of format date-time a timezone-aware datetime.datetime (annotated as pydantic's AwareDatetime; a naive datetime raises ValueError)
• Fields the models don't know (e.g. fields the API added to a response) are ignored instead of failing the validation

API Coverage

The client covers the V3 Import API as described by openapi/v1/swagger.json, synced from import.decidalo.dev on 2026-09-24. The tables are grouped by the tags of the spec (as in the Swagger UI).

83 of 110 operations are implemented.

Absence

ActivityType

Booking

Certificate

Company

CompanyDeprecated

GeneralActivity

HolidayCalendar

Order

Profile

Project

Rate

RecordingType

ResourceRequest

Role

Skill

Team

TimeRecording

User

UserHolidayCalendar

WorkingTimePattern

WorkPackage

App Client (DecidaloAppClient)

The App Client wraps the decidalo App API (api.decidalo.app). It is used for reading data from decidalo — searching for people, viewing profiles, exploring skills, certificates, and projects.

Authentication

The App Client authenticates via OAuth2 (Microsoft SSO) through login.decidalo.app. There are two authentication flows:

1. Device Code Flow (interactive, for first-time setup) — prints a URL and code to the console for you to open in a browser.
2. Refresh Token Flow (headless, for automation) — reuses a previously obtained refresh token.

import asyncio
from decidalo_app_client import DecidaloAppClient
from decidalo_app_client.auth import DecidaloAuth

async def first_time_login() -> None:
    """Interactive login — run this once to obtain a refresh token."""
    token = await DecidaloAuth.device_code_login()
    # The device code flow prints a URL and code to the console.
    # Open the URL in your browser and enter the code to authenticate.
    print(f"Save this refresh token for future use: {token.refresh_token}")

asyncio.run(first_time_login())

Store the refresh token securely (e.g. in an environment variable or a secrets manager). For subsequent runs, use the refresh token:

token = await DecidaloAuth.refresh("your-saved-refresh-token")

Minimal Working Example

import asyncio
from decidalo_app_client import DecidaloAppClient
from decidalo_app_client.auth import DecidaloAuth

async def main() -> None:
    # Use a refresh token obtained from a previous device_code_login()
    token = await DecidaloAuth.refresh("your-saved-refresh-token")

    async with DecidaloAppClient(token=token) as client:
        # Search for people with specific skills
        results = await client.search.find_people(keywords=["SAP", "Python"])
        for user in results.usersWithMatchedQualities:
            print(f"User {user.userId} (Score: {user.score})")

        # Get a user's profile header
        header = await client.profile.get_header(user_id=42)
        print(f"Profile quality: {header.profileQuality}, last edited by: {header.lastEditor}")

        # Browse available skill categories
        categories = await client.skills.get_categories()
        for cat in categories:
            print(f"Category: {cat.categoryName}")

asyncio.run(main())

You can also pass a static Bearer token string directly if you manage tokens yourself:

async with DecidaloAppClient(token="your-bearer-token") as client:
    ...

App Client Features

• Async HTTP client built on aiohttp with automatic token refresh
• OAuth2 Device Code Flow and Refresh Token Flow (direct OIDC HTTP, no extra dependency)
• Type-safe Pydantic models for most responses
• Domain-based API structure:
  • Search — Find people by skills/keywords, autocomplete user names, get filter fields
  • Profile — Read profile headers, skills, certificates, languages, industries, roles, competencies, projects
  • Projects — Get project headers, overviews, details, team members, references
  • Skills — Autocomplete skills, get levels, categories, skill grids, assessments
  • Certificates — Autocomplete certificates, get holders, certificate grids
  • Roles — Get roles, check user skills/certificates against role requirements
  • Teams — Get team details, find teams by manager, get members under current user

Development

Clone the repository and install the development environment:

git clone https://github.com/Hochfrequenz/decidalo_client.py.git
cd decidalo_client.py
uv sync --group dev

To sync the Import Client with the current API, download the spec and regenerate the Pydantic models from it:

curl -o openapi/v1/swagger.json https://import.decidalo.dev/swagger/v1/swagger.json
uv run --group codegen datamodel-codegen --input openapi/v1/swagger.json --output src/decidalo_client/models/_autogenerated.py --input-file-type openapi --output-model-type pydantic_v2.BaseModel --target-python-version 3.11 --use-annotated --use-double-quotes --collapse-root-models --field-constraints --strict-nullable --use-standard-collections --enum-field-as-literal one --extra-fields ignore --set-default-enum-member
uv run --group codegen ruff format src/decidalo_client/models/_autogenerated.py
uv run --group codegen ruff check --select I --fix src/decidalo_client/models/_autogenerated.py

Then run the tests: unittests/test_models.py checks that the models match the spec, and unittests/test_api_coverage.py checks the API Coverage section of this README against the spec and the client. To print the expected content of that section, run:

PYTHONPATH=src uv run --group tests python unittests/test_api_coverage.py

For detailed information on the development setup (uv configuration, IDE setup, etc.), see the Hochfrequenz Python Template Repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.