Wat is de Cirqll API?
Een API is de voordeur van een systeem voor andere software. Waar jij in Cirqll klikt en typt, stuurt een ander systeem via de API een verzoek en krijgt het gegevens terug, of maakt het iets aan.
De Cirqll API is een REST API die werkt met JSON en OAuth2. Cirqll noemt webhooks als derde bouwsteen: in plaats van steeds te vragen of er iets veranderd is, krijgt je koppeling een seintje zodra er iets gebeurt. De technische documentatie staat openbaar op docs.api.cirqll.nl.
Een paar praktische kenmerken uit die documentatie (peildatum 6 oktober 2026):
- Alle tijden zijn in UTC, in ISO 8601-formaat. Handig om te weten als je afspraken of deadlines naar een ander systeem zet.
- Je kunt resultaten pagineren, filteren en sorteren, gerelateerde gegevens in één keer meeladen en alleen de velden opvragen die je nodig hebt.
- De API ondersteunt ETag-headers, zodat je ongewijzigde gegevens niet steeds opnieuw hoeft op te halen.
Welke gegevens kun je via de Cirqll API ophalen en bijwerken?
Vrijwel alles waar je dagelijks mee werkt. De documentatie beschrijft onder meer deze onderdelen:
- Relaties en contactpersonen: de klanten en de mensen bij die klanten.
- Kansen, opdrachten en contracten: het financiële deel, van lopende deal tot afgesloten contract met start- en einddatum.
- Taken, afspraken, to-do's en notities: het werk rondom je klanten.
- E-mails en templates.
- Vrije velden: de eigen velden die je in Cirqll hebt aangemaakt, met hun categorie (bijvoorbeeld relatie of financieel), het type veld en de keuzeopties.
- Gebruikers, rollen en webhooks.
Voor de meeste onderdelen kun je gegevens niet alleen lezen, maar ook aanmaken, wijzigen en verwijderen. Wat een koppeling mag, hangt af van de rechten van de gebruiker waarmee je hem koppelt. Dat is een voordeel: je kunt een koppeling precies zoveel ruimte geven als hij nodig heeft.
Vooral die vrije velden zijn interessant. Veel bedrijven leggen daarin vast waar een klant vandaan komt of welke productgroep bij een kans hoort. Via de API komen die velden gewoon mee, zodat je er later op kunt rapporteren of automatiseren.
Waar zet je de Cirqll API voor in?
In de praktijk zien we drie soorten toepassingen terugkomen.
1. Rapportage en analyse
Je haalt kansen, afspraken en contracten op en zet ze in een datamodel. Daarop bouw je in Power BI een dashboard met trends, conversie per fase en prestaties per verkoper. Hoe dat stap voor stap gaat, lees je in Cirqll koppelen aan Power BI. Waarom je naast de rapportage in Cirqll zelf een tweede laag wilt, staat in Meer uit je Cirqll-rapportage halen met Power BI.
2. Automatisering
Een webhook meldt dat er een kans van fase wisselt of dat er een afspraak bijkomt, en een automatiseringsplatform doet de rest: een taak klaarzetten, een collega een seintje geven, een bevestiging versturen. Vijf concrete voorbeelden vind je in Cirqll en Make.com: 5 automatiseringen.
3. Gegevens synchroon houden met andere systemen
Leads van je website die direct als relatie in Cirqll komen, of klantgegevens die gelijk blijven met je boekhoudpakket. Daarmee voorkom je overtypen en dubbele invoer. Let wel: bij synchroniseren in twee richtingen moet je vooraf afspreken welk systeem leidend is, anders overschrijven ze elkaar.
Wat heb je nodig voor een koppeling met de Cirqll API?
Of je nu zelf bouwt of iemand inschakelt, deze vijf dingen moeten geregeld zijn.
- Een OAuth2-verbinding. Cirqll werkt alleen met OAuth2. Je koppeling vraagt via het autorisatiescherm van Cirqll toestemming, en krijgt daarna een toegangstoken en een refresh-token. Daarvoor heb je een callback-URL nodig: het adres waar Cirqll de gebruiker na het inloggen naartoe stuurt. Platforms als Make regelen dat voor je.
- Tokens die automatisch ververst worden. Een toegangstoken van Cirqll is 15 dagen geldig, een refresh-token 30 dagen. Ververst je koppeling die niet op tijd, dan stopt hij gewoon, vaak zonder dat iemand het merkt. Dit is in de praktijk de meest voorkomende reden dat een zelfgebouwde koppeling na een paar weken "ineens" niet meer werkt.
- Een gebruiker met passende rechten. Koppel niet via het account van de eigenaar, maar via een gebruiker die alleen kan wat de koppeling nodig heeft. Een rapportagekoppeling hoeft niets te kunnen verwijderen.
- Rekening houden met de limiet. Cirqll staat maximaal 100 verzoeken per minuut per client toe. Daarboven krijg je een foutmelding (429 Too Many Requests) en moet je een minuut wachten. Elke response vertelt via headers hoeveel verzoeken je nog over hebt. Bij een eerste grote import of een scenario dat door honderden records loopt, bouw je daarom pauzes of batches in.
- Een plek waar de koppeling draait. Dat kan een automatiseringsplatform zijn zoals Make, Power BI zelf, of een eigen script of cloudfunctie. Wil je historie bewaren of Cirqll combineren met andere bronnen, dan is een eigen database als tussenlaag vaak de verstandigste plek. Dat is data engineering-werk.
Daarnaast: er gaan persoonsgegevens door de koppeling. Leg vast welke gegevens waarheen gaan en kies waar mogelijk voor opslag in de EU.
Zelf bouwen, Zapier, Make of een kant-en-klare connector?
Je hoeft niet altijd zelf tegen de API aan te programmeren. Er zijn grofweg vier routes.
- Zapier. Cirqll biedt zelf een Zapier-koppeling aan, met triggers voor onder meer nieuwe klanten, taken, notities en contracten. Prima voor eenvoudige "als dit, dan dat"-stappen.
- Make.com. Op het moment van schrijven is er in Make geen kant-en-klare Cirqll-app, dus je werkt met een webhook-module en een HTTP-module met OAuth2. Iets meer inrichting, maar je kunt alles gebruiken wat de API biedt, inclusief meerdere stappen, voorwaarden en foutafhandeling.
- Een kant-en-klare connector voor rapportage. Voor Power BI hoef je de koppeling niet zelf te bouwen. Met de Cirqll Power BI Connector komen de tabellen klaar voor gebruik binnen, met een dashboardtemplate erbij.
- Zelf ontwikkelen. Een eigen script of applicatie geeft de meeste vrijheid, maar dan ben je ook zelf verantwoordelijk voor tokens, limieten, foutafhandeling en onderhoud.
Onze vuistregel: kies de eenvoudigste route die je vraag beantwoordt, en bouw pas zelf als de standaardroutes echt tekortschieten.
Voorbeeld: van vraag naar werkende koppeling
Een fictief voorbeeld om het concreet te maken. Een groothandel met vier accountmanagers werkt in Cirqll en wil twee dingen: elke maandag een overzicht van contracten die binnen 60 dagen aflopen, en een maandrapport met gewonnen kansen per herkomst van de klant.
Zo pakken ze het aan:
- Vraag scherp maken. Welke contracten tellen mee? Wie krijgt het overzicht? Wat betekent "gewonnen" precies?
- Velden controleren. De herkomst staat in een vrij veld bij de relatie. Via de API blijkt dat veld bij een deel van de relaties leeg te zijn, dus dat wordt eerst aangevuld.
- Route kiezen. Het contractoverzicht wordt een Make-scenario dat elke maandag de contracten opvraagt, filtert op einddatum en per accountmanager een mail of taak klaarzet. Het maandrapport komt in Power BI.
- Verbinding inrichten. Een aparte Cirqll-gebruiker met alleen leesrechten voor de rapportage, en een OAuth2-verbinding die tokens automatisch ververst.
- Testen en controleren. Komen het aantal contracten en de totalen overeen met wat ze in Cirqll zien? Pas dan gaat het live, met een melding als een run mislukt.
Resultaat: geen handmatige lijstjes meer op maandag, en een maandrapport waarin iedereen naar dezelfde cijfers kijkt.
Hulp bij je Cirqll API-koppeling
Wil je Cirqll koppelen zonder zelf met tokens, limieten en foutafhandeling bezig te zijn? Bekijk de Cirqll Power BI Connector en het dashboardtemplate, lees wat we doen op het gebied van workflow automation en dashboarding, of bekijk welke andere koppelingen we maken. Weet je nog niet waar je moet beginnen, lees dan eerst Cirqll automatiseren: welke handmatige taken je als eerste wegneemt.