API en MCP

Voor wie

De API en de MCP-server horen bij het abonnement (Plus en Plus XL). De eigenaar van het bureau maakt onder Team een API-sleutel aan voor een medewerker. De sleutel wordt één keer getoond; VacatureMatch bewaart alleen een versleutelde vingerafdruk. Intrekken kan op elk moment en werkt direct.

Wat de API kan

Zoeken: vacatures op functie, trefwoorden, plaats en straal, in reeksen van 20 bedrijven (POST /api/v1/search, volgende reeks POST /api/v1/search/batch, passendheid per vacature POST /api/v1/search/score). Een zoekopdracht telt als één zoekopdracht van je maandtegoed.

Kandidaat matchen: het werkprofiel van een kandidaat vergelijken met een reeks, met per vacature een percentage en één zin waarom de kandidaat wel of niet past (POST /api/v1/match). Telt als kandidaatmatch, net als in de app.

Kandidaten: je bewaarde kandidaten lezen, aanmaken, bijwerken en verwijderen, met de getoonde vacatures per kandidaat (GET en POST /api/v1/candidates, GET en DELETE /api/v1/candidates/{id}).

Aanbiedingen: per medewerker welke kandidaat bij welk bedrijf is voorgelegd (GET /api/v1/offers).

Aangeboden bij de werkgever: vastleggen of weghalen dat een kandidaat bij de werkgever van een getoonde vacature is aangeboden, op naam van de medewerker van de sleutel (POST /api/v1/candidates/{id}/employer met vacancyId en offered).

Tegoed: je pakket en wat er deze maand over is (GET /api/v1/account).

Rechten en grenzen

Een sleutel werkt als de medewerker voor wie hij is gemaakt, met de rechten van jullie abonnement: Plus of Plus XL, het maandtegoed, maximaal 10 vacatures per selectie en alleen de gegevens van je eigen bureau. Loopt het abonnement af, wordt het bureau gepauzeerd of verlaat de medewerker het bureau, dan werkt de sleutel niet meer. Per sleutel kunnen 120 aanroepen per minuut. Beheerders en supportmedewerkers krijgen geen sleutel, omdat hun toegang een authenticator vraagt.

MCP voor AI-assistenten

Met MCP (Model Context Protocol) kan een AI-assistent VacatureMatch rechtstreeks gebruiken, bijvoorbeeld: "zoek 20 vacatures voor deze kandidaat in Utrecht". Het adres is https://vacaturematch.kopplix.nl/api/mcp, met dezelfde sleutel. Dat werkt in assistenten die een vaste sleutel accepteren, zoals Claude Code, Cursor en de ontwikkelaarsmodus van ChatGPT. De webversie van Claude vraagt een andere manier van inloggen (OAuth); die is er nog niet.

Gegevens en privacy

Werkgevers worden in antwoorden aangeduid met een eigen code, niet met het nummer uit de bron. Stuur geen cv-bestanden of contactgegevens van kandidaten mee: de API werkt met het werkprofiel (ervaring, vaardigheden, opleiding), net als de app. De afspraken in de verwerkersovereenkomst gelden ook voor gebruik via de API.

Voorbeelden

Elke aanroep stuurt de sleutel mee in de kop Authorization: Bearer. Geef bij een zoekopdracht een eigen requestId mee: dezelfde aanvraag twee keer versturen telt dan maar één keer.

curl https://vacaturematch.kopplix.nl/api/v1/account \
  -H "Authorization: Bearer vmk_..."

curl https://vacaturematch.kopplix.nl/api/v1/search \
  -H "Authorization: Bearer vmk_..." -H "Content-Type: application/json" \
  -d '{"requestId":"<nieuwe uuid>","title":"planner","keywords":[],"keywordMode":"all",
       "location":"Utrecht","radius":25,"cv":false}'

MCP-instelling voor een assistent die een vaste sleutel accepteert:

{
  "mcpServers": {
    "vacaturematch": {
      "type": "http",
      "url": "https://vacaturematch.kopplix.nl/api/mcp",
      "headers": { "Authorization": "Bearer vmk_..." }
    }
  }
}

Een sleutel maken doe je als eigenaar onder Team. Nog geen abonnement? Bekijk de prijs.