Een aanvraag versturen met de REST API

Je hebt een gepubliceerd formulier nodig. Deze handleiding gebruikt het formulier gebouwd in Een formulier bouwen met een AI-agent: bedrijfsnaam, contact-e-mailadres, btw-nummer, een ja-of-nee-vraag over betalingsvoorwaarden, en een bestandsupload. Elke methode en optie die hier wordt gebruikt, staat beschreven in API-methoden.

1. Maak een API-token aan

Open in formbase OAuth en API-sleutels in de zijbalk van de werkruimte en maak een token aan. De waarde wordt één keer getoond. Bewaar hem in een omgevingsvariabele, niet in je code:

export FORMBASE_TOKEN='fb_...'

Een token bereikt alleen de ene werkruimte waarin hij is aangemaakt. Elke aanroep hieronder is een POST naar dezelfde URL met het token in de Authorization-header; de body noemt de methode en zijn parameters.

2. Zoek het formulier-id

Open het formulier in de editor. Het formulier-id is het deel van het adres na /forms/:

https://app.formbase.so/<workspace ID>/forms/jx75hdx8vb5hy1x85gm17nqgkn8f674g/edit

De commando’s hieronder gebruiken het formulier-id van deze handleiding. Vul je eigen id in.

3. Som de veldsleutels op

Een aanvraag vult vragen in, en de antwoorden komen terug, via veldsleutel. Vraag het formulier om zijn sleutels in plaats van ze te raden op basis van de titels:

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "fields.list", "params": {"formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g"}}'

Het antwoord somt elke vraag van het gepubliceerde formulier op. Ingekort:

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company name", "required": true, "prefillable": true },
      { "key": "contact_email", "type": "email", "title": "Contact email", "required": true, "prefillable": true },
      { "key": "vat_number", "type": "text", "title": "VAT number", "required": false, "prefillable": true },
      {
        "key": "do_you_accept_our_30_day_payment_terms", "type": "radio", "title": "Do you accept our 30-day payment terms?", "required": true, "prefillable": true,
        "options": [{ "key": "yes", "label": "Yes" }, { "key": "no", "label": "No" }]
      },
      { "key": "certificate_of_incorporation", "type": "file", "title": "Certificate of incorporation", "required": true, "prefillable": false }
    ],
    "hasMore": false
  }
}

Om een keuzevraag vooraf in te vullen, stuur je de key van de optie, hier “yes”, niet zijn label. Een vraag met prefillable: false, zoals de bestandsupload, kan alleen de ontvanger beantwoorden. De overige vlaggen staan uitgelegd onder fields.list.

4. Maak een testaanvraag aan

Stuur de aanvraag naar Ada Lovelace, met de bedrijfsnaam ingevuld en vergrendeld. test: true maakt er een testaanvraag van: hij mailt nooit iemand en telt nergens mee, dus je kunt deze stap zo vaak herhalen als je wilt, telkens met een nieuwe idempotencyKey.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "requests.create",
    "params": {
      "formId": "jx75hdx8vb5hy1x85gm17nqgkn8f674g",
      "recipient": { "email": "ada@acme.example", "name": "Ada Lovelace" },
      "prefill": { "company_name": "Analytical Engines Ltd" },
      "readonly": ["company_name"],
      "externalId": "supplier-2043",
      "idempotencyKey": "supplier-2043",
      "test": true
    }
  }'

• prefill vult antwoorden in die de ontvanger nog kan wijzigen. Een sleutel in readonly is dan ook vergrendeld.

• externalId is je eigen id voor dit stuk werk, zoals een leveranciersnummer. Hij komt terug bij elke uitlezing en callback.

• idempotencyKey maakt een nieuwe poging veilig. Als je code dezelfde aanroep twee keer stuurt, geeft formbase de eerste aanvraag terug met deduplicated: true in plaats van een tweede aan te maken.

Het antwoord draagt het aanvraag-id en de link voor de ontvanger:

{
  "ok": true,
  "data": {
    "id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "not_requested",
    "externalId": "supplier-2043",
    "deduplicated": false,
    "createdAt": 1790539225370,
    "expiresAt": 1793131225370
  }
}

deliveryStatus: “not_requested” betekent dat formbase geen e-mail heeft verstuurd; je levert de link zelf af. Om formbase de uitnodiging en herinneringen te laten versturen, voeg je “delivery”: “email” toe, wat een Pro- of Business-abonnement vereist. Zie Uitnodigingen, herinneringen & verlopen. Staat Herinneringen versturen aan op het formulier, dan krijgt een echte aanvraag met een e-mailadres van de ontvanger nog steeds de geplande herinneringen; voeg “reminders”: [] toe om er geen te sturen.

5. Rond hem af en lees de antwoorden

Open de url in een browser. De bedrijfsnaam is ingevuld en vergrendeld; beantwoord de rest en dien in. Lees de aanvraag dan terug met zijn id:

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer $FORMBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method": "requests.get", "params": {"requestId": "m17ayhcnj9xvzkff3atek49bdd8f6872"}}'

Zodra status op completed staat, bevat het antwoord twee kaarten, geordend op veldsleutel. answers is voor code: een keuzeantwoord is de sleutel van de optie, een bestandsantwoord is een lijst bestanden met downloadlink. display is voor mensen: labels en bestandsnamen.

"answers": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "yes",
  "certificate_of_incorporation": [{ "name": "certificate-of-incorporation.pdf", "type": "application/pdf", "size": 635, "url": "https://api.formbase.so/api/storage/..." }]
},
"display": {
  "company_name": "Analytical Engines Ltd",
  "do_you_accept_our_30_day_payment_terms": "Yes",
  "certificate_of_incorporation": "certificate-of-incorporation.pdf"
}

Keer op keer vragen tot de status verandert, werkt voor een test, maar niet in productie. Geef de aanvraag een callbackUrl mee en formbase roept je aan zodra hij eindigt; de volgende handleiding zet dat op.

Vervolgens