Open je gepubliceerde formulier, klik op Delen, en kies het tabblad Aanvragen. De kaart daar geeft je alles wat je nodig hebt om de eerste aanroep te doen:
> Een niet-gepubliceerd formulier kan niet worden aangevraagd, en de fragmenten blijven uitgeschakeld totdat je publiceert. Veldsleutels
> worden bevroren bij de eerste publicatie — dat is wat je automatisering in staat stelt company_name een jaar later nog
> steeds aan te spreken. Zie Veldsleutels.
>
fields.list geeft elk veld terug van de huidige gepubliceerde versie van het formulier, met de sleutel om het aan te spreken,
de waardevorm die het aanneemt, en tot welk vak het behoort.
context: true markeert een verborgen veld. De waarde ervan komt in context, nooit in prefill; de
sleutel van een verborgen veld in prefill wordt geweigerd met UNKNOWN_FIELD_KEY.
calculated: true markeert een berekend veld. Het formulier berekent de waarde zelf, dus niemand kan er een versturen; je
leest hem terug onder zijn sleutel in answers.
prefillable: false markeert een veld waarvoor niemand een waarde kan opgeven: bestandsupload, handtekening, betaling,
afspraak boeken, en Documentenblokken. De ontvanger vult die vragen zelf in. Verborgen velden en berekende velden tonen ook{' '}
prefillable: false: verborgen velden nemen context aan, berekende velden nemen niets aan.
options toont de keuzes voor een keuzevraag. Stuur de sleutel van de optie, niet het label; het label is
er zodat je de keuze die je kent kunt koppelen aan de sleutel. Een matrix toont zijn rows en columns op
dezelfde manier.
type: "group", repeating: true, en een lijst van{' '}
members.
deliveryStatus is "queued" wanneer Formstep de uitnodiging mailt en "not_requested" wanneer je de
link zelf aflevert.
Drie verschillende dingen kunnen aan een aanvraag worden gekoppeld, en ze door elkaar halen is de meest voorkomende beginnersfout.
Beginantwoorden voor de zichtbare vragen, zodat de ontvanger controleert en corrigeert in plaats van vanaf nul te typen. Alles wat je al van hen weet hoort hier thuis — de bedrijfsnaam uit je CRM, het bedrag van de factuur, de antwoorden van vorig jaar.
Zet een vooraf ingevulde sleutel in readonly en de ontvanger ziet de waarde maar kan hem niet wijzigen. Gebruik dit voor de
feiten die ze bevestigen in plaats van aanleveren — het contractnummer, de afgesproken prijs. Vergrendelen is per aanvraag: het formulier
zelf blijft onaangeroerd, en hetzelfde veld is bij de volgende aanvraag weer vrij bewerkbaar.
Elke vergrendelde sleutel moet ook vooraf ingevuld zijn, en een vergrendeld verplicht veld moet vooraf worden ingevuld met iets niet-leegs — anders zou de ontvanger een formulier krijgen dat ze nooit zouden kunnen indienen, en weigert Formstep de aanroep in plaats van die val te creëren.
Vertrouwde waarden voor de verborgen velden van het formulier — een dossiernummer, een workflow-run-id, een bedrag. Context voedt variabelen, voorwaardelijke logica, berekende velden en e-mailtekst, komt onveranderd terug in de callback, en de ontvanger kan het niet aanpassen. Dat laatste is het verschil met het vullen van een verborgen veld via een URL op een openbare link, waar iedereen de querystring kan bewerken; aanvraaglinks negeren URL-queryparameters volledig. Contextwaarden moeten een string, getal of boolean zijn.
Context is niet vrij invoerbaar: elke sleutel moet een verborgen veld zijn op de gepubliceerde versie van het formulier, en elke andere
sleutel wordt geweigerd met UNKNOWN_FIELD_KEY. Administratie zonder verborgen veld, zoals een uitvoerings-id, hoort in{' '}
metadata.
Verborgen velden worden niet op het formulier getoond, maar een contextwaarde is niet geheim voor de ontvanger. Hij ziet hem overal waar
het formulier of de uitnodiging hem toont: een vermelding in de forminhoud of e-mailtekst,
of een zichtbare vraag die dat verborgen veld als standaardwaarde{' '}
gebruikt. In dat laatste geval ziet de ontvanger de contextwaarde vooraf ingevuld in die vraag en kan hij het antwoord bewerken. De
contextwaarde zelf blijft ongewijzigd. Een prefill voor de eigen sleutel van die vraag heeft voorrang boven de
standaardwaarde.
Je eigen administratie — een uitvoerings-id, een CRM-record-id. Het bereikt het formulier nooit, dus het kan niet in tekst worden gepiped of door logica worden gelezen; het rijdt gewoon mee en komt terug in elke callback en statusuitlezing.
Stuur waarden in de vorm die het type uit fields.list vraagt. Een verkeerde vorm komt terug als een
validatiefout die de sleutel, het verwachte type, en — voor keuzevragen — de waarden noemt die geaccepteerd zouden zijn.
Een Documentenblok geeft bestanden door aan de ontvanger. De aangeleverde bestanden zijn voor iedereen hetzelfde en blijven altijd staan; een aanvraag voegt bestanden toe voor die ene ontvanger, eronder — het eigen huurcontract van de klant, een kopie van een identiteitsbewijs om te controleren. Bytes reizen nooit mee in de API-aanroep zelf: upload eerst, verwijs daarna.
``` "documents": [ { "documentId": "kn7...", "name": "Your lease contract" }, { "documentId": "kn8..." } ] ```
name overschrijft de weergavenaam die bij de upload is opgeslagen. Heeft het formulier meer dan één documentenblok, dan wijs
je het doel aan met field, de veldsleutel van het blok (fields.list toont die, samen met de vaste documenten die
elke respondent al krijgt). De bestanden komen onder die vaste documenten te staan — een aanvraag voegt bestanden toe, hij vervangt er
nooit een. Eén upload kan door zoveel aanvragen worden aangehaald als je wilt — een prijslijst die je één keer uploadt, bedient
vijfhonderd aanvragen.
Limieten: alleen PDF en afbeeldingen, 25 MB per document, 100 MB per aanvraag (DOCUMENTS_TOO_LARGE), en ten hoogste 20
documenten per blok, de vaste documenten meegeteld (DOCUMENTS_TOO_MANY). De bestanden tellen mee voor je werkruimte-opslag en
komen vrij zodra de aanvragen die ernaar verwijzen buiten het bewaarvenster van het formulier vallen. De inzending registreert de lijst
die de ontvanger onder de veldsleutel van het blok te zien kreeg, dus de callback vertelt je precies welke bestanden deze persoon heeft
gekregen.
Geef test: true op om de hele bedrading uit te proberen vóór een echte run. Een testaanvraag is echt in alles wat telt voor
de bedrading: de link opent en kan worden afgerond, de callback vuurt zoals gewoonlijk, en{' '}
requests.get geeft de antwoorden terug. Wat hij nooit doet, is iemand of iets bereiken dat je achteraf zou moeten opruimen:
delivery ook zegt. Herinnering versturen{' '}
wordt er geweigerd, en hij verbruikt niets van je maandelijkse quotum.
"test": true, zodat je workflow kan vertakken of het event kan negeren.
requests.list{' '}
tenzij je includeTest: true opgeeft.
expiresAt om langer vraagt; de expiresAt in het antwoord zegt wanneer. Op
Free mag een workspace 10 testaanvragen per dag aanmaken. De volgende mislukt met RATE_LIMITED en reden{' '}
TEST_REQUEST_LIMIT_REACHED, en retryAfterMs zegt wanneer je het opnieuw kunt proberen. Pro en Business hebben
geen dagelijkse limiet.
Probeer het zelf in het deelvenster is deze modus met één klik: hij neemt het concept van het tabblad Handmatig over — vooraf invullen, vergrendelingen, context, callback, verloop — richt de aanvraag aan je eigen account, verstuurt geen e-mail, en geeft je de link om zelf te openen.
Elk abonnement heeft één maandelijks quotum dat door beide kanalen wordt gedeeld: een inzending via een deellink
verbruikt één eenheid, en dat doet ook elke aanvraag die je aanmaakt — of de ontvanger nu antwoordt, hem negeert, of je hem annuleert. De
inzending die een aanvraag oplevert is al betaald en telt nergens mee. Free bevat 1.000 eenheden per maand, Pro en Business 50.000; de
telling wordt gereset op de 1e van elke maand, UTC. Bij het bereiken van het quotum mislukt requests.create met{' '}
UPGRADE_REQUIRED en reden MONTHLY_ALLOWANCE_REACHED; aanvragen die je al hebt aangemaakt blijven beantwoordbaar.
Op Free verbruikt een aanvraag die met "delivery": "email" wordt aangemaakt ook een van de{' '}
10 gratis uitnodigingen van het account. Ze worden nooit gereset;
zijn ze op, dan mislukt e-mailbezorging met UPGRADE_REQUIRED en reden FREE_INVITATIONS_USED.
Geef dezelfde idempotencyKey op met dezelfde inhoud en je krijgt de oorspronkelijke aanvraag terug, met{' '}
deduplicated: true en de oorspronkelijke link — geen tweede aanvraag, geen tweede e-mail. Hergebruik de sleutel met een{' '}
andere inhoud en Formstep weigert met IDEMPOTENCY_CONFLICT in plaats van te gokken welke je bedoelde. Sleutels zijn
gebonden aan de werkruimte en blijven 30 dagen geldig; daarna start dezelfde sleutel een nieuwe aanvraag.
In een workflowtool is de uitvoerings-id de natuurlijke sleutel: een run die opnieuw wordt geprobeerd na een netwerkstoring pakt de aanvraag op die al was aangemaakt.
requests.create en documents.create delen een budget van 60 aanroepen per minuut, geteld per
API-token (of per gebruiker, voor een aanroep zonder token). Een achterstand die je wegwerkt, moet zichzelf temporiseren; een piek boven
het budget wordt geweigerd en kan opnieuw worden geprobeerd.
Als het formulier al is gepubliceerd op een van je aangepaste domeinen, worden
aanvraaglinks daar automatisch gegenereerd — https://forms.jouwbedrijf.com/r/rq_…. Geef domainId expliciet op
wanneer het formulier op meer dan één domein is gepubliceerd. Het domein moet tot dezelfde werkruimte behoren als het formulier.
Precies het formulier dat jij hebt gemaakt — zelfde thema, zelfde logo, zelfde taal — met hun waarden ingevuld, vergrendelde velden alleen-lezen, en geen captcha om op te lossen. Wanneer ze indienen, krijgen ze jouw bedankpagina. Als ze later terugkomen op de link, krijgen ze de uitkomstpagina in plaats van een leeg formulier.
Er staat geen bericht van je automatisering op de pagina. Alles wat de ontvanger moet weten hoort in het formulier zelf, waar je het kunt personaliseren door een contextwaarde of een vooraf ingevuld veld te noemen.
Een AI-agent doorloopt dezelfde twee stappen als fields_list en request_create, met dezelfde opties — documenten
en domainId inbegrepen. Zie Aanvragen op de MCP-server.