Een websiteformulier koppelen via de publieke API

Laat je website server-side een nieuwe aanvraag en deal in Plenno maken, zonder dubbele inzendingen bij een retry.

Alleen eigenaren/beheerders

Doel

Je laat een formulier op je website een nieuwe aanvraag naar Plenno sturen. Plenno maakt bij die aanvraag automatisch een deal in de eerste actieve fase van het actieve Verkoopproces.

Vooraf nodig

Staan de integraties nog niet in je menu? Ga dan naar Instellingen en zet Ontwikkelaarsfuncties aan.

Ontwikkelaarsfuncties aanzetten in Instellingen

Ga daarna naar Instellingen → Integraties → API-sleutels (websiteformulieren). Geef de sleutel een herkenbare naam, kies Test zolang je het formulier uitprobeert en kies API-sleutel aanmaken. Gebruik pas een Live-sleutel wanneer het echte formulier klaar is.

Een veilige afgekorte Test-API-sleutel voor websiteformulieren

De sleutel hoort bij je eigen organisatie. Plenno bepaalt de organisatie aan de hand van de API-sleutel; stuur daarom geen organisatie-ID vanuit het formulier mee.

Gebruik de sleutel alleen server-side. Zet hem in een secret of omgevingsvariabele op je server. Plaats de sleutel nooit in browser-JavaScript, HTML of een openbare repository.

Gebruik in voorbeelden en testdocumentatie altijd een duidelijke placeholder, bijvoorbeeld <PLENNO_API_KEY>. Neem nooit een echte API-sleutel op.

Endpoint

Stuur iedere inzending als een POST-request naar:

https://app.plenno.nl/api/v1/leads

Gebruik een unieke external_id

Geef iedere nieuwe formulierinzending een unieke external_id. Bewaar die waarde aan de kant van je website en gebruik bij een retry exact dezelfde external_id.

Maak alleen een nieuwe external_id wanneer de bezoeker echt een nieuwe inzending doet. Zo kan een timeout of herhaalde webhook niet per ongeluk een tweede aanvraag en deal maken.

Antwoorden van de API

Status	Betekenis	Wat doe je?
`201`	Nieuwe aanvraag en deal aangemaakt	Verwerk de inzending als geslaagd
`200`	Dezelfde `external_id` was al verwerkt	Verwerk de retry als geslaagd; er is geen dubbele aanvraag of deal gemaakt
`410`	De oorspronkelijke aanvraag bij deze `external_id` is verwijderd	Bewaar de uitkomst; gebruik alleen bij een echt nieuwe inzending een nieuwe `external_id`

Een 410 is dus geen reden om dezelfde inzending opnieuw onder een andere external_id te sturen. Dat zou alsnog een nieuwe aanvraag en deal maken.

Resultaat

Een geldige nieuwe inzending staat onder Aanvragen. De automatisch aangemaakte deal staat in de eerste actieve fase van het actieve Verkoopproces.