CRM API: laat je AI-agent en je tools opvolgen vanuit dezelfde klantrecords

Een CRM API is de programmeerbare toegang tot de records van een CRM: andere software leest, maakt, wijzigt en verwijdert contactpersonen, organisaties en deals via HTTP en krijgt via webhooks bericht wanneer er iets verandert. Zo koppel je je CRM aan je website, je boekhouding of een AI-client, zonder iets over te typen. Customermates heeft een open REST API in elk abonnement, vanaf Starter voor € 12 per gebruiker per maand, en in de gratis zelf gehoste editie. Je authenticeert met een API-sleutel in de header x-api-key, het volledige schema is een OpenAPI 3.1-document op /api/v1/openapi en, in betaalde abonnementen en bij zelf hosten, melden 16 webhook-events je systemen wanneer er iets verandert. Er is geen apart developerabonnement en geen betaalde API-add-on.

Customermates is een open-source, AI-native CRM voor kleine teams met veel klantcontact, gebouwd in Duitsland. Deze pagina is voor twee soorten lezers: een developer die het CRM met een ander systeem wil synchroniseren, en een team dat wil dat een AI-client zoals Claude of ChatGPT records bijwerkt. De eerste gebruikt REST en webhooks. De tweede gebruikt het MCP-endpoint, dat op dezelfde rechten draait.

Waarom dit telt voor opvolging. Een antwoord aan een klant blijft liggen wanneer de feiten die je ervoor nodig hebt in een ander systeem staan. Via MCP leest je eigen AI-client, zoals Claude of ChatGPT, het record van een klant en, in Customermates Cloud vanaf Pro, de gesprekken met die klant, en kan hij een conceptantwoord opslaan dat jij nakijkt en verstuurt. Via REST en webhooks krijgen je andere tools dezelfde records en horen ze het wanneer er een verandert.

Wat kun je met een CRM API bouwen?

Een paar koppelingen, elk met de onderdelen die Customermates daarvoor biedt:

• Een formulier of je website vult het CRM. Een script maakt met POST /api/v1/records/mutate een contactpersoon aan en koppelt die aan een organisatie.
• Je boekhouding krijgt een seintje bij een gewonnen deal. Een webhook voor record.updated op de lijst Deals meldt de nieuwe fase aan je eigen workflowtool, die je boekhoudtool aanroept.
• Een dashboard of datawarehouse leest mee. POST /api/v1/records/query en POST /api/v1/reports/query halen records en totalen op, zoals de pipelinewaarde.
• Een AI-client werkt met je klantrecords. Claude of ChatGPT leest en werkt records bij via MCP, met de rechten van de verbonden gebruiker.

Wat de REST API dekt

De REST API werkt op elke lijst van het CRM. Een nieuwe werkruimte begint zonder lijsten: je maakt de lijsten die je nodig hebt (contactpersonen, organisaties, deals of je eigen lijsten) aan in Datamodel, via de API of MCP, of laat de AI-setup ze in de cloud opbouwen. Elke recordroute is een POST naar een benoemde actie met een JSON-body, dus dezelfde code werkt voor deals, contactpersonen of een lijst die je vorige week hebt toegevoegd.

Een record wordt aangesproken via een verwijzing, { "typeId": "...", "recordId": "..." }, niet via zijn URL. De basis-URL is het adres waarop je Customermates opent, in de cloud en op je eigen server. Wat sommige CRM's objecten, eigenschappen en associaties noemen, heet hier lijsten, velden en relaties. Contactpersonen, organisaties en deals zijn gewone lijsten die je in Datamodel aanmaakt; een relatie verbindt ze, bijvoorbeeld een contactpersoon met zijn organisatie. Maak eerst beide records aan en koppel ze daarna met een link-actie, met het relationId uit /model/read. Verdere routes dekken gebruikers (/api/v1/users/me, /api/v1/users/search), webhooks en de inbox: gesprekken, concepten, het versturen van e-mail en chatberichten, activiteiten en agenda's met alleen leestoegang.

Een paar details besparen je op de eerste dag tijd:

• Velden hebben vaste ID's. /model/read geeft het fieldId van elk veld terug, de optie-ID's van een veld met enkele keuze zoals de deal-Fase, en de schema-revision. ID's blijven gelijk wanneer iemand een lijst of veld hernoemt. Waarden zijn getypeerd, bijvoorbeeld { "kind": "text", "value": "Acme" }.
• Query's gebruiken een JSON-body. /records/query neemt typeId, filters, sort, page en pageSize (maximaal 500). Filters gebruiken de filtersyntaxis die ook in de app en bij MCP geldt.
• Schrijfacties zijn beveiligd. Een mutatie bevat expectedRevision (de schemarevisie), een idempotencyKey en de mutation zelf; bijwerken en verwijderen bevatten ook de expectedVersion van het record. Hetzelfde verzoek met dezelfde sleutel opnieuw sturen wordt niet twee keer toegepast.
• Koppelingen zijn een eigen actie. link en unlink nemen een relationId, een source en een target-recordverwijzing. Een update verwijdert nooit koppelingen die je niet noemt.
• Bulkschrijfacties nemen maximaal 100 records. updateMany past één wijziging atomair toe op maximaal 100 records en deleteMany verplaatst er maximaal 100 naar de prullenbak, dus een opschoning van 2.000 contactpersonen splits je in 20 verzoeken.

Webhooks: laat het CRM jou bellen

Een webhook stuurt een JSON-POST naar je URL wanneer een geabonneerd event plaatsvindt. Beheerders, en leden van wie de rol Leestoegang Alle en Aanmaken heeft bij API en webhooks, voegen er een toe onder Instellingen → Webhooks: URL, events, de lijst onder Records uit met optionele filters, een optioneel geheim, optionele eigen headers en een optioneel bodysjabloon. De webhookreferentie noemt elk event en elke payload.

• Events: 5 recordevents (record.created, record.updated, record.deleted wanneer een record naar de prullenbak gaat, record.restored en record.deletedPermanently) voor elke lijst die je kiest, ook je eigen lijsten, plus 11 inbox- en agenda-events.
• Wijzigingen inbegrepen: een record.updated-payload bevat de recordverwijzing en noemt elk gewijzigd veld met de waarde before en after. Een schrijfactie die niets wijzigt, stuurt geen event.
• Handtekeningen: met een geheim ingesteld wordt elke bezorging ondertekend met HMAC-SHA256 over de ruwe body.
• Nieuwe pogingen: een time-out, netwerkfout, 5xx, 408, 425 of 429 wordt automatisch opnieuw geprobeerd, tot in totaal 10 pogingen. Andere 4xx-antwoorden worden niet opnieuw geprobeerd, omdat een herhaling op dezelfde manier zou mislukken. Elke bezorging heeft een time-out van 5 seconden.
• Bezorglog: Instellingen → Webhooklog toont statuscode en antwoordbericht van elke bezorging, met een knop om opnieuw te versturen.
• Bodysjablonen: een sjabloon vervangt de standaardenvelop, zodat een chattool of automatiseringsendpoint dat een eigen JSON-vorm verwacht bezorgingen kan ontvangen zonder tussenlaag.

Bezorgingen komen niet strikt in volgorde aan. Twee updates van dezelfde contactpersoon met enkele milliseconden ertussen kunnen in omgekeerde volgorde binnenkomen, dus ontdubbel op het event-id, laat je handler werken op typeId en recordId, en gebruik de timestamp van de payload en de recordversie.

Zo doe je je eerste API-aanroep

1. Maak een sleutel aan

   Open Instellingen → API-sleutels & connectoren, kies Toevoegen, kies Standaard API-sleutel, geef de sleutel een naam zoals ERP-sync, productie en kopieer hem. Hij wordt maar één keer getoond. De gids over API-sleutels behandelt verloop en rotatie.

2. Lees het schema

   Haal /api/v1/openapi op via het adres van je werkruimte en importeer het in Postman, Insomnia of een clientgenerator. Stuur daarna POST /api/v1/model/discover met {"search":"deal"} om het typeId van je deals te krijgen, en POST /api/v1/model/read met {"typeIds":["<deal-type-id>"]} om de velden, de faseopties en de schema-revision te zien.

3. Vraag op

   Stuur POST /api/v1/records/query met de header x-api-key en een body zoals {"typeId":"<deal-type-id>","filters":[{"fieldId":"system:updatedAt","operator":"inLastDays","value":{"kind":"decimal","value":"7","currency":null}}],"page":1,"pageSize":25} om de deals op te vragen die de afgelopen week zijn gewijzigd.

4. Schrijf

   Verplaats een deal naar een andere fase met POST /api/v1/records/mutate en {"expectedRevision":<revision>,"idempotencyKey":"move-acme-to-demo","mutation":{"action":"update","ref":{"typeId":"<deal-type-id>","recordId":"<deal-id>"},"expectedVersion":<version>,"fields":[{"fieldId":"<stage-field-id>","value":{"kind":"select","value":"<option-id>"}}]}}. Wat je gebruiker in de app kan, kan de sleutel via de API.

5. Abonneer

   Voeg een webhook toe voor Record bijgewerkt op de lijst Deals met een geheim, richt hem op je endpoint en controleer de eerste bezorging onder Webhooklog.

Een onjuiste, verlopen of verwijderde sleutel krijgt HTTP 401. Een sleutel waarvan de eigenaar op Inactief is gezet, krijgt 403.

API-sleutels en rechten

Sleutels horen bij de gebruiker die ze heeft aangemaakt en handelen met de huidige rol van die gebruiker. Er zijn geen aparte API-gebruikers en geen scopes per sleutel, dus een sleutel kan niet tot alleen lezen worden beperkt. Moet een integratie alleen deals lezen, maak de sleutel dan aan onder een lid van wie de rol alleen dat toestaat. In Customermates Cloud is dat lid een betaalde gebruiker zoals elke andere.

Sleutels aanmaken vraagt om Leestoegang Alle en Aanmaken op de rij API en webhooks van een rol. Een nieuwe aangepaste rol begint zonder die rechten, dus standaard maken alleen beheerders sleutels aan. Dezelfde machtiging opent ook elke webhook in de werkruimte, wat goed is om te weten voordat je het recht uitdeelt. Om alle sleutels van iemand die vertrekt te stoppen, zet je het lid op Inactief. Ook als je Leestoegang Alle op API en webhooks uit hun rol haalt, stoppen hun sleutels.

MCP: de API voor AI-clients

Het MCP-endpoint op /api/v1/mcp geeft een externe AI-client 59 tools over dezelfde records, inbox en webhooks. Claude en ChatGPT verbinden via OAuth als eigen connector; Claude Code, Codex, Cursor en Gemini gebruiken een API-sleutel. De client, zijn model en zijn abonnement blijven van jou. Semantisch zoeken kan in Customermates Cloud nog wel meetellen voor het Mate-gebruik. De MCP-gids noemt elke tool.

Mate, de assistent in Customermates Cloud, is een aparte functie. Mate draait op gehoste AI-credits en heeft geen API-sleutel nodig. Zelf gehoste installaties hebben MCP maar geen Mate.

Wat de API niet doet

• Geen PUT of PATCH op records. Elke recordwijziging is een POST naar /api/v1/records/mutate.
• Geen OR tussen filterregels. Filterregels worden met AND gecombineerd. Voor OR draai je twee query's of gebruik je de operator in op één veld.
• Geen gepubliceerd verzoekquotum. Een drukke werkruimte antwoordt met 429 en een Retry-After-header. Splits bulktaken in batches van 100.
• Geen CSV-exportendpoint en geen export van het hele account. De app importeert Excel-, CSV- en JSON-bestanden en exporteert XLSX en JSON, steeds één lijst. Alles wat groter is, loopt via je eigen API-script.
• Geen inbox en geen Mate bij zelf hosten. De REST-recordroutes, webhooks en MCP werken daar; de berichtenroutes vragen om Customermates Cloud op Pro of hoger.

Buiten het pad /api/v1 wordt geen overgangsperiode voor achterwaartse compatibiliteit beloofd, dus behandel het huidige OpenAPI-document als het contract en test ertegen.

Hoe andere CRM's API-gebruik meten

Customermates publiceert deze pagina. Verificatiedatum: 8 oktober 2026. De cijfers hieronder komen uit de eigen documentatie van elke leverancier; ze veranderen, dus volg de links voordat je erop plant.

Kies HubSpot of Zoho CRM als je een gratis gehost abonnement met API-toegang wilt en je integratie binnen hun gepubliceerde aanroeplimieten past. Kies Pipedrive als een dagbudget dat meegroeit met abonnement en aantal gebruikers bij je volume past. Kies EspoCRM als je een zelf gehoste open-source CRM wilt met aparte API-gebruikers en hun eigen rollen. Customermates past bij een klein team dat de record-API, webhooks en een MCP-endpoint voor AI-clients wil tegen de prijs van het CRM zelf, met een AGPL-kern die het zelf kan hosten. Het past niet als je scopes per sleutel nodig hebt of, in Customermates Cloud, een API-gebruiker die niet als betaalde gebruiker meetelt.

Wat het kost

Voor API-toegang geldt geen toeslag. Een team van drie op Starter betaalt € 36 per maand en krijgt REST, webhooks en MCP. Hetzelfde team op Pro betaalt € 87 en krijgt de gecombineerde inbox en de bijbehorende berichtenroutes erbij. De open-sourceeditie zelf hosten kost niets aan licentiekosten; je draait de server zelf. Er wordt maandelijks gefactureerd, zie de prijzen. Bouw je flows in n8n, dan is n8n een apart product met eigen abonnementen; de n8n-gids laat de HTTP Request-instelling zien.