# Groepen

Groepen bevatten de gegevens (minimaal e-mailadres) van de studenten/respondenten bij evaluaties op uitnodiging. Vinden er alleen evaluaties live in de klas plaats, dan zijn groepen niet van toepassing.

### **Overzichtstabel termen**

| Naam            | Type    | Verplicht   | Omschrijving                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name            | string  | Ja          | Eigen naam (identificatie) voor de studentengroep                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| description     | string  | Nee         | Omschrijving van de cursus                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| externalId      | string  | Nee         | Dit kan een id van de groep in het eigen systeem zijn. Zie het onderdeel over externalId voor meer informatie. Dit veld is wel verplicht als je gebruik maakt van externalId voor groepen                                                                                                                                                                                                                                                                                                              |
| participants    | array   | Nee         | <p>Een lijst met participanten die aan de groep toegevoegd kunnen worden. Geef per participant een e-mailadres mee en optioneel een naam of externalId. Let op: Op het portaal is het wel verplicht om deelnemers toe te voegen<br><br>Het is ook mogelijk om participanten te labelen. Deze labels kunnen eind gebruikers vervolgens gebruiken om resultaten te filteren. Wijzigingen in labels bij deelnemers worden alleen toegepast op nieuwe evaluaties. Oude resultaten blijven ongewijzigd.</p> |
| organisation    | int     | n.v.t.      | **De organisatie waar de groep aan gekoppeld is**                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| topOrganisation | int     | n.v.t.      | **Geeft aan wat de hoofdorganisatie is waar de groep aan gekoppeld is**                                                                                                                                                                                                                                                                                                                                                                                                                                |
| id              | int     | J&#x61;*\** | *Alleen nodig bij updaten*                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| importLock      | boolean | Nee         | Zorgt ervoor dat op de frontend de groepen 'gelocked' worden. Hierdoor kunnen de groepen niet zomaar aangepast worden door gebruikers. Alleen een functioneel beheerder heeft de mogelijkheid om de groep aan te passen.                                                                                                                                                                                                                                                                               |
| integrations    | array   | Nee         | Nodig als er gebruik wordt gemaakt van de LTI integratie                                                                                                                                                                                                                                                                                                                                                                                                                                               |

## Groepen ophalen (Lijst)

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/group`

Haalt een lijst op met groepen die aan de organisatie zijn gekoppeld

#### Query Parameters

| Name     | Type         | Description                                             |
| -------- | ------------ | ------------------------------------------------------- |
| archived | boolean      | Filteren op gearchiveerde of niet gearchiveerde groepen |
| q        | string       | Zoeken binnen groepen (naam, omschrijving, externalId)  |
| status   | string array | Filter op active, archived, deleted (default = active)  |

{% tabs %}
{% tab title="200 " %}

```
{
  "metadata": {
    "timestamp": "2021-02-08T20:35:30.186Z",
    "resultSet": {
      "count": 4,
      "limit": 30
    }
  },
  "results": [
    {
      "organisation": 101,
      "topOrganisation": 100,
      "deleted": false,
      "createdBy": "2144",
      "modifiedBy": null,
      "externalId": "group1",
      "archived": false,
      "name": "Groep studenten",
      "description": "Studenten",
      "id": 1233,
      "createdAt": "2020-12-21T16:17:55.000Z",
      "updatedAt": "2020-12-21T16:17:55.000Z",
      "totalParticipants": 10
    },
    {
      "organisation": 101,
      "topOrganisation": 100,
      "deleted": false,
      "createdBy": "1234",
      "modifiedBy": null,
      "externalId": "group2",
      "archived": false,
      "name": "groep 2",
      "description": "Example groep 2",
      "id": 1234,
      "createdAt": "2021-02-08T20:35:11.000Z",
      "updatedAt": "2021-02-08T20:35:11.000Z",
      "totalParticipants": 5
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Groep ophalen (item)

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/group/:id`

Hiermee kan je een enkele groep ophalen. De lijst met deelnemers wordt ook meegestuurd in de response

#### Path Parameters

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| id   | string | Interne of externalId van de groep |

{% tabs %}
{% tab title="200 " %}

```
{
  "participants": [
    {
      "deleted": false,
      "createdBy": "3",
      "modifiedBy": null,
      "name": "",
      "email": "example@evalytics.nl",
      "externalId": null,
      "id": 12345,
      "createdAt": "2021-01-14T11:10:17.000Z",
      "updatedAt": "2021-01-14T11:10:17.000Z",
      "group": 1234
    }
  ],
  "organisation": 101,
  "topOrganisation": 100,
  "deleted": false,
  "createdBy": "3",
  "modifiedBy": null,
  "externalId": null,
  "archived": false,
  "name": "New group",
  "description": "Groep met studenten",
  "id": 1234,
  "createdAt": "2021-01-14T11:10:17.000Z",
  "updatedAt": "2021-01-14T11:10:17.000Z"
}
```

{% endtab %}
{% endtabs %}

## Groep aanmaken

<mark style="color:green;">`POST`</mark> `https://api-portal.evalytics.nl/group`

Maak een groep aan. Het meesturen van participants is niet verplicht.

{% tabs %}
{% tab title="200 " %}

```
{
  "name": "Groep voorbeeld",
  "description": "Groep voorbeeld omschrijving",
  "externalId": "abcd",
  "createdBy": "123",
  "organisation": 101,
  "topOrganisation": 100,
  "deleted": false,
  "archived": false,
  "createdAt": "2021-04-08T11:10:21.000Z",
  "updatedAt": "2021-04-08T11:10:21.000Z",
  "id": 1234,
  "modifiedBy": null,
  "importLock": false
}
```

{% endtab %}
{% endtabs %}

```json
{
  "name": (string - verplicht),
  "description": (string),
  "externalId": (string)
  "participants": [
    {
       "externalId": (string),
       "name": (string),
       "email": (string - email - verplicht),
       "labels": [{
          "name": (string - verplicht)
       }],
       "integrations": [{
          "type": "sisIntegrationId",
          "id": (string)
       }]
    }
  ],
  "importLock": (boolean)
}
```

## Groep bijwerken

<mark style="color:green;">`POST`</mark> `https://api-portal.evalytics.nl/group/:id`

Bijwerken van een groep

#### Path Parameters

| Name | Type   | Description                        |
| ---- | ------ | ---------------------------------- |
| id   | string | Interne of externalId van de groep |

#### Query parameters

| Name              | Type    | Description                                                                  |
| ----------------- | ------- | ---------------------------------------------------------------------------- |
| updateEvaluations | boolean | Past de deelnemers direct aan in evaluaties waar deze groep aan gekoppeld is |

{% tabs %}
{% tab title="200 " %}

```
{
  "name": "Groep voorbeeld",
  "description": "Groep voorbeeld omschrijving",
  "externalId": "abcd",
  "createdBy": "123",
  "organisation": 101,
  "topOrganisation": 100,
  "deleted": false,
  "archived": false,
  "createdAt": "2021-04-08T11:10:21.000Z",
  "updatedAt": "2021-04-08T11:10:21.000Z",
  "id": 1234,
  "modifiedBy": null,
  "importLock": false
}
```

{% endtab %}
{% endtabs %}

```json
{
  "name": (string - verplicht),
  "description": (string),
  "externalId": (string)
  "participants": [
    {
       "externalId": (string),
       "name": (string),
       "email": (string - email - verplicht),
       "labels": [{
          "name": (string - verplicht)
       }],
       "integrations": [{
          "type": "sisIntegrationId",
          "id": (string)
       }]
    }
  ],
  "importLock": (boolean)
}
```

## Groep verwijderen

<mark style="color:red;">`DELETE`</mark> `https://api-portal.evalytics.nl/group/:id`

Verwijderen van een groep. Door undo=true mee te geven kan je de actie ongedaan maken

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | Id of externalId van de groep |

#### Query Parameters

| Name | Type    | Description                                                     |
| ---- | ------- | --------------------------------------------------------------- |
| undo | boolean | Door undo=true mee te geven maak je de verwijder actie ongedaan |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Groep archiveren

<mark style="color:green;">`POST`</mark> `https://api-portal.evalytics.nl/group/:id/archive`

Groep archiveren

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | Id of externalId van de groep |

#### Query Parameters

| Name | Type   | Description                                                |
| ---- | ------ | ---------------------------------------------------------- |
| undo | string | Door undo=true mee te geve maak je de archivering ongedaan |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Deelnemer toevoegen aan groep

<mark style="color:green;">`POST`</mark> `https://api-portal.evalytics.nl/group/:id/participant`

Voeg een nieuwe deelnemer toe aan een groep. Indien de deelnemer al bestaat, krijg je geen foutmelding maar een 200 OK terug. Kan beheerd worden op basis van extern id.

Met participantUpdateType=email|externalId  kan je de check of een deelnemer al bestaat op externalId of op email (default) uitvoeren. Als een deelnemer al bestaat worden de andere gegevens (name, labels, ...) overschreven.&#x20;

Het is niet mogelijk om meerdere deelnemers met hetzelfde e-mail toe te voegen.

#### Path Parameters

| Name                                 | Type   | Description                           |
| ------------------------------------ | ------ | ------------------------------------- |
| id<mark style="color:red;">\*</mark> | string | Interne id of externalId van de groep |
| participantUpdateType                | string | externalId of email (default = email) |

{% tabs %}
{% tab title="200 " %}

```
{
  "deleted": false,
  "createdBy": "1",
  "modifiedBy": null,
  "name": "pascal",
  "email": "example@evalytics.nl",
  "externalId": "exampleExternalId",
  "group": 123,
  "id": 456,
  "createdAt": "2021-03-02T08:54:25.000Z",
  "updatedAt": "2021-03-02T08:54:36.000Z"
}
```

{% endtab %}
{% endtabs %}

```json
{
  "name": (string),
  "email": (string - verplicht),
  "externalId": (string),
  "labels": [{
          "name": (string)
  }], 
  "integrations": [{
          "type": "sisIntegrationId",
          "id": (string)
  }]
}
```

## Deelnemer toevoegen aan groep (identifier)

<mark style="color:green;">`POST`</mark> `https://api-portal.evalytics.nl/group/participant/identifier/externalId`

Voeg een deelnemer toe aan een groep met als identifier het externalId\
TODO: Meer typen zijn mogelijk

{% tabs %}
{% tab title="200 " %}

```
{
  "deleted": false,
  "createdBy": "123",
  "modifiedBy": null,
  "name": "example",
  "email": "example+example@evalytics.nl",
  "externalId": "exampleExternalId",
  "group": 1234,
  "id": 123456,
  "createdAt": "2021-03-02T08:54:25.000Z",
  "updatedAt": "2021-03-02T08:54:36.000Z"
}
```

{% endtab %}
{% endtabs %}

```
{
  "identifier": {
    "externalId": (string - verplicht - externalId van de groep)
  },
  "data": {
    "name": (string),
    "email": (string - verplicht),
    "externalId": (string - verplicht - externalId van de deelnemer),
    "labels": [{
          "name": (string)
    }]
  }
}
```

## Deelnemer verwijderen van groep

<mark style="color:red;">`DELETE`</mark> `https://api-portal.evalytics.nl/group/:id/participant/:participantId`

Verwijderd een deelnemer uit een groep. Als het gelukt is krijg je een 200 OK terug

#### Path Parameters

| Name          | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| participantId | string | Interne id of externalId van de deelnemer |
| id            | string | Interne id of externalId van de groep     |

{% tabs %}
{% tab title="200 " %}

```
{
  "removed": {
    "id": "92294",
    "group": "7397"
  }
}
```

{% endtab %}
{% endtabs %}

## Deelnemer verwijderen van groep (identifier)

<mark style="color:red;">`DELETE`</mark> `https://api-portal.evalytics.nl/group/participant/identifier/externalId`

Verwijderd een deelnemer van een groep op basis van identifier. \
TODO: meerdere identifiers zijn mogelijk

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

```
{
	"identifier": {
		"externalId": (string - verplicht - externalId van de groep),
		"participant": {
				"externalId": (string - verplicht - externalId van de deelnemer)
		}
	}
}
```

## Deelnemers in bulk importeren

<mark style="color:green;">`POST`</mark> `https://api-portal.evalytics.nl/group/bulkImportParticipants`

Hiermee is het mogelijk om in bulk deelnemers toe te voegen aan groepen doormiddel van een CSV import. Als de groupId een externalId is, voeg dan external=true toe.<br>

#### Path Parameters

| Name     | Type    | Description                               |
| -------- | ------- | ----------------------------------------- |
| external | boolean | De groupId in het bestand is een externId |

#### Headers

| Name         | Type   | Description         |
| ------------ | ------ | ------------------- |
| Content-Type | string | multipart/form-data |

#### Request Body

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| file | object | Het CSV bestand |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

{% file src="/files/-MdXYqcLcD-5rSlvaD1H" %}
Import example
{% endfile %}

{% hint style="info" %}

* Bestaande deelnemers in de import worden eventueel bijgewerkt
  {% endhint %}

## Deelnemer in groep bijwerken

<mark style="color:orange;">`PUT`</mark> `https://api-portal.evalytics.nl/group/:id/participant`

Update een deelnemer in een groep. Als identifier kan je **email** of **externalId** gebruiken.

#### Path Parameters

| Name                                 | Type   | Description      |
| ------------------------------------ | ------ | ---------------- |
| id<mark style="color:red;">\*</mark> | String | id of externalId |

{% tabs %}
{% tab title="200: OK " %}

```json
[
	{
		"id": 1,
		"email": "dev@evalytics.nl",
		"integrations": [
			{
				"type": "sisIntegrationId",
				"id": "1234"
			}
		],
		"name": "Dev student"
	}
]
```

{% endtab %}
{% endtabs %}

<pre class="language-json"><code class="lang-json">{
	"identifier": {
		"externalId": (string - required of gebruik id)
		"id": (number - required of gebruik externalId)
	},
	"data": {
		"externalId": (string),
		"name": (string),
		"email": (string),
		"labels": [{
			"name": (string - required)
<strong>		}],
</strong><strong>		"integrations": [{
</strong>		          "type": "sisIntegrationId",
		          "id": (string)
		 }]
	}
}
</code></pre>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.evalytics.nl/onderdelen/groepen.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.