Use the Teach Up public API and webhooks

The Teach Up public API lets your tools (HRIS, CRM, intranet, BI tool…) read and change data in your Teach Up space without going through the interface: create learners, put them in groups, assign them courses or retrieve their results. Webhooks work the other way round: Teach Up notifies your tool as soon as a learner is created or modified. This article is for the person who will build the integration.

Table of contents

• What you can do with the API
• Create an API key
• Send your first request
  • Test in the interactive documentation
• Available endpoints
  • Learners
  • Groups
  • Departments
  • Activities and assignments
• Retrieve learners' results
• Get notified with webhooks
  • Available events
  • Check that a request really comes from Teach Up
• Frequently asked questions

What you can do with the API

I want to…	Endpoint
Create a learner when they join the company	POST /api/v2/learners
Find a learner by email, first name or last name	GET /api/v2/learners?email=…
Update or deactivate a learner	PUT /api/v2/learners/{learnerId}
Create a group and add or remove learners	POST /api/v1/groups then PUT / DELETE /api/v1/groups/{groupId}/learners/{learnerId}
Add a learner to a department, remove or ban them	PUT / DELETE /api/v1/departments/{departmentId}/learners/{learnerId}, …/ban
List available courses	GET /api/v1/activities
Assign (or unassign) one or more courses to one or more learners	POST / DELETE /api/v1/assignments
See who is assigned to a course, or what is assigned to a learner	GET /api/v1/activities/{activityId}/AssignedLearners, GET /api/v2/learners/{learnerId}/AssignedActivities
Retrieve all learners' results (attempts)	GET /api/v1/learnings/attempts/export
Retrieve all learner sessions	GET /api/v1/learnings/sessions/export
Retrieve all practices	GET /api/v1/learnings/trainings/export

The API can't create or edit courses, and can't send emails to learners.

Create an API key

1. Log in to Teach Up with an administrator account.
2. Open "Subscription & configuration", then the "Integrations and advanced options" tab.
3. Under "Personal API keys", click "Create a new API key".
4. Name the key (for example after the tool that will use it), then click "Generate".
5. Click "Copy" and store the key somewhere secure.

Send your first request

All requests follow the same rules:

• base URL: https://api.teachup.com;
• authentication: your API key in the x-api-key header (not in Authorization: Bearer);
• format: JSON in and out (except the results export, which is CSV);
• identifiers: learners, groups, departments and activities are identified by an id (GUID) returned by the list requests.

Example: find a learner by email address. The request (method and URL, then the two headers):

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

Response:

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

If something goes wrong, the API returns:

• 401 Unauthorized: missing, wrong or deleted key, or key sent in the wrong header;
• 400 Bad Request: invalid request (the errors field of the response names the field at fault);
• 403 Forbidden: access to the resource denied (department and assignment endpoints).

Test in the interactive documentation

The interactive documentation lists every endpoint, its parameters and the exact response format. You can test requests there with your key:

1. Click "Authorize", paste your API key and confirm.
2. Open an endpoint, click "Try it out", fill in the parameters and click "Execute".

Available endpoints

The endpoints below are those of the official documentation. For learners, prefer v2: it returns the active status, the learner's groups and departments, and lets you filter the list. v1 remains available for existing integrations; it accepts groups by name (groups) on create and update.

Learners

Method and endpoint	What it does
GET /api/v2/learners	Lists learners. Optional filters: email, firstName, lastName.
POST /api/v2/learners	Creates a learner: email, firstname, lastname, language (for example en-US), customFields.
GET /api/v2/learners/{learnerId}	A learner's details, with their groups, active departments and departments they are banned from.
PUT /api/v2/learners/{learnerId}	Updates firstname, lastname, language, active and customFields. The email can't be changed.
GET /api/v2/learners/{learnerId}/AssignedActivities	Courses assigned to the learner.

The type field shows where the learner comes from: TeachUp (Teach Up account) or Scorm (from an LMS). internalScormId then holds the identifier sent by the LMS.

Groups

Method and endpoint	What it does
GET /api/v1/groups	Lists groups.
POST /api/v1/groups	Creates a group (name).
GET /api/v1/groups/{groupId}	A group's details and its learners.
PUT / DELETE /api/v1/groups/{groupId}/learners/{learnerId}	Adds the learner to the group / removes them.

Departments

Method and endpoint	What it does
GET /api/v1/departments	Lists departments.
GET /api/v1/departments/{departmentId}	A department's details, with its learners and banned learners.
PUT / DELETE /api/v1/departments/{departmentId}/learners/{learnerId}	Adds the learner to the department / removes them.
PUT /api/v1/departments/{departmentId}/learners/{learnerId}/ban	Bans the learner from the department.

Activities and assignments

Method and endpoint	What it does
GET /api/v1/activities	Lists activities. Optional filter: name.
GET /api/v1/activities/{activityId}	An activity's details (title, language, duration, catalog status, department).
GET /api/v1/activities/{activityId}/AssignedLearners	Learners assigned to the activity.
POST /api/v1/assignments	Assigns activities to learners: learnerIds and activityIds (lists).
DELETE /api/v1/assignments	Removes these assignments (same format).

The kind field gives the activity type: Formation (course), Evaluation (assessment), Course (training path) or CoachExpert.

Retrieve learners' results

The GET /api/v1/learnings/attempts/export endpoint returns a CSV file with every attempt of every learner in your organization, across all your activities. It's the way to feed a BI tool or an internal tracking dashboard.

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

The endpoint has no filters: it returns the whole history, and you filter it afterwards (by activity, by date…). In the interface, the "Integrations and advanced options" tab also offers a CSV export of all attempts.

Two other endpoints work the same way (CSV file, no filters, for your whole organization):

• GET /api/v1/learnings/sessions/export: all learner sessions;
• GET /api/v1/learnings/trainings/export: all practices.

Get notified with webhooks

A webhook sends an HTTP request (POST) to the address of your choice as soon as an event happens in Teach Up. To create one:

1. Open "Subscription & configuration" › "Integrations and advanced options", "Webhooks" section.
2. Create a webhook and fill in the Label (a name for you), the Url that will receive the requests and the Secret (used to check the signature, see below).
3. Under "Events to follow", tick the events you want.
4. Save. The webhook appears under "Your webhooks", where you can edit or delete it.

Available events

In the interface	Value of the type field
"Creating a learner"	learner.created
"Modifying a learner"	learner.modified

Example of the content received:

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

Check that a request really comes from Teach Up

Each request includes the X-Teachup-Webhook-Signature header: an HMAC-SHA256 hash of the request content, calculated with your webhook's secret. To check it:

1. get the raw content of the request;
2. compute its HMAC-SHA256 with your secret;
3. compare the result with the header value.

Ignore any request whose signature doesn't match.

Frequently asked questions

My requests return 401 although my key is valid, why?

Check the header: the key must be sent in x-api-key, not in Authorization: Bearer as with many other APIs. See the example in Send your first request.

Can I create several API keys?

Yes, for example one per connected tool. You can then cut off one tool's access without affecting the others.

I lost my API key, what should I do?

It can't be shown again. Delete it, create a new one, and update the tool that used it.

Can I retrieve the results of a single course?

Not directly: the attempts export covers all your activities. Filter the file on the activity you want.

Can I filter webhooks by group or course?

No, a webhook fires for all learners in your space.

Who can create API keys and webhooks?

The space's administrators, once the "API & Webhooks" option is enabled.