💡 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ée
scheduled - 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
limitetoffsetpour les grandes listes - Timeout : Minimum 30 secondes recommandé
- Retry : Backoff exponentiel pour les erreurs 5xx
Les étapes recommandées
- 🔑 Testez l'authentification avec vos identifiants
- 👥 Créez un employé test pour vous familiariser
- 🛤️ Lancez un parcours simple avec les templates par défaut
- 📝 Explorez les formulaires et leur structure de données
- 🔄 Implémentez la synchronisation avec votre système existant
- ⚙️ 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_idclient_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}/formsStatuts :
-
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}/documentsStatuts 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é