Waarom dit anders is dan "we hebben ook een API"
Veel diensten hebben een API die precies één ding kan: inzendingen ophalen. Dat is genoeg voor een koppeling naar een CRM en verder niets.
Wij zijn ervan uitgegaan dat de aanroeper een agent kan zijn die zelf nadenkt. Dat stelt andere eisen. Een agent moet kunnen **ontdekken** wat hij mag, hij moet het **schema** van een formulier kunnen lezen voordat hij iets instuurt, en hij moet **opnieuw kunnen proberen** zonder dubbele inzendingen te veroorzaken.
Vandaar drie dingen die je zelden ziet:
- **/api/v1/me** vertelt een sleutel wat hij mag en waar hij tegen praat. Geen documentatie doorspitten om erachter te komen dat je scope ontbreekt.
- **Het formulierschema is machineleesbaar**, inclusief veldtypen, verplichte velden, geldige optiewaarden en validatieregels. Een agent weet daardoor vooraf wat er wordt geaccepteerd.
- **Idempotency-Key** op het insturen. Een netwerktimeout waarbij de inzending wél aankwam levert anders een tweede inzending op, en dat merk je pas als dezelfde klant twee keer in de lijst staat.
Beginnen
Elke sleutel begint met frm_live_. Stuur hem mee als Bearer-token.
# Wat mag deze sleutel?
curl -H "Authorization: Bearer frm_live_..." \
https://formulira.com/api/v1/me
# Het schema van een formulier lezen
curl -H "Authorization: Bearer frm_live_..." \
https://formulira.com/api/v1/forms/aanvraag-demo
# Een formulier aanmaken uit een vragenset
curl -X POST -H "Authorization: Bearer frm_live_..." \
-H "Content-Type: application/json" \
-d '{"name":"Klantonderzoek","fields":[
{"key":"naam","type":"short_text","label":"Wat is uw naam?","required":true},
{"key":"cijfer","type":"scale","label":"Hoe tevreden bent u?","validation":{"min":1,"max":10}}
]}' \
https://formulira.com/api/v1/formsHet formulier wordt als concept aangemaakt en meteen naar alle actieve talen vertaald. Publiceren is een aparte aanroep, zodat een agent nooit per ongeluk iets live zet.
Scopes
Een sleutel krijgt precies wat hij nodig heeft. Een integratie die antwoorden ophaalt hoeft geen formulieren te kunnen publiceren.
| Scope | Wat het toestaat |
|---|---|
| forms:read | Formulieren en hun veldschema lezen |
| forms:write | Formulieren aanmaken, wijzigen en publiceren |
| submissions:read | Reacties lezen — dit is de scope met persoonsgegevens |
| submissions:write | Reacties indienen namens een invuller |
| invitations:write | Persoonlijke uitnodigingslinks aanmaken |
| webhooks:write | Webhooks beheren |
Wat er verder in zit
Webhooks met handtekening
Pollen is traag en duur. Registreer een URL en krijg een duw zodra er een inzending binnenkomt, met een HMAC-handtekening zodat je kunt vaststellen dat het bericht van ons komt en onderweg niet is aangepast.
Sleutel per formulier
Een sleutel kan aan één formulier worden gebonden. Dan komt hij nergens anders bij, ook niet als hij het id van een ander formulier kent.
Rate limit per sleutel
Duizend verzoeken per rollend uur, geteld per sleutel en niet per IP-adres. Twee integraties op hetzelfde kantoornetwerk zitten elkaar dus niet in de weg.
Alles in het audit-log
Elke schrijfactie via de API komt in het audit-log met de sleutel erbij. Bij een vraag achteraf is te zien welke integratie wat heeft gedaan.