---
title: "Lister les mois de paie"
description: "Liste les mois de paie de chaque établissement, du plus récent au plus ancien, avec l’état de leur DSN mensuelle. Seuls les mois ouverts dans Puncto sont listés, pas ceux repris de votre ancien logiciel de paie.\n\nUn mois rouvert crée une nouvelle révision : l’ancienne passe à `SUPERSEDED` et `supersededById` désigne la nouvelle."
---

> 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 › Déclarations

`GET /public/v1/payroll-months`

Liste les mois de paie de chaque établissement, du plus récent au plus ancien, avec l’état de leur DSN mensuelle. Seuls les mois ouverts dans Puncto sont listés, pas ceux repris de votre ancien logiciel de paie.

Un mois rouvert crée une nouvelle révision : l’ancienne passe à `SUPERSEDED` et `supersededById` désigne la nouvelle.

## Authentication

- `bearerAuth`, http, header `Authorization`

## Query parameters

- `page` (`listPayrollMonths.query.page`; integer, optional) — Numéro de page, à partir de 1.
  - min 1; default `1`
- `perPage` (`listPayrollMonths.query.perPage`; integer, optional) — Nombre d’éléments par page, 200 au plus.
  - min 1; max 200; default `50`
- `year` (`listPayrollMonths.query.year`; integer, optional) — Année du mois de paie.
  - min 2000; max 2100; example `2026`
- `month` (`listPayrollMonths.query.month`; integer, optional) — Mois de paie, de 1 (janvier) à 12.
  - min 1; max 12; example `9`
- `establishmentId` (`listPayrollMonths.query.establishmentId`; string, optional) — Identifiant Puncto de l’établissement.
  - example `"esta_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `status[]` (`listPayrollMonths.query.status[]`; array<string>, optional) — Statuts à garder. Répétez le paramètre pour en passer plusieurs.

## Code samples

### cURL

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

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/payroll-months';
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/payroll-months"

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

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

print(response.text)
```

## Responses

### 200

Page de mois de paie

#### Example

```json
{
  "data": [
    {
      "payrollMonthId": "pmon_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "establishmentId": "esta_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "year": 0,
      "month": 0,
      "status": "STARTED",
      "revision": 0,
      "closedAt": "2019-08-24T14:15:22Z",
      "reopenedAt": "2019-08-24T14:15:22Z",
      "reopenReason": "string",
      "supersededById": "pmon_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "dsn": {
        "declarationTrackingId": "dtra_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
        "status": "queued",
        "simplifiedStatus": "in-progress",
        "crmStatus": "ok",
        "idFlux": "string",
        "documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
        "createdAt": "2019-08-24T14:15:22Z",
        "updatedAt": "2019-08-24T14:15:22Z"
      },
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "total": 0,
    "page": 0,
    "perPage": 0,
    "currentPage": 0,
    "firstPage": 0,
    "lastPage": 0
  }
}
```

- `data` (`listPayrollMonths.response.200.data`; array<object>, required)
  - `payrollMonthId` (`listPayrollMonths.response.200.data.payrollMonthId`; string, required) — Identifiant Puncto du mois de paie
  - `establishmentId` (`listPayrollMonths.response.200.data.establishmentId`; string, required) — Établissement du mois de paie
  - `year` (`listPayrollMonths.response.200.data.year`; number, required) — Année
  - `month` (`listPayrollMonths.response.200.data.month`; number, required) — Mois (1-12)
  - `status` (`listPayrollMonths.response.200.data.status`; string, required) — `STARTED` : en cours ; `CLOSED` : clôturé, bulletins validés ; `SUPERSEDED` : révision remplacée après une réouverture
    - one of `"STARTED"`, `"CLOSED"`, `"SUPERSEDED"`
  - `revision` (`listPayrollMonths.response.200.data.revision`; number, required) — Numéro de révision : 1, puis augmenté de 1 à chaque réouverture du mois
  - `closedAt` (`listPayrollMonths.response.200.data.closedAt`; any of, required) — Date de clôture, null tant que le mois n'est pas clôturé
    - any of: `string`, `null`
  - `reopenedAt` (`listPayrollMonths.response.200.data.reopenedAt`; any of, required) — Révision ouverte par une réouverture : date de la réouverture, null sinon
    - any of: `string`, `null`
  - `reopenReason` (`listPayrollMonths.response.200.data.reopenReason`; string | null, required) — Révision ouverte par une réouverture : motif saisi, null sinon
  - `supersededById` (`listPayrollMonths.response.200.data.supersededById`; any of, required) — Révision remplacée (`SUPERSEDED`) : identifiant de la révision qui la remplace, null sinon
    - any of: `string`, `null`
  - `dsn` (`listPayrollMonths.response.200.data.dsn`; any of, required) — DSN mensuelle de la révision, null tant qu'elle n'est pas lancée
    - any of: `PublicApiPayrollMonthDsn`, `null`
  - `createdAt` (`listPayrollMonths.response.200.data.createdAt`; string, required) — Date de création du mois de paie
    - format `date-time`
  - `updatedAt` (`listPayrollMonths.response.200.data.updatedAt`; string, required) — Date de dernière modification du mois de paie
    - format `date-time`
- `meta` (`listPayrollMonths.response.200.meta`; object, required)
  - `total` (`listPayrollMonths.response.200.meta.total`; integer, required) — Nombre total d’éléments.
  - `page` (`listPayrollMonths.response.200.meta.page`; integer, required) — Page renvoyée.
  - `perPage` (`listPayrollMonths.response.200.meta.perPage`; integer, required)
  - `currentPage` (`listPayrollMonths.response.200.meta.currentPage`; integer, required)
  - `firstPage` (`listPayrollMonths.response.200.meta.firstPage`; integer, required)
  - `lastPage` (`listPayrollMonths.response.200.meta.lastPage`; integer, required)

### 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` (`listPayrollMonths.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`listPayrollMonths.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` (`listPayrollMonths.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`listPayrollMonths.response.403.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` (`listPayrollMonths.response.422.errors`; array<object>, required)
  - `message` (`listPayrollMonths.response.422.errors.message`; string, required)
  - `rule` (`listPayrollMonths.response.422.errors.rule`; string, required) — Règle de validation en échec.
  - `field` (`listPayrollMonths.response.422.errors.field`; string, required) — Chemin du champ, par exemple `absences.0.type`.


Source: https://docs.puncto.fr/reference/payroll-months/list/index.md
