# Get absences
Source: https://developers.malibou.com/api-reference/absences/get-absences

/api-reference/openapi/public-api-1.11.0.json get /organizations/{organizationId}/absences
Required scope: `org:absence:read`



# Get collaborator by id
Source: https://developers.malibou.com/api-reference/collaborators/get-collaborator-by-id

/api-reference/openapi/public-api-1.11.0.json get /organizations/{organizationId}/collaborators/{collaboratorId}
Required scope: `org:employee:read`



# Get collaborators
Source: https://developers.malibou.com/api-reference/collaborators/get-collaborators

/api-reference/openapi/public-api-1.11.0.json get /organizations/{organizationId}/collaborators
Required scope: `org:employee:read`



# Create complementary contract affiliation
Source: https://developers.malibou.com/api-reference/complementary-contracts-affiliations/create-complementary-contract-affiliation

/api-reference/openapi/public-api-1.11.0-partners.json put /organizations/{organizationId}/collaborators/{collaboratorId}/affiliations
Required scope: `org:employee:health_insurance:manage`



# Create complementary contract affiliations
Source: https://developers.malibou.com/api-reference/complementary-contracts-affiliations/create-complementary-contract-affiliations

/api-reference/openapi/public-api-1.11.0-partners.json put /organizations/{organizationId}/complementary-contracts/affiliations
Required scope: `org:employee:health_insurance:manage`



# Get complementary contract affiliations
Source: https://developers.malibou.com/api-reference/complementary-contracts-affiliations/get-complementary-contract-affiliations

/api-reference/openapi/public-api-1.11.0-partners.json get /organizations/{organizationId}/collaborators/{collaboratorId}/affiliations
Required scope: `org:employee:health_insurance:manage`



# Create complementary contracts from fiche parametrage
Source: https://developers.malibou.com/api-reference/complementary-contracts/create-complementary-contracts-from-fiche-parametrage

/api-reference/openapi/public-api-1.11.0-partners.json post /organizations/{organizationId}/complementary-contracts/fiche-parametrage
Required scope: `org:employee:health_insurance:manage`



# Get complementary contracts
Source: https://developers.malibou.com/api-reference/complementary-contracts/get-complementary-contracts

/api-reference/openapi/public-api-1.11.0-partners.json get /organizations/{organizationId}/complementary-contracts
Required scope: `org:employee:health_insurance:manage`



# Get meal vouchers
Source: https://developers.malibou.com/api-reference/meal-vouchers/get-meal-vouchers

/api-reference/openapi/public-api-1.11.0-partners.json get /organizations/{organizationId}/meal-vouchers
Required scope: `org:company:read`



# Get company
Source: https://developers.malibou.com/api-reference/organizations/get-company

/api-reference/openapi/public-api-1.11.0-partners.json get /organizations/{organizationId}
Required scope: `org:company:read`



# Get work locations
Source: https://developers.malibou.com/api-reference/work-locations/get-work-locations

/api-reference/openapi/public-api-1.11.0.json get /organizations/{organizationId}/work-locations
Required scope: `org:work_location:read`



# Authentication
Source: https://developers.malibou.com/authentication

How to authenticate against the malibou public API.

The malibou public API authenticates requests with an **API key**. You create a
key from the malibou app, then send it as a **Bearer token** on every request.

<Note>
  Creating and revoking API keys requires an **Admin** role on the organization.
</Note>

## Create an API key

<Steps>
  <Step title="Open the API keys page">
    In the malibou app, go to [**Profile button → My company → API keys**](https://app.malibou.com/admin/company/api-keys).
  </Step>

  <Step title="Create a key and choose permissions">
    Click **Create an API key**, give it a descriptive name (for example "Planning
    integration"), and tick the permissions the key should grant. Each permission
    limits the key to a specific kind of data. See [Scopes](#scopes) for the full
    list.
  </Step>

  <Step title="Copy your secret">
    The secret is shown **only once**. Copy it and store it somewhere safe (a
    secret manager, not source control). You will not be able to view it again
    after closing the window.

    <Warning>
      Treat the API key like a password. Anyone with the key can read the data
      covered by its permissions on behalf of your organization.
    </Warning>
  </Step>
</Steps>

## Scopes

Each API key is granted one or more scopes that restrict what data it can
access. Select only the scopes your integration actually needs.

| Scope                       | Description                                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `org:employee:read`         | Read collaborators basic data (last name, first name, personnel number, email)                                              |
| `org:employee:details:read` | Read collaborators personal data (social security number, address, phone, bank account, etc.). Requires `org:employee:read` |
| `org:contract:details:read` | Read contract data (start date and end date). Requires `org:employee:read`                                                  |
| `org:absence:read`          | Read absence requests                                                                                                       |
| `org:absence:type:read`     | Read absence type (leave code). Requires `org:absence:read`                                                                 |
| `org:work_location:read`    | Read work location and remote work requests                                                                                 |

## Partner-only scopes

Some endpoints, grouped under **Partners only** in the [API reference](/api-reference),
require scopes that are not listed above (`org:company:read`,
`org:employee:health_insurance:manage`). These scopes are not selectable when creating
an API key from the app: they are only granted to integration partners with an approved
partnership agreement with malibou. If you are interested in using these endpoints, please contact us.

<Note>
  If you are building a self-serve integration, you can safely ignore the
  **Partners only** section of the API reference: your API key will always
  return `403` on those endpoints, regardless of the permissions you select.
</Note>

## Retrieve your organization id

Every endpoint is scoped to an organization, whose id is part of the request path
(`/api/public/v1/organizations/{organizationId}/...`). You need it before calling
any endpoint. Retrieve it from the
[API keys page](https://app.malibou.com/admin/company/api-keys): open the actions
menu (next to **Create an API key**) and choose **Copy organization ID**.

## Authenticate your requests

Send the key in the `Authorization` header as a Bearer token:

```bash theme={null}
curl https://app.malibou.com/api/public/v1/organizations/{organizationId}/collaborators \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Every endpoint under `/api/public/v1` requires this header. A request with a
missing or invalid key returns `401`, and a key that lacks the permission an
endpoint requires returns `403` (see [Errors](/usage/errors)).

## Manage and revoke keys

The [API keys page](https://app.malibou.com/admin/company/api-keys) lists every
key for your organization with its name, permissions, status and creation date.

API keys **do not expire** by default. If a key is compromised or no longer
needed, **revoke** it from this page. Revocation is **immediate and
irreversible**. Any request made with a revoked key returns `401`.


# Changelog
Source: https://developers.malibou.com/changelog

All notable changes to the malibou public API.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## \[1.11.0] - 2026-08-03

### Changed

* `organismeCode` is now nullable on the complementary contracts and affiliations read endpoints.

## \[1.10.0] - 2026-07-20

### Added

* expose `type` (the leave code) on the absences list endpoint (needs `org:absence:type:read`)

## \[1.9.0] - 2026-06-29

### Added

* expose `phoneNumber` on the collaborators list and detail endpoints (needs `org:employee:details:read`)
* expose `manager` and `team` on the collaborators list endpoint (needs `org:employee:details:read`)
* all paginated endpoints now return a deterministic order: collaborators by last name then first name, absences and work locations by start date; the collaborator contracts array (returned with `org:contract:details:read`, not paginated) is also sorted by start date

### Changed

* `email` is now returned with the base `org:employee:read` scope on the collaborators endpoints (previously required `org:employee:details:read`)
* `GET /organizations/[organizationId]/collaborators/[collaboratorId]` now only requires `org:employee:read`; personal data is still returned only with `org:employee:details:read`, so the endpoint can be used to resolve a collaborator by id with the base scope
* renamed the absences response field `employeeId` to `collaboratorId`, for consistency with the other endpoints

> **Note on versioning**: renaming `employeeId` to `collaboratorId` is technically a breaking change but is released as a **minor** version. The absences endpoint has no production consumer yet, so the rename breaks no one in practice.

## \[1.8.0] - 2026-06-29

### Added

* List of contracts in API `GET /organizations/[organizationId]/collaborators/[collaboratorId]` (needs `org:contract:details:read scope`)

### Changed

* `GET /organizations/[organizationId]/collaborators` now requires `org:employee:details:read` to return detailed personal data and `org:contract:details:read` to return the current contract. Existing credentials with only `org:employee:read` have been migrated to include both scopes.

## \[1.7.0] - 2026-06-26

### Removed

* **Breaking change**: removed all `/companies/[organizationId]` endpoints (company, collaborators, complementary-contracts, meal-vouchers). Use the `/organizations/[organizationId]` equivalents instead (available since v1.3.0).

> **Note on versioning**: although this is technically a breaking change, it is released as a **minor** version (not a major bump). Every known consumer has already migrated to the `/organizations/[organizationId]` endpoints, so removing the `/companies` aliases breaks no one in practice. This is a deliberate, one-off exception to our Semantic Versioning policy; it is **not** a precedent (future breaking changes will still warrant a major version bump).

## \[1.6.0] - 2026-06-23

### Added

* work locations API: `GET /organizations/[organizationId]/work-locations`, returning work locations overlapping the requested `startDate`/`endDate` range, with an optional `status` filter and optional `establishmentId` filter

## \[1.5.0] - 2026-06-22

### Added

* collaborator API: `GET /organizations/[organizationId]/collaborators/[collaboratorId]`, returning a specific collaborator with detailed personal data.

## \[1.4.0] - 2026-06-22

### Added

* absences API: `GET /organizations/[organizationId]/absences`, returning absences overlapping the requested `startDate`/`endDate` range, with an optional `status` filter

## \[1.3.0] - 2026-06-18

### Added

* add `status` field (`past` / `active` / `future`) on the collaborators endpoint
* expose all endpoints under the `/organizations/[organizationId]` path, as an alias of `/companies/[organizationId]`

### Changed

* make the `establishmentId` query parameter optional on read endpoints (organization-wide results when omitted)
* make `establishmentId` nullable in the OIDC user info response

## \[1.2.1] - 2026-02-03

### Fixed

* do not allow non positive numbers for pagination `page` and `limit` parameters

## \[1.2.0] - 2026-01-07

### Changed

* make `estCadre` boolean field nullable

## \[1.1.0] - 2025-12-15

### Added

* add "external\_staff" employment type

## \[1.0.0] - 2025-10-15 (initial release)

### Added

* company API
* collaborators API
* meal-vouchers API
* complementary-contracts API


# Introduction
Source: https://developers.malibou.com/introduction

Build integrations on top of malibou with the public API.

The malibou public API lets partners and customers read and manage HR and
payroll data programmatically.

All endpoints are served under the `/api/public/v1` prefix.

<Note>
  Some endpoints, grouped under **Partners only** in the [API
  reference](/api-reference), are reserved for integration partners with an
  approved partnership agreement with malibou — a self-serve API key cannot
  access them. See [Partner-only scopes](/authentication#partner-only-scopes).
</Note>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Make your first successful call in a few minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Create an API key to call the API.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference">
    Browse every endpoint, its parameters and responses.
  </Card>
</CardGroup>

## Conventions

* All requests and responses use `application/json`.
* Dates are ISO 8601 strings.
* List endpoints are paginated (see [Pagination](/usage/pagination)).
* Errors follow standard HTTP status codes (see [Errors](/usage/errors)).


# Quickstart
Source: https://developers.malibou.com/quickstart

Make your first successful call to the malibou public API.

Get your first successful call working in a few minutes: create an API key,
call an endpoint, then page through the results.

<Steps>
  <Step title="Create an API key">
    In the malibou app, go to [**Profile button → My company → API
    keys**](https://app.malibou.com/admin/company/api-keys), click **Create
    an API key**, and tick the `org:employee:read` permission. Copy the
    secret shown (you won't be able to view it again). See
    [Authentication](/authentication) for the full list of scopes and how to
    manage keys.
  </Step>

  <Step title="Retrieve your organization id">
    Open the [API keys page](https://app.malibou.com/admin/company/api-keys), open
    the actions menu (next to **Create an API key**) and choose **Copy
    organisation ID**. See
    [Authentication](/authentication#retrieve-your-organization-id) for details.
  </Step>

  <Step title="Make your first request">
    Call the collaborators endpoint with your key as a Bearer token:

    ```bash theme={null}
    curl "https://app.malibou.com/api/public/v1/organizations/{organizationId}/collaborators" \
      -H "Authorization: Bearer $API_KEY"
    ```
  </Step>

  <Step title="Paginate through the results">
    List endpoints return results in pages. Add `page` and `limit` to control
    how many results come back:

    ```bash theme={null}
    curl "https://app.malibou.com/api/public/v1/organizations/{organizationId}/collaborators?page=1&limit=50" \
      -H "Authorization: Bearer $API_KEY"
    ```

    Iterate by incrementing `page` until a page returns fewer items than
    `limit`. See [Pagination](/usage/pagination) for details.
  </Step>
</Steps>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/authentication">
    Scopes, key management and the full authentication guide.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference">
    Browse every endpoint, its parameters and responses.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/usage/errors">
    How the API reports errors.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/usage/rate-limits">
    Stay within the request limits.
  </Card>
</CardGroup>


# Errors
Source: https://developers.malibou.com/usage/errors

How the API reports errors.

The API uses standard HTTP status codes. Errors return a JSON body describing
what went wrong.

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| `400`  | Bad request: invalid parameters or body.                                   |
| `401`  | Unauthorized: missing, invalid or expired API key.                         |
| `403`  | Forbidden: the API key lacks the required [scope](/authentication#scopes). |
| `404`  | Not found: the resource does not exist or is not accessible.               |
| `429`  | Too many requests: see [Rate limits](/usage/rate-limits).                  |
| `500`  | Internal server error: retry later or contact support.                     |

## Handling expired or revoked API keys

A `401` typically means the API key has expired or has been revoked. You may
generate a new API key.

## Handling validation errors

A `400` indicates a malformed request, for example a non-positive `page` or
`limit` (see [Pagination](/usage/pagination)). Inspect the response body for
details and correct the request before retrying.


# Pagination
Source: https://developers.malibou.com/usage/pagination

How to page through list endpoints.

List endpoints return results in pages. Control pagination with two query
parameters:

| Parameter | Type    | Description                                           |
| --------- | ------- | ----------------------------------------------------- |
| `page`    | integer | 1-based page number. Must be a positive integer.      |
| `limit`   | integer | Number of items per page. Must be a positive integer. |

<Warning>
  `page` and `limit` must be strictly positive integers. Non-positive values are
  rejected with `400 Bad Request`.
</Warning>

## Example

```bash theme={null}
curl "https://app.malibou.com/api/public/v1/organizations/{organizationId}/collaborators?page=1&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

Iterate by incrementing `page` until a page returns fewer items than `limit`.


# Rate limits
Source: https://developers.malibou.com/usage/rate-limits

Stay within the request limits.

To keep the API healthy for everyone, requests are rate limited. When you
exceed the limit, the API responds with `429 Too Many Requests`.

## Best practices

* **Back off and retry.** On a `429`, wait before retrying, ideally with
  exponential backoff.
* **Page efficiently.** Use a reasonable `limit` rather than many small requests
  (see [Pagination](/usage/pagination)).
* **Cache when possible.** Avoid re-fetching data that rarely changes.

<Note>
  If your integration needs a higher limit, [contact
  us](mailto:support@malibou.com).
</Note>


# Versioning
Source: https://developers.malibou.com/usage/versioning

How the malibou public API is versioned.

The malibou public API follows [Semantic Versioning](https://semver.org). The
current major version is **v1** and is served under `/api/public/v1`.

<Note>
  Only the latest version of the API is exposed and documented. There is no
  access to previous minor versions (as they do not introduce breaking changes).
</Note>

* **Major** (`v1` → `v2`): breaking changes.
* **Minor** (`1.1.0` → `1.2.0`): backward-compatible additions (new endpoints,
  new optional fields).
* **Patch** (`1.2.0` → `1.2.1`): backward-compatible fixes.

## Staying up to date

Every change is recorded in the [Changelog](/changelog).