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.

Common Recipes

Recipe 1: Sync Users from HRM

A common integration pattern: synchronize users from an external HR system to Pluvo.

For each user in the HRM system:

Step 1: Create or update the user

mutation SyncUser($email: String!, $name: String!, $ref: String!) {
  updateOrCreateUser(
    email: $email
    sendInvite: false
    user: {
      name: $name
      ref: $ref
      roles: [PARTICIPANT]
      language: NL
    }
  ) {
    user { id ref }
    created
  }
}

Step 2: Set custom fields (department, etc.)

mutation SetUserFields($userRef: String!, $department: String!) {
  updateExtraCategoryValues(
    contentType: USER
    modelRef: $userRef
    values: [
      { categoryRef: "department", stringValue: $department }
    ]
  ) {
    extraCategoryValues {
      ... on ExtraCategoryStringValue { stringValue }
    }
  }
}

Step 3: Add to group

mutation AddToGroup($groupRef: String!, $userRef: String!) {
  addUsersToGroup(
    groupRef: $groupRef
    userRefs: [$userRef]
  ) {
    addedIds
    alreadyAddedIds
  }
}

Handling leavers

For users who have left the organization:

mutation ArchiveUser($ref: String!) {
  updateOrCreateUser(
    ref: $ref
    user: { archived: true }
  ) {
    user { id archived }
  }
}

Recipe 2: Progress Report for a Group

Get completion status for all users in a group across their trainings.

query GroupProgress($groupId: UUID!, $cursor: String) {
  portfolioReport(
    userGroupIds: [$groupId]
    relatedObjectTypes: [TRAINING]
    first: 50
    after: $cursor
  ) {
    edges {
      node {
        user { id ref name email }
        title
        progress
        score
        completionDate
        timeSpent { days seconds }
      }
    }
    pageInfo { hasNextPage endCursor }
    count
  }
}

Loop through all pages (see Pagination guide) to get the complete report.

Recipe 3: Enroll Users in a Training

Automate enrollment when a user joins a specific group.

Step 1: Listen for GROUP_UPDATED webhook (or run on schedule)

Step 2: Get group members

query GroupMembers($groupRef: String!) {
  group(ref: $groupRef) {
    users(first: 50) {
      edges {
        node { id ref }
      }
    }
  }
}

Step 3: Enroll all members

mutation EnrollGroup($eventRef: String!, $userRefs: [String!]!) {
  createOfferEventEnrollments(
    offerEventRef: $eventRef
    userRefs: $userRefs
    sendMail: false
  ) {
    id
    user { ref }
    status
  }
}
Already-enrolled users are handled gracefully — they won't be duplicated.

Recipe 4: Certificate Monitoring

Track when users earn certificates, e.g. for compliance reporting.

Option A: Webhook-based (real-time)

Listen for the EVENT_CERTIFICATE_ACHIEVED webhook. Each payload includes the user, certificate title, and training:

{
  "event": "EVENT_CERTIFICATE_ACHIEVED",
  "user": { "id": "...", "name": "...", "ref": "..." },
  "title": "Safety Certificate",
  "training": { "id": "...", "title": "..." },
  "creationDate": "2024-03-15",
  "expiryDate": "2025-03-15"
}

Option B: Query-based (batch)

query RecentCertificates($from: Date!, $to: Date!) {
  portfolioReport(
    relatedObjectTypes: [CERTIFICATE]
    completionDateFrom: $from
    completionDateTo: $to
    first: 50
  ) {
    edges {
      node {
        title
        user { ref name email }
        completionDate
        endDate
      }
    }
    count
  }
}

Recipe 5: Bulk Assign Mandatory Training

Assign all users in a group to a mandatory training directly (without enrollment flow).

Step 1: Get group members

query {
  group(ref: "all-employees") {
    users(first: 50) {
      edges {
        node { ref }
      }
    }
  }
}

Step 2: Add all to training

mutation {
  addUsersToTraining(
    trainingRef: "safety-2024"
    userRefs: ["EMP-001", "EMP-002", "..."]
    sendInvites: true
    role: PARTICIPANT
  ) {
    addedRefs
    alreadyAddedRefs
    failedRefs
  }
}

Recipe 6: Find Inactive Users

Find users who haven't logged in for 6 months.

query InactiveUsers($before: DateTime!, $cursor: String) {
  paginatedUsers(
    archived: false
    lastLogin_Lt: $before
    first: 50
    after: $cursor
  ) {
    edges {
      node {
        id
        ref
        name
        email
        lastLogin
      }
    }
    pageInfo { hasNextPage endCursor }
    count
  }
}

Variables: { "before": "2024-04-01T00:00:00Z" }

Integration Architecture Tips

  • Use ref everywhere — it's your anchor between systems. Set it on users, groups, trainings, offers, and events.
  • Prefer updateOrCreateUser over separate create/update logic — it handles both cases.
  • Use webhooks for real-time — don't poll the API for changes.
  • Paginate in batches of 50 (the maximum page size) — good balance between speed and reliability.
  • Set sendInvite: false / sendMail: false during bulk operations to avoid notification storms.
  • Cache your OAuth token — it's valid for 24 hours. Request a new one proactively after ~23 hours or when you get a 401.