Utiliser l’API publique et les webhooks de Teach Up

L'API publique de Teach Up permet à vos outils (SIRH, CRM, intranet, outil de BI…) de lire et de modifier des données de votre espace Teach Up sans passer par l'interface : créer des apprenants, les ranger dans des groupes, leur assigner des formations ou récupérer leurs résultats. Les webhooks font l'inverse : Teach Up prévient votre outil dès qu'un apprenant est créé ou modifié. Cet article s'adresse à la personne qui fera l'intégration côté technique.

Sommaire

• Ce que vous pouvez faire avec l'API
• Créer une clé d'API
• Envoyer votre première requête
  • Tester dans la documentation interactive
• Les endpoints disponibles
  • Apprenants
  • Groupes
  • Départements
  • Activités et assignations
• Récupérer les résultats des apprenants
• Recevoir des notifications avec les webhooks
  • Événements disponibles
  • Vérifier qu'une requête vient bien de Teach Up
• Questions fréquentes

Ce que vous pouvez faire avec l'API

Je veux…	Endpoint
Créer un apprenant à son arrivée dans l'entreprise	POST /api/v2/learners
Retrouver un apprenant par e-mail, prénom ou nom	GET /api/v2/learners?email=…
Mettre à jour ou désactiver un apprenant	PUT /api/v2/learners/{learnerId}
Créer un groupe et y ajouter ou retirer des apprenants	POST /api/v1/groups puis PUT / DELETE /api/v1/groups/{groupId}/learners/{learnerId}
Ajouter un apprenant à un département, l'en retirer ou l'en bannir	PUT / DELETE /api/v1/departments/{departmentId}/learners/{learnerId}, …/ban
Lister les formations disponibles	GET /api/v1/activities
Assigner (ou retirer) une ou plusieurs formations à un ou plusieurs apprenants	POST / DELETE /api/v1/assignments
Savoir qui est assigné à une formation, ou ce qui est assigné à un apprenant	GET /api/v1/activities/{activityId}/AssignedLearners, GET /api/v2/learners/{learnerId}/AssignedActivities
Récupérer les résultats de tous les apprenants (tentatives)	GET /api/v1/learnings/attempts/export
Récupérer toutes les sessions des apprenants	GET /api/v1/learnings/sessions/export
Récupérer tous les entraînements	GET /api/v1/learnings/trainings/export

L'API ne permet pas de créer ou de modifier des formations, ni d'envoyer des e-mails aux apprenants.

Créer une clé d'API

1. Connectez-vous à Teach Up avec un compte administrateur.
2. Ouvrez « Abonnement & configuration », puis l'onglet « Intégrations et options avancées ».
3. Dans la rubrique « Clés API personnelles », cliquez sur « Créer une nouvelle clé API ».
4. Donnez un nom à la clé (par exemple le nom de l'outil qui l'utilisera), puis cliquez sur « Générer ».
5. Cliquez sur « Copier » et conservez la clé dans un endroit sécurisé.

Envoyer votre première requête

Toutes les requêtes suivent les mêmes règles :

• adresse de base : https://api.teachup.com ;
• authentification : la clé d'API dans l'en-tête x-api-key (et non dans Authorization: Bearer) ;
• format : JSON en entrée et en sortie (sauf l'export des résultats, en CSV) ;
• identifiants : les apprenants, groupes, départements et activités sont identifiés par un id (GUID) que renvoient les requêtes de liste.

Exemple : rechercher un apprenant par son adresse e-mail. La requête (méthode et adresse, puis les deux en-têtes) :

GET https://api.teachup.com/api/v2/learners?email=lea.martin@exemple.fr
accept: application/json
x-api-key: VOTRE_CLE_API

Réponse :

{
  "learners": [
    {
      "id": "3f2b6c1e-8a4d-4f7b-9c2e-1d5a7b9e0c11",
      "email": "lea.martin@exemple.fr",
      "active": true,
      "firstname": "Léa",
      "lastname": "Martin",
      "language": "fr-FR",
      "customFields": {},
      "type": "TeachUp",
      "internalScormId": null
    }
  ]
}

En cas de problème, l'API renvoie :

• 401 Unauthorized : clé absente, fausse ou supprimée, ou envoyée dans le mauvais en-tête ;
• 400 Bad Request : requête invalide (le champ errors de la réponse précise le champ en cause) ;
• 403 Forbidden : accès refusé à la ressource (endpoints des départements et des assignations).

Tester dans la documentation interactive

La documentation interactive liste tous les endpoints, leurs paramètres et le format exact des réponses. Vous pouvez y tester les requêtes avec votre clé :

1. Cliquez sur « Authorize », collez votre clé d'API, puis validez.
2. Ouvrez un endpoint, cliquez sur « Try it out », renseignez les paramètres et cliquez sur « Execute ».

Les endpoints disponibles

Les endpoints ci-dessous sont ceux de la documentation officielle. Pour les apprenants, utilisez de préférence la v2 : elle renvoie le statut active, les groupes et départements de l'apprenant, et permet de filtrer la liste. La v1 reste disponible pour les intégrations existantes ; elle accepte les groupes par leur nom (groups) à la création et à la mise à jour.

Apprenants

Méthode et endpoint	Rôle
GET /api/v2/learners	Liste les apprenants. Filtres facultatifs : email, firstName, lastName.
POST /api/v2/learners	Crée un apprenant : email, firstname, lastname, language (par exemple fr-FR), customFields.
GET /api/v2/learners/{learnerId}	Détail d'un apprenant, avec ses groupes, ses départements actifs et ceux dont il est banni.
PUT /api/v2/learners/{learnerId}	Met à jour firstname, lastname, language, active et customFields. L'e-mail ne se modifie pas.
GET /api/v2/learners/{learnerId}/AssignedActivities	Formations assignées à l'apprenant.

Le champ type indique l'origine de l'apprenant : TeachUp (compte Teach Up) ou Scorm (venu d'un LMS). internalScormId contient alors l'identifiant transmis par le LMS.

Groupes

Méthode et endpoint	Rôle
GET /api/v1/groups	Liste les groupes.
POST /api/v1/groups	Crée un groupe (name).
GET /api/v1/groups/{groupId}	Détail d'un groupe et liste de ses apprenants.
PUT / DELETE /api/v1/groups/{groupId}/learners/{learnerId}	Ajoute l'apprenant au groupe / l'en retire.

Départements

Méthode et endpoint	Rôle
GET /api/v1/departments	Liste les départements.
GET /api/v1/departments/{departmentId}	Détail d'un département, avec ses apprenants et ses apprenants bannis.
PUT / DELETE /api/v1/departments/{departmentId}/learners/{learnerId}	Ajoute l'apprenant au département / l'en retire.
PUT /api/v1/departments/{departmentId}/learners/{learnerId}/ban	Bannit l'apprenant du département.

Activités et assignations

Méthode et endpoint	Rôle
GET /api/v1/activities	Liste les activités. Filtre facultatif : name.
GET /api/v1/activities/{activityId}	Détail d'une activité (titre, langue, durée, présence au catalogue, département).
GET /api/v1/activities/{activityId}/AssignedLearners	Apprenants assignés à l'activité.
POST /api/v1/assignments	Assigne des activités à des apprenants : learnerIds et activityIds (listes).
DELETE /api/v1/assignments	Retire ces assignations (même format).

Le champ kind donne le type d'activité : Formation (module), Evaluation (évaluation), Course (parcours) ou CoachExpert.

Récupérer les résultats des apprenants

L'endpoint GET /api/v1/learnings/attempts/export renvoie un fichier CSV avec toutes les tentatives de tous les apprenants de votre organisation, sur l'ensemble de vos activités. C'est la porte d'entrée pour alimenter un outil de BI ou un tableau de suivi interne.

GET https://api.teachup.com/api/v1/learnings/attempts/export
x-api-key: VOTRE_CLE_API

L'endpoint n'a pas de filtre : il renvoie tout l'historique, à vous de filtrer ensuite (par activité, par date…). Dans l'interface, l'onglet « Intégrations et options avancées » propose aussi un export CSV de toutes les tentatives : voir Toutes les données dans un seul fichier (CSV).

Deux autres endpoints fonctionnent de la même façon (fichier CSV, sans filtre, pour toute votre organisation) :

• GET /api/v1/learnings/sessions/export : toutes les sessions des apprenants ;
• GET /api/v1/learnings/trainings/export : tous les entraînements.

Recevoir des notifications avec les webhooks

Un webhook envoie une requête HTTP (POST) vers l'adresse de votre choix dès qu'un événement a lieu dans Teach Up. Pour en créer un :

1. Ouvrez « Abonnement & configuration » › « Intégrations et options avancées », rubrique « Webhooks ».
2. Créez un webhook et renseignez le Label (un nom pour vous), l'Url qui recevra les requêtes et le Secret (il sert à vérifier la signature, voir plus bas).
3. Dans « Événements à suivre », cochez les événements voulus.
4. Enregistrez. Le webhook apparaît dans « Vos webhooks », où vous pouvez le modifier ou le supprimer.

Événements disponibles

Dans l'interface	Valeur du champ type
« Création d'un apprenant »	learner.created
« Modification d'un apprenant »	learner.modified

Exemple de contenu reçu :

{
  "webhookVersion": "1.0",
  "createdAt": "2024-07-23T14:37:05.367Z",
  "type": "learner.created",
  "data": {
    "id": "abc123",
    "firstname": "John",
    "lastname": "Doe",
    "groups": ["Equipe1"],
    "language": "fr-FR"
  }
}

Vérifier qu'une requête vient bien de Teach Up

Chaque requête contient l'en-tête X-Teachup-Webhook-Signature : un hash HMAC-SHA256 du contenu de la requête, calculé avec le secret de votre webhook. Pour vérifier :

1. récupérez le contenu brut de la requête ;
2. calculez son HMAC-SHA256 avec votre secret ;
3. comparez le résultat à la valeur de l'en-tête.

Ignorez toute requête dont la signature ne correspond pas.

Questions fréquentes

Mes requêtes renvoient 401 alors que ma clé est valide, pourquoi ?

Vérifiez l'en-tête : la clé doit être transmise dans x-api-key, et non dans Authorization: Bearer comme pour beaucoup d'autres API. Voir l'exemple dans Envoyer votre première requête.

Puis-je créer plusieurs clés d'API ?

Oui, par exemple une par outil connecté. Vous pourrez ainsi couper l'accès d'un outil sans toucher aux autres.

J'ai perdu ma clé d'API, que faire ?

Elle ne peut pas être affichée à nouveau. Supprimez-la et créez-en une nouvelle, puis mettez à jour l'outil qui l'utilisait.

Puis-je récupérer les résultats d'une seule formation ?

Pas directement : l'export des tentatives porte sur toutes vos activités. Filtrez ensuite le fichier sur l'activité voulue.

Puis-je filtrer les webhooks par groupe ou par formation ?

Non, un webhook se déclenche pour tous les apprenants de votre espace.

Qui peut créer des clés d'API et des webhooks ?

Les administrateurs de l'espace, une fois l'option « API & Webhooks » activée.