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.

Benutzer

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:

ParameterTypeDescription
qStringSearch by name or email
archivedBooleanFilter 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_GtDateTimeLast login after date
lastLogin_LtDateTimeLast login before date
sortByUserSortByInputSort 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
  }
}
The created field 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!]!): ArchiveUsers

CreateUserInput

FieldTypeRequiredDescription
emailStringYesUser's email address (unique per org)
nameStringYesFull name
refStringNoYour external reference (unique per org)
roles[Role]NoMANAGER, PLANNER, TRAINER, PARTICIPANT
languageLanguageNoNL, EN, DE, FR, etc.
archivedBooleanNoSet to true to create as archived
extraFieldsJSONStringNoLegacy extra fields (prefer ExtraCategory)
profileImageUUIDNoFile UUID for profile image
notificationsMissedMessageFrequencyNoEmail notification frequency
addParticipantGroups[UUID!]NoGroup IDs to add user as participant
addManagerGroups[UUID!]NoGroup IDs to add user as manager

UpdateUserInput additionally supports removeParticipantGroups and removeManagerGroups (both [UUID!]).

Notes

  • Use updateOrCreateUser as the standard mutation for integrations — it prevents duplicate logic.
  • archiveUsers is the designated way to deactivate users. There is no deleteUser mutation.
  • The isActive field is deprecated and returns null. Use archived instead (archived: false = active, archived: true = inactive).
  • The groups field is deprecated. Use participantGroups and managerGroups instead.
  • When creating users with sendInvite: true, the user receives an email invitation to set their password and log in.
  • The ref field is your anchor for synchronization. Always set it when creating users via integrations.