---
title: "Créer des collaborateurs et des contrats"
description: "Embaucher un salarié depuis votre SIRH, puis lui créer de nouveaux contrats."
---

> 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.

# Créer des collaborateurs et des contrats

- Pour une personne que Puncto ne connaît pas encore, utilisez
  [Créer un collaborateur et son premier contrat](/reference/collaborators/create).
- Pour un collaborateur déjà présent (réembauche, stage puis CDI, CDD puis CDI…), utilisez
  [Créer un contrat](/reference/contracts/create).
- Pour relire les données, utilisez [Lister les contrats](/reference/contracts/list),
  [Consulter un contrat](/reference/contracts/retrieve) et
  [Consulter un collaborateur](/reference/collaborators/retrieve).

## Embaucher un collaborateur

Une seule requête crée le collaborateur, son compte et son contrat :

```bash
curl https://api.puncto.fr/public/v1/collaborators \
  -H "Authorization: Bearer $PUNCTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "foreignErpId": "salarie-123",
    "identity": {
      "firstName": "Camille",
      "lastName": "Durand",
      "birthDate": "1991-06-14",
      "birthCountryCode": "FR",
      "birthCity": "Nantes",
      "birthDepartmentCode": "44",
      "nationality": "FR"
    },
    "contact": {
      "address": "12 rue de la Paix",
      "postalCode": "75002",
      "city": "Paris",
      "countryCode": "FR",
      "personalEmail": "camille.durand@example.com",
      "professionalEmail": "camille.durand@entreprise.fr"
    },
    "socialSecurityNumber": "2910644123456",
    "isBoeth": false,
    "dependentChildrenCount": 0,
    "iban": "FR7630004000031234567890143",
    "bic": "BNPAFRPPXXX",
    "contract": {
      "workerType": "EMPLOYEE_CDI",
      "startDate": "2026-11-02",
      "establishmentSiret": "55210055400013",
      "companyRoleName": "Développeuse backend",
      "managerId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XZ",
      "trialPeriodEndDate": "2027-03-01",
      "dpaeDoneByPuncto": true,
      "amendment": {
        "isCadre": true,
        "quotity": {
          "type": "HEURE",
          "monthlyWorkingHours": 151.67,
          "workingPercentage": 100,
          "paidContractualOvertimeHours": 0,
          "rttContractualOvertimeHours": 0,
          "rcrContractualOvertimeHours": 0
        },
        "conventionalWorkerStatus": "04",
        "workerOutsideFranceStatus": "99",
        "conventionalPosition": { "type": "CADRE", "position": "2.1 (au moins 26 ans)" },
        "weekDaysWorked": 31,
        "grossAnnualSalary": 48000,
        "codePcsEse": "388a"
      }
    }
  }'
```

La réponse `201` contient `{ "collaborator": …, "contract": … }`. En cas d’erreur, **rien n’est
enregistré**, pas même le poste qu’un `companyRoleName` inconnu aurait créé.

**Bon à savoir**

- `foreignErpId` (votre identifiant) est obligatoire. S’il correspond à un collaborateur déjà
  embauché, la réponse est `409` avec le `collaboratorId` existant, et rien n’est créé.
- Si le numéro de sécurité sociale est déjà connu dans l’entreprise, la réponse est `409` avec le
  `collaboratorId`. Créez alors le contrat avec `POST /public/v1/contracts`.
- `personalEmail` sert à la connexion. Il doit être unique sur tout Puncto, toutes entreprises
  confondues, sinon la réponse est `422`.
- Sans `socialSecurityNumber`, `sex` est obligatoire et Puncto attribue un NTT.
  `"dpaeDoneByPuncto": false` est aussi obligatoire, sinon la réponse est `400`.
- Avec un numéro, `identityType` vaut `NIR` par défaut (ou `NIA`), et `sex` doit correspondre au
  premier chiffre. Les NIR provisoires (commençant par 7 ou 8) sont refusés.

## Désigner l’établissement, le poste, l’équipe et le manager

Chacun se désigne soit par son identifiant Puncto, soit par votre référence, mais jamais par les
deux (`422`) :

| Désignation | Identifiant Puncto | Votre référence |
| --- | --- | --- |
| Établissement | `establishmentId` | `establishmentSiret` |
| Poste (obligatoire) | `companyRoleId` | `companyRoleName` |
| Équipe | `companyTeamId` | `companyTeamName` |
| Manager | `managerId` | aucune : identifiant Puncto seulement |

- Un nom (`companyRoleName`, `companyTeamName`) est comparé exactement, casse et accents compris.
  Un nom inconnu est créé.
- Si vous ne précisez pas l’établissement, Puncto prend celui du dernier contrat du collaborateur à
  sa fin (y compris après un [changement de lieu de travail](/reference/contracts/update)), sinon
  celui du contrat en attente de saisie dans Puncto, sinon le siège.
- Pour retrouver les identifiants, utilisez [Lister les établissements](/reference/establishments/list),
  [Lister les postes](/reference/company-roles/list),
  [Lister les équipes](/reference/company-teams/list) et
  [Lister les contrats de mutuelle et de prévoyance](/reference/oc-contracts/list).

Une fois le collaborateur créé :

- [Modifier un collaborateur](/reference/collaborators/update) permet de changer son identité,
  ses coordonnées, son mode de paiement ou son manager (`null` le retire). Les champs absents ne
  sont pas modifiés.
- [Supprimer un collaborateur](/reference/collaborators/delete) reste possible tant
  qu’aucune paie de son contrat n’est clôturée.

## Créer un contrat pour un collaborateur existant

Désignez le collaborateur par son identifiant Puncto, `collaboratorId`. Pour le retrouver à partir
de votre identifiant, appelez `GET /public/v1/collaborators?collaboratorForeignErpId=…`. Les autres
champs sont ceux de `contract` à l’embauche :

```bash
curl https://api.puncto.fr/public/v1/contracts \
  -H "Authorization: Bearer $PUNCTO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collaboratorId": "coll_01JB7Q6ZC8V3K9N2M4R5T7W8XY",
    "workerType": "EMPLOYEE_CDD",
    "startDate": "2027-01-04",
    "endDate": "2027-06-30",
    "cddMotif": "02",
    "companyRoleName": "Développeuse backend",
    "dpaeDoneByPuncto": false,
    "amendment": {
      "isCadre": false,
      "quotity": {
        "type": "HEURE",
        "monthlyWorkingHours": 151.67,
        "workingPercentage": 100,
        "paidContractualOvertimeHours": 0,
        "rttContractualOvertimeHours": 0,
        "rcrContractualOvertimeHours": 0
      },
      "conventionalWorkerStatus": "05",
      "workerOutsideFranceStatus": "99",
      "conventionalPosition": { "type": "ETAM", "position": "2.2" },
      "weekDaysWorked": 31,
      "grossAnnualSalary": 34000,
      "codePcsEse": "478a"
    }
  }'
```

La réponse `201` renvoie le contrat, avec ses valeurs résolues à sa date de début.

**Bon à savoir**

- Les autres contrats du collaborateur doivent se terminer avant la date de début. Un contrat sans
  date de fin (CDI) doit d’abord être clôturé dans Puncto, car l’API ne le permet pas.
- Si un contrat a été laissé en attente de saisie dans Puncto, la requête le complète au lieu d’en
  créer un second.
- Si un contrat du collaborateur commence déjà le même jour, la réponse est `409` avec son
  `contractId`.
- Un collaborateur invité à compléter son dossier doit d’abord finir son embauche dans Puncto, sinon
  la réponse est `400`.

## Après la création

> **Caution**
>
> `dpaeDoneByPuncto` est obligatoire. Avec `true`, Puncto dépose une **vraie DPAE** sur
> net-entreprises (CDI, CDD, apprentissage) 8 jours avant le début du contrat, ou immédiatement si le
> début est plus proche. Envoyez `false` si vous la déposez vous-même, et toujours quand vous
> reprenez des contrats passés. Si le collaborateur n’a ni NIR ni NIA à la date de début, `true`
> renvoie `400`.

- Le collaborateur reçoit son invitation à Puncto sur son email personnel 2 jours avant le début du
  contrat, ou immédiatement si le début est plus proche.
- Le bulletin du mois en cours est recalculé si le contrat couvre ce mois.
- Si ces envois échouent, la réponse reste `201`.

## Erreurs

### `422` : requête invalide

- `endDate` manquante pour un CDD, un apprentissage ou un stage.
- Contrat de professionnalisation (pas encore géré).
- Date hors format `YYYY-MM-DD` ou inexistante (`2026-02-31`).
- `codePcsEse` manquant sur un avenant (exigé par la DSN).
- Rémunération absente ou `null` :
  - `amendment.grossAnnualSalary` pour un CDI, un CDD ou un mandat social ;
  - `amendment.hourlyRate` (ou `amendment.smoothedMonthlyAmount`, gratification lissée) pour un stage ;
  - `remunerationPercentage` sur chaque avenant d’un apprentissage.

### `400` : règle de paie non respectée

Le message indique la règle qui bloque. Rien n’est enregistré.

- Salaire au moins égal au minimum Syntec et au SMIC, au prorata du temps de travail. Gratification
  minimale pour un stage, rémunération minimale de chaque année pour un apprentissage.
- Période d’essai entre la date de début et le maximum conventionnel. Pas de `trialPeriodEndDate`
  pour un stage ou un mandat social.
- Un CDD doit avoir un `cddMotif`, un stage un `internshipStudies` et un `internshipSchool`. Un CDI
  n’a pas de `endDate` (sa fin se saisit à la clôture).
- `isCadre` cohérent avec la position : `true` pour `CADRE`, `false` pour `ETAM`. Statut
  conventionnel `03` ou `04` pour un cadre, `05` à `07` pour un non-cadre.
- Mutuelle et prévoyance : contrats de l’entreprise, du bon type, en vigueur à la date de début,
  ouverts au statut du salarié (`isCadre`), avec une formule (`mutuelleForfaitChoice`) du contrat.
- DPAE par Puncto : NIR ou NIA du collaborateur, et `healthServiceCode` si l’établissement n’a pas
  encore de code de service de santé au travail.

## Contrat d’apprentissage

Pour un apprentissage, `amendment` est refusé. Envoyez `amendments`, avec un avenant par année de
formation qui commence au début de son année. Les années doivent :

- se suivre sans se chevaucher ;
- aller de `startDate` (première) à `endDate` (dernière) ;
- avoir chacune exactement un avenant.

Sinon, la réponse est `400`. Pour un apprenti qui commence en deuxième année, renseignez seulement
`SECOND_YEAR` et les années suivantes.

```jsonc
{
  "workerType": "APPRENTICESHIP_CONTRACT",
  "startDate": "2026-09-01",
  "endDate": "2028-08-31",
  "apprenticeshipFormationLevel": "06",
  "apprenticeshipFormationYearsPeriods": {
    "FIRST_YEAR": { "startDate": "2026-09-01", "endDate": "2027-08-31" },
    "SECOND_YEAR": { "startDate": "2027-09-01", "endDate": "2028-08-31" }
  },
  "amendments": [
    {
      "apprenticeshipFormationYear": "FIRST_YEAR",
      "remunerationPercentage": 53,
      "remunerationReference": "SMIC"
      // + les champs de amendment : isCadre, quotity, codePcsEse…
    },
    {
      "apprenticeshipFormationYear": "SECOND_YEAR",
      "remunerationPercentage": 61,
      "remunerationReference": "SMIC"
      // + les champs de amendment
    }
  ],
  // Facultatif : jours en formation, qui décalent la fin de la période d’essai
  "apprenticeshipCalendar": { "schoolDays": ["2026-09-07", "2026-09-08"] }
}
```

## Relire les contrats

- [Lister les contrats](/reference/contracts/list) renvoie tous les contrats de
  l’entreprise (terminés, à venir et en cours de création compris), avec avenants, périodes
  d’essai, clôture et affiliations. Filtres : collaborateur, `workerType[]`, `activationStatus[]`,
  `activeAt`.
- [Consulter un contrat](/reference/contracts/retrieve) renvoie le contrat par son identifiant
  Puncto. Avec `matchingBy`, il renvoie le contrat en vigueur d’un collaborateur, au format
  `ApiContractFull`. C’est ainsi que vous retrouvez l’identifiant Puncto à partir du vôtre.
  `matchingBy=BY_PUNCTO_CONTRACT_ID` est déprécié, car il renvoie le contrat en vigueur du
  collaborateur, qui n’est pas forcément celui demandé.
- `referenceDate` fixe la date de résolution de l’avenant en vigueur (`currentAmendment`) et de
  l’établissement (`establishmentId`). Par défaut, c’est la date du jour, ou la date de début si le
  contrat n’a pas encore commencé.

Source: https://docs.puncto.fr/developpeurs/guides/contrats/index.mdx
