API v1.1: aanvragen, deals en activiteiten

Koppel n8n, Make of je eigen systeem: lees en wijzig aanvragen en deals, voeg opvolgtaken toe en geef je API-sleutel alleen de benodigde rechten.

Alleen eigenaren/beheerders

Met API v1.1 kan een koppeling meer dan alleen een aanvraag insturen. Je kunt aanvragen en deals opvragen en bijwerken, activiteiten plannen of afronden en teamleden en verkoopprocessen opvragen. De basis is https://app.plenno.nl/api/v1.

Gebruik de API vanaf je server of workflow-tool. Zet een API-sleutel nooit in de HTML of JavaScript van je website. Voor een websiteformulier blijft POST /leads ongewijzigd werken; zie Een aanvraag aanmaken en bijwerken.

Een sleutel met de juiste rechten

Ga naar Instellingen → Integraties → API-sleutels. Je hebt toegang tot Integraties nodig en Ontwikkelaarsfuncties moet aanstaan. Kies bij het aanmaken Live of Test, en onder Rechten wat de koppeling mag doen.

Recht (scope)	Wat je koppeling mag
`leads:create`	Aanvragen insturen en uitsluitend de zelf aangemaakte aanvragen bijwerken met de oorspronkelijke velden. Dit staat standaard aan.
`leads:read`	Aanvragen lezen.
`leads:write`	Aanvragen insturen en aanvragen van het bedrijf bijwerken, inclusief fase, verantwoordelijke en opvolgdatum.
`deals:read` / `deals:write`	Deals lezen / bestaande deals bijwerken.
`activities:read` / `activities:write`	Activiteiten lezen / toevoegen en bijwerken.
`metadata:read`	Actieve teamleden, verkoopprocessen en fases opvragen.

Geef alleen de benodigde rechten. Schrijfrecht geeft geen apart leesrecht: wil je eerst een lijst ophalen, kies dan ook het bijbehorende leesrecht. Bestaande sleutels houden leads:create; ze krijgen niet automatisch ruimere toegang. Rechten kun je niet achteraf wijzigen. Maak daarvoor een nieuwe sleutel en trek de oude na het overzetten in.

Elke aanroep gebruikt Authorization: Bearer <jouw sleutel>. Bij een JSON-body stuur je ook Content-Type: application/json. De sleutel bepaalt je bedrijf en de modus; stuur geen organisatie- of gebruikers-ID mee om een ander bedrijf te kiezen.

Beschikbare endpoints

Alle paden hieronder komen na /api/v1.

Methode en pad	Doel
`GET /me`	Controleer de API-versie, sleutelmodus en rechten.
`POST /leads`	Een aanvraag insturen.
`GET /leads` en `GET /leads/{id}`	Aanvragen lezen.
`PATCH /leads/{id}`	Een aanvraag bijwerken.
`GET /deals` en `GET /deals/{id}`	Deals lezen.
`PATCH /deals/{id}`	Een bestaande deal bijwerken.
`GET /activities`	Activiteiten lezen.
`POST /activities` en `PATCH /activities/{id}`	Een activiteit toevoegen of bijwerken.
`GET /users`	Actieve teamleden: ID en naam.
`GET /pipelines` en `GET /pipelines/{id}/stages`	Actieve verkoopprocessen en fases.

Er zijn geen DELETE-endpoints. De API maakt geen CRM-relaties, offertes, facturen of werkbonnen aan en verstuurt geen e-mail of WhatsApp. Een activiteit van type email registreert werk; die verstuurt geen bericht.

Aanvragen en deals bijwerken

Met leads:write kun je naast contactgegevens ook stage_id, assigned_user_id en reminder_at wijzigen. Gebruik de IDs uit de metadata-endpoints. Naar een verloren aanvraagfase verplaatsen wist de geplande opvolging. De verantwoordelijke wijzigen neemt passende open deals mee, volgens dezelfde regels als in de app.

Met deals:write kun je title, stage_id, status (open, won, lost), lost_reason en assigned_user_id wijzigen. Fase en status staan los van elkaar: de fase wijzigen markeert de deal niet automatisch als gewonnen of verloren. Bedrag, sluitdatum en koppelingen wijzig je in Plenno zelf.

Een wijziging door een koppeling verschijnt in de tijdlijn als Via <naam van de sleutel>. Relevante statuswijzigingen gebruiken dezelfde webhookregels als de app.

Een activiteit plannen

Stuur bij POST /activities een subject, een koppeling aan minstens één aanvraag (lead_id), deal (deal_id) of bedrijf (company_id) en een due_at. type is call, meeting, email of task. assigned_user_id is optioneel. Voor een al uitgevoerd contactmoment kun je completed: true gebruiken; dan is due_at niet verplicht.

{
  "subject": "Offerte telefonisch opvolgen",
  "type": "call",
  "due_at": "2026-11-02T10:00:00+01:00",
  "lead_id": "00000000-0000-4000-8000-000000000001"
}

Vervang het voorbeeld-ID door het ID van een aanvraag die zichtbaar is voor je sleutel. Een tijdstip bevat altijd een tijdzone. Een activiteit krijgt geen eigen herinneringsmelding; voor een melding gebruik je een herinnering op de aanvraag.

Lijsten en gelijktijdige wijzigingen

Een lijst geeft data en next_cursor. Gebruik limit (1–100, standaard 50). Is next_cursor niet null, vraag dan de volgende pagina op met cursor en dezelfde filters. Lijsten staan op aanmaakmoment, nieuwste eerst. Voor wijzigingen sinds een vorige synchronisatie gebruik je updated_since.

Bij één resource krijg je een ETag-header. Stuur die mee als If-Match bij een PATCH die op eerder gelezen gegevens is gebaseerd. Krijg je 409 conflict, dan heeft iemand de gegevens inmiddels gewijzigd: lees opnieuw en bepaal opnieuw wat je wilt aanpassen. Zonder If-Match wint de laatste schrijver.

Een ontbrekend recht geeft 403 insufficient_scope. Bij 429 wacht je de Retry-After-tijd. De body mag maximaal 16 kB zijn. Zie Foutcodes en limieten.

Eerst testen

Een testsleutel ziet uitsluitend testaanvragen en hun activiteiten. Testactiviteiten verschijnen niet in je echte Vandaag-overzicht of dagelijkse samenvatting. Testsleutels krijgen geen deals: de lijst is leeg; een echte deal wijzigen geeft 404. Metadata lezen is wel mogelijk. Een livesleutel ziet uitsluitend livegegevens.

Dit is de API-scheiding. Als je daarna zelf in Plenno documenten of een deal bij een testaanvraag maakt, kunnen die wel meetellen. Zie Live- en testsleutels.