---
title: "Créer une variable récurrente"
description: "Crée une variable récurrente : prime (indemnité d’occupation du domicile ou autre), avantage en nature, véhicule de fonction dont Puncto calcule l’avantage chaque mois, ou abonnement annuel de transport public. Les brouillons de bulletin des mois concernés sont recalculés.\n\nElle se crée sur des mois encore ouverts, dans les dates du contrat. Son contenu ne se modifie plus : pour changer un montant, supprimez-la (tant qu’aucun mois verrouillé ne l’a versée) ou fixez son dernier mois de versement, puis créez-en une nouvelle.\n\nJustificatifs : envoyez la requête en `multipart/form-data` avec des fichiers `proofFiles[i]` (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip)."
---

> 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 › Variables récurrentes

`POST /public/v1/recurring-variables`

Crée une variable récurrente : prime (indemnité d’occupation du domicile ou autre), avantage en nature, véhicule de fonction dont Puncto calcule l’avantage chaque mois, ou abonnement annuel de transport public. Les brouillons de bulletin des mois concernés sont recalculés.

Elle se crée sur des mois encore ouverts, dans les dates du contrat. Son contenu ne se modifie plus : pour changer un montant, supprimez-la (tant qu’aucun mois verrouillé ne l’a versée) ou fixez son dernier mois de versement, puis créez-en une nouvelle.

Justificatifs : envoyez la requête en `multipart/form-data` avec des fichiers `proofFiles[i]` (pdf, jpg, jpeg, png, webp, heic, txt, csv, xml, json, xlsx, doc, docx, zip).

## Authentication

- `bearerAuth`, http, header `Authorization`

## Request body

_Required._

- `contractMatching` (`createRecurringVariable.contractMatching`; object, required) — Contrat qui verse la variable. Désigné par le collaborateur : son contrat actif à `eventDate`, à défaut à la fin puis au début du premier mois de versement, et pour un abonnement annuel commencé avant l’embauche, son contrat actuel.
  - `type` (`createRecurringVariable.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` (`createRecurringVariable.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` (`createRecurringVariable.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"`
- `data` (`createRecurringVariable.data`; one of, required) — Ce que la variable verse chaque mois.
  - one of: `Prime`, `Avantage en nature`, `Véhicule de fonction évalué au forfait`, `Abonnement annuel de transport public`
- `foreignErpId` (`createRecurringVariable.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
- `status` (`createRecurringVariable.status`; string, optional) — Par défaut `VALIDATED`. Seule une variable `VALIDATED` est versée. - `PENDING` : En attente - `VALIDATED` : Accepté - `REJECTED` : Refusé
  - one of `"PENDING"`, `"VALIDATED"`, `"REJECTED"`
- `frequency` (`createRecurringVariable.frequency`; string, optional) — Périodicité des versements. Requise, sauf pour un abonnement annuel. - `MONTHLY` : Mensuelle
  - one of `"MONTHLY"`
- `startYear` (`createRecurringVariable.startYear`; integer, optional) — Année du premier mois de versement. Requise, sauf pour un abonnement annuel.
  - min 2000; max 2100; example `2027`
- `startMonth` (`createRecurringVariable.startMonth`; integer, optional) — Premier mois de versement. Requis, sauf pour un abonnement annuel.
  - min 1; max 12; example `1`
- `endYear` (`createRecurringVariable.endYear`; integer | null, optional) — Année du dernier mois de versement, avec `endMonth`.
  - min 2000; max 2100; example `2027`
- `endMonth` (`createRecurringVariable.endMonth`; integer | null, optional) — Dernier mois de versement inclus, avec `endYear`. Omis, la variable court sans fin.
  - min 1; max 12; example `1`

## Example request

```json
{
  "foreignErpId": "teletravail-salarie-123",
  "contractMatching": {
    "type": "BY_PUNCTO_COLLABORATOR_ID",
    "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  },
  "data": {
    "type": "PRIME",
    "name": "Indemnité d’occupation du domicile",
    "amount": 30,
    "primeType": "HOME_OCCUPATION_ALLOWANCE",
    "isAbsenceSensitive": false
  },
  "frequency": "MONTHLY",
  "startYear": 2026,
  "startMonth": 12
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.puncto.fr/public/v1/recurring-variables \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "foreignErpId": "teletravail-salarie-123",
  "contractMatching": {
    "type": "BY_PUNCTO_COLLABORATOR_ID",
    "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
  },
  "data": {
    "type": "PRIME",
    "name": "Indemnité d’occupation du domicile",
    "amount": 30,
    "primeType": "HOME_OCCUPATION_ALLOWANCE",
    "isAbsenceSensitive": false
  },
  "frequency": "MONTHLY",
  "startYear": 2026,
  "startMonth": 12
}
'
```

### TypeScript

```typescript
const url = 'https://api.puncto.fr/public/v1/recurring-variables';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    foreignErpId: 'teletravail-salarie-123',
    contractMatching: {type: 'BY_PUNCTO_COLLABORATOR_ID', value: 'coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY'},
    data: {
      type: 'PRIME',
      name: 'Indemnité d’occupation du domicile',
      amount: 30,
      primeType: 'HOME_OCCUPATION_ALLOWANCE',
      isAbsenceSensitive: false
    },
    frequency: 'MONTHLY',
    startYear: 2026,
    startMonth: 12
  })
};

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/recurring-variables"

payload = {
    "foreignErpId": "teletravail-salarie-123",
    "contractMatching": {
        "type": "BY_PUNCTO_COLLABORATOR_ID",
        "value": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY"
    },
    "data": {
        "type": "PRIME",
        "name": "Indemnité d’occupation du domicile",
        "amount": 30,
        "primeType": "HOME_OCCUPATION_ALLOWANCE",
        "isAbsenceSensitive": False
    },
    "frequency": "MONTHLY",
    "startYear": 2026,
    "startMonth": 12
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

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

print(response.text)
```

## Responses

### 201

Variable récurrente créée

#### Example

```json
{
  "recurringVariableId": "rvar_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "foreignErpId": "string",
  "contractId": "cont_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
  "collaboratorForeignErpId": "string",
  "data": {
    "type": "PRIME",
    "name": "string",
    "amount": 0,
    "primeType": "HOLIDAY_BONUS",
    "isAbsenceSensitive": true
  },
  "frequency": "MONTHLY",
  "status": "PENDING",
  "startYear": 0,
  "startMonth": 0,
  "endYear": 0,
  "endMonth": 0,
  "lockedThrough": {
    "year": 0,
    "month": 0
  },
  "proofFiles": [
    {
      "documentId": "cfil_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
      "displayFileName": "string",
      "fileType": "PAYSLIP",
      "mimeType": "image/jpeg",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
```

- `recurringVariableId` (`createRecurringVariable.response.201.recurringVariableId`; string, required) — Identifiant Puncto de la variable récurrente
- `foreignErpId` (`createRecurringVariable.response.201.foreignErpId`; string | null, required) — Identifiant de la variable récurrente dans votre système, null si elle n'a pas été importée
- `contractId` (`createRecurringVariable.response.201.contractId`; string, required) — Contrat qui verse la variable
- `collaboratorId` (`createRecurringVariable.response.201.collaboratorId`; string, required) — Collaborateur titulaire du contrat
- `collaboratorForeignErpId` (`createRecurringVariable.response.201.collaboratorForeignErpId`; string | null, required) — Identifiant du collaborateur dans votre système, null s'il n'a pas été renseigné
- `data` (`createRecurringVariable.response.201.data`; any of, required) — Ce que la variable verse chaque mois
  - any of: `PublicApiRecurringPrimeData`, `PublicApiRecurringInKindBenefitData`, `PublicApiAnnualPublicTransportData`
- `frequency` (`createRecurringVariable.response.201.frequency`; string, required) — Périodicité des versements
- `status` (`createRecurringVariable.response.201.status`; string, required) — Seule une variable validée (`VALIDATED`) est versée ; une variable en attente (`PENDING`) attend un administrateur
  - one of `"PENDING"`, `"VALIDATED"`, `"REJECTED"`
- `startYear` (`createRecurringVariable.response.201.startYear`; number, required) — Année du premier mois de versement
- `startMonth` (`createRecurringVariable.response.201.startMonth`; number, required) — Premier mois de versement, de 1 à 12
- `endYear` (`createRecurringVariable.response.201.endYear`; number | null, required) — Année du dernier mois de versement, null tant que la variable court sans fin
- `endMonth` (`createRecurringVariable.response.201.endMonth`; number | null, required) — Dernier mois de versement inclus, de 1 à 12, null tant que la variable court sans fin
- `lockedThrough` (`createRecurringVariable.response.201.lockedThrough`; any of, required) — Dernier mois de la période déjà verrouillé (paie clôturée ou bulletin validé), null si aucun ou si la variable n'est pas validée. Une variable verrouillée ne se supprime plus et ne se modifie plus : seul son dernier mois de versement peut encore être fixé, après ce mois
  - any of: `PublicApiYearMonth`, `null`
- `proofFiles` (`createRecurringVariable.response.201.proofFiles`; array<object>, required) — Justificatifs joints dans Puncto
  - `documentId` (`createRecurringVariable.response.201.proofFiles.documentId`; string, required) — Identifiant Puncto du document
  - `displayFileName` (`createRecurringVariable.response.201.proofFiles.displayFileName`; string, required) — Nom du document affiché dans Puncto
  - `fileType` (`createRecurringVariable.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` (`createRecurringVariable.response.201.proofFiles.mimeType`; any of, required) — Type MIME du fichier
    - any of: `ImageMimeType`, `OtherMimeType`
  - `createdAt` (`createRecurringVariable.response.201.proofFiles.createdAt`; string, required) — Date d'enregistrement du document dans Puncto
    - format `date-time`
- `createdAt` (`createRecurringVariable.response.201.createdAt`; string, required) — Date de création dans Puncto
  - format `date-time`
- `updatedAt` (`createRecurringVariable.response.201.updatedAt`; string, required) — Date de dernière modification dans Puncto
  - format `date-time`

### 400

Saisie refusée : mois verrouillé, hors du contrat, abonnement annuel chevauchant un autre

#### Example

```json
{
  "error": "Un mois de cette période est déjà clôturé : la variable récurrente doit commencer après le dernier mois clôturé."
}
```

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

### 404

Collaborateur ou contrat introuvable

#### Example

```json
{
  "error": "Aucun contrat trouvé pour ce collaborateur sur cette période"
}
```

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

### 409

`foreignErpId` déjà utilisé par une variable récurrente ou de paie

#### Example

```json
{
  "error": "Une variable récurrente existe déjà avec le foreignErpId teletravail-salarie-123 : une variable récurrente ne se modifie pas, arrêtez-la ou supprimez-la, puis créez la nouvelle."
}
```

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


Source: https://docs.puncto.fr/reference/recurring-variables/create/index.md
