Each guide was walked through in the real tool against a test workspace, and shows the day it was last checked. When a step needs the details of a payload or a setting, the guide links to the reference page instead of repeating it.
The formbase app for Zapier listens for submissions and request outcomes, and creates, finds, reminds and cancels requests. Start with connecting your workspace; every other guide assumes it is done.
The formbase community node for self-hosted n8n does the same as the Zapier app: it listens for submissions and request outcomes, and creates, finds, reminds and cancels requests. It can also pause a workflow until the recipient answers. Start with installing the node.
Claude, ChatGPT, Cursor and other AI tools reach formbase over MCP. Once connected, an agent builds and publishes forms, sends requests and reads the answers in one workspace.
Any tool with an HTTP step, or your own code, can send requests through the REST API and receive the answers as a signed callback.
In Zapier, click Create › Zaps, then click the trigger or action step and search for{' '} formbase. Pick any event for now; you can change it later. The list shows what the app can do:
Under Account, click Sign in (or Change › Connect a new account if you already have one). Zapier opens a window; click Connect.
If you are not signed in to formbase in this browser, formbase asks you to sign in first. Then it shows what Zapier may do and asks which workspace to connect.
Choose the workspace under Workspace and click Authorize. The window closes and the account appears in the step, named after your formbase email.
> ℹ️ **One connection, one workspace** >> To use a second workspace, connect a new account and pick the other workspace on this screen. Zapier then shows both connections, and > each Zap step uses the one you choose. >
Pick an event and continue to Configure. The Form dropdown lists the forms of the connected workspace:
In Zapier, open App connections, find formbase, and remove the connection. Zaps that use it stop until you connect formbase again and pick the new connection in each of them.
Removing it in Zapier does not end Zapier's access on the formbase side. In formbase, open OAuth and API Keys and click Disconnect next to Zapier under Connected apps as well.
You need a formbase connection in Zapier and a published form with a share link. A submission to a request link does not start these Zaps; see Act on a request's outcome for that.
Create a Zap, choose formbase as the trigger app, and pick one of the three public link events:
Edit after submit turned on for the form.', ], }, { label: 'Public Link Submission Abandoned', cells: [ 'A respondent starts the form and leaves it unfinished for the time you choose, from 12 hours to 1 week.', 'A Pro or Business plan, which saves partial submissions.', ], }, ]} />Pick your account, click Continue, and choose the form under Form. For the Abandoned trigger, also set{' '} Consider submission abandoned after. formbase checks once an hour, so the Zap can start up to an hour after that time.
Click Continue, then Test trigger. Zapier loads a record such as{' '} Public Link Submission A. Open it to see the fields you can map:
> ℹ️ **The test record is a sample** >
> It carries every question of the form with made-up answers, so you can map fields before anyone has submitted. Real runs carry the
> respondent's answers. The sample has Test Event set to true; real submissions have false.
>
Every answer appears twice:
approve, a number, a date.
Approve), a formatted date.
Where a field key reads differently from its question title, the label names the key in parentheses:{' '}
Your Decision (decision) is the question whose field key is decision.
Once mapped, a field shows its key path, such as Data › Display › Decision.
Use display in messages and answers in filters and lookups. The full shape of both is in the{' '} webhooks reference.
Click Continue with selected record and add the action. This guide uses Email by Zapier ›{' '}
Send Outbound Email. In each field, type / or click + and search for the question by its
title:
Click Publish. Open the form's share link, submit it, and open Zap history in Zapier. The run appears within seconds:
Open the run to see the real answers the Zap received.
You need a formbase connection in Zapier and a published form. What a request is, and every option it takes, is in Creating requests; this guide shows where those options sit in Zapier.
Start with the trigger that should send the request: a deal marked won in your CRM, a new row in Google Sheets, a scheduled date. Add an action, choose formbase, and pick Create Request.
de. Leave it empty for the form's default.
Once you pick the form, each question you can prefill appears below as a field, named after its field key. Signature, file upload, payment, appointment and calculated questions have none. Fill in any answer you already have; the recipient sees it filled in. Add a question to Read-only fields to lock it, so the recipient can see it but not change it. A locked question must also be prefilled.
The recipient opens the link and finds their name filled in and locked:
Hidden fields of the form show up as (context) fields: the recipient cannot change them and sees them only where the form mentions them, and they come back both in the request's Context and among the answers. If the form has a Documents block, a{' '} Documents field takes files from earlier steps. See{' '} Prefill, locked fields, and context for the difference.
Put your own id for this piece of work in External ID, like the deal number deal-1042. It does two jobs:
true. The
same External ID with any input changed, within 30 days, fails with Idempotency key … was already used for a different request.
Use a new External ID for each request, like deal-1042-onboarding, and a fresh one when you change a test step's inputs,
including Test Request.
Reminders, Expires At and Metadata are optional. A request expires after 30 days unless you set another date, at most 365 days away.
Click Test step. formbase creates the request and returns it. Request URL is the link for the recipient; map it into the step that sends it.
> ⚠️ **Testing the step creates a real request** >> Unless Test Request is on, the test is a real request: with Email delivery, the recipient gets the invitation. Turn > Test Request on while you build the Zap. A test request sends no email and counts nowhere, and it does not start any Zap with a > request trigger. Turn it off before you publish. >
You need a formbase connection in Zapier and requests to act on, sent from a Zap as in Send a request from a Zap or from anywhere else: the dashboard, the API or an agent. To branch on a verdict, the form needs a Decision question.
Create a Zap, choose formbase as the trigger app, and search for Request:
Pick Request Completed, pick your account, and choose the form. The Zap fires for requests to that form only.
Click Test trigger. As with public link triggers, Zapier loads a sample built from the form's questions, so you can map fields before any request is completed:
Where a field key reads differently from its question title, the label names the key in parentheses.{' '}
Your Decision (decision) is the answer whose field key is decision, and a mapped field shows it as{' '}
Data › Answers › Decision.
Besides answers and display, a request event carries a request group:
approve, decline or changes, the recipient's answer to the Decision
question. On this form it is the same value as Answers › Decision, because the Decision question's key is
decision. Outcome is missing when the form has no Decision question.
Every field is described in the callback payload; Zapier receives the same event.
Add the action. This guide uses Email by Zapier › Send Outbound Email, with the recipient's name and their decision in the subject and the External ID in the body:
Publish the Zap. When the recipient completes the request, the email arrives with a subject like Ada Lovelace answered: Approve, and the run appears in Zap history.
To act on one verdict only, add a Filter step between the trigger and the action. Set it to continue only if{' '}
Data › Answers › Decision exactly matches approve:
The Decision question's field key is always decision, so Data › Answers › Decision has the same name on
every form. Data › Request › Outcome holds the same value.
Compare with the value from answers, not the label from display: the label changes when you rename the option or the recipient answers in another language, the value does not. To handle each verdict differently, use Paths{' '} instead of a filter, one path per value.
> ℹ️ **Filters and Paths need a paid Zapier plan** >> A Zap with a Filter or Paths step has more than two steps, and Zapier's Free plan publishes only two-step Zaps. On Free, keep the > trigger and one action, and branch in the app the action writes to. >
You need a formbase connection in Zapier and a request created with an External ID, as in{' '} Send a request from a Zap. The same actions exist in the dashboard; see The Requests page.
Your CRM knows the deal as deal-1042, not by formbase's request ID. Add a formbase action with the event{' '}
Find Request
and map your id into External ID:
The result is the whole request: its status, outcome, recipient, timestamps, and what you prefilled and locked.
Get Request takes a Request: map the Request ID from a Create Request step, a Find Request step or a request trigger. It returns the request plus its link, and once the request is completed, the answers. Pick the request's form under{' '} Form so the answers are labelled with the question titles; without it they arrive under their field keys.
Remind Request emails the recipient a reminder now. Scheduled reminders still go out as planned. It works when:
A test request is never reminded.
Cancel Request withdraws a pending request. The link stops working, and the recipient sees a withdrawn notice instead of the form. Fill in Reason to record why: it stays on the request and is carried by the Request Canceled trigger, so another Zap can tell your team.
> ℹ️ **Only pending requests can be canceled** >> A completed, expired or already canceled request stays as it is, and the step fails with an error such as{' '} > This request is already canceled and cannot be canceled. >
Every n8n guide was checked on self-hosted n8n 2.40, running in Docker, with version 0.10.1 of the node. Everything that depends on where n8n runs is on this page. The other guides work the same once the node is installed.
A self-hosted n8n needs two things before it can install the node:
https:// URLs
on the public internet. An n8n that is reachable only on localhost can connect but never receives anything.
n8n builds the URLs it hands to formbase from its own settings, not from the address in your browser. Set these environment variables on the n8n container or process:
WEBHOOK_URL: the public HTTPS address, with a trailing slash, like https://n8n.example.com/. n8n builds the
URL of a published trigger and the resume URL of Wait for the Outcome{' '}
from it.
N8N_EDITOR_BASE_URL: the same address. n8n builds a trigger's test URL for Execute step from it, and the{' '}
OAuth Redirect URL of the formbase credential.
N8N_PROXY_HOPS: set it to 1 when n8n runs behind one reverse proxy or tunnel, so n8n reads the proxy's
forwarded headers.
With Docker, that looks like this:
``` docker run -d --name n8n -p 5678:5678 \ -e WEBHOOK_URL=https://n8n.example.com/ \ -e N8N_EDITOR_BASE_URL=https://n8n.example.com/ \ -e N8N_PROXY_HOPS=1 \ -v n8n_data:/home/node/.n8n \ docker.n8n.io/n8nio/n8n ```
With docker compose or an npm install, set the same variables in n8n's environment. Point your proxy or tunnel at port 5678,
pass /webhook/, /webhook-test/ and /webhook-waiting/ through unchanged, and open n8n through the
public address from then on.
> formbase refuses to send events to an http:// URL or a private network address. If a trigger shows this error on{' '}
> Execute step, N8N_EDITOR_BASE_URL is not set; on Publish, WEBHOOK_URL is
> not. Set that variable, restart n8n, and try again. If you change WEBHOOK_URL later, unpublish and publish each formbase
> workflow again so its trigger registers the new address.
>
Open Settings › Community nodes and click Install. Type n8n-nodes-formbase{' '}
under npm Package Name, tick the box that says you understand the risks of installing unverified code, and click{' '}
Install.
After a few seconds the package appears in the list with its two nodes:
Update or uninstall the package from the same list. If Community nodes is missing from Settings, your n8n was started
with N8N_COMMUNITY_PACKAGES_ENABLED=false; remove that setting.
> n8n Cloud installs only community nodes that n8n has verified, and the formbase node is not verified yet. Until it is, use a self-hosted > n8n, or call the REST API from an HTTP Request node. A Cloud instance > already has a public HTTPS address, so once the node is available there, only the install steps on this page change. >
Open a workflow, click + and search for formbase. The node details show six actions and six triggers:
Add a formbase node to a workflow, open Credential and click Create new credential. You can also start from Overview › Credentials › Create and search for{' '} Formbase OAuth2 API.
There is nothing to fill in. n8n registers itself with formbase when you click Connect, including the{' '} OAuth Redirect URL shown here. The note below that URL asks you to enter it in formbase; you can ignore it, because formbase has no place to paste it.
Click Connect. n8n opens a formbase window. If you are not signed in to formbase in this browser, sign in first. formbase then shows what n8n may do and asks which workspace to connect:
Choose the workspace under Workspace and click Authorize. The window reports that the connection succeeded, and the credential in n8n shows as connected. Save it. If you connect more than one workspace, rename each credential after the workspace it reaches.
> ℹ️ **One credential, one workspace** >> To use a second workspace, create a second credential and pick the other workspace on this screen. Each formbase node then uses the > credential you choose in it. >
Add a formbase Trigger and pick the credential. The form list shows the forms of the connected workspace. A form marked{' '} (not published) sends no events and takes no requests until you publish it.
In n8n, delete the credential under Overview › Credentials. Workflows that use it stop until you pick another credential in each formbase node.
Deleting it in n8n does not end n8n's access on the formbase side. In formbase, open OAuth and API Keys, click the bin icon next to n8n under Connected apps, and confirm with Disconnect.
You need a formbase credential in n8n and a published form with a{' '} share link. Your n8n must be reachable from the internet over HTTPS; see{' '} Install the formbase node in n8n. A submission to a request link does not start these workflows; see Act on a request's outcome in n8n for that.
Create a workflow, click +, search for formbase and pick formbase Trigger. Choose the credential, the form, and one of the three public link events under Event:
Edit after submit turned on for the form.', ], }, { label: 'Public Link Submission Abandoned', cells: [ 'A respondent leaves the form unfinished for the time under Consider Abandoned After (12 hours to 1 week). formbase checks hourly, so the run can come up to an hour later.', 'A Pro or Business plan, which saves partial submissions.', ], }, ]} />Click Execute step. The node shows Listening for test event, and formbase starts sending this form's events to the node's test URL for two minutes. Open the form's share link in another tab and submit it within that time. The submission arrives in the node within seconds:
n8n has no sample record: the test is a real submission, and test is false. Every answer appears twice:
yes, a number, a date, or a list of files.
Yes.
Use display in messages and answers in conditions. See the{' '} webhooks reference for both.
Abandoned submissions arrive hours later, so Execute step cannot catch one. For that event, publish the workflow and check Executions.
Add an Edit Fields (Set) node after the trigger. Drag answers from the input panel into Fields to Set, or type the expressions yourself:
The next node, say Gmail or Google Sheets, reads {'{{ $json.company }}'} and the other fields from here. When a question is
renamed, its field key stays the same, so these expressions keep working.
Click Publish, give the version a name, and confirm. formbase now sends every new submission to the workflow's production URL. Unpublishing the workflow stops that.
Submit the form once more and open the Executions tab. The run appears within seconds. Runs you started with{' '} Execute step carry a flask icon; a production run has none:
http:// or private URL. See{' '}
Tell n8n its public address.
> The formbase Trigger checks the X-formbase-Signature header of every event and rejects any that fails. Keep the n8n host's
> clock accurate: an event signed more than five minutes earlier is rejected too.
>
You need a formbase credential in n8n and a published form. What a request is, and every option it takes, is in Creating requests; this guide shows where those options sit in n8n.
Start with the trigger that should send the request: a new row in a sheet, a deal marked won in your CRM, a schedule. This guide uses a
manual trigger and an Edit Fields node named Supplier that holds supplier_id,{' '}
company_name and contact_email. Click + after it, search for formbase, and
pick Create request.
{'{{ $json.contact_email }}'}. It is needed for email
delivery and for reminders.
Once you pick the form, Values to Send lists every question you can prefill by its title and{' '} field key, like Company name (company_name). File upload, signature, payment and schedule appointment questions, calculated fields and Documents blocks are not listed: the recipient or the form supplies those. Map the answers you already have; fields left empty are not sent. The recipient sees the mapped ones filled in.
Mapping Column Mode can also be Map Automatically: then every input field named after a field key of the form is sent. That suits an input you shaped for this form with an Edit Fields node.
Hidden fields of the form are listed too, marked · context. The recipient cannot change them and sees them only where the form mentions them. See Prefill, locked fields, and context for the difference.
Pick a question under Read-Only Field Names or IDs to lock it, so the recipient can see it but not change it. A locked question must also be prefilled. If the form has a Documents block, Documents takes files from a binary field of the input item.
Click Add Field under Additional Fields:
url, by Slack, SMS or your own email tool.
2d, 5d, which
needs Pro or Business.
supplier-{'{{ $json.supplier_id }}'}. A later
workflow can find the request by it. It is also the{' '}
idempotency key: run the node again with the same External ID and the same
parameters, and you get the same request back with deduplicated: true, not a second one. Within 30 days, the same External
ID with any parameter changed, Test Mode included, fails with{' '}
CONFLICT: Idempotency key … was already used for a different request.
Click Execute step. formbase creates the request and returns it: id, status{' '}
pending, and url, the link for the recipient. Map {'{{ $json.url }}'} into the node that sends it.{' '}
deliveryStatus is not_requested when Delivery is None, because formbase sent nothing.
> Unless Test Mode is on, every run, including Execute step in the editor, is a real request: with email > delivery the recipient gets the invitation. Turn Test Mode on while you build the workflow. A test request does not start any workflow > with a request trigger. Before you publish, turn Test Mode off and change the External ID, > because the old one belongs to the test request. >
You need a formbase credential in n8n, and your n8n must be reachable from the internet over HTTPS; see{' '} Install the formbase node in n8n. To branch on a verdict, the form needs a{' '} Decision question. This guide uses an Approval form with one.
Add a formbase Trigger, pick the credential and the form, and choose one of the request events under{' '} Event:
A test request never starts a request trigger, so send a real one with Delivery set to None, as in{' '} Send a request from an n8n workflow, and open its link yourself. Then click{' '} Execute step and submit the form within two minutes.
The event carries a data.request object next to the answers. Its outcome is approve,{' '}
decline or changes, and its externalId is the ID you set, so you can find the record the request
was about. Every field is in the callback payload.
Expired and canceled events are hard to catch with Execute step. Publish the workflow and check{' '} Executions instead.
Add a Switch node with one routing rule per verdict. Each rule compares {'{{ $json.data.request.outcome }}'}{' '}
with a value; turn on Rename Output to name the branch after it:
Branch on data.request.outcome rather than data.answers.decision: it is missing, not some other value, when the
request expired or was canceled. Compare values, never the labels in data.display: a label changes when you rename the option
or the recipient answers in another language.
Connect a node to each branch, then Publish the workflow. From then on every completed request to the form runs it.
Here the workflow that sends the request pauses until the recipient answers, then carries on. It takes three changes to the workflow from{' '} Send a request from an n8n workflow.
In the Create request node, turn on Wait for the Outcome. The node sends formbase this execution's resume URL as the request's callback. Leave Callback URL empty; the node refuses both at once.
Each execution has its own resume URL, so an External ID reused from an earlier execution fails. Include{' '}
{'{{ $execution.id }}'} in it, or leave it empty.
Add a Wait node right after it, with Resume set to On Webhook Call and the HTTP method
left at POST.
Add a Switch after the Wait node. The Wait node puts the event under body, so compare{' '}
{'{{ $json.body.data.request.outcome }}'}. To tell a completed request from an expired or canceled one, compare{' '}
{'{{ $json.body.type }}'} with request.completed, request.expired or request.canceled.
Run the workflow. The execution stops at the Wait node until the recipient submits, then resumes down the matching branch:
request.expired. Set Expires At to end the wait sooner.
X-formbase-Signature header; it relies on the resume URL being hard to guess. If that is
not enough, use the formbase Trigger, which checks every event.
http:// or private resume URL. See{' '}
Tell n8n its public address.
/webhook-waiting/.
You need a formbase credential in n8n and a request created with an External ID, as in{' '} Send a request from an n8n workflow. The same actions exist in the dashboard; see{' '} The Requests page.
Your system knows the supplier as SUP-1042, not by formbase's request ID. Add a formbase node, pick{' '}
Get many requests, and filter by the External ID you set when you created the request:
Each request is one output item, so the nodes after it run once per request. When nothing matches, the node outputs no items and the
workflow stops there; turn on Always Output Data in the node's settings to carry on. Every node below takes the request
as Request › By ID {'{{ $json.id }}'}, or pick one of the newest requests under{' '}
From list.
Get request returns the request: its status, outcome, recipient, timestamps, what you prefilled and locked, and its link.
Once it is completed, it also carries answers and display at the top level, as{' '}
{'{{ $json.answers }}'}. Unlike the events, its timestamps are Unix time in milliseconds.
Remind request recipient emails the recipient a reminder now. Scheduled reminders still go out as planned. It works when:
A test request is never reminded. The node fails with{' '} CONFLICT: This is a test request, so nothing is emailed for it; a reminder has nobody to write to.
Cancel request withdraws a pending request. The link stops working, and the recipient sees a withdrawn notice instead of
the form. Fill in Reason to record why: it comes back as cancelReason on the request and in the{' '}
Request Canceled event, so another workflow can tell your team.
> A completed, expired or already canceled request stays as it is, and the node fails with an error such as{' '} > This request is already canceled and cannot be canceled. >
If a request had a callback URL and your receiver missed the delivery, Replay request callback sends the callback of a
completed, expired or canceled request again. It returns an eventId, the same ID as the first delivery, so a receiver that
deduplicates on it acts only once. See retries.
An agent's work spends no formbase AI credits; your AI tool bills you under its own pricing. See{' '} AI credits & usage.
Every tool asks for the same thing, the server URL:
``` https://api.formbase.so/api/mcp ```Leave any client ID, secret or token field empty. The tool finds the sign-in page from the server and registers itself. Where to paste the URL depends on the tool:
Customize › Connectors › + › Add custom connector. A connector added on claude.ai also works in the desktop and mobile apps. On Team and Enterprise, an owner adds it first under Organization settings › Connectors; on Free you can add one custom connector.', 'Anthropic', ], }, { label: 'Claude Code', cells: [ 'Runclaude mcp add --transport http formbase https://api.formbase.so/api/mcp, then type /mcp in Claude Code to sign in.',
'Anthropic',
],
},
{
label: 'ChatGPT',
cells: [
'Turn on developer mode, then Settings › Apps › Create. Creating and changing forms needs ChatGPT Business, Enterprise or Edu, on the web. On Business, a workspace admin turns on developer mode first.',
'OpenAI',
],
},
{
label: 'Codex',
cells: [
'Run codex mcp add formbase --url https://api.formbase.so/api/mcp, then codex mcp login formbase.',
'OpenAI',
],
},
{
label: 'Cursor',
cells: [
'Click Add to Cursor. Or add {"mcpServers": {"formbase": {"url": "https://api.formbase.so/api/mcp"}}} to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project.',
'Cursor',
],
},
{
label: 'VS Code',
cells: [
'Run MCP: Add Server from the Command Palette and choose HTTP.',
'Microsoft',
],
},
]}
/>
Any other tool that supports remote MCP servers with sign-in works the same way: look for where it adds a server by URL.
The first time the agent uses formbase, your AI tool opens a formbase page in the browser. Sign in if you are asked to. formbase then shows which tool is asking, what it may do, and the workspaces you belong to:
Pick the workspace and click Authorize. The browser returns to your AI tool. The connection reaches that one workspace only; to use another workspace, add formbase to your tool a second time and pick the other one.
Ask the agent something only formbase can answer:
``` List my formbase forms and whether each one is published. ```The agent calls formbase and answers with the forms in the workspace you picked. Some tools, like Claude Code, first say they are loading tool definitions: formbase offers all its tools at once, and the tool fetches the details of the ones a task needs.
> ℹ️ **Some actions ask first** >> Deleting a form, unpublishing it, canceling a request and a few other actions are marked for confirmation, and most AI tools ask you > before running them. The prompt comes from your AI tool, so check its own approval settings. The full list is in the{' '} > MCP server reference. >
In formbase, open OAuth and API Keys in the workspace sidebar. Your connection is listed under{' '} Connected apps, with when it was connected and last used:
Click the Disconnect button and confirm. The agent loses access at once, and asks you to sign in again the next time it needs formbase.
You need an AI tool with formbase connected. The prompts below are the ones this guide was tested with; any wording works, as long as it says what to ask and whether to publish.
Name the form, list what it should ask, and say that it stays a draft for now:
``` Build a formbase form called "[Guide] Supplier onboarding". Ask for the company name, a contact email, the company's VAT number, and whether they accept our 30-day payment terms (yes or no). Keep it as a draft and send me the preview link. ```The agent creates the form in the workspace you connected, adds one question at a time, and reads the form back to check the order. It picks a question type for each item: an email field for the contact email, a single choice for yes or no. When it is done, it replies with the questions it added and a preview link.
The preview link shows the draft as the recipient will see it, and it follows the agent's edits live, so keep it open while you ask for changes.
The same form is in formbase under Forms, where you can open it in the editor and change anything by hand. What the agent builds is an ordinary form.
Say what to change in the same conversation, naming the questions by their titles:
``` Make the VAT number optional and add a file upload for their certificate of incorporation at the end. ```The open preview shows the change as soon as the agent makes it:
Most of what you set in the editor, you can ask an agent for: required or optional, a description, choice options, conditional logic, the theme, translations. For long forms, ask for one part at a time and check the preview in between.
When the preview looks right, ask the agent to publish:
``` Looks good. Publish it, give me the link to share, and list each question's field key. ```The agent publishes the form and lists the field keys. The first publish always creates a share link anyone can open, and the agent gives it to you. An agent reads the keys from the published form, so asked before you publish, it says it cannot list them yet.
Each key comes from the question's title: Company name becomes company_name. Keys are how a request prefills a
question and how the answers come back, and they stay the same when you later rename a question.
An agent cannot choose a key. To shorten a long one, edit it in the editor's
Keys table, best before the first publish, while no automation uses it yet.
> Once published, anyone with the share link can submit the form. To take answers only from named people, ask the agent to revoke the > share link and send requests instead. >
You need an AI tool with formbase connected and a published form. This guide uses the one built in{' '} Build a form with an AI agent. What a request is, and every option it takes, is in{' '} Creating requests.
Say which form, who it goes to, what you already know, and how the link reaches them:
``` Send a formbase request with the "[Guide] Supplier onboarding" form to Ada Lovelace (ada@acme.example). Fill in the company name "Analytical Engines Ltd" and lock it so she cannot change it. Use supplier-2041 as the external ID. Don't email her; give me the link and I will send it myself. ```The agent finds the form, reads its field keys, and creates the request. It replies with the link for the recipient and when the request expires.
> Say send a test request while you try this out. A test request never emails > anyone and counts nowhere, so open the link yourself. The Requests page lists it only with the Show test requests > filter on. To look it up by external ID, tell the agent it is a test request. A test request cannot be reminded. >
The recipient opens the link and finds the company name filled in and locked:
The request shows in formbase under Requests, pending until the recipient submits and completed after:
The agent is not told when the recipient submits. Ask it, in the same conversation or a new one:
``` Has the formbase request supplier-2041 been answered? Show me the answers. ```The agent looks the request up by its external ID and, once it is completed, lists each answer. A file answer comes with a download link. If the form has a decision question, the reply also says whether the recipient approved, declined or asked for changes.
To act on answers without asking, have a workflow receive a callback when the request finishes, or start one from Zapier.
While a request is pending, ask the agent to remind Ada about supplier-2041 to send a reminder email now, or to cancel{' '} it. Reminders need the recipient's email and a Pro or Business plan. A request gets at most eight reminders, scheduled and manual together, and manual ones at least ten minutes apart; see{' '} Invitations, reminders & expiry. Canceling is permanent: the link stops working at once, and most AI tools ask you to confirm first.
You need a published form. This guide uses the one built in Build a form with an AI agent: company name, contact email, VAT number, a yes or no question about payment terms, and a file upload. Every method and option used here is described in API methods.
In formbase, open OAuth and API Keys in the workspace sidebar and{' '} create a token. The value is shown once. Keep it in an environment variable, not in your code:
``` export FORMBASE_TOKEN='fb_...' ```
A token reaches the one workspace it was created in. Every call below is a POST to the same URL with the token in the{' '}
Authorization header; the body names the method and its parameters.
Open the form in the editor. The form ID is the part of the address after /forms/:
The commands below use this guide's form ID. Put your own in its place.
A request fills in questions, and the answers come back, by field key. Ask the form for its keys instead of guessing them from the titles:
``` 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"}}' ```The reply lists each question of the published form. Shortened:
``` { "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 } } ```
To prefill a choice question, send the option's key, here "yes", not its label. A question with{' '}
prefillable: false, like the file upload, only the recipient can answer. The other flags are explained under{' '}
fields.list.
Send the request to Ada Lovelace, with the company name filled in and locked. test: true makes it a{' '}
test request: it never emails anyone and counts nowhere, so you can repeat this step
as often as you like, with a new idempotencyKey each time.
deduplicated: true instead of creating a second one.
The reply carries the request ID and the link for the recipient:
``` { "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" means formbase sent no email; you deliver the link yourself. To have formbase send the
invitation and reminders, add "delivery": "email", which needs a Pro or Business plan. See{' '}
Invitations, reminders & expiry. If the form has Send reminders on, a
real request with a recipient email still gets the scheduled reminders; add "reminders": [] to send none.
> The Requests page lists test requests only when you turn on the Show test requests
> filter. Open the url yourself to complete it. Drop test when you send the real thing.
>
Open the url in a browser. The company name is filled in and locked; answer the rest and submit. Then read the request back
with its ID:
Once status is completed, the reply holds two maps keyed by field key. answers is for code: a
choice answer is the option key, a file answer is a list of files with download URLs. display is for people: labels and file
names.
Asking again and again until the status changes works for a test, but not in production. Give the request a callbackUrl and
formbase calls you when it ends; the next guide sets that up.
You need an API token and a published form, as in Send a request with the REST API, and Node or Python on your machine. What a callback carries, and how retries work, is in Callbacks & signing.
formbase signs every callback with your workspace's request signing secret. Open OAuth and API Keys in the workspace sidebar and find the Request signing secret card:
Click the copy button and keep the secret in an environment variable in the terminal where your receiver will run:
``` export FORMBASE_SIGNING_SECRET='rqs_...' ``` > ⚠️ **Do not regenerate it** >> The third button makes a new secret, and the old one stops working at once, also for callbacks already on their way. You do not need it > to follow this guide. >
Save the verify function from Callbacks & signing next to your receiver: as{' '}
verify.mjs for Node, since it uses import, or as verify.py for Python. The receiver reads the raw
body, checks the signature, and only then parses the JSON:
Hash the body exactly as it arrived. Parsing it and turning it back into JSON changes the bytes, and the signature no longer matches.
Start the receiver:
``` node receiver.mjs # or: python3 receiver.py ```
formbase only calls public HTTPS addresses, so localhost will not do. While you test, a tunnel gives your machine one.{' '}
Cloudflare's quick tunnel
{' '}
needs no account. Run it in a second terminal:
It prints an address like https://horn-cod-classics-arab.trycloudflare.com. ngrok and similar tools work the same way. In
production, use your server's own HTTPS URL instead.
Create a test request as in the previous guide, and add callbackUrl with
the tunnel address. Use your own form ID:
Use a new idempotencyKey: the same key with a different body is rejected. Open the url from the reply, answer
the form, and submit.
A few seconds after you submit, the receiver prints the event type, your external ID and the answers. The Node receiver prints:
``` request.completed supplier-2044 {"certificate_of_incorporation":[{"name":"certificate-of-incorporation.pdf","size":635,"type":"application/pdf","url":"https://api.formbase.so/api/storage/...",...}],"company_name":"Analytical Engines Ltd","contact_email":"ada@acme.example","do_you_accept_our_30_day_payment_terms":"yes","vat_number":"GB123456789"} ```
To see a rejection, send the receiver any POST yourself, for example curl -X POST -d '{}' http://localhost:8787. It has no
valid signature, so the receiver prints rejected: bad signature and answers 401.
type.
{' '}
The same URL also hears request.expired and request.canceled, which carry no answers.
id. Store the ids you have handled and skip a repeat.
test.
{' '}
A callback from a test request has "test": true. Drop test from
requests.create for real recipients.
If your receiver was down for longer than the retries last, the answers are not lost. Read them with requests.get, or send
the callback again with requests.replayCallback or from the{' '}
Requests page.