De Leads-API in het kort

Wat de publieke Leads-API doet, hoe authenticatie werkt en waar je een API-sleutel aanmaakt.

Alleen eigenaren/beheerders

Doel

Met de Leads-API zet een externe website of een formulier-backend een aanvraag rechtstreeks in Plenno, in plaats van hem per e-mail door te sturen. De aanvraag verschijnt direct in de pijplijn, met dezelfde opvolging als een aanvraag die via het Plenno-websiteformulier binnenkomt.

Dit artikel geeft het overzicht. De andere artikelen in deze categorie gaan in op de velden en PATCH (Een aanvraag aanmaken en bijwerken), live/testsleutels (Live- en testsleutels), foutcodes en limieten (Foutcodes en limieten) en uitgaande webhooks (Webhooks instellen en beveiligen).

Vooraf nodig

Je bent eigenaar, of teamlid met het lidtype Ontwikkelaar.
Ontwikkelaarsfuncties staat aan in de instellingen van de organisatie. Een eigenaar zet dit aan; zonder deze schakelaar is het menu-item niet zichtbaar, ook niet voor een eigenaar zelf.

Endpoints

POST  https://app.plenno.nl/api/v1/leads
PATCH https://app.plenno.nl/api/v1/leads/{id}

POST maakt een nieuwe aanvraag aan. PATCH werkt een aanvraag bij die je eerder zelf via deze API hebt aangemaakt. Beide accepteren uitsluitend Content-Type: application/json.

Stap 1 — open API-sleutels

Ga naar Instellingen → Integraties → API-sleutels (websiteformulieren).

Stap 2 — maak een sleutel aan

Geef de sleutel een herkenbare naam (bijvoorbeeld "website offerteformulier") en kies Live of Test — zie Live- en testsleutels voor het verschil. De volledige sleutel wordt één keer getoond, direct na het aanmaken. Bewaar hem meteen: Plenno kan hem daarna niet opnieuw laten zien. Raak je hem kwijt, maak dan een nieuwe aan en trek de oude in.

Authenticatie

Elke aanroep stuurt de sleutel mee als bearer-token:

Authorization: Bearer pln_live_xxxxxxxx_...

De sleutel bepaalt zelf bij welk bedrijf de aanvraag hoort. Je stuurt dus nooit een bedrijfs-, account- of gebruikers-ID mee in de aanvraag zelf; dat wordt geweigerd (zie Foutcodes en limieten).

Nooit in de browser. Zet de sleutel nooit in de JavaScript of de HTML van je website. Iedere bezoeker kan die dan uitlezen en aanvragen in jullie Plenno zetten. De aanroep hoort van je server (PHP, Node, een formulier-plugin, een workflow-tool) naar Plenno te gaan. De API ondersteunt daarom bewust geen CORS: een browser kan hem niet rechtstreeks aanroepen, ook niet per ongeluk.

Als het niet lukt

Zie je Integraties niet in Instellingen? Vraag een eigenaar om Ontwikkelaarsfuncties aan te zetten, of om jou het lidtype Ontwikkelaar te geven.
Krijg je op elke aanroep 401 unauthorized? Controleer of de sleutel volledig en ongewijzigd is overgenomen, en of hij niet is ingetrokken.

Let op

Trek een sleutel in zodra hij niet meer gebruikt wordt, of zodra je vermoedt dat hij gelekt is. Dat werkt direct — de sleutel weigert vanaf dat moment elke aanroep.

Vervolg

Lees Een aanvraag aanmaken en bijwerken.