Een aanvraag aanmaken en bijwerken

Doel

Dit artikel beschrijft de velden van POST /api/v1/leads en PATCH /api/v1/leads/{id}, met werkende voorbeelden. Zie De Leads-API in het kort voor endpoint en authenticatie.

Velden bij het aanmaken (POST)

Veld	Type	Verplicht	Max	Toelichting
name	string	ja	120	Naam van de aanvrager.
email	string	ja*	160	Geldig e-mailadres.
phone	string	ja*	40	Telefoonnummer, vrije notatie.
message	string	nee	4000	Het bericht uit het formulier.
company	string	nee	120	Bedrijfsnaam. Komt in een eigen, doorzoekbaar veld terecht — geen notitietekst.
address	string	nee	240	Adres.
source	string	nee	80	Waar de aanvraag vandaan komt, bv. website.
form	string	nee	120	Welk formulier, bv. offerte-aanvraag.
external_id	string	nee	128	Jouw eigen referentie. Zie Dubbele aanvragen voorkomen hieronder.
metadata	object	nee	25 velden	Extra context, bv. pagina, campagne, UTM's en gclid.
type	string	nee	40	Classificatie van de aanvraag. Zie hieronder.
tags	array	nee	10 items	Vrije labels, bv. ["website","whitepaper"].

* email of phone is verplicht — minstens één van de twee.

Regels

• metadata is plat: waarden mogen alleen tekst, een getal of true/false zijn. Geen geneste objecten of lijsten. Samen maximaal 4 kB. UTM-parameters (utm_source, utm_medium, utm_campaign, utm_content, utm_term) en gclid horen hier gewoon in thuis, als losse sleutels.
• external_id mag letters, cijfers en _ . : @ / + - bevatten. Geen spaties.
• tags mag maximaal 10 labels bevatten, elk maximaal 40 tekens.
• De hele aanvraagbody is maximaal 16 kB.
• Velden die niet in de tabel staan worden geweigerd (422 validation_error) — dat is opzet, zo merk je een typefout meteen in plaats van dat een veld stilzwijgend verdwijnt.

company — een eigen veld, geen automatisch CRM-bedrijf

company komt in een eigen, doorzoekbaar veld van de aanvraag terecht. Plenno maakt er nooit automatisch een CRM-bedrijf van: bij een net iets andere spelling van dezelfde klant zou dat een duplicaat opleveren. Wil je de aanvraag aan een bestaand of nieuw CRM-bedrijf koppelen, dan doe je dat zelf in Plenno.

type en tags — bepaalt of er een verkoopkans komt

Zonder type (of met "type": "lead") verschijnt een aanvraag als lead ÉN als verkoopkans (deal) in je pijplijn. Stuur je een ander type mee, dan slaat Plenno de automatische verkoopkans over: de aanvraag komt gewoon binnen en is terug te vinden, maar verschijnt niet ongevraagd tussen je echte verkoopkansen.

type	Betekenis	Automatische verkoopkans
lead (of leeg)	Een gewone aanvraag/offerteverzoek	Ja
download	Bijvoorbeeld een whitepaper-download	Nee
application	Bijvoorbeeld een sollicitatie	Nee

type is vrije tekst (kleine letters, cijfers, _/-, max 40 tekens), geen vaste lijst. Alleen type = "lead" maakt automatisch een verkoopkans. tags is puur informatief.

Dubbele aanvragen voorkomen (external_id)

Stuur je bij elke aanvraag een eigen referentie mee in external_id, dan maakt Plenno gegarandeerd één aanvraag aan — ook als je formulier door een time-out of netwerkfout twee keer verstuurt.

• Eerste keer: HTTP 201, "created": true
• Elke volgende keer met dezelfde external_id: HTTP 200, "created": false, hetzelfde lead_id

Referenties zijn per bedrijf en per sleutel-modus (zie Live- en testsleutels): een live- en een testaanvraag mogen dezelfde external_id gebruiken zonder elkaar te blokkeren. Laat je external_id weg, dan levert elke aanroep een nieuwe aanvraag op.

Plenno onthoudt een external_id 90 dagen; daarna is de referentie weer vrij. Blijft een eerdere poging halverwege hangen (bijvoorbeeld door een afgebroken verbinding), dan krijg je heel even 409 duplicate_in_progress — na twee minuten kun je dezelfde external_id gewoon opnieuw aanbieden. Is de bijbehorende aanvraag daarna in Plenno verwijderd, dan krijg je 410 lead_deleted en maakt Plenno hem bewust niet opnieuw aan; gebruik dan een nieuwe external_id.

Voorbeeld 1 — een normale aanvraag

curl -X POST https://app.plenno.nl/api/v1/leads \
  -H "Authorization: Bearer pln_live_xxxxxxxx_VERVANG_DOOR_JE_EIGEN_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jan Jansen",
    "email": "jan@voorbeeld.nl",
    "phone": "0612345678",
    "message": "Ik wil graag meer informatie",
    "company": "Jansen Dakwerken",
    "source": "website",
    "form": "offerte-aanvraag",
    "external_id": "website-form-123456",
    "tags": ["website"],
    "metadata": {
      "page": "/diensten/seo",
      "campaign": "google-ads",
      "utm_source": "google",
      "utm_medium": "cpc",
      "gclid": "Cj0KCQjw..."
    }
  }'

Antwoord — HTTP 201

{
  "success": true,
  "lead_id": "7543de5d-bc88-4ea8-afe3-2696856157e5",
  "url": "https://app.plenno.nl/app/leads/7543de5d-bc88-4ea8-afe3-2696856157e5",
  "status": "Nieuw",
  "created": true,
  "mode": "live"
}

url is de directe link naar de aanvraag in Plenno. status is de naam van de fase waarin de aanvraag nu staat — die kan per Plenno-account verschillen, want fasen zijn zelf in te richten. mode is "live" of "test", afhankelijk van welke sleutel je gebruikte.

Voorbeeld 2 — een sollicitatie (type=application)

curl -X POST https://app.plenno.nl/api/v1/leads \
  -H "Authorization: Bearer pln_live_xxxxxxxx_VERVANG_DOOR_JE_EIGEN_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fatima El Amrani",
    "email": "fatima@voorbeeld.nl",
    "message": "Sollicitatie voor de functie Buitendienst",
    "external_id": "vacature-2026-08",
    "type": "application",
    "tags": ["sollicitatie", "buitendienst"]
  }'

Deze aanvraag komt binnen en is terug te vinden, maar levert geen automatische verkoopkans op.

Voorbeeld 3 — een download (type=download)

curl -X POST https://app.plenno.nl/api/v1/leads \
  -H "Authorization: Bearer pln_live_xxxxxxxx_VERVANG_DOOR_JE_EIGEN_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Piet de Vries",
    "email": "piet@voorbeeld.nl",
    "external_id": "whitepaper-onderhoudsplan-2026",
    "type": "download",
    "form": "whitepaper-onderhoudsplan",
    "metadata": { "utm_source": "linkedin", "utm_medium": "social" }
  }'

PATCH — een eerdere aanvraag bijwerken

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

Werkt een aanvraag bij die je eerder via deze API hebt aangemaakt. Dezelfde Authorization-header, dezelfde sleutel.

Bijwerkbare velden (allemaal optioneel — stuur alleen mee wat je wilt wijzigen):

Veld	Toelichting
name	Zelfde regels als bij aanmaken.
email	Zelfde regels als bij aanmaken.
phone	Zelfde regels als bij aanmaken.
address	Zelfde regels als bij aanmaken.
company	Vervangt de vrije bedrijfsnaam. Koppelt nooit aan een CRM-bedrijf.
message	Vervangt de volledige notitie van de aanvraag (geen samenvoeging).
tags	Vervangt de volledige labelset.

Niet bijwerkbaar (bewust): external_id (de idempotentiesleutel van het aanmaken), type (bepaalt of er ooit een verkoopkans is aangemaakt) en metadata/source/form (horen bij het aanmaakmoment).

Voorbeeld 5 — een bestaande aanvraag bijwerken

curl -X PATCH https://app.plenno.nl/api/v1/leads/7543de5d-bc88-4ea8-afe3-2696856157e5 \
  -H "Authorization: Bearer pln_live_xxxxxxxx_VERVANG_DOOR_JE_EIGEN_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0687654321",
    "message": "Klant belde terug: liever een offerte voor het hele pand.",
    "tags": ["website", "opgevolgd"]
  }'

Antwoord — HTTP 200

{
  "success": true,
  "lead_id": "7543de5d-bc88-4ea8-afe3-2696856157e5",
  "url": "https://app.plenno.nl/app/leads/7543de5d-bc88-4ea8-afe3-2696856157e5",
  "status": "Nieuw",
  "mode": "live"
}

Aanbevolen werkwijze

1. Verstuur vanaf je server, niet vanuit de browser.
2. Stuur altijd een external_id mee, zodat een retry nooit een duplicaat oplevert.
3. Bewaar het lead_id (of de url) uit het antwoord als je de aanvraag later wilt terugvinden of bijwerken.
4. Gebruik type om niet-sales-inzendingen (downloads, sollicitaties, …) uit je verkooppijplijn te houden — laat het gewoon weg voor een normale offerteaanvraag.

Vervolg

Lees Foutcodes en limieten voor het volledige overzicht van fout- en statuscodes.