Öffne dein veröffentlichtes Formular, klicke auf Teilen und wähle den Tab Anfragen. Die Karte dort gibt dir alles, was du für den ersten Aufruf brauchst:
> Ein unveröffentlichtes Formular kann nicht per Request versendet werden, und die Snippets bleiben deaktiviert, bis du veröffentlichst.
> Feldschlüssel frieren bei der ersten Veröffentlichung ein — deshalb kann deine Automation company_name auch noch ein Jahr
> später ansprechen. Siehe Feldschlüssel.
>
fields.list liefert jedes Feld der aktuell veröffentlichten Version des Formulars, mit dem Schlüssel, über den es
angesprochen wird, der Wertform, die es erwartet, und dem Bucket, zu dem es gehört.
context: true markiert ein verstecktes Feld. Sein Wert gehört in context, niemals in prefill; der
Schlüssel eines versteckten Felds in prefill wird mit UNKNOWN_FIELD_KEY abgelehnt.
calculated: true markiert ein berechnetes Feld. Das Formular ermittelt seinen Wert selbst, also kann niemand einen liefern;
du liest ihn unter seinem Schlüssel in answers zurück.
prefillable: false markiert ein Feld, für das niemand einen Wert liefern kann: Datei-Upload, Signatur, Zahlung,
Terminbuchung und Dokumente-Blöcke. Die Fragen füllt die empfangende Person selbst aus. Versteckte Felder und berechnete Felder zeigen
ebenfalls prefillable: false: versteckte Felder übernehmen context, berechnete Felder übernehmen nichts.
options listet die Auswahlmöglichkeiten einer Auswahlfrage. Sende den Schlüssel der Option, nicht ihr
Label; das Label ist nur dazu da, damit du die dir bekannte Option auf ihren Schlüssel abbilden kannst. Eine Matrix listet ihre{' '}
rows und columns auf dieselbe Weise auf.
type: "group", repeating: true und einer Liste von{' '}
members zurück.
deliveryStatus ist "queued", wenn Formstep die Einladung per E-Mail versendet, und "not_requested",
wenn du den Link selbst zustellst.
Drei verschiedene Dinge lassen sich an einen Request anhängen, und sie zu verwechseln ist der häufigste erste Fehler.
Anfangsantworten für die sichtbaren Fragen, sodass die empfangende Person prüft und korrigiert, statt von vorne zu tippen. Alles, was du bereits über sie weißt, gehört hierher — der Firmenname aus deinem CRM, der Betrag aus der Rechnung, die Antworten vom letzten Jahr.
Liste einen vorausgefüllten Schlüssel in readonly auf, und die empfangende Person sieht den Wert, kann ihn aber nicht ändern.
Nutze das für Fakten, die bestätigt statt geliefert werden — die Vertragsnummer, den vereinbarten Preis. Die Sperrung gilt pro Request:
Das Formular selbst bleibt unberührt, und dasselbe Feld ist beim nächsten Request wieder frei bearbeitbar.
Jeder gesperrte Schlüssel muss auch vorausgefüllt sein, und ein gesperrtes Pflichtfeld muss mit etwas Nicht-Leerem vorausgefüllt sein — sonst stünde die empfangende Person vor einem Formular, das sie nie absenden könnte, und Formstep lehnt den Aufruf ab, statt diese Falle zu erstellen.
Vertrauenswürdige Werte für die versteckten Felder des Formulars — eine Fallnummer, eine Workflow-Run-ID, ein Betrag. Kontext speist Variablen, bedingte Logik, berechnete Felder und E-Mail-Texte, kommt unverändert im Callback zurück, und die empfangende Person kann ihn nicht ändern. Das ist der Unterschied zum Befüllen eines versteckten Felds über eine URL bei einem öffentlichen Link, wo jeder die Query-String bearbeiten kann; Request-Links ignorieren URL-Query-Parameter vollständig. Kontextwerte müssen ein String, eine Zahl oder ein Boolean sein.
Kontext ist nicht frei formulierbar: Jeder Schlüssel muss ein verstecktes Feld auf der veröffentlichten Version des Formulars sein, und
jeder andere Schlüssel wird mit UNKNOWN_FIELD_KEY abgelehnt. Buchhaltung ohne passendes verstecktes Feld, wie eine
Ausführungs-ID, gehört in metadata.
Versteckte Felder werden im Formular nicht angezeigt, aber ein Kontextwert ist vor der empfangenden Person nicht geheim. Sie sieht ihn
überall dort, wo das Formular oder die Einladung ihn zeigt: als Erwähnung im Formularinhalt
oder im E-Mail-Text, oder als sichtbare Frage, die dieses versteckte Feld als{' '}
Standardwert verwendet. In diesem letzten Fall sieht die empfangende
Person den Kontextwert in dieser Frage vorausgefüllt und kann die Antwort bearbeiten. Der Kontextwert selbst bleibt unverändert. Ein{' '}
prefill für den eigenen Schlüssel dieser Frage hat Vorrang vor dem Standardwert.
Deine eigene Buchhaltung — eine Ausführungs-ID, eine CRM-Datensatz-ID. Sie erreicht das Formular gar nicht, kann also nicht in Texte eingespeist oder von Logik gelesen werden; sie fährt einfach mit und kommt in jedem Callback und jeder Statusabfrage zurück.
Sende Werte in der Form, die der type aus fields.list verlangt. Eine falsche Form kommt als Validierungsfehler
zurück, der den Schlüssel, den erwarteten Typ und — bei Auswahlfragen — die akzeptierten Werte nennt.
Ein Dokumentenblock reicht der ausfüllenden Person Dateien. Seine hinterlegten Dateien sind für alle gleich und bleiben immer erhalten; ein Request fügt Dateien für seine eine empfangende Person darunter hinzu — den eigenen Mietvertrag der Kundin, eine Ausweiskopie zur Prüfung. Bytes wandern nie durch den API-Aufruf selbst: erst hochladen, dann referenzieren.
``` "documents": [ { "documentId": "kn7...", "name": "Your lease contract" }, { "documentId": "kn8..." } ] ```
name überschreibt den auf dem Upload gespeicherten Anzeigenamen. Hat das Formular mehr als einen Dokumente-Block, benennst du
das Ziel mit field, dem Feldschlüssel des Blocks (fields.list führt ihn auf, zusammen mit den hinterlegten
Dokumenten, die alle Antwortenden ohnehin erhalten). Die Dateien erscheinen unterhalb dieser hinterlegten Dokumente — ein Request fügt
Dateien hinzu, er ersetzt nie eine. Ein Upload kann von so vielen Requests referenziert werden, wie du willst — eine einmal hochgeladene
Preisliste bedient fünfhundert Requests.
Limits: nur PDF und Bilder, 25 MB pro Dokument, 100 MB pro Request (DOCUMENTS_TOO_LARGE), und höchstens 20 Dokumente pro
Block einschließlich der hinterlegten (DOCUMENTS_TOO_MANY). Die Dateien werden auf dein Workspace-Speicherkontingent
angerechnet und werden freigegeben, sobald die Requests, die auf sie verweisen, aus dem Aufbewahrungszeitraum des Formulars fallen. Die
Einreichung protokolliert die Liste, die die empfangende Person unter dem Feldschlüssel des Blocks gesehen hat, sodass der Callback dir
genau sagt, welche Dateien dieser Person gegeben wurden.
Übergib test: true, um die gesamte Verkabelung vor einem echten Lauf durchzuspielen. Eine Testanfrage ist in jeder Hinsicht,
die für die Verkabelung zählt, echt: Der Link öffnet sich und lässt sich abschließen, der Callback{' '}
feuert wie gewohnt, und requests.get liefert die Antworten. Was sie nie tut, ist jemanden oder etwas zu erreichen, das du
danach wieder aufräumen müsstest:
delivery sagt. Erinnerung senden{' '}
wird dafür verweigert, und sie verbraucht nichts von deinem monatlichen Kontingent.
"test": true, sodass deine Automation danach verzweigen oder das Ereignis ignorieren kann.
requests.list ausgelassen, sofern du nicht{' '}
includeTest: true übergibst.
expiresAt mehr verlangt; das expiresAt in der
Antwort nennt den Zeitpunkt. Auf Free darf ein Workspace 10 Testanfragen pro Tag erstellen. Die nächste schlägt mit{' '}
RATE_LIMITED und dem Grund TEST_REQUEST_LIMIT_REACHED fehl, und retryAfterMs sagt, wann du es
erneut versuchen kannst. Pro und Business haben kein Tageslimit.
Selbst ausprobieren im Share-Sheet ist dieser Modus per Knopfdruck: Er übernimmt den Entwurf aus dem Tab Manuell — Prefill, Sperren, Kontext, Callback, Ablauf —, adressiert den Request an dein eigenes Konto, verschickt keine E-Mail und übergibt dir den Link zum selbst Öffnen.
Jeder Plan hat ein monatliches Kontingent, das sich beide Kanäle teilen: Eine Einreichung über einen Freigabelink
verbraucht eine Einheit, und jeder Request, den du erstellst, ebenfalls — egal ob die empfangende Person antwortet, ihn ignoriert, oder du
ihn stornierst. Die Einreichung, die ein Request einsammelt, ist bereits bezahlt und zählt nirgends. Free enthält 1.000 Einheiten pro
Monat, Pro und Business 50.000; der Zähler wird am 1. jedes Monats zurückgesetzt, UTC. Am Limit schlägt requests.create mit{' '}
UPGRADE_REQUIRED und dem Grund MONTHLY_ALLOWANCE_REACHED fehl; bereits erstellte Requests bleiben beantwortbar.
Im Free-Plan verbraucht ein Request, der mit "delivery": "email" erstellt wird, zusätzlich eine der{' '}
10 kostenlosen Einladungen des Kontos. Sie werden nie zurückgesetzt;
sind sie aufgebraucht, schlägt die E-Mail-Zustellung mit UPGRADE_REQUIRED und dem Grund FREE_INVITATIONS_USED{' '}
fehl.
Sende denselben idempotencyKey mit demselben Body und du bekommst den ursprünglichen Request zurück, mit{' '}
deduplicated: true und dem ursprünglichen Link — kein zweiter Request, keine zweite E-Mail. Verwendest du den Schlüssel mit
einem anderen Body erneut, lehnt Formstep mit IDEMPOTENCY_CONFLICT ab, statt zu raten, welchen du meintest.
Schlüssel sind an den Workspace gebunden und gelten 30 Tage; danach startet derselbe Schlüssel einen neuen Request.
In einem Workflow-Tool ist die Ausführungs-ID der natürliche Schlüssel: Ein Lauf, der nach einem Netzwerkaussetzer wiederholt wird, greift den Request auf, den er bereits erstellt hat.
requests.create und documents.create teilen sich ein Budget von 60 Aufrufen pro Minute, gezählt
pro API-Token (oder pro Nutzer, bei einem Aufruf ohne Token). Ein Rückstand, den du abarbeitest, sollte sich selbst drosseln; ein Schub
über das Budget hinaus wird abgelehnt und kann wiederholt werden.
Ist das Formular bereits auf einer deiner benutzerdefinierten Domains veröffentlicht,
werden Request-Links dort automatisch erstellt — https://forms.deinunternehmen.com/r/rq_…. Nenne domainId{' '}
explizit, wenn das Formular auf mehr als einer veröffentlicht ist. Die Domain muss zum selben Workspace wie das Formular gehören.
Genau das Formular, das du erstellt hast — gleiches Theme, gleiches Logo, gleiche Sprache — mit ihren Werten an Ort und Stelle, gesperrten Feldern schreibgeschützt, und ohne ein Captcha lösen zu müssen. Beim Absenden bekommt sie deine Dankesseite. Kehrt sie danach zum Link zurück, bekommt sie die Ergebnisseite statt eines leeren Formulars.
Auf der Seite steht keine Nachricht von deiner Automation. Alles, was der empfangenden Person mitgeteilt werden muss, gehört ins Formular selbst, wo du es personalisieren kannst, indem du einen Kontextwert oder ein vorausgefülltes Feld{' '} erwähnst.
Ein KI-Agent führt dieselben zwei Schritte aus wie fields_list und request_create, mit denselben Optionen —
einschließlich documents und domainId. Siehe Requests auf dem MCP-Server.