# Een aanvraag versturen met de REST API

Maak een API-token aan, lees de veldsleutels van een formulier, en maak een vooraf ingevulde aanvraag met curl, vanuit elke tool die een HTTP-aanroep kan doen.

## Een aanvraag versturen met de REST API

Elke tool met een HTTP-stap kan een aanvraag versturen: Pipedream, een serverless functie, een script. Deze handleiding doet het met curl, zodat je elke aanroep ziet voordat je hem in je eigen code overneemt.

<p>
  Je hebt een gepubliceerd formulier nodig. Deze handleiding gebruikt het formulier gebouwd in{' '}
  <a href="/nl/guides/ai-agents/build-a-form">Een formulier bouwen met een AI-agent</a>: 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{' '}
  <a href="/nl/developers/rest-api">API-methoden</a>.
</p>

<h2 id="token">1. Maak een API-token aan</h2>

<p>
  Open in formbase <strong>OAuth en API-sleutels</strong> in de zijbalk van de werkruimte en{' '}
  <a href="/nl/developers/api-tokens#create">maak een token aan</a>. De waarde wordt één keer getoond. Bewaar hem in een omgevingsvariabele,
  niet in je code:
</p>

```
export FORMBASE_TOKEN='fb_...'
```

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

<h2 id="form-id">2. Zoek het formulier-id</h2>

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

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

<p>De commando's hieronder gebruiken het formulier-id van deze handleiding. Vul je eigen id in.</p>

<h2 id="fields">3. Som de veldsleutels op</h2>

<p>
  Een aanvraag vult vragen in, en de antwoorden komen terug, via <a href="/nl/requests/field-keys">veldsleutel</a>. Vraag het formulier om
  zijn sleutels in plaats van ze te raden op basis van de titels:
</p>

```
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"}}'
```

<p>Het antwoord somt elke vraag van het gepubliceerde formulier op. Ingekort:</p>

```
{
  "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
  }
}
```

<p>
  Om een keuzevraag vooraf in te vullen, stuur je de <code>key</code> van de optie, hier <code>"yes"</code>, niet zijn label. Een vraag met{' '}
  <code>prefillable: false</code>, zoals de bestandsupload, kan alleen de ontvanger beantwoorden. De overige vlaggen staan uitgelegd onder{' '}
  <a href="/nl/developers/rest-api#fields-list">fields.list</a>.
</p>

<h2 id="create">4. Maak een testaanvraag aan</h2>

<p>
  Stuur de aanvraag naar Ada Lovelace, met de bedrijfsnaam ingevuld en vergrendeld. <code>test: true</code> maakt er een{' '}
  <a href="/nl/requests/creating-requests#test-mode">testaanvraag</a> van: hij mailt nooit iemand en telt nergens mee, dus je kunt deze stap
  zo vaak herhalen als je wilt, telkens met een nieuwe <code>idempotencyKey</code>.
</p>

```
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
    }
  }'
```

<ul>
  <li>
    <strong>prefill</strong> vult antwoorden in die de ontvanger nog kan wijzigen. Een sleutel in <strong>readonly</strong> is dan ook{' '}
    <a href="/nl/requests/creating-requests#locked-fields">vergrendeld</a>.
  </li>
  <li>
    <strong>externalId</strong> is je eigen id voor dit stuk werk, zoals een leveranciersnummer. Hij komt terug bij elke uitlezing en
    callback.
  </li>
  <li>
    <strong>idempotencyKey</strong> maakt een nieuwe poging veilig. Als je code dezelfde aanroep twee keer stuurt, geeft formbase de eerste
    aanvraag terug met <code>deduplicated: true</code> in plaats van een tweede aan te maken.
  </li>
</ul>

<p>Het antwoord draagt het aanvraag-id en de link voor de ontvanger:</p>

```
{
  "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
  }
}
```

<p>
  <code>deliveryStatus: "not_requested"</code> 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 <code>"delivery": "email"</code> toe, wat een Pro- of Business-abonnement
  vereist. Zie <a href="/nl/requests/invitations-and-reminders">Uitnodigingen, herinneringen & verlopen</a>. Staat{' '}
  <strong>Herinneringen versturen</strong> aan op het formulier, dan krijgt een echte aanvraag met een e-mailadres van de ontvanger nog
  steeds de geplande herinneringen; voeg <code>"reminders": []</code> toe om er geen te sturen.
</p>

> ℹ️ **Testaanvragen blijven uit het zicht**
> <p>
>     De pagina <strong>Aanvragen</strong> toont testaanvragen alleen wanneer je de filter <strong>Testaanvragen weergeven</strong> aanzet.
>     Open de <code>url</code> zelf om hem af te ronden. Laat <code>test</code> weg wanneer je de echte aanvraag verstuurt.
>   </p>

<h2 id="read">5. Rond hem af en lees de antwoorden</h2>

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

```
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"}}'
```

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

```
"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"
}
```

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

<h2 id="next">Vervolgens</h2>

<div class="not-prose grid gap-3 sm:grid-cols-2 mb-8">
  - [De callback ontvangen en verifiëren](/nl/guides/rest-api/verify-the-callback) — Krijg de antwoorden naar je endpoint gepusht, en controleer dat formbase ze heeft verstuurd.
  - [Een aanvraag maken](/nl/requests/creating-requests) — Elke optie die een aanvraag meeneemt: context, metadata, documenten, verlopen.
</div>