# Evaluation

## Add participant(s) to an evaluation

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

Add a new participant to an evaluation. You can only add participants when the evaluation has not yet been finished. You can also provide a groupId, so the group will also be linked to the invitationUser.

#### Path Parameters

| Name                               | Type   | Description                               |
| ---------------------------------- | ------ | ----------------------------------------- |
| <mark style="color:red;">\*</mark> | String | Internal or external id of the evaluation |

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

```javascript
{
    "newInvited": [
      "deleted": false,
      "createdBy": "123",
      "modifiedBy": null,
      "evaluator": 123,
      "evaluation": 456,
      "groupName": "Some group",
      "groupId": 1000,
      "id": 1,
      "createdAt": "2021-11-08T12:00:00.000Z",
      "updatedAt": null,
      "email": "example@evalytics.nl",
      "name": "Example Student"
    ],
    "alreadyInvited": [{
      "deleted": false,
      "createdBy": "123",
      "modifiedBy": null,
      "evaluator": 122,
      "evaluation": 456,
      "groupName": "Some group",
      "groupId": 1000,
      "id": 2,
      "createdAt": "2021-11-08T12:00:00.000Z",
      "updatedAt": null,
      "email": "dev@evalytics.nl",
      "name": "Dev Student"
    }]
}
```

{% endtab %}

{% tab title="400: Bad Request When one of the groups could not be linked to the invited participant" %}

```json
{
    "userMessage": "The evaluation could not be found",
    "errorCode": "22531c1b-cf00-4e25-ad7c-ebca49a51614"
}
```

```json
{
    "userMessage": "The evaluation visibility is not set to invitation",
    "errorCode": "fe635a42-bff9-4234-9985-1b94a88656ae"
}
```

```json
{
    "userMessage": "The evaluation has already been finished",
    "errorCode": "4988f6c0-df89-4200-9e27-e0025d0bd68a"
}
```

```json
{
  "userMessage": "One or multiple invitationUsers could not be found in the given group",
  "errorCode": "4e26d890-5dc8-41f9-ad61-41b053f9a043",
  "context": [
    {
      "email": "example@evalytics",
      "name": "Example",
      "group": {
        "externalId": "nonExistingGroup"
      }
    }
  ],
  "status": 400
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
We will ignore participants that are already added to the evaluation (**alreadyInvited** in the API response)
{% endhint %}

{% hint style="info" %}
You cannot add participants to an evaluation that is finished
{% endhint %}

#### Example post data

```
{
	"participants": [{
		"email": (string - required),
		"name": (string - not required),
		"group": (optional) {
			"externalId": (string)
		}, {
			"id": (int)
		},
		"labels": [{
	      		"name": (string)
	    	}]
	}]
}
```

## Removes one or multiple participants from the evaluation

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

Remove participants from the evaluation. Please note you can only remove participants when the evaluation has not yet been finished. The invitation url will no longer work, when the student is already invited for the evaluation.

#### Path Parameters

| Name                                 | Type   | Description                               |
| ------------------------------------ | ------ | ----------------------------------------- |
| id<mark style="color:red;">\*</mark> | String | Internal or external id of the evaluation |

{% tabs %}
{% tab title="200: OK Returns the total deleted evaluators" %}

```
{
	"totalDeletedEvaluators": number
}
```

{% endtab %}

{% tab title="400: Bad Request " %}
**Validation error**

```
{
	"userMessage": "Error in parameters",
	"context": [
		"\"participants\" is required"
	],
	"errorCode": "7d0a889a-1ce5-4eb1-9ce7-cb89b994656b",
	"status": 400
}
```

**Visibility is not set to invitation**

<pre><code><strong>{
</strong>	"userMessage": "The evaluation visibility is not set to invitation",
	"errorCode": "380be142-e6aa-4daa-aa81-a406759a9531",
	"status": 400
}
</code></pre>

**The evaluation has already been finished**

```
{
	"userMessage": "The evaluation has already been finished",
	"errorCode": "e6b371eb-8e14-43bb-8805-81318925d950",
	"status": 400
}
```

{% endtab %}
{% endtabs %}

**Example post data**

```
{
	"participants": [{
		"email": (string - required)
	}]
}
```

{% hint style="info" %}
You cannot remove participants when the evaluation has been finished
{% endhint %}

{% hint style="info" %}
Already emailed participants can no longer use the invitation url, because they are no longer invited for the evaluation
{% endhint %}


---

# 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/evaluation.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.