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.

Filtern mit ExtraCategories

Overview

Several queries (like paginatedUsers) support filtering by ExtraCategory values. This allows you to find users, groups, or other objects based on custom field values — for example, "all users in department Marketing" or "all users hired after 2024".

ExtraCategoryFilterInput

The filter input has this structure:

input ExtraCategoryFilterInput {
  id: UUID!                    # The ExtraCategory ID to filter on
  type: ExtraCategoryFilterType!  # STRING, BOOLEAN, or DATETIME
  stringValue: String          # For STRING type
  booleanValue: Boolean        # For BOOLEAN type
  datetimeValue: DateTime      # For DATETIME type
  dateComparison: DateComparison  # GREATER_THAN or LESSER_THAN (for DATETIME)
}

Filter by text/choice value

Find users where a specific extra category has a certain text or choice value:

query {
  paginatedUsers(
    first: 50
    extraCategories: [
      {
        id: "uuid-of-department-category"
        type: STRING
        stringValue: "Marketing"
      }
    ]
  ) {
    edges {
      node { id name email }
    }
    count
  }
}
For SELECT and MULTISELECT categories, use type: STRING and pass the choice option's stringValue.

Filter by boolean

Find users where a boolean extra category is true:

query {
  paginatedUsers(
    extraCategories: [
      {
        id: "uuid-of-active-employee-category"
        type: BOOLEAN
        booleanValue: true
      }
    ]
    first: 50
  ) {
    edges {
      node { id name }
    }
  }
}

Filter by date

Find users where a date category is after a specific date:

query {
  paginatedUsers(
    extraCategories: [
      {
        id: "uuid-of-hire-date-category"
        type: DATETIME
        datetimeValue: "2024-01-01T00:00:00Z"
        dateComparison: GREATER_THAN
      }
    ]
    first: 50
  ) {
    edges {
      node { id name }
    }
  }
}

GREATER_THAN means "on or after". LESSER_THAN means "on or before".

Combining multiple filters

You can pass multiple filters in the extraCategories array:

query {
  paginatedUsers(
    extraCategories: [
      {
        id: "uuid-department"
        type: STRING
        stringValue: "Marketing"
      },
      {
        id: "uuid-active"
        type: BOOLEAN
        booleanValue: true
      }
    ]
    first: 50
  ) {
    edges {
      node { id name email }
    }
    count
  }
}

Filter logic

  • Filters with different category IDs are combined with AND — the object must match all of them.
  • Filters with the same category ID are combined with OR — the object must match at least one.

Example: "Users in Marketing OR Sales who are active employees"

extraCategories: [
  { id: "uuid-department", type: STRING, stringValue: "Marketing" },
  { id: "uuid-department", type: STRING, stringValue: "Sales" },
  { id: "uuid-active", type: BOOLEAN, booleanValue: true }
]

This returns users where (department = Marketing OR department = Sales) AND (active = true).

Step 1: Find the category ID

Before you can filter, you need the category's UUID. Use this query:

query {
  extraCategories(contentType: USER) {
    id
    title
    categoryType
    choiceOptions {
      id
      stringValue
    }
  }
}

This returns all extra categories for users, with their IDs and available choice options.