Developer docs
De Pluvo API geeft je programmatische toegang tot je leeromgeving. Beheer gebruikers, groepen, trainingen, inschrijvingen en certificaten vanuit je eigen systemen.
De API is gebaseerd op GraphQL. Je bepaalt zelf welke data je opvraagt of muteert, zonder overbodige velden. Authenticatie verloopt via OAuth 2.0 met client credentials. Webhooks houden je systemen real-time op de hoogte van wijzigingen.
GraphQL Interface
- The Pluvo API is a GraphQL-based interface for managing users, trainings, events, and more.
- Authentication is handled via an OAuth token based on
client_idandclient_secret. - Webhooks provide real-time updates about enrollments, statuses, and more.
- Endpoint:
https://[organization].pluvo.com/graphql/
The Pluvo API enables external systems such as HRM platforms and integration tools to programmatically communicate with the Pluvo platform.
Authentication
Access to the API requires an OAuth token that you request via:
POST https://[organization].pluvo.com/oauth/token/Important:
- Endpoint requires trailing slash
/ - Headers:
Content-Type: application/x-www-form-urlencoded - Body parameters:
grant_type=client_credentialsclient_id=...client_secret=...scope=...(e.g.,users.read trainings.write)
A valid token is included as a Bearer token in API requests:
Authorization: Bearer <your_token>Access tokens are valid for 24 hours. After expiry, request a new token using the same credentials. There is no refresh token flow for client_credentials — simply request a new token.Scopes and Access Levels
Scopes control what your API client can access. Request only the scopes you need.
| Scope | Access | Description |
|---|---|---|
users.read | Users | View user profiles, roles, groups, extra fields |
users.write | Users | Create, update, archive users |
trainings.read | Trainings | View learning journeys, modules, progress |
trainings.write | Trainings | Create, update, archive trainings |
groups.read | Groups | View groups, members, managers |
groups.write | Groups | Create, update, delete groups and memberships |
events.read | Events | View module groups, offers, enrollments |
events.write | Events | Create, update, manage offers and enrollments |
extra_categories.write | Extra Categories | Create and update custom categorization fields |
Multiple scopes can be requested in a single token by separating them with spaces: scope=users.read users.write trainings.readAPI Endpoint
All requests are made to:
https://[organization].pluvo.com/graphql/The trailing slash is required. Requests without it will return a redirect or error.
GraphQL: Brief Overview
The Pluvo API implements a full GraphQL interface. You determine which fields you retrieve or update, ensuring minimal payloads and maximum flexibility.
Example query:
query user($ref: String!) {
user(ref: $ref) {
ref
name
email
isActive
}
}The ref serves as a unique identifier within your own system. You can determine this value yourself when creating an object, as long as it remains unique within the entity.
Error Handling
GraphQL errors are returned in the response body with HTTP status 200. Always check the errors array:
{
"data": null,
"errors": [
{
"message": "User not found",
"locations": [{"line": 2, "column": 3}],
"path": ["user"]
}
]
}Common error scenarios:
- Invalid or expired token — HTTP 401. Request a new token.
- Insufficient scope — Error message indicates which scope is required.
- Object not found —
nullresult with error inerrorsarray. - Validation error — Detailed message about which field failed validation.
Webhooks
Pluvo supports webhooks for real-time notifications about:
- User changes (created, updated, deleted)
- Training and course completion
- Enrollment status changes
- Portfolio and certificate events
- Group changes
Webhook configuration is done through the admin interface of your organization's Pluvo environment. Each webhook request contains an HMAC signature for verification.
See the Webhooks page for a full list of events and payload examples.