Einen Request mit der REST API senden

Du brauchst ein veröffentlichtes Formular. Diese Anleitung nutzt das aus Ein Formular mit einem KI-Agenten bauen: Firmenname, Kontakt-E-Mail, USt-IdNr., eine Ja-oder-Nein-Frage zu den Zahlungsbedingungen, und ein Datei-Upload. Jede hier genutzte Methode und Option ist in API-Methoden beschrieben.

1. Ein API-Token erstellen

Öffne in formbase OAuth und API-Schlüssel in der Workspace-Seitenleiste und erstelle ein Token. Der Wert wird einmal angezeigt. Bewahre ihn in einer Umgebungsvariable auf, nicht in deinem Code:

export FORMBASE_TOKEN='fb_...'

Ein Token erreicht nur den Workspace, in dem es erstellt wurde. Jeder Aufruf unten ist ein POST an dieselbe URL mit dem Token im Authorization-Header; der Body nennt die Methode und ihre Parameter.

2. Die Formular-ID finden

Öffne das Formular im Editor. Die Formular-ID ist der Teil der Adresse nach /forms/:

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

Die Befehle unten nutzen die Formular-ID dieser Anleitung. Setze deine eigene an ihre Stelle.

3. Die Feldschlüssel auflisten

Ein Request füllt Fragen aus, und die Antworten kommen zurück, über den Feldschlüssel. Frag das Formular nach seinen Schlüsseln, statt sie aus den Titeln zu erraten:

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

Die Antwort listet jede Frage des veröffentlichten Formulars auf. Gekürzt:

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

Um eine Auswahlfrage vorauszufüllen, sende den key der Option, hier “yes”, nicht ihr Label. Eine Frage mit prefillable: false, wie der Datei-Upload, kann nur die empfangende Person beantworten. Die anderen Flags sind unter fields.list erklärt.

4. Eine Testanfrage erstellen

Sende den Request an Ada Lovelace, mit dem Firmennamen ausgefüllt und gesperrt. test: true macht ihn zu einer Testanfrage: Sie verschickt nie eine E-Mail und zählt nirgends, du kannst diesen Schritt also so oft wiederholen, wie du willst, jedes Mal mit einem neuen 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 füllt Antworten aus, die die empfangende Person noch ändern kann. Ein Schlüssel in readonly ist außerdem gesperrt.

• externalId ist deine eigene ID für dieses Stück Arbeit, wie eine Lieferantennummer. Sie kommt bei jedem Lesen und jedem Callback zurück.

• idempotencyKey macht eine Wiederholung sicher. Sendet dein Code denselben Aufruf zweimal, gibt formbase den ersten Request mit deduplicated: true zurück, statt einen zweiten zu erstellen.

Die Antwort trägt die Request-ID und den Link für die empfangende Person:

{
  "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” bedeutet, dass formbase keine E-Mail versendet hat; du lieferst den Link selbst aus. Damit formbase die Einladung und Erinnerungen selbst verschickt, füge “delivery”: “email” hinzu, was einen Pro- oder Business-Plan braucht. Siehe Einladungen, Erinnerungen & Ablauf. Hat das Formular Erinnerungen senden aktiviert, bekommt ein echter Request mit einer Empfänger-E-Mail trotzdem die geplanten Erinnerungen; füge “reminders”: [] hinzu, um keine zu senden.

5. Abschließen und die Antworten lesen

Öffne die url in einem Browser. Der Firmenname ist ausgefüllt und gesperrt; beantworte den Rest und sende ab. Lies dann den Request mit seiner ID zurück:

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

Sobald status completed ist, trägt die Antwort zwei Maps, indiziert nach Feldschlüssel. answers ist für Code: Eine Auswahlantwort ist der Optionsschlüssel, eine Datei-Antwort ist eine Liste von Dateien mit Download-URLs. display ist für Menschen: Labels und Dateinamen.

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

Immer wieder nachzufragen, bis sich der Status ändert, funktioniert für einen Test, aber nicht in Produktion. Gib dem Request eine callbackUrl, und formbase ruft dich auf, wenn er endet; die nächste Anleitung richtet das ein.

Als Nächstes