---
title: "Créer une période d’astreinte"
description: "Crée une période d’astreinte : une variable de paie `ON_CALL` validée, rattachée au mois de paie de son début, avec le libellé et la contrepartie du type d’astreinte.\n\n- La période tient dans les dates du contrat, sans chevaucher une autre période du même contrat.\n- Une intervention tient dans la période et finit le jour où elle commence : découpez à minuit une intervention de nuit.\n- Contrat en heures : les interventions sont des heures supplémentaires, le contrat doit y être éligible (temps plein). Elles sont payées, ou compensées en repos compensateur de remplacement (`compensationMode`).\n- Forfait jours : une intervention peut créditer des jours de repos (`dayCount`), une journée au plus par jour.\n- Mois de paie clôturé : la paie suivante régularise, et un nouveau récapitulatif d’astreintes est remis au salarié.\n\nVoir le guide [Astreintes](/guides/astreintes)."
---

> 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 › Astreintes

`POST /public/v1/on-call-periods`

Crée une période d’astreinte : une variable de paie `ON_CALL` validée, rattachée au mois de paie de son début, avec le libellé et la contrepartie du type d’astreinte.

- La période tient dans les dates du contrat, sans chevaucher une autre période du même contrat.
- Une intervention tient dans la période et finit le jour où elle commence : découpez à minuit une intervention de nuit.
- Contrat en heures : les interventions sont des heures supplémentaires, le contrat doit y être éligible (temps plein). Elles sont payées, ou compensées en repos compensateur de remplacement (`compensationMode`).
- Forfait jours : une intervention peut créditer des jours de repos (`dayCount`), une journée au plus par jour.
- Mois de paie clôturé : la paie suivante régularise, et un nouveau récapitulatif d’astreintes est remis au salarié.

Voir le guide [Astreintes](/guides/astreintes).

## Authentication

- `bearerAuth`, http, header `Authorization`

## Request body

_Required._

- `contractMatching` (`createOnCallPeriod.contractMatching`; object, required) — Désigne le contrat. Pour un collaborateur, Puncto retient son contrat en vigueur à `eventDate`, à défaut au début de la période.
  - `type` (`createOnCallPeriod.contractMatching.type`; string, required) — Clé de correspondance utilisée par `value`. - `BY_PUNCTO_COLLABORATOR_ID` : `value` est l’identifiant Puncto du collaborateur - `BY_PUNCTO_CONTRACT_ID` : `value` est l’identifiant Puncto du contrat (`GET /public/v1/contracts`), `eventDate` est ignorée
    - one of `"BY_PUNCTO_COLLABORATOR_ID"`, `"BY_PUNCTO_CONTRACT_ID"`
  - `value` (`createOnCallPeriod.contractMatching.value`; string, required) — Identifiant Puncto du collaborateur, ou du contrat avec `BY_PUNCTO_CONTRACT_ID`. Depuis votre `foreignErpId`, retrouvez-le avec `GET /public/v1/collaborators?collaboratorForeignErpId=…`.
    - minLength 1
  - `eventDate` (`createOnCallPeriod.contractMatching.eventDate`; string, optional) — Date de l’événement, pour choisir le contrat quand le collaborateur en a plusieurs sur le mois.
    - format `date`; example `"2026-10-05"`
- `onCallTypeId` (`createOnCallPeriod.onCallTypeId`; string, required) — Identifiant Puncto du type d’astreinte (`GET /public/v1/on-call-types`). Un type désactivé n’est plus accepté pour une nouvelle période.
  - minLength 1; example `"octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY"`
- `start` (`createOnCallPeriod.start`; string, required) — Début de la période. Heure de Paris, sans fuseau : `YYYY-MM-DDTHH:mm`.
  - pattern `^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d$`; example `"2026-11-13T18:00"`
- `end` (`createOnCallPeriod.end`; string, required) — Fin de la période, après son début. Heure de Paris, sans fuseau : `YYYY-MM-DDTHH:mm`.
  - pattern `^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d$`; example `"2026-11-16T08:00"`
- `interventions` (`createOnCallPeriod.interventions`; array<object>, required) — Interventions pendant la période ; tableau vide s’il n’y en a pas.
  - `start` (`createOnCallPeriod.interventions.start`; string, required) — Début de l’intervention, temps de déplacement compris. Heure de Paris, sans fuseau : `YYYY-MM-DDTHH:mm`.
    - pattern `^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d$`; example `"2026-11-14T10:00"`
  - `end` (`createOnCallPeriod.interventions.end`; string, required) — Fin de l’intervention, le jour de son début (00h00 le lendemain au plus tard). Heure de Paris, sans fuseau : `YYYY-MM-DDTHH:mm`.
    - pattern `^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d$`; example `"2026-11-14T12:00"`
  - `location` (`createOnCallPeriod.interventions.location`; string, required) — - `REMOTE` : À distance - `ON_SITE` : Sur site
    - one of `"REMOTE"`, `"ON_SITE"`
  - `dayCount` (`createOnCallPeriod.interventions.dayCount`; string, optional) — Forfait jours uniquement, refusé sur un contrat en heures : jours de repos crédités au compteur de JNT. Par défaut, une demi-journée un jour de repos ou d’absence validée, aucun un jour travaillé. - `NONE` : Aucun (jour travaillé) - `HALF_DAY` : Demi-journée - `FULL_DAY` : Journée
    - one of `"NONE"`, `"HALF_DAY"`, `"FULL_DAY"`
  - `compensationMode` (`createOnCallPeriod.interventions.compensationMode`; string, optional) — Contrat en heures uniquement, `REST` refusé au forfait jours : `PAYMENT` (par défaut) paie l’intervention en heures supplémentaires, `REST` crédite ses heures, majoration comprise, au compteur de repos compensateur de remplacement (RCR). - `PAYMENT` : Paiement des heures supplémentaires - `REST` : Repos compensateur de remplacement
    - one of `"PAYMENT"`, `"REST"`
- `foreignErpId` (`createOnCallPeriod.foreignErpId`; string, optional) — Identifiant de l’élément dans votre système, unique dans l’entreprise pour les variables de paie, astreintes et variables récurrentes réunies : un `foreignErpId` déjà utilisé renvoie `409`.
  - minLength 1; maxLength 255
- `periodCount` (`createOnCallPeriod.periodCount`; number, optional) — Nombre de périodes indemnisées pour un type décompté à la période, deux décimales au plus, 1 par défaut. Ignoré pour un type à l’heure, payé sur la durée de la période.

## Example request

```json
{
  "foreignErpId": "astreinte-2026-11-13-salarie-123",
  "contractMatching": {
    "type": "BY_PUNCTO_COLLABORATOR_ID",
    "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  },
  "onCallTypeId": "octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "start": "2026-11-13T18:00",
  "end": "2026-11-16T08:00",
  "interventions": [
    {
      "start": "2026-11-14T10:00",
      "end": "2026-11-14T12:00",
      "location": "REMOTE"
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.puncto.fr/public/v1/on-call-periods \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "foreignErpId": "astreinte-2026-11-13-salarie-123",
  "contractMatching": {
    "type": "BY_PUNCTO_COLLABORATOR_ID",
    "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  },
  "onCallTypeId": "octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "start": "2026-11-13T18:00",
  "end": "2026-11-16T08:00",
  "interventions": [
    {
      "start": "2026-11-14T10:00",
      "end": "2026-11-14T12:00",
      "location": "REMOTE"
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/on-call-periods';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    foreignErpId: 'astreinte-2026-11-13-salarie-123',
    contractMatching: {type: 'BY_PUNCTO_COLLABORATOR_ID', value: 'coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY'},
    onCallTypeId: 'octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY',
    start: '2026-11-13T18:00',
    end: '2026-11-16T08:00',
    interventions: [{start: '2026-11-14T10:00', end: '2026-11-14T12:00', location: 'REMOTE'}]
  })
};

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/on-call-periods"

payload = {
    "foreignErpId": "astreinte-2026-11-13-salarie-123",
    "contractMatching": {
        "type": "BY_PUNCTO_COLLABORATOR_ID",
        "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
    },
    "onCallTypeId": "octy_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
    "start": "2026-11-13T18:00",
    "end": "2026-11-16T08:00",
    "interventions": [
        {
            "start": "2026-11-14T10:00",
            "end": "2026-11-14T12:00",
            "location": "REMOTE"
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 201

Période créée

#### Example

```json
{
  "payrollVariableId": "pvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "foreignErpId": "string",
  "contractId": "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorForeignErpId": "string",
  "year": 0,
  "month": 0,
  "status": "PENDING",
  "data": {
    "type": "PRIME",
    "name": "string",
    "amount": 0,
    "base": 0,
    "primeType": "HOLIDAY_BONUS",
    "isAbsenceSensitive": true,
    "attachmentPeriod": {
      "startDate": "2019-08-24",
      "endDate": "2019-08-24"
    }
  },
  "proofFiles": [
    {
      "documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "displayFileName": "string",
      "fileType": "PAYSLIP",
      "mimeType": "image/jpeg",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "businessMealParticipantContractIds": [
    "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  ],
  "origin": "ENTRY",
  "isLocked": true,
  "lockState": {
    "state": "OPEN"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

- `payrollVariableId` (`createOnCallPeriod.response.201.payrollVariableId`; string, required) — Identifiant Puncto de la variable de paie
- `foreignErpId` (`createOnCallPeriod.response.201.foreignErpId`; string | null, required) — Identifiant de la variable dans votre système, null si elle n'en a pas
- `contractId` (`createOnCallPeriod.response.201.contractId`; string, required) — Contrat qui porte la variable
- `collaboratorId` (`createOnCallPeriod.response.201.collaboratorId`; string, required) — Collaborateur titulaire du contrat
- `collaboratorForeignErpId` (`createOnCallPeriod.response.201.collaboratorForeignErpId`; string | null, required) — Identifiant du collaborateur dans votre système, null s'il n'a pas été renseigné
- `year` (`createOnCallPeriod.response.201.year`; number, required) — Année du mois de paie
- `month` (`createOnCallPeriod.response.201.month`; number, required) — Mois de paie, de 1 (janvier) à 12
- `status` (`createOnCallPeriod.response.201.status`; string, required) — Seules les variables `VALIDATED` entrent dans le bulletin
  - one of `"PENDING"`, `"VALIDATED"`, `"REJECTED"`
- `data` (`createOnCallPeriod.response.201.data`; any of, required) — Contenu de la variable
  - any of: `PublicApiPayrollVariablePrimeData`, `PublicApiPayrollVariableSalaryDeductionData`, `PublicApiPayrollVariableInKindBenefitData`, `PublicApiPayrollVariableOvertimeData`, `PublicApiPayrollVariableMonthlyOvertimeData`, `PublicApiPayrollVariableRemoteWorkDayData`, `PublicApiPayrollVariableMealAllowanceAdjustmentData`, `PublicApiPayrollVariableMealVoucherAdjustmentData`, `PublicApiPayrollVariableSalaryAdvanceData`, `PublicApiPayrollVariableProfitSharingData`, `PublicApiPayrollVariableHolidayVoucherData`, `PublicApiPayrollVariablePrevoyanceIjData`, `PublicApiPayrollVariableOnCallData`, `PublicApiPayrollVariableExpenseNoteData`, `PublicApiPayrollVariablePersonalTransportData`, `PublicApiPayrollVariableOtherTaxFreeIndemnityData`
- `proofFiles` (`createOnCallPeriod.response.201.proofFiles`; array<object>, required) — Justificatifs, dans leur ordre d'ajout
  - `documentId` (`createOnCallPeriod.response.201.proofFiles.documentId`; string, required) — Identifiant Puncto du document
  - `displayFileName` (`createOnCallPeriod.response.201.proofFiles.displayFileName`; string, required) — Nom du document affiché dans Puncto
  - `fileType` (`createOnCallPeriod.response.201.proofFiles.fileType`; string, required) — Type de document
    - one of `"PAYSLIP"`, `"PAYSLIP_ARCHIVED"`, `"DSN_MONTHLY"`, `"DSN_WORK_STOPPAGE"`, `"DSN_WORK_STOPPAGE_RESUMPTION"`, `"DSN_FCTU"`, `"DSN_SADV"`, `"CRM"`, `"EXPENSE_BILL"`, `"MEAL_VOUCHER_EXPORT"`, `"SEPA_PAYROLL"`, `"SEPA_SDTC"`, `"ABSENCE_PROOF"`, `"DPAE"`, `"DPAE_RETURN"`, `"ACCOUNTING_PAYROLL_OD"`, `"ACCOUNTING_PAYROLL_DSN_RECAP"`, `"ACCOUNTING_CONTRIBUTIONS_DETAIL"`, `"ACCOUNTING_CONTRIBUTIONS_RECAP"`, `"ACCOUNTING_PAYBOOK"`, `"ACCOUNTING_PAYROLL_LOG"`, `"ACCOUNTING_REST_RECAP"`, `"IDENTITY"`, `"VITALE"`, `"RIB"`, `"CONTRACT"`, `"INTERNSHIP_AGREEMENT"`, `"INTERNSHIP_CERTIFICATE"`, `"INTERNSHIP_CERTIFICATE_SIGNED"`, `"WORK_CERTIFICATE"`, `"WORK_CERTIFICATE_SIGNED"`, `"FINAL_SETTLEMENT_RECEIPT"`, `"FINAL_SETTLEMENT_RECEIPT_SIGNED"`, `"PROFIT_SHARING_STATEMENT"`, `"ON_CALL_STATEMENT"`, `"PROFIT_SHARING_AGREEMENT_RECEIPT"`, `"BILLING_INVOICE"`, `"COMPANY_SETUP_CHECKLIST"`, `"FCTU_AER"`, `"EXPORT"`, `"ABSENCE_BATCH"`, `"VARIABLE_BATCH"`, `"OC_FICHE"`, `"BPIJ"`, `"SIGNATURE_AUDIT_TRAIL"`, `"OTHER"`
  - `mimeType` (`createOnCallPeriod.response.201.proofFiles.mimeType`; any of, required) — Type MIME du fichier
    - any of: `ImageMimeType`, `OtherMimeType`
  - `createdAt` (`createOnCallPeriod.response.201.proofFiles.createdAt`; string, required) — Date d'enregistrement du document dans Puncto
    - format `date-time`
- `businessMealParticipantContractIds` (`createOnCallPeriod.response.201.businessMealParticipantContractIds`; array<string>, required) — Note de frais de repas d'affaires : contrats des participants, dont les titres restaurant du mois sont réduits dès l'enregistrement de la note, quel que soit son statut
- `origin` (`createOnCallPeriod.response.201.origin`; string, required) — Parcours de Puncto qui a créé la variable : - `ENTRY` : saisie dans Puncto ou importée par l'API ; aussi les indemnités générées par la clôture d'un contrat (celles du mois du solde de tout compte se modifient depuis la clôture) et le report d'un net négatif, généré à la clôture du mois sur le mois suivant (retenue `LAST_MONTH_NEGATIVE_PAY_ADVANCE`) ; - `VARIABLE_BATCH` : import d'un fichier de variables dans Puncto, modifiable comme une saisie ; - `TIMESHEET` : heures supplémentaires payées d'une feuille de temps validée, modifiables seulement depuis la feuille ; - `ON_CALL_PERIOD` : période d'astreinte, modifiable par l'import des périodes d'astreinte ; - `PROFIT_SHARING` : versement d'intéressement, modifiable seulement depuis ce versement ; - `HOLIDAY_BONUS`, `HOLIDAY_VOUCHER_ATTRIBUTION` : prime de vacances ou chèques-vacances de la page Primes, modifiables seulement depuis cette page ; - `VALUE_SHARING_BONUS` : versement de prime de partage de la valeur (PPV) de la page Primes ; comme dans l'application, la variable peut changer de statut ou être supprimée ; - `PREVOYANCE_IJ_SLIP` : part d'un bordereau de paiement prévoyance, modifiable seulement depuis ce bordereau.
  - one of `"ENTRY"`, `"VARIABLE_BATCH"`, `"TIMESHEET"`, `"ON_CALL_PERIOD"`, `"PROFIT_SHARING"`, `"HOLIDAY_BONUS"`, `"HOLIDAY_VOUCHER_ATTRIBUTION"`, `"VALUE_SHARING_BONUS"`, `"PREVOYANCE_IJ_SLIP"`
- `isLocked` (`createOnCallPeriod.response.201.isLocked`; boolean, required) — Plus aucune modification n'est possible : le mois de paie est clôturé et aucune paie ouverte ne peut porter la régularisation (`lockState.state` vaut `BLOCKED`)
- `lockState` (`createOnCallPeriod.response.201.lockState`; any of, required) — Effet d'une modification de la variable : sur la paie du mois, ou en saisie tardive régularisée par une paie ultérieure
  - any of: `object`, `object`, `object`
- `createdAt` (`createOnCallPeriod.response.201.createdAt`; string, required) — Date de création de la variable
  - format `date-time`
- `updatedAt` (`createOnCallPeriod.response.201.updatedAt`; string, required) — Date de dernière modification de la variable
  - format `date-time`

### 400

Période refusée : astreintes non activées ou règle non respectée

#### Example

```json
{
  "error": "Les astreintes ne sont pas activées pour cette entreprise."
}
```

- `error` (`createOnCallPeriod.response.400.error`; string, required) — Message lisible, en français.
- `errorCode` (`createOnCallPeriod.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` (`createOnCallPeriod.response.401.error`; string, required) — Message lisible, en français.
- `errorCode` (`createOnCallPeriod.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` (`createOnCallPeriod.response.403.error`; string, required) — Message lisible, en français.
- `errorCode` (`createOnCallPeriod.response.403.errorCode`; string, optional) — Code stable, sur certaines erreurs.

### 404

Collaborateur ou contrat introuvable

#### Example

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

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

### 409

`foreignErpId` déjà utilisé

#### Example

```json
{
  "error": "Le foreignErpId astreinte-2026-11-13-salarie-123 désigne déjà une autre variable."
}
```

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


Source: https://docs.puncto.fr/reference/on-call-periods/create/index.md
