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.

Gruppen

Use Cases

Get single group

Retrieves a single group via id or ref. Useful for requesting group details or member counts.

query {
  group(id: "uuid-here") {
    id
    name
    ref
    maxUsers
    enableChat
    isEditable
    userCount
    managerCount
  }
}

You can also look up a group by ref:

query {
  group(ref: "your-external-id") { id name userCount }
}

Get list

Provides a list of all groups in the organization.

query {
  groups {
    id
    name
    ref
    userCount
    managerCount
  }
}

For advanced filtering and pagination, use paginatedGroups:

query {
  paginatedGroups(q: "sales", first: 50) {
    edges {
      node {
        id
        name
        ref
        userCount
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    count
  }
}

Create group

Creates a new group. You can optionally add a ref for external identification.

mutation {
  createGroup(group: {
    name: "Sales Team"
    maxUsers: 50
    enableChat: true
    ref: "group-sales"
  }) {
    group {
      id
      name
      ref
    }
  }
}

Update group

Modifies an existing group. You can identify the group by id or ref.

mutation {
  updateGroup(
    ref: "group-sales"
    group: {
      name: "Sales & Marketing"
      enableChat: false
    }
  ) {
    group {
      id
      name
    }
  }
}

Delete group

Deletes a single group permanently.

mutation {
  deleteGroup(id: "uuid-here") {
    ok
  }
}

Delete multiple groups

Deletes multiple groups at once. You will receive a report of successful and failed deletions.

mutation {
  deleteGroups(ids: ["uuid-1", "uuid-2"]) {
    bulkDelete {
      succeededIds
      failedIds
    }
  }
}

GraphQL Definitions

Type

type Group {
  id: UUID!
  name: String!
  ref: String
  maxUsers: Int!
  enableChat: Boolean!
  isEditable: Boolean!
  users: UserConnection
  managers: UserConnection
  trainings: [TrainingListItem!]!
  extraCategoryValues: [ExtraCategoryValue!]!
  userCount: Int
  managerCount: Int
  permissions: JSONString
  skills: [SkillListItem!]
}

Queries

group(id: UUID, ref: String): Group
groups(groupVia: GroupVia): [Group!]
paginatedGroups(
  q: String
  first: Int
  after: String
  offset: Int
  sortBy: GroupSortByInput
): GroupConnection

Mutations

createGroup(group: CreateGroupInput!): CreateGroup
updateGroup(id: UUID, ref: String, group: UpdateGroupInput!): UpdateGroup
deleteGroup(id: UUID!): DeleteGroup
deleteGroups(ids: [UUID!]): DeleteGroups

Notes

  • Use ref or id to select specific groups — both work in queries and mutations.
  • paginatedGroups is recommended for extensive filtering, sorting and pagination.
  • Groups support extraCategoryValues for custom metadata.
  • Deleting a group is permanent — unlike users, groups do not have an archive mechanism.
  • Use separate mutations for managing users and managers within a group (see Group User & Manager page).