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
| ContentType | Applies to | Example use |
|---|---|---|
USER | User profiles | Department, job title, date of birth |
GROUP | Groups | Location, business unit |
TRAINING | Learning journeys | Competency area, difficulty level |
OFFER | Offers | Target audience |
COURSE | Courses/modules | Learning objectives |
VIDEO | Videos | Topic, 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
| Type | Value field | GraphQL value type |
|---|---|---|
TEXT | stringValue | ExtraCategoryStringValue |
NUMBER | stringValue | ExtraCategoryStringValue |
DATE | datetimeValue | ExtraCategoryDatetimeValue |
SELECT | choiceValues | ExtraCategoryChoiceValue |
MULTISELECT | choiceValues | ExtraCategoryChoiceValue[] |
BOOLEAN | booleanValue | ExtraCategoryBooleanValue |
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!]!): UpdateExtraCategoryValuesNotes
- Use
updateExtraCategoryValuesto set values — this is the primary mutation for filling in custom fields. - Values are identified by
categoryIdorcategoryRefwithin thevaluesarray. - For
SELECTandMULTISELECT, choice options can be referenced byid,ref, orstringValue. - 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.writescope is required for creating/updating categories.