API-Methoden

Formulare in einem Workspace auflisten. Unterstützt Cursor-Paginierung und optionale unscharfe Namenssuche.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "forms.list",
    "params": { "workspaceId": "ws_abc123" }
  }'

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "frm_abc123",
        "name": "Contact Form",
        "folderId": null,
        "workspaceId": "ws_abc123",
        "isPublished": true,
        "publishedAt": 1714041851000,
        "unpublishedAt": null,
        "createdAt": 1714041800000,
        "lastEditedAt": 1714042000000,
        "emoji": null
      }
    ],
    "nextCursor": null,
    "hasMore": false,
    "canPaginate": false
  }
}

Vollständige Details für ein einzelnes Formular abrufen, einschließlich Fragen, Cover, Logo und einer Vorschau-URL.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "forms.get",
    "params": { "formId": "frm_abc123" }
  }'

{
  "ok": true,
  "data": {
    "id": "frm_abc123",
    "name": "Event Feedback",
    "folderId": null,
    "workspaceId": "ws_abc123",
    "isPublished": true,
    "publishedAt": 1714041851000,
    "unpublishedAt": null,
    "createdAt": 1714041800000,
    "lastEditedAt": 1714042000000,
    "emoji": null,
    "questions": [
      {
        "id": "q_1",
        "type": "email-input",
        "inputType": "email",
        "title": "Your email",
        "metadata": null
      },
      {
        "id": "q_2",
        "type": "rating-input",
        "inputType": "rating",
        "title": "Overall experience",
        "metadata": { "kind": "rating", "maxStars": 5 }
      }
    ],
    "hasContent": true,
    "cover": null,
    "logo": null,
    "isDeleted": false,
    "trashedAt": null,
    "previewUrl": "https://formbase.so/preview/abc..."
  }
}

Ein neues leeres Formular erstellen. Gibt das Formular und eine Vorschau-URL zurück.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "forms.create",
    "params": {
      "name": "Contact",
      "workspaceId": "ws_abc123"
    }
  }'

const res = await fetch('https://api.formbase.so/api/v1', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FORMBASE_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    method: 'forms.create',
    params: { name: 'Contact', workspaceId: 'ws_abc123' },
  }),
})
const { ok, data } = await res.json()

import os, requests
res = requests.post(
  "https://api.formbase.so/api/v1",
  headers={"Authorization": f"Bearer {os.environ['FORMBASE_TOKEN']}"},
  json={
    "method": "forms.create",
    "params": {
      "name": "Contact",
      "workspaceId": "ws_abc123",
    },
  },
)
data = res.json()

{
  "ok": true,
  "data": {
    "id": "frm_new123",
    "name": "Contact",
    "workspaceId": "ws_abc123",
    "folderId": null,
    "isPublished": false,
    "createdAt": 1714041851000,
    "previewUrl": "https://formbase.so/preview/abc..."
  }
}

Formular-Metadaten aktualisieren: Name, Ordner, Emoji, Cover oder Logo. Aktualisiert nicht den Formularinhalt (dafür die Editor-Tools verwenden).

Übergib mindestens eines der fünf aktualisierbaren Felder. Das ändert nicht den Formularinhalt — nutze dafür die MCP-Editor-Tools.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "forms.update",
    "params": {
      "formId": "frm_abc123",
      "name": "Updated Name",
      "emoji": "📋"
    }
  }'

{
  "ok": true,
  "data": {
    "id": "frm_abc123",
    "name": "Updated Name",
    "folderId": null,
    "emoji": "📋"
  }
}

cover und logo kommen nur zurück, wenn du sie mitgeschickt hast. Ein Payload, der bei jedem skalaren Feld dem aktuellen Zustand entsprach, ergänzt noChange: true.

Ein Formular veröffentlichen, damit es Antworten entgegennehmen kann, und seine Feldschlüssel in einem neuen Snapshot einfrieren. Idempotent: ein bereits veröffentlichtes Formular liefert Erfolg mit alreadyPublished: true, und ein depubliziertes Formular wird aus seinem letzten Snapshot erneut veröffentlicht.

Ein Formular mit Inhaltsblöcken, aber ohne Fragen, wird mit einer Warnung veröffentlicht. Ein Formular ganz ohne Inhalt lässt sich nicht veröffentlichen. Veröffentlichen erzeugt keine öffentliche URL — rufe dafür shareLinks.create auf.

Ein Formular offline nehmen. Ausfüllende können es nicht mehr öffnen. Idempotent — ein Formular, das nicht veröffentlicht ist, liefert alreadyUnpublished: true. Umkehrbar mit forms.publish.

Ein Formular in den Papierkorb verschieben. Seine aktiven Freigabelinks werden widerrufen, ihre öffentlichen URLs liefern also nichts mehr aus.

Ein Formular aus dem Papierkorb wiederherstellen.

Ein Formular, das nicht im Papierkorb liegt, liefert alreadyRestored: true.

Die Verhaltenseinstellungen eines Formulars lesen.

Liefert { settings, isDefault, availableEmailDomains, defaultFromAddress, payment }. isDefault ist wahr, wenn das Formular noch keine gespeicherte Einstellungszeile hat und du die Standardwerte siehst. availableEmailDomains enthält die verifizierten Domain-IDs, die du als emailDomainId übergeben kannst, und payment meldet, ob Stripe verbunden ist (das Verbinden selbst ist ein Dashboard-Schritt).

Die Verhaltenseinstellungen eines Formulars aktualisieren. Ein partielles Update: nur die gesendeten Felder werden geschrieben.

Betreffzeilen und Texte sind Klartext und akzeptieren {{variable}}-Platzhalter; Zeilenumbrüche werden zu Absätzen. Einen Betreff oder Text für die ausfüllende Person anzupassen macht ihn übersetzbar, seine Schlüssel erscheinen also sofort in translations.listEntries.

Die Einreichungen eines Formulars auflisten, neueste Seite zuerst, mit Cursor-Paginierung.

{
  "ok": true,
  "data": {
    "formId": "frm_abc123",
    "formName": "Event Feedback",
    "items": [
      {
        "id": "sub_xyz789",
        "submittedAt": "2026-05-18 18:02:28",
        "isCompleted": true,
        "createdAt": "2026-05-18 18:02:19",
        "answers": {
          "email": "user@example.com",
          "plan": "pro",
          "contacts": [{ "name": "Ada" }, { "name": "Grace" }]
        },
        "display": {
          "email": "user@example.com",
          "plan": "Pro",
          "contacts": "Ada, Grace"
        }
      }
    ],
    "nextCursor": null,
    "hasMore": false,
    "canPaginate": false
  }
}

Einen Link zum PDF einer Einreichung abrufen. Für den Zapier-Connector gebaut: Es liefert nur dann ein Ergebnis, wenn das Formular eine aktive Zapier-Integration hat, die so konfiguriert ist, dass sie das PDF einschließt, und das PDF aufbewahrt wurde.

{
  "ok": true,
  "data": {
    "url": "https://api.formbase.so/api/storage/...",
    "filename": "formbase-submission-sub_xyz789.pdf",
    "contentType": "application/pdf",
    "byteLength": 148213
  }
}

Ein Beispiel-Payload für die Einreichung eines Formulars bauen, ohne echte Daten. Es hat exakt die Form, die die Zustellung einer Einreichung über den öffentlichen Link trägt, Connectors nutzen es also für die Felderkennung; eine aus einem Request entstandene Einreichung erreicht ein Abonnement stattdessen als request.completed — das Beispiel dafür liefert

requests.sample. data.form.snapshotId ist die aktuell veröffentlichte Version des Formulars, dieselbe ID, die Live-Events tragen, oder null, solange das Formular unveröffentlicht ist.

{
  "ok": true,
  "data": {
    "id": "evt_example000000000000",
    "type": "submission.completed",
    "createdAt": "2026-05-18T19:00:00.000Z",
    "apiVersion": "2026-09-24",
    "test": true,
    "data": {
      "form": { "id": "frm_abc123", "name": "Event Feedback", "snapshotId": "js7abc123" },
      "submission": {
        "id": "sub_example000000000000",
        "respondentEmail": "respondent@example.com",
        "submittedAt": "2026-05-18T19:00:00.000Z",
        "updatedAt": null,
        "editCount": 0,
        "pdfUrl": null,
        "language": "en"
      },
      "answers": { "your_email": "john@example.com" },
      "display": { "your_email": "john@example.com" }
    }
  }
}

Feld- und Payload-Semantik sind einmalig dokumentiert, in der Webhooks-Referenz.

Freigabe-Links für ein Formular auflisten.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "sl_abc123",
        "code": "RPjNes52",
        "url": "https://formbase.so/RPjNes52",
        "customDomainUrl": null,
        "formId": "frm_abc123",
        "createdAt": 1714041851000,
        "expiresAt": null,
        "maxClaims": null,
        "claimedCount": 7,
        "isRevoked": false,
        "revokedAt": null,
        "customDomainId": null,
        "customSlug": null
      }
    ],
    "availableCustomDomains": [],
    "nextCursor": null,
    "hasMore": false,
    "canPaginate": false
  }
}

Einen Freigabe-Link für ein Formular erstellen. Das Formular muss zuerst veröffentlicht sein.

Die Antwort ist der Freigabe-Link (dieselbe Form wie ein shareLinks.list-Eintrag) plus availableCustomDomains, sodass du mit shareLinks.update nachfassen kannst, um eine zu verknüpfen.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "shareLinks.create",
    "params": {
      "formId": "frm_abc123",
      "maxClaims": 100
    }
  }'

Einen Freigabe-Link aktualisieren. Ablauf, maximale Nutzungen, benutzerdefinierte Domain, Slug oder Widerruf des Links können geändert werden.

Jedes Feld der aktuell veröffentlichten Version eines Formulars auflisten, mit dem Schlüssel, über den es angesprochen wird. Vor requests.create aufrufen, statt Schlüssel fest im Code zu hinterlegen. Siehe Feldschlüssel.

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

{
  "ok": true,
  "data": {
    "published": true,
    "items": [
      { "key": "company_name", "type": "text", "title": "Company", "required": true, "prefillable": true },
      {
        "key": "company_size", "type": "select", "title": "Company size", "required": false, "prefillable": true,
        "options": [
          { "key": "1_50", "label": "1–50" },
          { "key": "51_200", "label": "51–200" }
        ]
      },
      {
        "key": "satisfaction", "type": "matrix", "title": "How did we do?", "required": false, "prefillable": true,
        "rows": [{ "key": "delivery_speed", "label": "Delivery speed" }],
        "columns": [{ "key": "very_good", "label": "Very good" }, { "key": "poor", "label": "Poor" }]
      },
      { "key": "case_id", "type": "hidden", "title": "Case", "required": false, "prefillable": false, "context": true },
      { "key": "total", "type": "number", "title": "Total", "required": false, "prefillable": false, "calculated": true }
    ],
    "hasMore": false
  }
}

Eine Wiederholungsgruppe ist type: “group” mit repeating: true und einem members-Array. Ein Dokumente-Block ist type: “documents” und trägt documents: [{ name }], die vom Autor hinterlegten Dateien, die jede ausfüllende Person bereits sieht.

Einen Request erstellen. Verbraucht eine Einheit des monatlichen Kontingents des Workspace, unabhängig davon, ob die empfangende Person antwortet.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "requests.create",
    "params": {
      "formId": "j57...",
      "recipient": { "email": "ada@acme.com", "name": "Ada" },
      "prefill": { "company_name": "Acme" },
      "readonly": ["company_name"],
      "context": { "case_id": "CASE-9" },
      "delivery": "email",
      "externalId": "run-42",
      "callbackUrl": "https://automation.example/webhook/resume-abc",
      "idempotencyKey": "run-42"
    }
  }'

{
  "ok": true,
  "data": {
    "id": "kd7...",
    "status": "pending",
    "url": "https://form.formbase.so/r/rq_...",
    "deliveryStatus": "queued",
    "expiresAt": 1794787200000,
    "createdAt": 1789379200000,
    "externalId": "run-42",
    "deduplicated": false
  }
}

deliveryStatus ist not_requested, bis eine Einladung eingereiht wird, dann queued → sent oder failed, und bounced, sobald der Mail-Anbieter einen Hard Bounce oder eine Beschwerde meldet.

Einen Request vollständig abrufen: Status, Ergebnis, was vorausgefüllt wurde, seine Timeline und — sobald abgeschlossen — answers und display nach Feldschlüssel, dieselben zwei Maps, die auch der Callback trägt.

{
  "ok": true,
  "data": {
    "id": "kd7...",
    "formId": "j57...",
    "status": "completed",
    "outcome": "approve",
    "isTest": false,
    "recipient": { "email": "ada@acme.com", "name": "Ada" },
    "language": "en",
    "externalId": "run-42",
    "metadata": null,
    "context": { "case_id": "CASE-9" },
    "prefill": { "company_name": "Acme" },
    "readonlyKeys": ["company_name"],
    "delivery": "email",
    "deliveryStatus": "sent",
    "hasCallback": true,
    "callbackFailedAt": null,
    "submissionId": "kp2...",
    "url": "https://form.formbase.so/r/rq_...",
    "answers": { "company_name": "Acme", "decision": "approve" },
    "display": { "company_name": "Acme", "decision": "Approve" },
    "timeline": [
      { "id": "kd7...:created", "type": "created", "at": 1789379200000 },
      { "id": "kd7...:completed", "type": "completed", "at": 1789465600000 }
    ],
    "expiresAt": 1794787200000,
    "completedAt": 1789465600000
  }
}

Das Beispiel oben ist gekürzt. Eine vollständige Antwort trägt außerdem workspaceId, formSnapshotId, createdVia, documents, reminderStep, remindersSent, reminderDueAt, dataPurgedAt und den Rest der Zeitstempel (updatedAt, openedAt, startedAt, lastActivityAt, expiredAt, canceledAt, canceledBy, cancelReason).

Zwei Felder sagen dir, wann die Kopie vor dir die einzige ist. callbackFailedAt ist gesetzt, während der Callback dieses Requests keine Versuche mehr übrig hat, und wird geleert, sobald einer durchkommt oder du ihn erneut sendest. dataPurgedAt ist gesetzt, sobald die Aufbewahrung den Request gestrippt hat: context, prefill und metadata kommen leer zurück, readonlyKeys und documents sind [], und submissionId, answers und display sind null.

timeline ist abgeleitet, älteste zuerst. Jeder Eintrag hat eine id, ein at und einen type — created, invitation, reminder, opened, started, completed, expired, canceled, callback. Zustellungs-Einträge ergänzen deliveryStatus und attemptCount, und Callbacks ergänzen eventType. Zustellungszeilen bleiben 30 Tage erhalten, ältere Timelines dünnen also auf die Zeitstempel aus.

Requests in einem Workspace oder zu einem Formular auflisten, neueste zuerst. Testanfragen bleiben außen vor, sofern du nicht danach fragst.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "kd7...",
        "formId": "j57...",
        "status": "pending",
        "outcome": null,
        "recipient": { "email": "ada@acme.com", "name": "Ada" },
        "externalId": "run-42",
        "deliveryStatus": "sent",
        "expiresAt": 1794787200000,
        "createdAt": 1789379200000
      }
    ],
    "nextCursor": null,
    "hasMore": false
  }
}

Listeneinträge tragen dieselben Felder wie requests.get, minus url, answers, display und timeline, und jeder trägt isTest. Gib workspaceId oder formId an — keines von beiden ergibt 400 VALIDATION_ERROR mit dem Grund SCOPE_REQUIRED. outcome hat Vorrang vor status, denn nur ein abgeschlossener Request hat ein Urteil.

Einen ausstehenden Request zurückziehen. Der Link funktioniert nicht mehr, die empfangende Person sieht einen Hinweis auf den Rückzug, und ein request.canceled-Callback wird ausgelöst.

Die empfangende Person jetzt per E-Mail erreichen, ohne den Erinnerungsplan anzurühren. Braucht eine E-Mail der empfangenden Person und einen Pro- oder Business-Plan.

Zwei Untergrenzen gelten: mindestens 10 Minuten zwischen manuellen Erinnerungen, und höchstens 8 Erinnerungen pro Request insgesamt, manuelle und geplante zusammengerechnet. Der automatische Zeitplan bleibt unberührt — reminderStep und reminderDueAt bleiben, wo sie waren.

Den Callback, den ein Request bei seinem Ende ausgelöst hat, erneut senden — gleiche Payload, gleiche Event-ID, sodass ein Empfänger, der ihn bereits verarbeitet hat, dedupliziert. Nach dem Beheben eines defekten Endpunkts verwenden.

{
  "ok": true,
  "data": { "dispatchId": "kf9...", "eventId": "evt_kf9..." }
}

Ein Beispiel-Request-Ereignis für ein Formular bauen, ohne echten Request. Es ist genau der Umschlag, den ein mit

webhooks.create erstelltes request_*-Abonnement empfängt, Connectors nutzen es also für die Felderkennung. Ein abgeschlossenes Beispiel trägt dieselben Beispielantworten, die submissions.sample zeigt; ein abgelaufenes oder storniertes Beispiel trägt nur den Request-Block.

{
  "ok": true,
  "data": {
    "id": "evt_example000000000000",
    "type": "request.completed",
    "createdAt": "2026-05-18T19:00:00.000Z",
    "apiVersion": "2026-09-24",
    "test": true,
    "data": {
      "request": {
        "id": "req_example000000000000",
        "externalId": "order-1234",
        "status": "completed",
        "language": "en",
        "recipient": { "email": "recipient@example.com", "name": "Sample Recipient" },
        "metadata": { "source": "sample" },
        "context": {},
        "createdAt": "2026-05-18T18:00:00.000Z",
        "completedAt": "2026-05-18T19:00:00.000Z"
      },
      "form": { "id": "frm_abc123", "name": "Event Feedback", "snapshotId": "js7abc123" },
      "submission": {
        "id": "sub_example000000000000",
        "respondentEmail": "respondent@example.com",
        "submittedAt": "2026-05-18T19:00:00.000Z",
        "updatedAt": null,
        "editCount": 0,
        "pdfUrl": null,
        "language": "en"
      },
      "answers": { "your_email": "john@example.com" },
      "display": { "your_email": "john@example.com" }
    }
  }
}

Der Request-Block und das Ergebnis sind auf der Callbacks-Seite dokumentiert; die Einreichungshälfte in der Webhooks-Referenz. Beispiel-IDs sind die oben gezeigten festen Platzhalter, und test ist true, sodass ein Empfänger ein Beispiel von einem Live-Ereignis unterscheiden kann.

Einen Upload für eine Datei reservieren, die du einer empfangenden Person über den Dokumente-Block des Formulars übergibst. Bytes wandern nie durch diese API: Du bekommst ein vorsigniertes PUT, lädst hoch, und requests.create prüft das Objekt, bevor der Request existiert.

{
  "ok": true,
  "data": {
    "id": "kn7...",
    "name": "Lease contract draft",
    "contentType": "application/pdf",
    "size": 412000,
    "uploadUrl": "https://...",
    "expiresAt": 1792198800000
  }
}

PUTe die rohen Bytes innerhalb einer Stunde an uploadUrl, mit Content-Type auf den deklarierten Typ gesetzt, und referenziere dann die ID von requests.create aus:

{
  "method": "requests.create",
  "params": {
    "formId": "j57...",
    "documents": [
      { "documentId": "kn7...", "name": "Your lease contract" },
      { "documentId": "kn8...", "field": "attachments" }
    ]
  }
}

• field ist der Feldschlüssel des Dokumente-Blocks. Optional, wenn das Formular genau einen Block hat; erforderlich bei zwei oder mehr.

• Die vom Autor hinterlegten Dokumente des Blocks bleiben; deine erscheinen darunter, nur für diese eine empfangende Person.

• Obergrenzen: 25 MB pro Dokument, 100 MB Dokumente pro Request, 20 pro Block angezeigte Dokumente einschließlich der vom Autor hinterlegten.

• Ein Upload kann von beliebig vielen Requests referenziert werden. Ein Upload, den niemand referenziert, läuft irgendwann aus. Bytes zählen gegen den Speicher des Workspace-Inhabers, bis der letzte Request, der sie referenziert, von der Aufbewahrung gestrippt wird.

Jeder Fehler hier ist 400 VALIDATION_ERROR mit einem details.reason: DOCUMENT_TYPE_NOT_ALLOWED, DOCUMENT_TOO_LARGE, INVALID_DOCUMENT_NAME oder INVALID_DOCUMENT_SHA256 von dieser Methode, und DOCUMENT_NOT_FOUND, DOCUMENT_NOT_UPLOADED (du hast das PUT übersprungen), DOCUMENT_INVALID, INVALID_DOCUMENT_TARGET, DOCUMENTS_TOO_LARGE oder DOCUMENTS_TOO_MANY von requests.create.

Webhook-Abonnements für ein Formular auflisten.

{
  "ok": true,
  "data": {
    "items": [
      {
        "subscriptionId": "int_abc123",
        "formId": "frm_abc123",
        "provider": "zapier",
        "targetUrl": "https://hooks.zapier.com/...",
        "eventType": "submission_created",
        "status": "active",
        "createdAt": 1714041851000
      }
    ],
    "hasMore": false
  }
}

Eine URL für Formularereignisse abonnieren: neue oder abgebrochene Einreichungen, oder Requests, die auf dem Formular enden. Die URL muss HTTPS verwenden.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "webhooks.create",
    "params": {
      "formId": "frm_abc123",
      "targetUrl": "https://hooks.zapier.com/hooks/catch/...",
      "provider": "zapier",
      "eventType": "submission_created",
      "signingSecret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
  }'

{
  "ok": true,
  "data": {
    "subscriptionId": "int_new123",
    "formId": "frm_abc123",
    "provider": "zapier",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/...",
    "eventType": "submission_created"
  }
}

Abonnements für abgebrochene Einreichungen liefern das gewählte idleWindow sowohl von webhooks.create als auch von webhooks.list zurück. Jedes andere Abonnement lässt es aus.

Ein Request-Abonnement hört dieselben Ereignisse wie ein Callback, aber als eigene Zustellung: eigene Event-ID, eigene Signatur und ein eigenes Wiederholungsbudget von fünf Versuchen, nach dem das Abonnement pausiert. Ein Request, der mit einer callbackUrl auf einem Formular mit einem request_completed-Abonnement erstellt wurde, feuert deshalb zweimal, einmal an jeden Empfänger. requests.replayCallback sendet nur den Callback erneut. Verwende requests.sample, um das Payload zu sehen, bevor irgendein Request geendet hat.

Ein Webhook-Abonnement entfernen.

{
  "ok": true,
  "data": {
    "subscriptionId": "int_abc123",
    "deleted": true
  }
}

Aggregierte Analysekennzahlen für ein Formular abrufen. Unterstützt Datumsbereich, Gerät, Verkehrsquelle und Länderfilter.

Analysen sind eine Pro-Funktion, und die Regel richtet sich nach dem Tarif des Workspace-Eigentümers, genau wie der Analytics-Tab im Dashboard. Ist der Eigentümer nicht auf Pro, gibt der Aufruf UPGRADE_REQUIRED zurück — auch für Verlaufsdaten aus der Zeit davor. Ein Free-Mitglied im Workspace eines Pro-Eigentümers erhält die Daten.

Raten sind Zahlen von 0 bis 100, Zählungen sind Ganzzahlen, und totalEvents ist die rohe Event-Zeilenzahl vor der Deduplizierung zu eindeutigen Besuchern.

{
  "ok": true,
  "data": {
    "formId": "frm_abc123",
    "period": { "from": null, "to": null },
    "totalEvents": 17,
    "metrics": {
      "views": 7,
      "uniqueVisitors": 7,
      "engaged": 6,
      "submissions": 4,
      "engagementRate": 86,
      "completionRate": 57,
      "bounceRate": 14
    },
    "breakdown": {
      "byBrowser": { "Chrome": 17 },
      "byCountry": { "US": 10, "DE": 7 },
      "byDevice": { "desktop": 14, "mobile": 3 },
      "bySource": { "Direct": 12, "Google": 5 }
    }
  }
}

Die Workspaces auflisten, die dein Token erreichen kann. Keine Parameter.

Ein API-Token ist an einen Workspace gebunden, liefert also genau diesen einen zurück — auch wenn dein Konto zu mehreren gehört.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "ws_abc123",
        "name": "Acme Inc",
        "createdAt": 1714041800000,
        "role": "owner"
      }
    ],
    "nextCursor": null,
    "hasMore": false,
    "canPaginate": false
  }
}

Einen Einladungslink für einen Workspace erstellen.

{
  "ok": true,
  "data": {
    "id": "inv_abc123",
    "workspaceId": "ws_abc123",
    "code": "aBcDeFgH",
    "expiresAt": null,
    "maxUses": null,
    "uses": 0,
    "createdAt": 1714041851000
  }
}

Eine einzelne Workspace-Einladung abrufen. Liefert dieselbe Form wie workspaces.createInvite.

Eine bestehende Workspace-Einladung aktualisieren. Gib mindestens eines von expiresAt oder maxUses an, sonst wird der Aufruf abgelehnt. Liefert die aktualisierte Einladung.

Eine Workspace-Einladung dauerhaft widerrufen.

{
  "ok": true,
  "data": {
    "inviteId": "inv_abc123",
    "revoked": true
  }
}

Ordner in einem Workspace auflisten.

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "fld_abc123",
        "name": "Customer Feedback",
        "workspaceId": "ws_abc123",
        "parentId": null,
        "createdAt": 1714041800000
      }
    ],
    "nextCursor": null,
    "hasMore": false,
    "canPaginate": false
  }
}

Einen Ordner in einem Workspace erstellen. Idempotent — gibt den bestehenden Ordner zurück, wenn bereits ein Ordner mit demselben Namen existiert.

{
  "ok": true,
  "data": {
    "id": "fld_new123",
    "name": "Customer Feedback",
    "workspaceId": "ws_abc123",
    "parentId": null,
    "createdAt": 1714041851000,
    "alreadyExisted": false
  }
}

Einen Ordner umbenennen oder in einen anderen übergeordneten Ordner verschieben.

Einen Ordner und seinen gesamten Inhalt (Unterordner und Formulare) dauerhaft löschen.

{
  "ok": true,
  "data": {
    "folderId": "fld_abc123",
    "deletedFolderIds": ["fld_abc123"],
    "deletedFormIds": ["frm_in_folder"],
    "message": "Folder and 1 form deleted."
  }
}

Alle für ein Formular konfigurierten Sprachen auflisten.

{
  "ok": true,
  "data": {
    "formId": "frm_abc123",
    "items": [
      {
        "language": "es",
        "completion": { "total": 15, "current": 12, "outdated": 2, "missing": 1, "suggested": 0 },
        "lastUpdatedAt": 1714041851000
      }
    ],
    "nextCursor": null,
    "hasMore": false,
    "canPaginate": false
  }
}

Eine Sprache auf einem Formular registrieren. Jede andere Übersetzungsmethode schlägt mit 404 NOT_FOUND fehl, bis du das getan hast.

{
  "ok": true,
  "data": {
    "formId": "frm_abc123",
    "language": "es",
    "rowId": "tl_new123"
  }
}

Eine Sprache und alle ihre Übersetzungen aus einem Formular entfernen.

Jeden Quellschlüssel für eine Sprache in einem Formular auflisten, mit seinem aktuellen Zustand. So findest du die key-Werte, die translations.setEntry erwartet.

{
  "ok": true,
  "data": {
    "formId": "frm_abc123",
    "language": "es",
    "completion": { "total": 15, "current": 12, "outdated": 2, "missing": 1, "suggested": 0 },
    "items": [
      {
        "key": "block_q_1.title",
        "status": "current",
        "value": "[{\"text\":\"Tu correo electrónico\"}]",
        "sourceFragment": "[{\"text\":\"Your email\"}]",
        "updatedAt": 1714041851000,
        "block": { "id": "q_1", "type": "email-input", "label": "Your email" }
      }
    ],
    "hasMore": false
  }
}

status ist missing (nichts gespeichert), outdated (die Quelle hat sich seither geändert), current, oder suggested (ein KI-Vorschlag, vorgemerkt, aber nicht übernommen). Schlüssel decken Formularinhalt ab (block_<id>.) und, sobald ein Autor sie angepasst hat, die Bestätigungs- und Erinnerungs-E-Mails an die ausfüllende Person (email.confirmation., email.reminder.*).

Einen einzelnen Übersetzungseintrag setzen. Die Sprache muss zuvor über translations.addLanguage hinzugefügt worden sein.

curl -X POST https://api.formbase.so/api/v1 \
  -H "Authorization: Bearer fb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "translations.setEntry",
    "params": {
      "formId": "frm_abc123",
      "language": "es",
      "key": "block_q_1.title",
      "value": "[{\"text\":\"Tu correo electrónico\"}]"
    }
  }'

Liefert { formId, language, key }.

Einen einzelnen Übersetzungseintrag löschen und diesen Schlüssel zur Standardsprache des Formulars zurücksetzen. Idempotent. Verschwindet der letzte Eintrag einer Sprache, fällt die Sprache aus den veröffentlichten Sprachen des Formulars.

Informationen über den authentifizierten Benutzer abrufen.

{
  "ok": true,
  "data": {
    "id": "usr_abc123",
    "email": "you@example.com",
    "name": "Jane Doe"
  }
}

Jeden Methodennamen auflisten, den dieses Deployment bereitstellt, sortiert. Die maßgebliche Antwort, wenn diese Seite und der Server sich widersprechen.

{
  "ok": true,
  "data": {
    "methods": [
      "methods.list",
      "analytics.get",
      "folders.create",
      "folders.delete",
      "folders.list",
      "folders.update",
      "formSettings.get",
      "formSettings.update",
      "forms.create",
      "forms.delete",
      "forms.get",
      "forms.list",
      "..."
    ]
  }
}