# Einen Request mit der REST API senden

Erstelle ein API-Token, lies die Feldschlüssel eines Formulars und erstelle mit curl einen vorausgefüllten Request, aus jedem Tool, das einen HTTP-Aufruf machen kann.

## Einen Request mit der REST API senden

Jedes Tool mit einem HTTP-Schritt kann einen Request senden: Pipedream, eine serverlose Funktion, ein Skript. Diese Anleitung macht es mit curl, damit du jeden Aufruf siehst, bevor du ihn in deinen eigenen Code überträgst.

<p>
  Du brauchst ein veröffentlichtes Formular. Diese Anleitung nutzt das aus{' '}
  <a href="/de/guides/ai-agents/build-a-form">Ein Formular mit einem KI-Agenten bauen</a>: 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{' '}
  <a href="/de/developers/rest-api">API-Methoden</a> beschrieben.
</p>

<h2 id="token">1. Ein API-Token erstellen</h2>

<p>
  Öffne in formbase <strong>OAuth und API-Schlüssel</strong> in der Workspace-Seitenleiste und{' '}
  <a href="/de/developers/api-tokens#create">erstelle ein Token</a>. Der Wert wird einmal angezeigt. Bewahre ihn in einer Umgebungsvariable
  auf, nicht in deinem Code:
</p>

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

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

<h2 id="form-id">2. Die Formular-ID finden</h2>

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

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

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

<h2 id="fields">3. Die Feldschlüssel auflisten</h2>

<p>
  Ein Request füllt Fragen aus, und die Antworten kommen zurück, über den <a href="/de/requests/field-keys">Feldschlüssel</a>. Frag das
  Formular nach seinen Schlüsseln, statt sie aus den Titeln zu erraten:
</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>Die Antwort listet jede Frage des veröffentlichten Formulars auf. Gekürzt:</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>
  Um eine Auswahlfrage vorauszufüllen, sende den <code>key</code> der Option, hier <code>"yes"</code>, nicht ihr Label. Eine Frage mit{' '}
  <code>prefillable: false</code>, wie der Datei-Upload, kann nur die empfangende Person beantworten. Die anderen Flags sind unter{' '}
  <a href="/de/developers/rest-api#fields-list">fields.list</a> erklärt.
</p>

<h2 id="create">4. Eine Testanfrage erstellen</h2>

<p>
  Sende den Request an Ada Lovelace, mit dem Firmennamen ausgefüllt und gesperrt. <code>test: true</code> macht ihn zu einer{' '}
  <a href="/de/requests/creating-requests#test-mode">Testanfrage</a>: 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 <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> füllt Antworten aus, die die empfangende Person noch ändern kann. Ein Schlüssel in <strong>readonly</strong>{' '}
    ist außerdem <a href="/de/requests/creating-requests#locked-fields">gesperrt</a>.
  </li>
  <li>
    <strong>externalId</strong> ist deine eigene ID für dieses Stück Arbeit, wie eine Lieferantennummer. Sie kommt bei jedem Lesen und jedem
    Callback zurück.
  </li>
  <li>
    <strong>idempotencyKey</strong> macht eine Wiederholung sicher. Sendet dein Code denselben Aufruf zweimal, gibt formbase den ersten
    Request mit <code>deduplicated: true</code> zurück, statt einen zweiten zu erstellen.
  </li>
</ul>

<p>Die Antwort trägt die Request-ID und den Link für die empfangende Person:</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> bedeutet, dass formbase keine E-Mail versendet hat; du lieferst den Link selbst aus. Damit
  formbase die Einladung und Erinnerungen selbst verschickt, füge <code>"delivery": "email"</code> hinzu, was einen Pro- oder Business-Plan
  braucht. Siehe <a href="/de/requests/invitations-and-reminders">Einladungen, Erinnerungen & Ablauf</a>. Hat das Formular{' '}
  <strong>Erinnerungen senden</strong> aktiviert, bekommt ein echter Request mit einer Empfänger-E-Mail trotzdem die geplanten Erinnerungen;
  füge <code>"reminders": []</code> hinzu, um keine zu senden.
</p>

> ℹ️ **Testanfragen bleiben unsichtbar**
> <p>
>     Die <strong>Anfragen</strong>-Seite listet Testanfragen nur, wenn du den Filter <strong>Testanfragen anzeigen</strong>
>     aktivierst. Öffne die <code>url</code> selbst, um sie abzuschließen. Lass <code>test</code> weg, wenn du die echte Sache sendest.
>   </p>

<h2 id="read">5. Abschließen und die Antworten lesen</h2>

<p>
  Öffne die <code>url</code> 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:
</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>
  Sobald <code>status</code> <code>completed</code> ist, trägt die Antwort zwei Maps, indiziert nach Feldschlüssel. <code>answers</code> ist
  für Code: Eine Auswahlantwort ist der Optionsschlüssel, eine Datei-Antwort ist eine Liste von Dateien mit Download-URLs.{' '}
  <code>display</code> ist für Menschen: Labels und Dateinamen.
</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>
  Immer wieder nachzufragen, bis sich der Status ändert, funktioniert für einen Test, aber nicht in Produktion. Gib dem Request eine{' '}
  <code>callbackUrl</code>, und formbase ruft dich auf, wenn er endet; die nächste Anleitung richtet das ein.
</p>

<h2 id="next">Als Nächstes</h2>

<div class="not-prose grid gap-3 sm:grid-cols-2 mb-8">
  - [Den Callback empfangen und prüfen](/de/guides/rest-api/verify-the-callback) — Die Antworten an deinen Endpunkt gepusht bekommen und prüfen, dass formbase sie gesendet hat.
  - [Einen Request erstellen](/de/requests/creating-requests) — Jede Option, die ein Request bietet: Kontext, Metadata, Dokumente, Ablauf.
</div>