> 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/kandidaten/ophalen.md).

# Ophalen

Alle kandidaten, één kandidaat of een selectie ophalen.

Je kunt alle kandidaten ophalen, één kandidaat op kenmerk, of een aantal kandidaten tegelijk.

* **Vereist recht:** Alle kandidaten inzien

## Alle kandidaten

* **Aanroep:** `GET /recruiter/candidates`
* **Verplicht:** niets
* **Optioneel:** niets

Het antwoord bevat alle kandidaten van de omgeving, ook kandidaten die niet beschikbaar zijn (`isAvailable` is `false`).

```bash
curl "https://mijn.cootje.com/api/recruiter/candidates" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

## Eén kandidaat

* **Aanroep:** `GET /recruiter/candidates/{id}`
* **Verplicht:** `id` in de URL, het `_id` van de kandidaat
* **Optioneel:** niets

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

## Meerdere kandidaten tegelijk

* **Aanroep:** `POST /recruiter/candidates/subset`
* **Verplicht:** een lijst met `_id`'s als inhoud van het verzoek
* **Optioneel:** niets

Kenmerken die niet bestaan, ontbreken in het antwoord.

```bash
curl -X POST "https://mijn.cootje.com/api/recruiter/candidates/subset" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    "KANDIDAAT_ID_1",
    "KANDIDAAT_ID_2"
  ]'
```

## Wat je terugkrijgt

Eén kandidaat ziet er zo uit:

```json
{
  "_id": "9e8d7c6b-5a4f-4e3d-a2c1-0a9f8e7d6c5b",
  "name": "Sanne de Vries",
  "companyId": "",
  "company": "",
  "email": "sanne@voorbeeld.nl",
  "zipCode": "3511 AB",
  "title": "Projectleider",
  "houseNumber": "12",
  "city": "Utrecht",
  "address": "Voorbeeldstraat",
  "phone": "0612345678",
  "linkedIn": "https://www.linkedin.com/in/sannedevries",
  "isAvailable": true,
  "expectedAvailabilityDate": null,
  "hoursPerWeek": 32,
  "plannedHolidays": "",
  "memo": "",
  "recruiterId": "",
  "priceLow": 80,
  "priceHigh": 95,
  "gender": 2,
  "skills": [
    "projectmanagement",
    "zorg"
  ],
  "offerForm": 1,
  "supplier": null,
  "contractForms": [
    1
  ],
  "kvkNumber": "",
  "kvkCompanyName": "",
  "experiences": [
    {
      "title": "Projectleider",
      "company": "Voorbeeld Zorg B.V.",
      "companyId": "",
      "startDate": "2022-01-01",
      "endDate": null,
      "location": "Utrecht",
      "description": "Invoering van een nieuw roostersysteem."
    }
  ],
  "educations": [
    {
      "title": "Bedrijfskunde",
      "institution": "Hogeschool Utrecht",
      "kind": "hbo",
      "graduationDate": "2015-07-01"
    }
  ],
  "notificationsEnabled": true
}
```

De aanroepen voor alle kandidaten en voor meerdere kandidaten geven een lijst van deze objecten, tussen `[` en `]`.

* `expectedAvailabilityDate` is een tijdstip in milliseconden sinds 1970, of `null`. De datums bij werkervaring en opleiding zijn tekst.
* `gender` is `1` (man), `2` (vrouw) of `null`.
* `offerForm` is `1` (de kandidaat biedt zichzelf aan) of `2` (via een leverancier). Alleen bij `2` is `supplier` gevuld.
* `contractForms` bevat getallen: `1` zzp, `3` loondienst, `4` tijdelijke arbeidsovereenkomst.
* `company` is de naam van het bedrijf, afgeleid van `companyId`.

De vacatures waaraan een kandidaat gekoppeld is, vraag je op met `GET /recruiter/relations/candidate/{id}`.

## Antwoorden

| Code  | Betekenis                                            |
| ----- | ---------------------------------------------------- |
| `200` | De kandidaat of de lijst met kandidaten              |
| `401` | Geen geldig token, of het account mist het recht     |
| `404` | De kandidaat bestaat niet (alleen bij één kandidaat) |
