---
title: "Lister les soldes de congés"
description: "Calcule à une date les compteurs de congés de chaque contrat en vigueur : congés payés N, N-1 et N-2, ancienneté, fractionnement, jours non travaillés des forfaits jours, RTT, repos compensateurs et congés de stage. Les absences validées sont décomptées, pas les demandes en attente. Rien n’est enregistré.\n\n- Un solde incalculable vaut `null`, avec sa raison dans `unavailableReason`, sans faire échouer la page.\n- Les mandats sociaux n’ont pas de compteurs et ne sont pas listés.\n- 50 contrats par page au plus ; date de calcul au plus tard la fin du douzième mois à venir."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.puncto.fr/llms.txt
> Use this file to discover all available pages before exploring further.

Path: API Puncto › Temps et congés

`GET /public/v1/holidays-balances`

Calcule à une date les compteurs de congés de chaque contrat en vigueur : congés payés N, N-1 et N-2, ancienneté, fractionnement, jours non travaillés des forfaits jours, RTT, repos compensateurs et congés de stage. Les absences validées sont décomptées, pas les demandes en attente. Rien n’est enregistré.

- Un solde incalculable vaut `null`, avec sa raison dans `unavailableReason`, sans faire échouer la page.
- Les mandats sociaux n’ont pas de compteurs et ne sont pas listés.
- 50 contrats par page au plus ; date de calcul au plus tard la fin du douzième mois à venir.

## Authentication

- `bearerAuth`, http, header `Authorization`

## Query parameters

- `page` (`listHolidaysBalances.query.page`; integer, optional) — Numéro de page, à partir de 1.
  - min 1; default `1`
- `perPage` (`listHolidaysBalances.query.perPage`; integer, optional) — Nombre d’éléments par page, 50 au plus.
  - min 1; max 50; default `50`
- `calculationDate` (`listHolidaysBalances.query.calculationDate`; string, optional) — Date de calcul des soldes. Par défaut, aujourd’hui (heure de Paris). Au plus tard la fin du douzième mois à venir (le 31/10/2027 pour une demande du 28/10/2026), sinon `422`.
  - format `date`; example `"2026-10-15"`
- `contractId` (`listHolidaysBalances.query.contractId`; string, optional) — Identifiant Puncto du contrat. Page vide s’il n’est pas en vigueur à `calculationDate`.
  - example `"cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `collaboratorId` (`listHolidaysBalances.query.collaboratorId`; string, optional) — Identifiant Puncto du collaborateur. Ne pas combiner avec `collaboratorForeignErpId`.
  - example `"coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `collaboratorForeignErpId` (`listHolidaysBalances.query.collaboratorForeignErpId`; string, optional) — Identifiant du collaborateur dans votre système (`foreignErpId`). Ne pas combiner avec `collaboratorId`.
  - example `"salarie-123"`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://api.puncto.fr/public/v1/holidays-balances \
  --header 'Authorization: Bearer <token>'
```

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/holidays-balances';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.puncto.fr/public/v1/holidays-balances"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Page de soldes de congés

#### Example

```json
{
  "data": [
    {
      "contractId": "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "collaboratorForeignErpId": "string",
      "calculationDate": "2019-08-24",
      "balance": {
        "pto": {
          "earned": 0,
          "used": 0
        },
        "ptoN1": {
          "earned": 0,
          "used": 0
        },
        "ptoN2": {
          "earned": 0,
          "used": 0
        },
        "seniority": {
          "earned": 0,
          "used": 0
        },
        "splitDays": {
          "earned": 0,
          "used": 0
        },
        "jnt": {
          "earned": 0,
          "used": 0
        },
        "rtt": {
          "earned": 0,
          "used": 0
        },
        "cor": {
          "earned": 0,
          "used": 0
        },
        "rcr": {
          "earned": 0,
          "used": 0
        },
        "internshipPto": {
          "earned": 0,
          "used": 0
        }
      },
      "periods": {
        "pto": {
          "startDate": "2019-08-24",
          "endDate": "2019-08-24"
        },
        "ptoN1": {
          "startDate": "2019-08-24",
          "endDate": "2019-08-24"
        },
        "ptoN2": {
          "startDate": "2019-08-24",
          "endDate": "2019-08-24"
        },
        "seniority": {
          "startDate": "2019-08-24",
          "endDate": "2019-08-24"
        },
        "splitDays": {
          "startDate": "2019-08-24",
          "endDate": "2019-08-24"
        },
        "jnt": {
          "startDate": "2019-08-24",
          "endDate": "2019-08-24"
        }
      },
      "unavailableReason": "string"
    }
  ],
  "meta": {
    "total": 0,
    "page": 0,
    "perPage": 0,
    "currentPage": 0,
    "firstPage": 0,
    "lastPage": 0
  }
}
```

- `data` (`listHolidaysBalances.response.200.data`; array<object>, required)
  - `contractId` (`listHolidaysBalances.response.200.data.contractId`; string, required) — Identifiant Puncto du contrat
  - `collaboratorId` (`listHolidaysBalances.response.200.data.collaboratorId`; string, required) — Identifiant Puncto du collaborateur
  - `collaboratorForeignErpId` (`listHolidaysBalances.response.200.data.collaboratorForeignErpId`; string | null, required) — Identifiant du collaborateur dans votre système, null s'il n'a pas été renseigné
  - `calculationDate` (`listHolidaysBalances.response.200.data.calculationDate`; string, required) — Date à laquelle les soldes sont calculés
    - format `date`
  - `balance` (`listHolidaysBalances.response.200.data.balance`; any of, required) — Compteurs de congés, null quand ils ne peuvent pas être calculés (voir `unavailableReason`)
    - any of: `PublicApiHolidaysBalanceCounters`, `null`
  - `periods` (`listHolidaysBalances.response.200.data.periods`; object, required) — Périodes de référence des compteurs
    - `pto` (`listHolidaysBalances.response.200.data.periods.pto`; object, required) — Période des congés payés en cours d'acquisition (N)
      - `startDate` (`listHolidaysBalances.response.200.data.periods.pto.startDate`; string, required) — Premier jour de la période
        - format `date`
      - `endDate` (`listHolidaysBalances.response.200.data.periods.pto.endDate`; string, required) — Dernier jour de la période
        - format `date`
    - `ptoN1` (`listHolidaysBalances.response.200.data.periods.ptoN1`; object, required) — Période des congés payés N-1
      - `startDate` (`listHolidaysBalances.response.200.data.periods.ptoN1.startDate`; string, required) — Premier jour de la période
        - format `date`
      - `endDate` (`listHolidaysBalances.response.200.data.periods.ptoN1.endDate`; string, required) — Dernier jour de la période
        - format `date`
    - `ptoN2` (`listHolidaysBalances.response.200.data.periods.ptoN2`; object, required) — Période des congés payés N-2
      - `startDate` (`listHolidaysBalances.response.200.data.periods.ptoN2.startDate`; string, required) — Premier jour de la période
        - format `date`
      - `endDate` (`listHolidaysBalances.response.200.data.periods.ptoN2.endDate`; string, required) — Dernier jour de la période
        - format `date`
    - `seniority` (`listHolidaysBalances.response.200.data.periods.seniority`; object, required) — Période des congés d'ancienneté
      - `startDate` (`listHolidaysBalances.response.200.data.periods.seniority.startDate`; string, required) — Premier jour de la période
        - format `date`
      - `endDate` (`listHolidaysBalances.response.200.data.periods.seniority.endDate`; string, required) — Dernier jour de la période
        - format `date`
    - `splitDays` (`listHolidaysBalances.response.200.data.periods.splitDays`; object, required) — Période des jours de fractionnement
      - `startDate` (`listHolidaysBalances.response.200.data.periods.splitDays.startDate`; string, required) — Premier jour de la période
        - format `date`
      - `endDate` (`listHolidaysBalances.response.200.data.periods.splitDays.endDate`; string, required) — Dernier jour de la période
        - format `date`
    - `jnt` (`listHolidaysBalances.response.200.data.periods.jnt`; object, required) — Période des jours non travaillés (forfait jours)
      - `startDate` (`listHolidaysBalances.response.200.data.periods.jnt.startDate`; string, required) — Premier jour de la période
        - format `date`
      - `endDate` (`listHolidaysBalances.response.200.data.periods.jnt.endDate`; string, required) — Dernier jour de la période
        - format `date`
  - `unavailableReason` (`listHolidaysBalances.response.200.data.unavailableReason`; string | null, required) — Raison pour laquelle `balance` vaut null, null sinon
- `meta` (`listHolidaysBalances.response.200.meta`; object, required)
  - `total` (`listHolidaysBalances.response.200.meta.total`; integer, required) — Nombre total d’éléments.
  - `page` (`listHolidaysBalances.response.200.meta.page`; integer, required) — Page renvoyée.
  - `perPage` (`listHolidaysBalances.response.200.meta.perPage`; integer, required)
  - `currentPage` (`listHolidaysBalances.response.200.meta.currentPage`; integer, required)
  - `firstPage` (`listHolidaysBalances.response.200.meta.firstPage`; integer, required)
  - `lastPage` (`listHolidaysBalances.response.200.meta.lastPage`; integer, required)

### 400

Date de calcul antérieure au paramétrage de paie de l’entreprise dans Puncto

#### Example

```json
{
  "error": "Les soldes de congés ne peuvent pas être calculés avant le 01/01/2024, début du paramétrage de paie de l'entreprise."
}
```

- `error` (`listHolidaysBalances.response.400.error`; string, required) — Message lisible, en français.
- `errorCode` (`listHolidaysBalances.response.400.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 401

Clé d’API absente, invalide ou révoquée

#### Example

```json
{
  "error": "Les endpoints de l’API publique sont réservés aux comptes application."
}
```

- `error` (`listHolidaysBalances.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`listHolidaysBalances.response.401.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 403

Opération hors de l’accès de la clé d’API

#### Example

```json
{
  "error": "Opération interdite"
}
```

- `error` (`listHolidaysBalances.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`listHolidaysBalances.response.403.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 404

Collaborateur du filtre introuvable

#### Example

```json
{
  "error": "Collaborateur non trouvé"
}
```

- `error` (`listHolidaysBalances.response.404.error`; string, required) — Message lisible, en français.
- `errorCode` (`listHolidaysBalances.response.404.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 422

Paramètres invalides

#### Example

```json
{
  "errors": [
    {
      "message": "Le champ statut de l’absence doit être une valeur autorisée",
      "rule": "enum",
      "field": "status"
    }
  ]
}
```

- `errors` (`listHolidaysBalances.response.422.errors`; array<object>, required)
  - `message` (`listHolidaysBalances.response.422.errors.message`; string, required)
  - `rule` (`listHolidaysBalances.response.422.errors.rule`; string, required) — Règle de validation en échec.
  - `field` (`listHolidaysBalances.response.422.errors.field`; string, required) — Chemin du champ, par exemple `absences.0.type`.


Source: https://docs.puncto.fr/reference/holidays-balances/list/index.md
