Use the Teach Up public API and webhooks

The Teach Up public API allows you to connect your external systems to your TeachUp platform to automate actions or retrieve data. Webhooks enable you to receive real-time notifications when specific events occur on the platform.

Table of contents

• Discover the API
  • Manage API keys
  • Use an API key
  • Explore the interactive documentation
  • Review concrete use cases
• Set up webhooks
  • Create and manage webhooks
  • Identify available events
  • Verify the origin of an event
  • Frequently asked questions

Discover the API

The TeachUp public API (v1) allows you to automate data exchanges between your system and TeachUp.

Manage API keys

To generate an API key, follow these steps:

1. Log in to https://app.teachup.com using a concepteur and administrator account.
2. Go to the «Subscription & configuration» tab.
3. Scroll down to the «Personal API keys» section.
4. Create a new key and save the displayed secret (it will only be shown once).

Use an API key

To authenticate your requests:

Use a bearer token in the Authorization header:

TeachUp does not store any record of created keys. If a key is lost or you have any security concerns, delete it and generate a new one.

Explore the interactive documentation

All available endpoints can be accessed here:
👉 https://api.teachup.com/swagger

This interface allows you to:

• view all available endpoints with their parameters and detailed responses,
• enter your API key directly to test requests in real time from the interface,
• explore the response formats returned by Teach Up.

Review concrete use cases

• Create a participant when they join your company → POST /api/v2/learners
• List all participants to synchronize your internal tools → GET /api/v2/learners
• Update a participant’s information → PUT /api/v2/learners/{learnerId}
• Track activities assigned to a participant → GET /api/v2/learners/{learnerId}/AssignedActivities
• Retrieve the full list of available activities → GET /api/v1/activities
• Check which participants are enrolled in an activity → GET /api/v1/activities/{activityId}/AssignedLearners
• Assign an activity to multiple participants → POST /api/v1/assignments
• Remove an assigned activity → DELETE /api/v1/assignments
• Automatically create a participant group → POST /api/v1/groups
• Manage a participant’s group membership → PUT or DELETE /api/v1/groups/{groupId}/learners/{learnerId}
• Add a participant to a department or ban them → PUT /api/v1/departments/{departmentId}/learners/{learnerId} and /ban

Set up webhooks

Webhooks allow TeachUp to send HTTP requests to your system when a specific event occurs.

Create and manage webhooks

To configure your webhooks:

1. Log in to https://app.teachup.com with an administrator account.
2. Open «Subscription & configuration».
3. Go to the «Webhooks» section.
4. Add a receiving URL and select the events you want to monitor.

Identify available events

Two events are currently available:

• learner.created: when a participant is added.
• learner.modified: when a participant is updated.

Example JSON payload:

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

Verify the origin of an event

Each webhook event includes a signature:

• The X-Teachup-Webhook-Signature header contains an HMACSHA256 hash.
• This hash is calculated using your webhook’s unique secret.

To validate authenticity:

1. Retrieve the raw request body.
2. Recalculate the hash.
3. Compare it with the received signature.

It is strongly recommended to ignore any webhook whose signature is invalid.

Frequently asked questions

Can I generate multiple API keys for the same organization?
Yes. You can create several keys depending on your needs (per environment, application, or service).

What should I do if I lose my API key?
Immediately delete the key from the interface and create a new one. The secret is only displayed once.

Can I filter webhooks by group or course?
No. Current webhooks are triggered for each global event. More granular filtering is not yet available.