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.

ExtraCategory

Application and Structure

An ExtraCategory groups custom fields that can be used to collect additional information about various objects within Pluvo. Each category has a type and can be attached to different entity types.

Supported entity types

ContentTypeApplies toExample use
USERUser profilesDepartment, job title, date of birth
GROUPGroupsLocation, business unit
TRAININGLearning journeysCompetency area, difficulty level
OFFEROffersTarget audience
COURSECourses/modulesLearning objectives
VIDEOVideosTopic, language

Use Cases

List all categories

query {
  extraCategories {
    id
    title
    categoryType
    forModelTypes
    choiceOptions { id stringValue ref color }
  }
}

List categories for a specific entity type

query {
  extraCategories(contentType: GROUP) {
    id
    title
    categoryType
  }
}

Get values for a specific object

Extra category values are available on the object itself:

query {
  user(id: "uuid") {
    extraCategoryValues {
      ... on ExtraCategoryStringValue {
        category { id title }
        stringValue
      }
      ... on ExtraCategoryChoiceValue {
        category { id title }
        choiceValue { id stringValue }
      }
      ... on ExtraCategoryBooleanValue {
        category { id title }
        booleanValue
      }
      ... on ExtraCategoryDatetimeValue {
        category { id title }
        datetimeValue
      }
    }
  }
}

Set values for an object

Use updateExtraCategoryValues to fill in values. Identify the object by modelId or modelRef.

mutation {
  updateExtraCategoryValues(
    contentType: USER
    modelId: "uuid-of-user"
    values: [
      {
        categoryId: "uuid-of-category"
        stringValue: "Marketing"
      },
      {
        categoryRef: "birthdate"
        datetimeValue: "1990-01-01T00:00:00Z"
      },
      {
        categoryId: "uuid-of-select-category"
        choiceValues: [{ stringValue: "HBO" }]
      }
    ]
  ) {
    extraCategoryValues {
      ... on ExtraCategoryStringValue { stringValue }
      ... on ExtraCategoryChoiceValue { choiceValue { stringValue } }
      ... on ExtraCategoryDatetimeValue { datetimeValue }
    }
  }
}

Create a new category

mutation {
  createExtraCategory(
    extraCategoryInput: {
      name: "Target Groups"
      categoryType: MULTISELECT
      forModelTypes: [GROUP]
      color: "#00AAFF"
      filter: true
      showLabel: true
      multipleChoices: true
      choiceOptions: [
        { stringValue: "MBO", color: "#F7C100" }
        { stringValue: "HBO", color: "#FF6600" }
      ]
    }
  ) {
    extraCategory {
      id
      title
    }
  }
}

Update a category

mutation {
  updateExtraCategory(
    id: "uuid-here"
    extraCategoryInput: {
      name: "New title"
      forModelTypes: [GROUP, OFFER]
    }
  ) {
    extraCategory {
      id
      title
    }
  }
}

Field Types

TypeValue fieldGraphQL value type
TEXTstringValueExtraCategoryStringValue
NUMBERstringValueExtraCategoryStringValue
DATEdatetimeValueExtraCategoryDatetimeValue
SELECTchoiceValuesExtraCategoryChoiceValue
MULTISELECTchoiceValuesExtraCategoryChoiceValue[]
BOOLEANbooleanValueExtraCategoryBooleanValue

GraphQL Definitions

Mutations

createExtraCategory(extraCategoryInput: CreateExtraCategoryInput!): CreateExtraCategory
updateExtraCategory(id: UUID, ref: String, extraCategoryInput: UpdateExtraCategoryInput!): UpdateExtraCategory
archiveExtraCategories(archive: Boolean!, ids: [UUID!]!): ArchiveExtraCategories
updateExtraCategoryValues(contentType: ContentType!, modelId: UUID, modelRef: String, values: [ExtraCategoryValuesUpdateInput!]!): UpdateExtraCategoryValues

Notes

  • Use updateExtraCategoryValues to set values — this is the primary mutation for filling in custom fields.
  • Values are identified by categoryId or categoryRef within the values array.
  • For SELECT and MULTISELECT, choice options can be referenced by id, ref, or stringValue.
  • Colors must be provided in hex format (e.g., #FF9900).
  • Archiving makes a category invisible but does not delete it or its values.
  • The extra_categories.write scope is required for creating/updating categories.