L'API Workelo 🔢

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 :
⚠️ Les règles de sélection automatique des modèles ne s'appliquent pas ici.

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]
}

Si des champs d'identification doivent être remplis, vous pouvez le faire par un autre call après la création du parcours en brouillon.

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 RH

Consulter 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}/documents

Statuts : 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}

POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}
{
  "value": "CDI",
  "external_id": "contract_cdi",
  "position": 1
}

POST /collection_values?resource_type=PaperworkResource&resource_id={paperwork_resource_id}
{
  "value": "Paris 1er",
  "external_id": "75056",
  "position": 1,
  "parent_id": 1001
}

PUT /collection_values/{id}
{
  "value": "Paris 1er Arrondissement",   // modifier le libellé
  "position": 2,                          // changer l'ordre
  "parent_id": 1050                       // changer de branche hiérarchique
}

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

📑 Articles complémentaires

• API : ReadMe / Prise en main 💻
• API : quels process RH automatiser ⚡️
• Documentation technique ℹ️

🔄 Automatiser vos process RH avec l'API Workelo

Vous passez des heures chaque mois à copier-coller des informations entre vos outils. Créer des parcours d'onboarding un par un. Ressaisir les formulaires administratifs dans votre paie. Télécharger et classer des documents signés.

Le constat est simple : vos équipes RH perdent 30 à 40% de leur temps sur des tâches à faible valeur ajoutée. Des tâches répétitives, chronophages, sources d'erreurs. Et si vous pouviez automatiser tout ça ?

L'API Workelo est gratuite et connecte votre écosystème RH : SIRH, ATS, paie, GED. Une fois configurée, elle travaille pour vous 24h/24. Zéro intervention manuelle. Zéro erreur de saisie. Des heures récupérées pour ce qui compte vraiment : accompagner vos collaborateurs.

Voici 6 process RH que nos clients automatisent avec des résultats mesurables.

1️⃣ Créer des parcours depuis votre ATS ou SIRH

🔴 Le problème : quand un candidat est validé dans votre ATS ou qu'un nouveau salarié apparaît dans votre SIRH, les RH en charge de l'onboarding, doivent créer manuellement le parcours dans Workelo et remplir des informations déjà connues.

Cette double saisie est frustrante : "On a déjà ces infos dans notre SIRH, pourquoi les ressaisir ?

✅ La solution avec l'API : votre ATS ou SIRH envoie automatiquement les informations vers Workelo. En quelques secondes, l'employé est créé, son parcours lancé avec les bons modèles, et l'invitation envoyée. Vous ne touchez à rien.

Flux automatisé :

📊 ATS/SIRH (nouvel employé validé)
    ↓
🔄 API Workelo (création automatique)
    ↓
✉️ Parcours créé dans Workelo + invitation envoyée au collaborateur

💡 Exemple concret :
Une entreprise embauche 25 personnes par mois. Au lieu de créer ces 25 parcours d'onboarding à la main, dès que le recrutement passe en "Validé" dans l'ATS, le parcours se crée automatiquement en quelques secondes.

📊 ROI et gain chiffré :
10 min gagnées par parcours → plus de 3h récupérées pour 20 embauches par mois ou près de 2 jours pour 100 embauches par mois.

Métriques observées chez nos clients :

• Temps de création d'un parcours : -95% (8 min → 10 sec)
• Délai d'envoi de l'invitation : J+0 vs J+2 en moyenne (réactivité)
• Taux d'erreur de saisie : -100% (nom, email, poste...)
• ROI fort, investissement vite rentabilisé

🛠️ Difficulté technique : ⭐️ Facile
La plupart des ATS ou SIRH disposent d'une API ou de webhooks, l'intégration se fait en 1-2 jours.

2️⃣ Compléter des données de l'employé depuis votre ATS ou SIRH

🔴 Le problème : vous avez déjà collecté des informations dans votre ATS (téléphone, adresse, date de naissance...). Mais quand vous créez le parcours Workelo, ces champs sont vides. Vous devez soit ressaisir manuellement ces données ou les laisser vide et demander au collaborateur de tout remplir (y compris ce qu'il a déjà fourni au recrutement).

Le collaborateur vit une expérience frustrante : "Je dois redonner mon adresse ? Je l'ai déjà donnée 3 fois..."

✅ La solution avec l'API : l'API récupère automatiquement les données déjà présentes dans votre ATS/SIRH et pré-remplit les champs Workelo. Le collaborateur arrive sur un formulaire déjà complété à 60-70%. Il vérifie, corrige si besoin, et valide. Fini la saisie répétitive.

Flux automatisé :

📊 ATS/SIRH (données collectées au recrutement)
    ↓
🔄 API Workelo (pré-remplissage automatique)
    ↓
✅ Collaborateur valide (au lieu de ressaisir)

💡 Exemple concret
Une agence recrute 15 collaborateurs par mois. L'ATS contient déjà : téléphone, adresse, date de naissance, diplômes. Avant, le collaborateur recevait un formulaire vierge avec 25 champs à remplir. Taux d'abandon : 12%. Temps moyen : 18 minutes.
Avec l'API, le formulaire arrive pré-rempli avec les données de l'ATS. Le collaborateur complète juste les 8 champs manquants (N° Sécu, IBAN, mutuelle...). Temps moyen : 6 minutes.

📊 ROI et gain chiffré

Gain de temps collaborateur : X min * nombre de données pré-complétées

Métriques observées chez nos clients :

• Taux de complétion des formulaires : +15% (moins d'abandon)
• Satisfaction collaborateur (NPS onboarding) : +12 points
• Qualité des données : +25% (moins de champs vides ou erronés)
• Temps RH de relance : -80% (moins de formulaires incomplets)

🛠️ Difficulté technique : ⭐️ Facile
Nécessite de mapper les champs entre votre ATS/SIRH et Workelo (ex: "date_naissance" → "birth_date"). Un développeur peut le faire en 2-3 jours. Une fois configuré, ça tourne seul.

3️⃣ Envoyer les données collectées pour la paie

🔴 Le problème : le collaborateur a rempli son formulaire administratif dans Workelo (numéro de Sécurité Sociale, IBAN, adresse, situation familiale, choix de mutuelle...). Maintenant, vous devez :

• Ouvrir chaque formulaire dans Workelo
• Copier-coller chaque champ dans votre logiciel de paie
• Télécharger les pièces jointes (RIB, attestation Sécu...)
• Les renommer et les classer

C'est la tâche la plus chronophage de l'onboarding administratif. Chaque erreur de saisie (mauvais IBAN, N° Sécu inversé) génère un retraitement et un retard de paiement.

✅ La solution avec l'API : dès qu'un formulaire est complété dans Workelo, l'API envoie automatiquement les données vers votre logiciel de paie (Silae, Payfit, Cegid...). Les champs sont mappés automatiquement. Les pièces jointes sont téléchargées et classées. Zéro ressaisie. Zéro erreur.

Flux automatisé :

✅ Collaborateur complète son formulaire Workelo
    ↓
🔄 API récupère les données + fichiers
    ↓
💰 Envoi automatique vers le logiciel de paie
    ↓
📧 Notification RH : "Formulaire synchronisé"

💡 Exemple concret
Un groupe de restauration rapide embauche 80 personnes par mois (forte rotation). 2 gestionnaires passaient 6h par semaine à ressaisir les formulaires dans la paie avec un taux d'erreur de 8% (retards de paiement, mécontentement). Avec l'API, les formulaires complétés sont automatiquement envoyés au SIRH chaque nuit. Les gestionnaires vérifient juste les imports (30 min/semaine). Taux d'erreur : <0,5%.

📊 ROI et gain chiffré

Gain de temps : 6h/semaine → 30 min/semaine = 5h30/semaine récupérées

Métriques observées chez nos clients :

• Temps de saisie paie : -92%
• Erreurs de saisie : -95% (quasi nulles)
• Retards de paiement liés à des erreurs admin : -90%
• ROI : 22h/mois récupérées (pour 80 embauches/mois)

En coût RH : ~1 ETP récupéré pour les entreprises à forte volumétrie (100+ embauches/mois).

🛠️ Difficulté technique : ⭐️ ⭐️ Moyen
Dépend de votre logiciel de paie. Si API disponible, intégration en 3 jours maximum. Sinon, génération d'un fichier CSV formaté (2 jours). Une fois en place, quasi aucune maintenance.

4️⃣ Archiver le dossier administratif complet vers votre GED

🔴 Le problème : les documents signés (contrat de travail, règlement intérieur, charte IT...) et les pièces jointes (RIB, pièce d'identité, diplômes...) sont dans Workelo. Mais pour être conformes, vous devez les archiver dans votre GED ou coffre-fort numérique. Aujourd'hui, vous :

• Téléchargez chaque document un par un
• Les renommez selon votre nomenclature ("NOM_Prénom_TypeDoc_Date.pdf")
• Les classez dans la bonne arborescence (RH/Collaborateurs/NOM_Prenom/Contrats/)
• Renseignez les métadonnées (date de signature, type de document...)

Avec 20 documents par collaborateur et 30 embauches/mois, ça fait 600 documents à traiter manuellement chaque mois.

✅ La solution avec l'API : dès qu'un document est signé ou un fichier uploadé dans Workelo, l'API le récupère et l'envoie automatiquement à votre GED. Le fichier est automatiquement renommé, classé et métadaté. Tout votre dossier collaborateur se constitue seul.

Flux automatisé :

✍️ Document signé dans Workelo (ou fichier uploadé)
    ↓
🔄 API récupère le PDF + métadonnées
    ↓
📁 Classement auto dans GED :
    RH/Collaborateurs/MARTIN_Jean/Contrats/CDI_2026-05-13_signé.pdf
    ↓
📧 Notification : "Document archivé"

💡 Exemple concret
Un groupe industriel de 2000 salariés embauche 40 personnes par mois. Chaque dossier contient en moyenne 18 documents. Une assistante RH passait 4h par semaine à télécharger, renommer et classer les documents dans la GED. Risque d'oubli ou de mauvais classement : ~10% des documents.
Désormais, les documents sont automatiquement archivés dans la GED chaque nuit. L'assistante vérifie juste la complétude des dossiers (20 min/semaine). Taux d'erreur de classement : 0%.

📊 ROI et gain chiffré

Gain de temps : 4h/semaine → 20 min/semaine = 3h40/semaine récupérées

Métriques observées chez nos clients :

• Temps d'archivage : -92%
• Documents mal classés ou perdus : -100%
• Conformité RGPD : 100% (traçabilité complète)
• Temps de recherche d'un document : -80% (nomenclature standardisée)
• ROI : 15h/mois récupérées (pour 40 embauches/mois)

🛠️ Difficulté technique : ⭐️ ⭐️ Moyen
Si votre GED a une API, intégration en 3-5 jours. Sinon, export vers un dossier réseau structuré (2 jours). Configuration initiale de la nomenclature nécessaire.

5️⃣ Synchroniser votre base d'employés

🔴 Le problème : votre SIRH est la référence pour la liste des employés actifs. Mais Workelo a aussi sa propre base. Résultat : vous devez maintenir la cohérence manuellement :

• Un nouveau salarié ? → Le créer dans Workelo
• Un départ ? → Le désactiver dans Workelo
• Un changement de poste/service ? → Mettre à jour dans Workelo

La désynchronisation crée des bugs : parcours envoyés à des personnes parties, organigramme obsolète, rapports faussés.

✅ La solution avec l'API : l'API synchronise automatiquement votre base d'employés entre le SIRH et Workelo. Chaque nuit (ou en temps réel), les nouveaux, les départs et les modifications sont propagés. Vos deux bases restent toujours alignées. Zéro maintenance.

Flux automatisé :

📊 SIRH (source de vérité)
    ↓
🔄 API synchronise (chaque nuit ou en temps réel)
    ↓
✅ Workelo (base à jour automatiquement)
    • Nouveaux employés créés
    • Départs désactivés
    • Changements de poste/service mis à jour

💡 Exemple concret
Une société de services embauche 30 personnes/mois et gère 15 départs/mois (rotation naturelle). Un RH passait 2h par semaine à vérifier et corriger les désynchronisations (employés en doublon, personnes parties toujours actives...). Des parcours étaient parfois envoyés à des emails invalides.
Désormais, synchronisation automatique chaque nuit à 2h du matin. La base Workelo reflète toujours exactement le SIRH. Temps de maintenance : 0 min/semaine.

📊 ROI et gain chiffré

Gain de temps : 2h/semaine → 0 min = 2h/semaine récupérées

Métriques observées chez nos clients :

• Temps de maintenance des bases : -100%
• Taux de désynchronisation : 0%
• Erreurs d'envoi (emails invalides, personnes parties) : -95%
• Fiabilité des rapports : 100% (données toujours exactes)
• ROI : 8h/mois récupérées

🛠️ Difficulté technique :  : ⭐️  Facile à  ⭐️ ⭐️ Moyen
Si votre SIRH a une API, intégration en 1 à 2 jours via un script de synchronisation qui tourne en cron job. Configuration initiale du mapping des champs.

6️⃣ Synchroniser votre organigramme

🔴 Le problème : votre structure organisationnelle évolue : nouveau service créé, fusion de départements, changement de rattachement... Ces modifications doivent être répercutées dans Workelo pour que :

• Les parcours soient envoyés aux bons managers/services
• Les rapports soient corrects (onboarding par département)
• Les collaborateurs voient la bonne structure

Maintenir manuellement 2 structures dans 2 outils est une source d'erreurs permanente.

✅ La solution avec l'API  : l'API synchronise automatiquement votre organigramme depuis le SIRH vers Workelo. Création de services, modifications de rattachements, suppressions... tout est propagé automatiquement. Votre organigramme Workelo est toujours le reflet exact de votre SIRH. Zéro décalage.

Flux automatisé :

📊 SIRH (organigramme modifié)
    ↓
🔄 API synchronise (hebdo ou temps réel)
    ↓
✅ Workelo (structure à jour)
    • Nouveaux services créés
    • Rattachements mis à jour
    • Services fermés archivés

💡 Exemple concret
Une scale-up tech de 500 personnes crée 2-3 nouveaux services par trimestre et réorganise régulièrement (squads agiles). Le HRBP devait recréer manuellement chaque service dans Workelo, vérifier les rattachements, corriger les erreurs. Temps : 1h par réorganisation. Délai moyen de mise à jour : 1 semaine (décalage avec le SIRH). 
Désormais, synchronisation automatique chaque dimanche soir. Le lundi, l'organigramme Workelo reflète exactement la nouvelle structure. Temps de maintenance : 0 min.

📊 ROI et gain chiffré

Gain de temps : 1h/réorganisation × 8 réorgs/an = 8h/an récupérées

Métriques observées chez nos clients :

• Temps de maintenance de l'organigramme : -100%
• Délai de mise à jour : J+7 → J+0 (temps réel)
• Erreurs de rattachement : -100%
• Cohérence SIRH/Workelo : 100%

Bénéfice indirect : Fiabilité des rapports par service/département (impossible si l'organigramme est obsolète).

🛠️ Difficulté technique : ⭐️ ⭐️ Moyen
Nécessite de comprendre la structure hiérarchique de votre SIRH (parent/child, niveaux organisationnels). Intégration en 3-5 jours. Une fois configuré, synchronisation automatique sans intervention.

🚀 Et concrètement, comment ça marche ?

C'est simple en 3 étapes :

1️⃣ Vous définissez votre besoin (10 minutes) Quel process voulez-vous automatiser ? Quels sont vos systèmes actuels (SIRH, paie, GED) ?

2️⃣ Vous configurez l'intégration (2 à 5 jours) Votre équipe IT (ou un prestataire, ou nous) connecte les systèmes via l'API. Pas besoin d'être expert : la documentation est claire et des exemples de code sont fournis.

3️⃣ Ça tourne tout seul (0 minute de maintenance) Une fois en place, les process tournent en automatique. Vous recevez juste des notifications de confirmation.

❓ Questions fréquentes

Est-ce que l'API est incluse dans mon abonnement ?

L'API est gratuite et accessible directement dans Compte > Intégrations > API. Contactez votre Customer Success Manager si besoin.

Faut-il être développeur pour utiliser l'API ?

Pas forcément. Deux options :

• Votre équipe IT configure l'intégration en quelques jours
• Un prestataire/ESN peut le faire (nous avons des partenaires référencés)

Combien de temps pour mettre en place une automatisation ?

Entre 2 et 5 jours selon la complexité et la disponibilité des API de vos outils. Une fois configuré, c'est permanent.

📑 Articles complémentaires

• Documentation technique ℹ️
• API : ReadMe / Prise en main 💻
• API : nos recettes prêtes à l'emploi 👩‍🍳

💡 L'API Workelo permet d'intégrer les fonctionnalités de la plateforme directement dans vos systèmes et applications. Cette documentation vous guide progressivement dans l'utilisation de l'API pour automatiser vos processus RH et gérer vos parcours collaborateurs.

📄 Documentation technique : https://api.workelo.eu/docs/apis

📋 Vue d'ensemble

L'API Workelo (version 1.6) est une API REST qui permet d'automatiser et d'intégrer vos processus RH.

Que pouvez-vous faire ?

• ✅ Gérer les parcours collaborateurs (onboarding, crossboarding, offboarding)
• ✅ Gérer les employés et leurs champs
• ✅ Collecter les données administratives
• ✅ Gérer les organisations et niveaux
• ✅ Automatiser des actions RH

Architecture de l'API

• Type : API REST
• Format : JSON
• Authentification : OAuth 2.0
• Base URL : https://api.workelo.eu/v1/
• Rate limit : 1000 requêtes/heure par token ⚠️

🔑 Concepts clés

Avant de commencer, voici les notions essentielles définies dans Workelo :

👥 Employés et collaborateurs

Employé : Une personne faisant partie du référentiel de l'entreprise sur Workelo.

Collaborateur : Un employé vivant son (parcours) moment clé avec Workelo.

Identification flexible dans l'API :

• ID (identifiant par défaut)
• external_id : votre identifiant système
• Email : adresse email

🛤️ Parcours (Tracks)

Parcours : Le moment clé vécu par le collaborateur au sein de l’entreprise.

Types de moment clé :

• Onboarding : Processus d'intégration d'un nouveau collaborateur dans l'entreprise
• Crossboarding : Processus d'accompagnement lors d'une mobilité interne ou d'un changement de poste
• Offboarding : Processus d'accompagnement du départ d'un collaborateur de l'entreprise

Statuts :

• Brouillon draft
• Invitation envoyée invitation_sent
• Programméescheduled
• En cours in_progress
• Clos closed
• Annulé cancelled

Acteurs impliqués : Un employé étant impliqué dans le moment clé d'un collaborateur

• RH rh
• Responsable administratif second_rh
• Manager manager
• Parrain buddy
• Contributeur second_manager

📝 Ressources

Ressource : Un élément précis qui est paramétré afin d'enrichir l'expérience proposée sur Workelo

Types de ressources disponibles :

• Formulaire : Ressource dont l'objectif est de récupérer des informations administratives auprès de l'employé
• Document : Fichier ou ressource à consulter, télécharger ou signer dans un parcours
• Questionnaire : Ressource dont l'objectif est de récupérer du feedback de la part du collaborateur
• Quiz : Ressource dont l'objectif est de tester les connaissances du collaborateur
• Tâche : Action concrète à réaliser par un acteur ou un collaborateur dans le cadre d'un parcours
• Kit : Ressource dont l'objectif est de définir un accessoire/outil/logiciel/accès qu'il est nécessaire de préparer/récupérer pour le collaborateur
• Contenu : Ressource dont l'objectif est de pousser de l'information au collaborateur via un fichier ou un lien
• Communication : Message ou notification envoyé aux utilisateurs dans le cadre d'un parcours

🏢 Structure organisationnelle

Environnement : C'est le niveau du référentiel organisation que l'on choisit pour définir les différents périmètres du compte.

Dans l'API :

• Level Organizations : niveaux hiérarchiques (Direction, Service)
• Unit Organizations : unités concrètes (RH, IT, Marketing)

🎯 Modèles (Templates)

Modèle : Un ensemble de ressources qui sont cadencées par rapport à une date clé et qui ont chacune un responsable attitré

🛠️ Bonnes pratiques

Codes de réponse HTTP

• 200 : Succès
• 201 : Ressource créée
• 404 : Ressource non trouvée
• 422 : Données non valides
• 401 : Non autorisé

Gestion d'erreurs

Exemple d'erreur 422 :

{
  "errors": ["Invalid email format", "Unit organization not found"],
  "message": "unprocessable_entity", 
  "code": 422
}

Limites et performance

• Rate limit : 1000 requêtes/heure par token
• Pagination : Utilisez limit et offset pour les grandes listes
• Timeout : Minimum 30 secondes recommandé
• Retry : Backoff exponentiel pour les erreurs 5xx

Les étapes recommandées

1. 🔑 Testez l'authentification avec vos identifiants
2. 👥 Créez un employé test pour vous familiariser
3. 🛤️ Lancez un parcours simple avec les templates par défaut
4. 📝 Explorez les formulaires et leur structure de données
5. 🔄 Implémentez la synchronisation avec votre système existant
6. ⚙️ Automatisez vos processus selon vos cas d'usage

🎯 Conseil : Commencez petit ! Un parcours d'onboarding basique avec les templates existants vous permettra de maîtriser les concepts avant d'implémenter des logiques avancées.

Pour aller plus loin

🚀 Premiers pas

Étape 1 : Obtenir vos identifiants API

Vous pouvez créer vos identifiants depuis la section Compte > Avancés > API de votre compte Workelo.

• client_id
• client_secret

Étape 2 : Premier appel - Lister les employés

# 1. Obtenir un token d'accès
curl -X POST https://api.workelo.eu/v1/tokens \\
  -F "client_id=your_client_id" \\
  -F "client_secret=your_client_secret"

# 2. Utiliser le token pour lister les employés
curl -X GET https://api.workelo.eu/v1/employees \\
  -H "Authorization: Bearer YOUR_TOKEN"

Étape 3 : Comprendre une réponse typique

{
  "data": [
    {
      "id": 123,
      "first_name": "Marie",
      "last_name": "Dubois",
      "email": "marie.dubois@entreprise.com",
      "role": "colleague",
      "unit_organization": {
        "id": 5,
        "name": "Service RH"
      }
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 10,
    "offset": 0
  }
}

💡 Premier succès ! Si vous obtenez cette réponse, votre intégration fonctionne. Vous pouvez maintenant explorer les autres endpoints.

🔐 Authentification

L'API utilise OAuth 2.0 avec des tokens d'accès temporaires.

Obtenir un token

POST /tokens
Content-Type: multipart/form-data

client_id=your_client_id
client_secret=your_client_secret

Réponse :

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Utiliser le token

Ajoutez le token dans l'en-tête de toutes vos requêtes :

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

⏰ Durée de vie : Les tokens sont valides 1 heure et peuvent être réutilisés. Prévoyez un système de renouvellement automatique.

👥 Gestion des employés

Lister les employés

GET /employees

or 

GET /employees?limit=10&offset=0&role=colleague

Paramètres de filtrage :

• role : colleague, manager, hr, owner
• unit_organization_ids : IDs des organisations (séparés par virgules)

Créer un employé

POST /employees
Content-Type: application/json

{
  "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 identifications personnalisées

POST /employees/{employee_id}/identifications
Content-Type: application/json

{
  "identification_resource_id": 5,
  "value": "BADGE-001"
}

Rechercher un employé par external_id

GET /employees?external_id=EMP-001

🛤️ Parcours collaborateurs

Créer un parcours

POST /tracks
Content-Type: application/json

{
  "mobility": "onboarding",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "employee": {
    "external_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "job_position": "string",
    "unit_organization_id": 0
  },
  "implications": {
    "hr_id": 0,
    "second_hr_id": 0,
    "manager_id": 0,
    "second_manager_id": 0,
    "buddy_id": 0
  },
  "template_ids": [
    0
  ]
}

Envoyer l'invitation au parcours

PUT /tracks/{id}/start
Content-Type: application/json

{
  "invite_at": "2019-08-24"
}

Générer un lien d'accès sécurisé

GET /user_magic_links/{employee_id}

Réponse :

{
  "magic_link": "https://app.workelo.eu/magic/97abc...",
  "expires_in": 7200
}

🔗 Sécurité : Les liens magiques expirent après 2 heures et ne sont accessibles qu'aux collaborateurs ayant un parcours actif.

📝 Formulaires et informations

Lister les formulaires d'un parcours

GET /tracks/{id}/forms

Statuts :

• opened : formulaire ouvert, en attente de saisie
• closed : formulaire fermé et complété
• missing_validation : en attente de validation RH

Consulter les détails et données saisies

GET /forms/{id}

Structure de réponse :

{
  "id": 123,
  "name": "Informations personnelles", 
  "status": "closed",
  "paperworks": [
    {
      "id": 456,
      "paperwork_resource_name": "Adresse personnelle",
      "value": "123 Rue de la Paix, Paris",
      "paperwork_files": []
    },
    {
      "id": 789, 
      "paperwork_resource_name": "Photo d'identité",
      "value": null,
      "paperwork_files": [
        {
          "id": 101,
          "file": {"url": "https://..."}
        }
      ]
    }
  ]
}

Modifier une information

PUT /paperworks/{id}
Content-Type: application/json

{
  "value": "Nouvelle valeur"
}

Gérer les fichiers uploadés

Récupérer un fichier :

GET /paperwork_files/{id}

Uploader un nouveau fichier :

POST /paperwork_files/
Content-Type: multipart/form-data

paperwork_id={paperwork_id}
file={file_data}

📄 Documents 

Lister les documents d'un parcours

GET /tracks/{id}/documents

Statuts des documents :

• supplying : en cours de préparation par l'organisation
• receipting : disponible pour action du collaborateur
• finalized : action terminée par le collaborateur

Télécharger le fichier associé au document

GET /attachments/{id}

Réponse (fichier encodé base64) :

{
  "id": 123,
  "name": "Contrat de travail",
  "filename": "contrat_martin_jean.pdf", 
  "extension": "pdf",
  "content": "JVBERi0xLjQKMSAwIG9iao8CAovVHlwZSA..."
}

🏢 Structure organisationnelle

Comprendre la hiérarchie

Lister les niveaux organisationnels :

GET /level_organizations

Lister les organisations d'un niveau :

GET /unit_organizations?level_organization_id={level_id}

Créer une organisation

POST /unit_organizations
Content-Type: application/json

{
  "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é

Donner accès à une organisation :

POST /employees/{id}/unit_organization_managements
Content-Type: application/json

{
  "unit_organization_id": 42
}

Retirer l'accès :

DELETE /unit_organization_managements/{management_id}

⚙️ Fonctionnalités avancées

Templates et modèles

Lister les templates disponibles :

GET /templates

or 

GET /templates?mobility=onboarding&unit_organization_id=42

Utiliser des templates lors de la création :

Les templates sont spécifiés via template_ids dans la création de parcours.

⚡ Performance : L'application des templates peut prendre du temps. Le parcours est créé immédiatement, les ressources sont ajoutées en arrière-plan.

Suivi et logs

GET /logs?event=track_creation&from=2025-09-01T00:00:00Z&to=2025-09-09T23:59:59Z

Événements principaux :

• user_creation : création d'employé
• track_creation : création de parcours
• track_start : démarrage de parcours
• form_completion : formulaire complété

📑 Articles complémentaires

• API : quels process RH automatiser ⚡️

• API : nos recettes prêtes à l'emploi 👩‍🍳