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).

Zoekgeschiedenis: je recente zoekopdrachten (GET /api/v1/history).

Contactgegevens: de contactgegevens van de werkgever bij een vacature uit je eigen zoekopdracht (POST /api/v1/vacancies/contact met runId, page en vacancyId). Dezelfde grenzen als in de app: hooguit 30 per minuut per medewerker en 200 per dag per bureau, samen met de app.

Bedrijven volgen: volgen, ontvolgen, je gevolgde bedrijven en hun vacatures (POST /api/v1/companies/follows met action list, follow, unfollow of vacancies).

Bureau melden: een bedrijf in de resultaten melden als bureau, en de meldingen van een zoekopdracht bekijken (POST /api/v1/companies/reports met action create of list). Klopt de melding, dan krijg je die reeks terug. Beoordelen doet VacatureMatch zelf.

Bedrijfssamenvattingen: korte samenvattingen van de bedrijven in een reeks (POST /api/v1/companies/summaries).

Selecties: een selectie voor een kandidaat maken, mailen, bekijken, intrekken, beantwoorde vacatures verbergen, contactgegevens van de werkgever opvragen en een anonieme kandidaattekst maken (POST /api/v1/shortlists/create, send, list, read, revoke, hide, contact en draft). Bij maken maakt VacatureMatch zelf de geheime link voor de kandidaat en geeft die terug; dezelfde aanvraag herhalen geeft dezelfde link. Bewaar de link dus veilig. Mailen kan alleen met confirmed: true.

Support: je eigen supporttickets bekijken, een vraag stellen en reageren (GET en POST /api/v1/support met action read, create of reply). Tickets beheren doet VacatureMatch zelf.

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 20 vacatures per selectie en alleen de gegevens van je eigen bureau. Wordt de medewerker of het bureau gepauzeerd, verlaat de medewerker het bureau of gaat het bureau van Plus af, dan werkt de sleutel niet meer. Is de betaalperiode afgelopen terwijl het bureau op Plus staat, dan kun je niet meer zoeken of matchen, maar nog wel bewaarde kandidaten lezen en verwijderen, net als in de app. Per sleutel kunnen 120 stappen per minuut; één verzoek gebruikt er vaak twee of meer, reken dus op hooguit ongeveer 60 verzoeken 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. De assistent kan zoeken met alle filters, matchen (ook grote reeksen in delen), kandidaten bewaren en verwijderen, selecties bekijken, bedrijven volgen, bureaus melden, kandidaatteksten maken en supportvragen stellen. Een selectie maken of mailen kan alleen via de API, omdat daar naam en e-mailadres van de kandidaat voor nodig zijn. Met een vaste sleutel werkt het in onder meer Claude Code en Cursor; zonder sleutel zie hieronder.

Koppelen zonder sleutel

In Claude (web, desktop en telefoon) en ChatGPT kan de eigenaar van een Plus-bureau koppelen, zonder sleutel of instellingenbestand. Collega’s kunnen dat niet zelf: voor hen maakt de eigenaar onder Team een API-sleutel. Kies in de assistent Connector toevoegen (in Claude onder Instellingen → Connectors, in ChatGPT onder de connectors in de instellingen) en vul dit adres in: https://vacaturematch.kopplix.nl/api/mcp. De assistent opent dan VacatureMatch: log in met je eigen account en klik Toestaan. Daarna werkt de assistent met jouw rechten en het tegoed van je bureau.

De koppeling verschijnt onder Team als "Koppeling: Claude" (of de naam van de assistent). De eigenaar kan hem daar altijd intrekken; opnieuw koppelen vervangt de vorige koppeling van dezelfde assistent. Is iemand geen eigenaar meer, dan werkt zijn koppeling niet meer. Beheerders en support kunnen niet koppelen: hun toegang vraagt een authenticator.

Gegevens en privacy

Werkgevers worden in antwoorden aangeduid met een eigen code, niet met het nummer uit de bron. Stuur geen cv-bestanden mee: de API werkt met het werkprofiel (ervaring, vaardigheden, opleiding), net als de app. Naam en e-mailadres van een kandidaat gaan alleen mee bij het maken van een selectie via de API, om de kandidaat te mailen. Via MCP gaan de naam en het e-mailadres uit een selectie niet naar de AI-assistent, en worden e-mailadressen en telefoonnummers in kandidaatlabels weggehaald. Een naam in een label of in lopende tekst kan VacatureMatch niet herkennen: die ziet de assistent wel. Gebruik voor kandidaten daarom een eigen referentie in plaats van een naam. Contactgegevens van werkgevers geeft VacatureMatch niet aan een AI-assistent: die vraag je op in de app of via de API. 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.

API-aanroepen — bash
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:

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