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.
In this second part, we dive deeper into the technical structure of extra categories in Pluvo. Here you'll find the specific GraphQL types used to store values, how they connect to entities like users or trainings, and how to manage them using mutations.
Value per type
Text value
type ExtraCategoryStringValue {
category: ExtraCategory!
color: Color
stringValue: String!
modelId: UUID!
}Date value
type ExtraCategoryDatetimeValue {
category: ExtraCategory!
color: Color
datetimeValue: DateTime!
modelId: UUID!
}Choice option
type ExtraCategoryChoiceValue {
category: ExtraCategory!
color: Color
choiceValue: ExtraCategoryChoiceOption!
modelId: UUID!
}Boolean value
type ExtraCategoryBooleanValue {
category: ExtraCategory!
color: Color
booleanValue: Boolean!
modelId: UUID!
}Contextual connection
All value types contain:
category: the correspondingExtraCategorymodelId: ID of the linked object (e.g., user or training)color: optional color for visualization
Notes
- These value types are not directly mutated via separate GraphQL mutations, but usually via JSON fields on the target objects (like
extraFieldsonUserorTraining). reffields on choice options enable external mapping with other systems.Coloris optional and is used for visual indication in interfaces.
GraphQL Definitions
Type: ExtraCategory
type ExtraCategory {
id: ID!
title: String!
extraFields: [ExtraField!]
archivedAt: DateTime
}Type: ExtraField
type ExtraField {
id: ID!
key: String!
label: String!
type: ExtraFieldType!
}Enum: ExtraFieldType
enum ExtraFieldType {
TEXT
NUMBER
DATE
SELECT
MULTISELECT
BOOLEAN
}Mutations
createExtraCategory(category: CreateExtraCategoryInput!): CreateExtraCategoryPayload
updateExtraCategory(id: UUID!, category: UpdateExtraCategoryInput!): UpdateExtraCategoryPayload
archiveExtraCategories(archive: Boolean!, ids: [UUID!]!): ArchiveExtraCategoriesPayloadNotes
- Use extra categories for dynamically managing additional data.
- Archiving makes a category invisible, but does not delete it.
- Fields must be managed separately (see
ExtraFielddocumentation for details).
Mutations and updates in detail
In addition to the basic structure of extra categories, advanced mutations are available for creating, updating, and filling in these categories.
Query: extraCategories by content type
Retrieve categories that apply to a specific model type, such as GROUP, USER, OFFER, etc.
query {
extraCategories(contentType: GROUP) {
id
title
}
}CreateExtraCategory
Create a new category with configuration such as color, filter option, and list of choices (for SELECT or MULTISELECT).
mutation {
createExtraCategory(
extraCategoryInput: {
name: "Target Groups"
color: "#00AAFF"
filter: true
showLabel: true
categoryType: MULTISELECT
forModelTypes: [GROUP]
multipleChoices: true
choiceOptions: [
{ stringValue: "MBO", color: "#F7C100" }
{ stringValue: "HBO", color: "#FF6600" }
]
}
) {
extraCategory {
id
title
}
}
}UpdateExtraCategory
Update an existing category based on id or ref. You can also adjust the choice list.
mutation {
updateExtraCategory(
id: "uuid-here"
extraCategoryInput: {
name: "New title"
showLabel: false
forModelTypes: [GROUP, OFFER]
}
) {
extraCategory {
id
title
}
}
}UpdateExtraCategoryValues
Use this mutation to fill in values for a specific content (such as a user or group). Use modelId or modelRef.
mutation {
updateExtraCategoryValues(
contentType: GROUP
modelId: "uuid-of-group"
values: [
{
categoryId: "uuid-of-category"
choiceValues: [{ stringValue: "HBO" }]
},
{
categoryRef: "birthdate"
datetimeValue: "1990-01-01T00:00:00Z"
}
]
) {
extraCategoryValues {
... on ExtraCategoryChoiceValue {
choiceValue {
stringValue
}
}
... on ExtraCategoryDatetimeValue {
datetimeValue
}
}
}
}Notes
- Only the correct field value may be used within
ExtraCategoryValuesUpdateInput, depending on the type (stringValue,booleanValue,datetimeValue,choiceValues). - Choice options can be controlled via
idorref. - The
Colorvalue must be provided in hex code, for example#FF9900.