Teamleader API koppelen aan je website.

Teamleader Focus is een CRM met offertes, facturatie, projecten en urenregistratie eromheen, gemaakt in Gent en veel gebruikt in het Nederlandse en Belgische mkb.

Het verschil met een puur verkoop-CRM is dat de hele keten erin zit: van eerste contact tot factuur. Voor een website betekent dat iets praktisch: een aanvraag die binnenkomt kan meteen op de goede plek in die keten worden gezet, in plaats van in een mailbox te belanden waar iemand hem overtypt.

De API is versie 2 en werkt met JSON. Aanmelden gaat met OAuth 2.0: je registreert een integratie in de Marketplace van Teamleader en krijgt een client id en een secret.

Daarmee haalt de koppeling een access token op, dat een uur geldig is. Daarna vraag je met het refresh token een nieuw aan. Die cyclus hoort in de koppeling te zitten, want anders werkt hij alleen in het uur waarin hij is gebouwd.

Wij zetten de sleutels op de server. Het formulier op je site praat met je eigen server, en die met Teamleader.

In stappen:

1. We registreren een integratie op de bouwpagina van de Teamleader Marketplace, met de rechten die de koppeling nodig heeft en het adres waar Teamleader na het aanmelden naar terugstuurt. Dat adres moet precies overeenkomen met wat de koppeling meestuurt.
2. Iemand met een account in jullie Teamleader geeft de integratie eenmalig toegang. Teamleader stuurt dan een code terug die 10 minuten geldig is en één keer kan worden ingewisseld voor een access token en een refresh token.
3. Met users.me controleren we of de koppeling in het goede account zit.
4. We testen met een paar aanvragen en kijken in de pijplijn of contact, bedrijf en deal op de goede plek staan, met de bron erbij.
5. Na de livegang blijft het refresh token werken tot iemand de toegang intrekt of de integratie verwijdert. Elk refresh token is maar één keer bruikbaar, dus de koppeling bewaart na elke vernieuwing het nieuwe paar.

De route die wij standaard bouwen: een aanvraag op je site maakt of vindt het contact, koppelt het aan het bedrijf als dat er is, en maakt er een deal bij in de fase die jij hebt gekozen.

Daar zetten we de bron bij: de pagina, de campagne, de zoekterm. Dat is wat later de vraag beantwoordt welke advertentie klanten oplevert en niet alleen leads. Hoe we die meting inrichten staat bij Data & Tracking.

Bestaat het contact al, dan koppelen we eraan. Dat is geen detail: een CRM met drie keer dezelfde persoon erin is een CRM waar niemand meer op vertrouwt, en het gebeurt vanzelf zodra een formulier blind aanmaakt.

Teamleader telt aanvragen in een glijdend venster van een minuut. Elk antwoord vertelt met x-ratelimit-limit hoeveel er per minuut mogen, met x-ratelimit-remaining hoeveel er nog over zijn en met x-ratelimit-reset wanneer je weer verder kunt. Wie eroverheen gaat krijgt een 429. Voor een formulier is dat zelden een probleem, voor een eerste synchronisatie van een heel adresboek wel.

De API werkt anders dan je van REST gewend bent. Elke handeling heeft een eigen adres, zoals contacts.list of contacts.add, en alles gaat als POST met JSON. Voor een synchronisatie haal je met updated_since alleen op wat sinds de vorige keer is gewijzigd.

De fout die de meeste schade doet zit in bijwerken. Lijsten zoals tags, adressen en eigen velden worden bij een update in hun geheel vervangen: stuur je alleen de nieuwe waarde mee, dan verdwijnen de andere. Voor eigen velden zet je custom_fields_update_strategy op partial, en voor tags gebruik je de aparte handelingen contacts.tag en contacts.untag.

De andere kant op kan ook. Met webhooks meldt Teamleader wanneer er iets verandert, bijvoorbeeld dat een offerte is verstuurd of een factuur is betaald.

Daarmee kun je een besloten deel op je site bouwen waar een klant zijn offertes, projecten of facturen terugvindt. Voor een dienstverlener met terugkerende klanten scheelt dat een stapel mails.

Begin daar niet mee. Zet eerst de aanvraagkant goed neer en kijk daarna of een portaal genoeg oplevert; het is een apart traject met een eigen ontwerp en eigen vragen over wie wat mag zien.

Op WordPress bouwen we het formulier in de opmaak van je site, zonder een formulierplugin die zijn eigen stijl meebrengt. Bij het versturen gaat de aanvraag naar de server, die het contact zoekt of aanmaakt en de deal erbij zet. Lukt dat een keer niet, dan blijft de inzending bewaard en gaat hij later alsnog door, zodat er geen lead verloren gaat.

Op een maatwerksite in Next.js met Payload staat dezelfde logica in een eigen serverroute, en daar past ook het klantportaal bij dat met webhooks wordt bijgewerkt.

Werk je met HubSpot in plaats van Teamleader, dan gaat de koppeling op dezelfde manier maar met een andere aanmelding; zie de pagina over HubSpot.