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.
Use Cases
Get single user
Retrieves a single specific user via id, ref or email. Useful for displaying user profiles or checking status.
query {
user(id: "uuid-here") {
id
name
email
ref
archived
roles
language
participantGroups { id name }
managerGroups { id name }
}
}You can also look up users by ref or email:
query {
user(ref: "your-external-id") { id name email }
}Get list
Returns a paginated list of users. Supports filtering, sorting and search.
query {
paginatedUsers(first: 50, archived: false) {
edges {
node {
id
name
email
ref
archived
roles
}
}
pageInfo {
hasNextPage
endCursor
}
count
}
}Available filters for paginatedUsers:
| Parameter | Type | Description |
|---|---|---|
q | String | Search by name or email |
archived | Boolean | Filter by archived status |
userRoles | [Role!] | Filter by role (MANAGER, TRAINER, PARTICIPANT) |
groupIds | [UUID!] | Filter by group membership |
trainingIds | [UUID!] | Filter by training participation |
extraCategories | [ExtraCategoryFilterInput] | Filter by custom field values |
lastLogin_Gt | DateTime | Last login after date |
lastLogin_Lt | DateTime | Last login before date |
sortBy | UserSortByInput | Sort by field and direction (default: NAME ASC) |
Create user
Creates a new user. An invitation email is sent by default unless sendInvite: false is set.
mutation {
createUser(
sendInvite: true
user: {
email: "jane@example.com"
name: "Jane Doe"
ref: "EMP-12345"
roles: [MANAGER]
language: NL
addParticipantGroups: ["group-uuid-1"]
addManagerGroups: ["group-uuid-2"]
}
) {
user {
id
name
email
ref
}
created
}
}Update user
Modifies an existing user based on id or ref.
mutation {
updateUser(
ref: "EMP-12345"
user: {
name: "Jane Smith"
roles: [TRAINER]
addParticipantGroups: ["group-uuid-3"]
removeParticipantGroups: ["group-uuid-1"]
}
) {
user {
id
name
roles
participantGroups { id name }
}
}
}Create or update (recommended for sync)
Looks up a user based on email or ref, and creates one if it doesn't exist. This is the recommended mutation for integrations as it handles both creation and updates in a single call.
mutation {
updateOrCreateUser(
email: "jane@example.com"
sendInvite: false
user: {
name: "Jane Doe"
ref: "EMP-12345"
roles: [TRAINER]
language: NL
}
) {
user {
id
name
email
ref
}
created
}
}Thecreatedfield in the response tells you whether the user was newly created (true) or updated (false).
Archive/deactivate
Archives one or more users. These users are deactivated without permanently deleting them.
mutation {
archiveUsers(
archive: true
ids: ["uuid-1", "uuid-2"]
) {
response {
succeededIds
failedIds
}
}
}To reactivate archived users, use archive: false.
GraphQL Definitions
Type
type User {
id: ID!
modelId: ID!
email: String
name: String!
archived: Boolean!
archivedAt: DateTime
ref: String
roles: [Role]
profileImage: File!
language: Language!
extraFields: JSONString
extraFieldsProfile: JSONString
hasPassword: Boolean
participantGroups: [Group!]
managerGroups: [Group!]
groupCount: Int
invitedOn: DateTime
lastLogin: DateTime
userVia: [UserVia!]
}Queries
user(id: UUID, ref: String, email: String): User
paginatedUsers(
q: String
archived: Boolean
extraCategories: [ExtraCategoryFilterInput]
lastLogin_Gt: DateTime
lastLogin_Lt: DateTime
userRoles: [Role!]
groupIds: [UUID!]
trainingIds: [UUID!]
activityFrom: DateTime
activityTo: DateTime
sortBy: UserSortByInput = {field: NAME, direction: ASC}
offset: Int
before: String
after: String
first: Int
last: Int
): UserSelectorConnection!Mutations
createUser(sendInvite: Boolean = true, user: CreateUserInput!): CreateUser
updateUser(ref: String, id: UUID, user: UpdateUserInput!): UpdateUser
updateOrCreateUser(email: String, ref: String, sendInvite: Boolean, user: UpdateOrCreateUserInput!): UpdateOrCreateUser
archiveUsers(archive: Boolean!, ids: [UUID!]!): ArchiveUsersCreateUserInput
| Field | Type | Required | Description |
|---|---|---|---|
email | String | Yes | User's email address (unique per org) |
name | String | Yes | Full name |
ref | String | No | Your external reference (unique per org) |
roles | [Role] | No | MANAGER, PLANNER, TRAINER, PARTICIPANT |
language | Language | No | NL, EN, DE, FR, etc. |
archived | Boolean | No | Set to true to create as archived |
extraFields | JSONString | No | Legacy extra fields (prefer ExtraCategory) |
profileImage | UUID | No | File UUID for profile image |
notifications | MissedMessageFrequency | No | Email notification frequency |
addParticipantGroups | [UUID!] | No | Group IDs to add user as participant |
addManagerGroups | [UUID!] | No | Group IDs to add user as manager |
UpdateUserInput additionally supports removeParticipantGroups and removeManagerGroups (both [UUID!]).
Notes
- Use
updateOrCreateUseras the standard mutation for integrations — it prevents duplicate logic. archiveUsersis the designated way to deactivate users. There is nodeleteUsermutation.- The
isActivefield is deprecated and returnsnull. Usearchivedinstead (archived: false= active,archived: true= inactive). - The
groupsfield is deprecated. UseparticipantGroupsandmanagerGroupsinstead. - When creating users with
sendInvite: true, the user receives an email invitation to set their password and log in. - The
reffield is your anchor for synchronization. Always set it when creating users via integrations.