> For the complete documentation index, see [llms.txt](https://docs.cootje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cootje.com/cootje-api/recruitment/ai-analyses/matching-score.md).

# Matching Score

Opvragen hoe goed een kandidaat bij een vacature past: scores van 0 tot 100, harde eisen en de uitleg van AI.

De matching score laat zien hoe goed een kandidaat bij een vacature past. AI vergelijkt het profiel van de kandidaat (vaardigheden, werkervaring en opleiding) met de tekst van de vacature en geeft een score van 0 tot en met 100.

| Wat                                | Aanroep                                                                 | Vereist recht          |
| ---------------------------------- | ----------------------------------------------------------------------- | ---------------------- |
| Eén kandidaat tegen alle vacatures | `GET /recruiter/relations/candidate/{id}/scores`                        | Alle kandidaten inzien |
| Eén vacature tegen alle kandidaten | `GET /recruiter/relations/vacancy/{id}/scores`                          | Alle vacatures inzien  |
| Losse combinaties                  | `POST /recruiter/relations/scores`                                      | Alle vacatures inzien  |
| Uitleg bij een score               | `GET /recruiter/relations/scores/{vacancyId}/{candidateId}/explanation` | Alle vacatures inzien  |

Cootje berekent de scores op het moment dat je erom vraagt en slaat ze niet op.

## Eén kandidaat tegen alle vacatures

* **Aanroep:** `GET /recruiter/relations/candidate/{id}/scores`
* **Vereist recht:** Alle kandidaten inzien
* **Verplicht:** `id` in de URL, het `_id` van de kandidaat
* **Optioneel:** niets

De kandidaat wordt vergeleken met elke vacature waarvan de sluitingsdatum nog niet voorbij is. Vervulde vacatures tellen ook mee.

```bash
curl "https://mijn.cootje.com/api/recruiter/relations/candidate/9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b/scores" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

### Wat je terugkrijgt

Eén regel per vacature:

```json
[
  {
    "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "candidateId": "9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b",
    "score": 82,
    "missingRequirements": null
  },
  {
    "vacancyId": "a7b8c9d0-2e3f-4a5b-9c6d-7e8f9a0b1c2d",
    "candidateId": "9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b",
    "score": 64,
    "missingRequirements": [
      "Minimaal 5 jaar ervaring als projectleider in de zorg"
    ]
  }
]
```

* `score` is een geheel getal van 0 tot en met 100. Hoe hoger, hoe beter de kandidaat bij de vacature past.
* `score` is `null` als er niets te vergelijken valt, bijvoorbeeld omdat de kandidaat geen vaardigheden, werkervaring of opleiding heeft.
* `missingRequirements` bevat de eisen van de vacature waaraan de kandidaat niet voldoet. Is dit veld gevuld, dan valt de kandidaat af, ook als de score hoog is. Dat gebeurt alleen bij vacatures waarvan de eisen een harde voorwaarde zijn (`assignmentRequirementsKnockOut`). Anders is het veld `null`.

## Eén vacature tegen alle kandidaten

* **Aanroep:** `GET /recruiter/relations/vacancy/{id}/scores`
* **Vereist recht:** Alle vacatures inzien
* **Verplicht:** `id` in de URL, het `_id` van de vacature
* **Optioneel:** niets

Hiermee zoek je geschikte kandidaten bij een vacature. De vacature wordt vergeleken met elke kandidaat die beschikbaar is (`isAvailable` is `true`) en vaardigheden, werkervaring of opleiding heeft. De kandidaat hoeft niet aan de vacature gekoppeld te zijn.

```bash
curl "https://mijn.cootje.com/api/recruiter/relations/vacancy/c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f/scores" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

### Wat je terugkrijgt

Eén regel per kandidaat:

```json
[
  {
    "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "candidateId": "9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b",
    "score": 82,
    "missingRequirements": null
  },
  {
    "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "candidateId": "8d7c6b5a-4f3e-4d2c-b1a0-9f8e7d6c5b4a",
    "score": 47,
    "missingRequirements": null
  }
]
```

* `score` is een geheel getal van 0 tot en met 100. Hoe hoger, hoe beter de kandidaat bij de vacature past.
* `score` is `null` als er niets te vergelijken valt, bijvoorbeeld omdat de kandidaat geen vaardigheden, werkervaring of opleiding heeft.
* `missingRequirements` bevat de eisen van de vacature waaraan de kandidaat niet voldoet. Is dit veld gevuld, dan valt de kandidaat af, ook als de score hoog is. Dat gebeurt alleen bij vacatures waarvan de eisen een harde voorwaarde zijn (`assignmentRequirementsKnockOut`). Anders is het veld `null`.

## Losse combinaties

* **Aanroep:** `POST /recruiter/relations/scores`
* **Vereist recht:** Alle vacatures inzien
* **Verplicht:** een lijst met combinaties als inhoud van het verzoek. Elke combinatie heeft een `vacancyId` en een `candidateId`
* **Optioneel:** niets

```bash
curl -X POST "https://mijn.cootje.com/api/recruiter/relations/scores" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "candidateId": "9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b"
    },
    {
      "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "candidateId": "7c6b5a49-3e2d-4c1b-a09f-8e7d6c5b4a39"
    }
  ]'
```

### Wat je terugkrijgt

Eén regel per combinatie. Een combinatie met een `_id` dat niet bestaat, ontbreekt in het antwoord:

```json
[
  {
    "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "candidateId": "9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b",
    "score": 82,
    "missingRequirements": null
  },
  {
    "vacancyId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "candidateId": "7c6b5a49-3e2d-4c1b-a09f-8e7d6c5b4a39",
    "score": null,
    "missingRequirements": null
  }
]
```

* `score` is een geheel getal van 0 tot en met 100. Hoe hoger, hoe beter de kandidaat bij de vacature past.
* `score` is `null` als er niets te vergelijken valt, bijvoorbeeld omdat de kandidaat geen vaardigheden, werkervaring of opleiding heeft.
* `missingRequirements` bevat de eisen van de vacature waaraan de kandidaat niet voldoet. Is dit veld gevuld, dan valt de kandidaat af, ook als de score hoog is. Dat gebeurt alleen bij vacatures waarvan de eisen een harde voorwaarde zijn (`assignmentRequirementsKnockOut`). Anders is het veld `null`.

## Uitleg bij een score

* **Aanroep:** `GET /recruiter/relations/scores/{vacancyId}/{candidateId}/explanation`
* **Vereist recht:** Alle vacatures inzien
* **Verplicht:** `vacancyId` en `candidateId` in de URL
* **Optioneel:** niets

AI schrijft in het Nederlands waarom de kandidaat wel of niet bij de vacature past. De eerste keer duurt dat even. Daarna bewaart Cootje de uitleg tot de vacature of de kandidaat wijzigt.

```bash
curl "https://mijn.cootje.com/api/recruiter/relations/scores/c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f/9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b/explanation" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

### Wat je terugkrijgt

```json
{
  "scoreSummary": "Sanne heeft ruime ervaring als projectleider in de zorg en heeft eerder een roostersysteem ingevoerd. Haar vaardigheden sluiten goed aan op de omschrijving van de opdracht.",
  "scoreImprovements": "Het profiel noemt geen ervaring met het begeleiden van grote groepen gebruikers. Een toelichting daarop maakt de match sterker.",
  "missingRequirements": null
}
```

* `scoreSummary` is de samenvatting van de match.
* `scoreImprovements` beschrijft wat het profiel van de kandidaat sterker zou maken voor deze vacature.
* `missingRequirements` bevat de eisen waaraan de kandidaat niet voldoet, net als bij de score zelf. Anders is het veld `null`.

Bestaat de vacature of de kandidaat niet meer, dan is het antwoord `404`.

## Als het berekenen te lang duurt

Bij veel vacatures of kandidaten kan het berekenen langer duren dan Cootje toestaat. Het antwoord is dan `503`:

```json
[
  {
    "propertyName": "scoring",
    "errorMessage": "Het berekenen van de matchscores duurde te lang en is afgebroken. Wat al berekend was, is bewaard - een volgende poging gaat daardoor sneller. Probeer het over een moment opnieuw."
  }
]
```

Probeer het na een moment opnieuw. Wat al berekend was, blijft bewaard, dus een volgende poging is sneller klaar.

## Antwoorden

| Code  | Betekenis                                                            |
| ----- | -------------------------------------------------------------------- |
| `200` | De lijst met scores, of de uitleg                                    |
| `401` | Geen geldig token, of het account mist het recht                     |
| `404` | De vacature of de kandidaat bestaat niet meer (alleen bij de uitleg) |
| `503` | Het berekenen duurde te lang. Probeer het opnieuw                    |
