Voici un guide complet, structuré par user story principale, avec tous les appels API nécessaires dans l'ordre (y compris les appels préalables pour récupérer les IDs).
🙋 Pour prendre en main l'API, rendez-vous dans la documentation dédiée dans un premier temps.
1. Gérer la base employés 👥
Récupérer les IDs nécessaires
→ Récupérer le user_role_id correspondant au rôle souhaité (colleague, manager, hr...) :
GET /user_roles
→ Récupérer l'id de l'organisation à laquelle rattacher l'employé :
GET /unit_organizations
→ Récupérer les identification_resource_id des champs personnalisés disponibles (badge, matricule, etc.) :
GET /identification_resources
Créer l'employé
POST /employees
{
"first_name": "Marie",
"last_name": "Dubois",
"email": "marie.dubois@entreprise.com",
"job_position": "Manager",
"external_id": "EMP-001",
"unit_organization_id": 5,
"user_role_id": 234
}Ajouter des champs d'identification personnalisés
POST /employees/{employee_id}/identifications
{
"identification_resource_id": 5,
"value": "BADGE-001"
}Consulter / Modifier l'employé
GET /employees/{id}
PUT /employees/{id}
GET /employees?role=manager ← lister par rôle
GET /employees?external_id=EMP-001 ← retrouver par ID externe
2. Gérer votre structure organisationnelle 🏢
Comprendre la hiérarchie existante
→ Lister les niveaux (ex : Direction, Service, Site) :
GET /level_organizations
→ Lister les unités d'un niveau donné :
GET /unit_organizations?level_organization_id={level_id}Créer une nouvelle organisation
POST /unit_organizations
{
"external_id": "IT-001",
"name": "Service Informatique",
"level_organization_id": 2,
"parent_id": 15,
"language": "fr"
}Gérer les périmètres d'un employé (scope d'accès)
GET /employees/{employee_id}/unit_organization_managements
POST /employees/{employee_id}/unit_organization_managements
{ "unit_organization_id": 42 }
DELETE /unit_organization_managements/{management_id}3. Créer un parcours 🛤️
Prérequis — récupérer les IDs nécessaires
→ unit_organization_id de l'organisation du collaborateur :
GET /unit_organizations
→ id du manager, RH, buddy, etc. :
GET /employees?role=manager GET /employees?role=hr
→ id des templates à appliquer :
GET /templates?mobility=onboarding&unit_organization_id={id}
Créer le parcours (statut draft)
POST /tracks
{
"mobility": "onboarding",
"start_date": "2026-06-01",
"end_date": "2026-09-01",
"employee": {
"first_name": "Jean",
"last_name": "Martin",
"email": "jean.martin@entreprise.com",
"job_position": "Développeur",
"unit_organization_id": 5
},
"implications": {
"hr_id": 101,
"manager_id": 202,
"buddy_id": 303
},
"template_ids": [999056]
}Lancer le parcours et envoyer les invitations
PUT /tracks/{id}/start
{
"invite_at": "2026-05-28" ← optionnel : date d'invitation du collaborateur
}4. Piloter et suivre les parcours 🧐
Lister et filtrer les parcours
GET /tracks GET /tracks?status=in_progress GET /tracks?status=draft
Statuts disponibles : draft, invitation_sent, scheduled, in_progress, closed, cancelled
Consulter le détail d'un parcours (avec métriques live)
→ Retourne santé du parcours, progression, taux de disponibilité des actions, nombre d'actions réalisées :
GET /tracks/{id}Modifier un parcours (dates, acteurs)
PUT /tracks/{id}
{
"start_date": "2026-06-15",
"apply_on_actions": true, ← décale automatiquement les actions
"implications": {
"manager_id": 205
}
}5. Gérer l'administratif 📃
Lister les formulaires d'un parcours
GET /tracks/{track_id}/forms
GET /tracks/{track_id}/forms?status=opened ← en attente de saisie
GET /tracks/{track_id}/forms?status=missing_validation ← en attente de validation RHConsulter le détail et les données saisies
→ Retourne tous les paperworks avec leurs valeurs remplies :
GET /forms/{id}Modifier une valeur d'un champ
PUT /paperworks/{id}
{ "value": "Nouvelle valeur" }Gérer les fichiers chargés dans un formulaire
GET /paperwork_files/{id} ← récupérer un fichier
POST /paperwork_files ← uploader un fichier
{ "paperwork_id": 456, "file": "..." }Lister les ressources de formulaire disponibles
GET /paperwork_resources GET /paperwork_resources?type=selection ← listes déroulantes GET /paperwork_resources?type=date
Lister les documents d'un parcours
GET /tracks/{track_id}/documentsStatuts : supplying (en préparation), receipting (disponible), finalized (complété)
Télécharger un fichier (base64)
GET /attachments/{id}Lister les ressources documents disponibles
GET /document_resources GET /document_resources?type=sign GET /document_resources?type=download
6. Gérer les listes déroulantes d'options 🔽
Lister les options d'une ressource
GET /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}Paginer aveclimit/offsetpour les grandes listes.
Créer une option simple
POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}
{
"value": "CDI",
"external_id": "contract_cdi",
"position": 1
}
Créer une option avec un parent (liste dépendante)
POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}
{
"value": "Paris 1er",
"external_id": "75056",
"position": 1,
"parent_id": 1001
}
Leparent_idest l'idde lacollection_valueparente (ex : le code postal75001).
Mettre à jour une option (libellé, position, ou parent)
PUT /collection_values/{id}
{
"value": "Paris 1er Arrondissement", // modifier le libellé
"position": 2, // changer l'ordre
"parent_id": 1050 // changer de branche hiérarchique
}
Les valeurs existantes dans des parcours conservent leur ancienne valeur (pas de cascade)
7. Générer un lien d'accès sécurisé (Magic Link) 🔗
GET /user_magic_links/{employee_id}
GET /user_magic_links_by_email/{email}
GET /user_magic_links_by_external_id/{external_id}⏱️ Les liens expirent après 2 heures et ne fonctionnent que si le collaborateur a un parcours actif.
8. Analyser et auditer l'activité 📈
GET /logs
GET /logs?event=user_creation&from=2026-01-01&to=2026-05-26
GET /logs/{uuid}
9. Consulter les actions assignées (acteurs) ✔️
→ Récupérer l'id de l'acteur :
GET /employees?role=manager
Lister les actions d'un acteur
GET /owners/{owner_id}/actions
GET /owners/{owner_id}/actions?limit=20&offset=0
📊 Récapitulatif visuel
| User Story | Calls principaux |
|---|---|
| Créer un employé |
GET /user_roles → GET /unit_organizations → POST /employees
|
| Enrichir un profil |
GET /identification_resources → POST /employees/{id}/identifications
|
| Gérer les orgs |
GET /level_organizations → POST /unit_organizations
|
| Créer un parcours |
GET /unit_organizations + GET /employees + GET /templates → POST /tracks
|
| Lancer l'invitation | PUT /tracks/{id}/start |
| Suivre les parcours |
GET /tracks → GET /tracks/{id}
|
| Modifier un parcours | PUT /tracks/{id} |
| Formulaires admin |
GET /tracks/{id}/forms → GET /forms/{id} → PUT /paperworks/{id}
|
| Documents |
GET /tracks/{id}/documents → GET /attachments/{id}
|
| Magic Link | GET /user_magic_links/{id} |
| Actions acteurs |
GET /employees → GET /owners/{id}/actions
|
| Logs & audit | GET /logs |