Hibob Python API Docs | dltHub

HiBob is an HRIS platform providing a RESTful Public API (Bob API) to access employee data, metadata, time-off, and related HR resources. The REST API base URL is https://api.hibob.com/v1 and all requests require Basic auth using a service user ID and token (Authorization: Basic <base64(id:token)>).

dlt is an open-source Python library that handles authentication, pagination, and schema evolution automatically. dlthub provides AI context files that enable code assistants to generate production-ready pipelines. Install with uv pip install "dlt[workspace]" and start loading Hibob data in under 10 minutes.

---

What data can I load from Hibob?

Here are some of the endpoints you can load from Hibob:

---

How do I authenticate with the Hibob API?

HiBob uses API Service Users. Requests use HTTP Basic authentication with the service user ID and token (base64‑encoded) in the Authorization header ("Basic <base64(id:token)>"). Service users are created in the HiBob admin and grant scoped permissions.

1. Get your credentials

1. In HiBob admin, create an API Service User (see 'API Service Users' in Developer Docs). 2) Assign the service user the necessary permissions for the data scopes you need (People, Time off, Metadata, etc.). 3) Save the generated service user ID and token; store them securely. 4) Use HTTP Basic auth with the header Authorization: Basic <base64(service_user_id:service_user_token)> for API requests.

2. Add them to .dlt/secrets.toml

Copy
[sources.hibob_source]
service_user_id = "your_service_user_id"
service_user_token = "your_service_user_token"

dlt reads this automatically at runtime — never hardcode tokens in your pipeline script. For production environments, see setting up credentials with dlt for environment variable and vault-based options.

---

How do I set up and run the pipeline?

Set up a virtual environment and install dlt:

Copy
uv venv && source .venv/bin/activate
uv pip install "dlt[workspace]"

1. Install the dlt AI Workbench:

Copy
dlt ai init --agent <your-agent> # <agent>: claude | cursor | codex

This installs project rules, a secrets management skill, appropriate ignore files, and configures the dlt MCP server for your agent. Learn more →

2. Install the rest-api-pipeline toolkit:

Copy
dlt ai toolkit rest-api-pipeline install

This loads the skills and context about dlt the agent uses to build the pipeline iteratively, efficiently, and safely. The agent uses MCP tools to inspect credentials — it never needs to read your secrets.toml directly. Learn more →

3. Start LLM-assisted coding:

Use /find-source to load data from the Hibob API into DuckDB.

The rest-api-pipeline toolkit takes over from here — it reads relevant API documentation, presents you with options for which endpoints to load, and follows a structured workflow to scaffold, debug, and validate the pipeline step by step.

4. Run the pipeline:

Copy
python hibob_pipeline.py

If everything is configured correctly, you'll see output like this:

Copy
Pipeline hibob_pipeline load step completed in 0.26 seconds
1 load package(s) were loaded to destination duckdb and into dataset hibob_data
The duckdb destination used duckdb:/hibob.duckdb location to store data
Load package 1749667187.541553 is LOADED and contains no failed jobs

Inspect your pipeline and data:

Copy
dlt pipeline hibob_pipeline show

This opens the Pipeline Dashboard where you can verify pipeline state, load metrics, schema (tables, columns, types), and query the loaded data directly.

---

Python pipeline example

This example loads profiles and people/search from the Hibob API into DuckDB. It mirrors the endpoint and data selector configuration from the table above:

Copy
import dlt
from dlt.sources.rest_api import RESTAPIConfig, rest_api_resources

@dlt.source
def hibob_source(service_user_token=dlt.secrets.value):
    config: RESTAPIConfig = {
        "client": {
            "base_url": "https://api.hibob.com/v1",
            "auth": {
                "type": "http_basic",
                "token": service_user_token,
            },
        },
        "resources": [
            {"name": "profiles", "endpoint": {"path": "profiles"}},
            {"name": "people_search", "endpoint": {"path": "people/search", "data_selector": "results"}}
        ],
    }
    yield from rest_api_resources(config)


def get_data() -> None:
    pipeline = dlt.pipeline(
        pipeline_name="hibob_pipeline",
        destination="duckdb",
        dataset_name="hibob_data",
    )
    load_info = pipeline.run(hibob_source())
    print(load_info)

To add more endpoints, append entries from the resource table to the "resources" list using the same name, path, and data_selector pattern.

---

How do I query the loaded data?

Once the pipeline runs, dlt creates one table per resource. You can query with Python or SQL.

Python (pandas DataFrame):

Copy
import dlt

data = dlt.pipeline("hibob_pipeline").dataset()
sessions_df = data.profiles.df()
print(sessions_df.head())

SQL (DuckDB example):

Copy
SELECT * FROM hibob_data.profiles LIMIT 10;

In a marimo or Jupyter notebook:

Copy
import dlt

data = dlt.pipeline("hibob_pipeline").dataset()
data.profiles.df().head()

See how to explore your data in marimo Notebooks and how to query your data in Python with dataset.

---

What destinations can I load Hibob data to?

dlt supports loading into any of these destinations — only the destination parameter changes:

Change the destination in dlt.pipeline(destination="snowflake") and add credentials in .dlt/secrets.toml. See the full destinations list.

---

Troubleshooting

Authentication failures

If you receive 401 responses with a message like {"key":"exception.authentication.tokenNotMatch","error":"Token not matches."}, verify the service user ID and token are correct and that the Authorization header is Basic base64(id:token). Ensure the token is not expired or revoked.

Permission / 403 errors

A 403 response indicates the service user lacks required permissions for the endpoint or field. Grant the necessary scopes to the service user in HiBob admin.

Bad request / 400 errors

A 400 response may include a structured {"key":...,"error":...,"args":[...] } explaining the invalid parameter (for example, invalid time‑off policy). Validate request body and field IDs.

Pagination quirks

HiBob documents pagination on object‑based endpoints. Some endpoints use offset/limit or page/size parameters and others use POST‑based search with pagination fields in the request body—check the specific endpoint docs for the exact parameters and response paging fields.

Rate limiting

The docs mention rate limiting; monitor API audit logs and implement exponential backoff/retries for 429 responses. If you hit limits frequently, request higher quotas from HiBob support.

Ensure that the API key is valid to avoid 401 Unauthorized errors. Also, verify endpoint paths and parameters to avoid 404 Not Found errors.

---

Next steps

Continue your data engineering journey with the other toolkits of the dltHub AI Workbench:

• data-exploration — Build custom notebooks, charts, and dashboards for deeper analysis with marimo notebooks.
• dlthub-runtime — Deploy, schedule, and monitor your pipeline in production.

Copy
dlt ai toolkit data-exploration install
dlt ai toolkit dlthub-runtime install

• How to deploy a pipeline
• How to explore your data in marimo Notebooks
• How to query your data in Python with dataset
• Join the dlt community on Slack