A form is a reusable design. A request is one assignment of that design to one named person — with their data already filled in, their case number attached, and a callback waiting for the moment they finish.
You do not build a different form for this. Any published form can be sent as a request. Nothing about the form changes; what changes is who opens it and what your automation knows when they are done.
In the Share sheet, a published form has two tabs — Public link and Requests. These are the two{' '} channels a form reaches people through, and a form can use both at once. The public link goes on your website; requests go to the three suppliers you are chasing this week. Same form, same submission inbox.
> ℹ️ **Three ways to create a request** >> Open a published form, press Share, and pick the Requests channel. The Manual tab > creates one request by hand — fill in the recipient, prefill what you know, and press Send invitation or{' '} > Create link. The curl and MCP tabs hand you a ready-made snippet for the same thing > from Make, Zapier, Claude, or a direct API call. >
>> A request made by hand behaves exactly like one an automation created: same lifecycle, same reminders, same signed callback.{' '} > Try it yourself creates a test request addressed to you and hands you its link — nothing is emailed — so you can walk > the whole flow through before you wire anything up. >
> ℹ️ **Step by step in Zapier and n8n** >> The Zapier guides walk through it click by click:{' '} > send a request from a Zap, act on its outcome, > and look it up, remind or cancel it. The same three jobs have{' '} > guides for self-hosted n8n. >
requests.create with a form id, the recipient, and any values you already know.
https://form.formbase.so/r/rq_…. It opens as many
times as the recipient needs, from any device.
If they never finish, reminders chase them on a schedule, and the request eventually expires. Either way your automation is told — the callback fires on expiry and cancellation too, so a workflow run is never left hanging.
Completed, expired, and canceled are terminal: the link keeps working but shows an outcome page — a receipt, or a plain "this request has expired" notice — instead of the form.
While a request is pending, formbase also records when it was first opened, when the first answer was saved, and the last activity. That is what the Requests page means by "not opened", "opened", and "in progress" — activity, not extra statuses.
Open your published form, click Share, and pick the Requests tab. The card there gives you everything you need to make the first call:
> An unpublished form cannot be requested, and the snippets stay disabled until you publish. Field keys are frozen at first publish — that
> is what lets your automation keep addressing company_name a year later. See Field keys.
>
fields.list returns every field of the form's current published version, with the key to address it by, the value shape it
takes, and which bucket it belongs in.
context: true marks a hidden field. Its value goes in context, never in prefill; a hidden field's
key in prefill is rejected with UNKNOWN_FIELD_KEY.
calculated: true marks a calculated field. The form works out its value, so nothing can send one; you read it back under
its key in answers.
prefillable: false marks a field nobody can supply a value for: file upload, signature, payment, appointment booking, and
Documents blocks. The recipient fills in the questions themselves. Hidden fields and calculated fields also show{' '}
prefillable: false: hidden fields take context, and calculated fields take nothing.
options lists the choices for a choice question. Send the option's key, not its label; the label is there
so you can match the choice you know to its key. A matrix lists its rows and columns the same way.
type: "group", repeating: true, and a list of{' '}
members.
deliveryStatus is "queued" when formbase emails the invitation and "not_requested" when you deliver
the link yourself.
Three different things can be attached to a request, and mixing them up is the most common first mistake.
Initial answers for the visible questions, so the recipient reviews and corrects instead of typing from scratch. Everything you already know about them belongs here — the company name from your CRM, the amount from the invoice, last year's answers.
List a prefilled key in readonly and the recipient sees the value but cannot change it. Use it for the facts they are
confirming rather than supplying — the contract number, the agreed price. Locking is per request: the form itself is untouched, and the
same field is freely editable on the next request.
Every locked key must also be prefilled, and a locked required field must be prefilled with something non-empty — otherwise the recipient would face a form they could never submit, and formbase rejects the call instead of creating that trap.
Trusted values for the form's hidden fields — a case number, a workflow run id, an amount. Context feeds variables, conditional logic, calculated fields, and email copy, comes back unchanged in the callback, and the recipient cannot alter it. That last part is the difference from seeding a hidden field through a URL on a public link, where anyone can edit the query string; request links ignore URL query parameters entirely. Context values must be a string, number, or boolean.
Context is not free-form: every key must be a hidden field on the form's published version, and any other key is rejected with{' '}
UNKNOWN_FIELD_KEY. Bookkeeping that has no hidden field, like an execution id, belongs in metadata.
Hidden fields are not shown on the form, but a context value is not secret from the recipient. They see it wherever the form or the
invitation shows it: a mention in the form content or email copy, or a visible question that
uses that hidden field as its default value. In that last case the
recipient sees the context value pre-filled in that question and can edit the answer. The context value itself stays unchanged. A{' '}
prefill for that question's own key wins over the default.
Your own bookkeeping — an execution id, a CRM record id. It never reaches the form at all, so it cannot be piped into copy or read by logic; it just rides along and comes back in every callback and status read.
Send values in the shape the type from fields.list asks for. A wrong shape comes back as a validation error
naming the key, the expected type, and — for choice questions — the values that would have been accepted.
A Documents block hands files to the respondent. Its authored files are the same for everyone and always stay; a request adds files for its one recipient below them — the customer's own lease contract, an ID copy to check. Bytes never travel through the API call itself: upload first, then reference.
``` "documents": [ { "documentId": "kn7...", "name": "Your lease contract" }, { "documentId": "kn8..." } ] ```
name overrides the display name stored on the upload. When the form has more than one Documents block, name the target with{' '}
field, the block's field key (fields.list lists it, together with the authored documents every respondent
already gets). The files land below those authored documents — a request adds files, it never replaces one. One upload can be referenced
by as many requests as you like — a price list uploaded once serves five hundred requests.
Limits: PDF and images only, 25 MB per document, 100 MB per request (DOCUMENTS_TOO_LARGE), and at most 20 documents per block
counting the authored ones (DOCUMENTS_TOO_MANY). The files count against your workspace storage and are freed once the
requests referencing them fall out of the form's retention window. The submission records the list the recipient saw under the block's
field key, so the callback tells you exactly which files this person was given.
Pass test: true to exercise the whole shape before a real run. A test request is real in every way that matters for wiring:
the link opens and can be completed, the callback fires as usual, and requests.get returns
the answers. What it never does is reach anyone or anything you would have to clean up afterwards:
delivery says. Send reminder is refused on it, and it
spends none of your monthly allowance.
"test": true, so your workflow can branch or ignore it.
requests.list unless you pass includeTest: true.
expiresAt asks for longer; the expiresAt in the response says when.
On Free, a workspace may create 10 test requests a day. The next one fails with RATE_LIMITED and reason{' '}
TEST_REQUEST_LIMIT_REACHED, and retryAfterMs says when you can try again. Pro and Business have no daily cap.
Try it yourself on the Share sheet is this mode with a single click: it takes the Manual tab's draft — prefill, locks, context, callback, expiry — addresses the request to your own account, sends no email, and hands you the link to open yourself.
Every plan has one monthly allowance shared by both channels: a share-link submission spends one unit, and so does every
request you create — whether the recipient answers, ignores it, or you cancel it. The submission a request collects is already paid for
and counts nowhere. Free includes 1,000 units a month, Pro and Business 50,000; the count resets on the 1st of each month, UTC. At the
cap, requests.create fails with UPGRADE_REQUIRED and reason MONTHLY_ALLOWANCE_REACHED; requests you
already created stay answerable.
On Free, a request created with "delivery": "email" also spends one of the account's{' '}
10 free invitations. They never reset; once they are gone, email
delivery fails with UPGRADE_REQUIRED and reason FREE_INVITATIONS_USED.
Pass the same idempotencyKey with the same body and you get the original request back, with deduplicated: true{' '}
and the original link — no second request, no second email. Reuse the key with a different body and formbase refuses with{' '}
IDEMPOTENCY_CONFLICT rather than guessing which one you meant. Keys are scoped to the workspace and honoured for 30 days;
after that the same key starts a new request.
In a workflow tool, the execution id is the natural key: a run that is retried after a network blip picks up the request it already created.
requests.create and documents.create share a budget of 60 calls a minute, counted per API token
(or per user, for a call made without one). A backlog you are draining should pace itself; a burst over the budget is refused and can be
retried.
If the form is already published on one of your custom domains, request links are minted
there automatically — https://forms.yourcompany.com/r/rq_…. Name domainId explicitly when the form is published
on more than one. The domain must belong to the same workspace as the form.
Exactly the form you authored — same theme, same logo, same language — with their values in place, locked fields read-only, and no captcha to solve. When they submit, they get your thank-you page. If they come back to the link afterwards, they get the outcome page instead of a blank form.
There is no message from your automation on the page. Anything the recipient needs to be told belongs in the form itself, where you can personalise it by mentioning a context value or a prefilled field.
An AI agent runs the same two steps as fields_list and request_create, with the same options — documents and{' '}
domainId included. See Requests on the MCP server.
Without field keys, an automation has to address your questions by internal ids that mean nothing to anyone — and a webhook payload arrives full of them. With field keys, both sides read the same way:
``` { "company_name": "Acme", "employees": 120, "contacts": [{ "name": "Ada" }] } ```
Field keys are used in two places: prefill, context, and readonly when creating a request; and the{' '}
answers and display maps in every callback and every webhook payload.
Every key the form publishes lives in one place, the Keys table: each field, and under a choice question each option,
under a matrix each row and column. It ends with a preview of the answers object your callback will carry, with your keys in
it.
Each option's hint row — the grey line under the option you are editing — ends with its key as a chip. Click the chip to edit the key in place, press Enter or Escape when done. A matrix shows the chip for the row or column whose label you are editing. A chip turns amber when the form is published and the key you typed would move the one automations already use.
The same table appears read-only where you wire an integration: under the webhook's field mapping, and under the request snippets in the
Share sheet's Requests card. You can also read every key at once with fields.list.
You do not have to set anything. Until you edit it, a key is derived from the question's title: accents are folded and letters such as ø, æ and ß become o, ae and ss, everything is lowercased, each run of anything that is not a letter or digit becomes a single underscore, leading and trailing underscores are dropped, and the result is cut to 64 characters.
A title written only in a non-Latin script, such as Arabic, Hebrew, Cyrillic, Greek, Chinese or Japanese, has nothing to fold, so its key
is field_ plus its position, and an option's is option_ plus its position. These keys are as stable as any other
once published, but they say nothing about the question. When an automation reads the answers, set a readable key yourself in the Keys
table.
If two fields would end up with the same key, formbase breaks the tie in document order by appending _2, _3, and
so on. A key you set yourself always wins its claim, and the derived one yields.
Type a name in the Field key input to override the derived one. Clearing the input goes back to the derived key. Allowed characters are
letters, digits, _, . and -, up to 64 characters — anything else is refused with{' '}
"Use only letters, numbers and _ . - (max 64 characters)." Spaces are turned into underscores as you type, so "contact name"
becomes contact_name.
Keys are case-sensitive and must be unique within one form. Reusing one already taken by another question, repeating group, hidden field, or calculated field is refused with "Another field already uses this key."
> On a published form, the Field key input warns you that the form is published and automations using the current key will break. Nothing > stops you, but every workflow that prefills or reads that key stops matching the moment you publish the change. Update the automation in > the same sitting. Publish warns you again before the change goes live. >
The first time you publish, every field's key is written into that published version. Every later publish carries the same keys forward, which means:
company_name.
Your automations keep working; only the words on the page change.
_2; derived keys are made unique at publish.
Publishing is also where key collisions are caught, and both of them stop the publish rather than silently renaming a field:
Both show up beside the Publish button with every other pre-flight finding — see{' '} Publish checks.
A key belongs to the field it was published on, not to its title. So there are two ways to lose one without meaning to: type a different key on a published field, or delete a question and add a new one in its place. The new question is a new field — it gets a fresh key derived from its own title, and the old key is gone.
Nothing fails on formbase's side when that happens. The webhook still fires and the callback still arrives, only without that answer, and{' '}
requests.create starts refusing the old key with UNKNOWN_FIELD_KEY. So publish checks for it first. When a key
the live version publishes would not exist in the next one, the publish dialog and the issue indicator beside the Publish button show a
warning:
form_publish returns the same messages in warnings.
A repeating group has its own key, and so does each field inside it. Automations address the group as a whole and nest the members:
``` { "contacts": [{ "name": "Ada", "email": "ada@acme.com" }, { "name": "Grace", "email": "grace@acme.com" }] } ```
A field inside a group is only reachable through its group — there is no top-level name here, only{' '}
contacts[0].name. Rename the group's key and the whole array moves; rename one member's key and only that name inside each
object changes.
A hidden field's parameter name is its field key. That is the key you put in{' '}
context when creating a request, and the same name you would use in a URL parameter on a public link.
A calculated field's name is its field key, and it shares the form's one set of keys with
everything else. It is read-only: the form works out its value, so you can never send one — fields.list lists it with{' '}
calculated: true and requests.create refuses it in prefill and context. You do read it
back: it arrives in answers under its name (answers.total). Renaming a published calculated field renames its
key, with the same publish warning as any other field.
The parts of a question that an answer names get keys too. Every option of a radio, select, checkbox, picture choice or ranking question, and every row and column of a matrix, has an option key: derived from its label the same way a field key is derived from a title, editable, and frozen at publish. So an answer reads as a name on both sides:
``` { "plan": "pro", "interests": ["billing", "api"], "satisfaction": { "delivery_speed": "very_good" } } ```
A workflow branches on answers.plan == "pro" whatever language the respondent answered in, and a request prefills a choice
with {'{ "plan": "pro" }'}. The keys are listed by fields.list under each field's options, or a
matrix's rows and columns, and edited in the Keys table or on the option's chip. Each
question's options are their own namespace, so two questions may both have a yes, and a matrix row and column may share a
key. Two options of one question that would derive the same key are told apart with _2, like fields.
The decision question is an ordinary radio whose three options carry the keys{' '}
approve, decline and changes; that is what makes a request's outcome a closed set.
Every choice already has an option key, so a workflow can branch on any radio. What a
workflow cannot do is know, across every form that has an approval, which key means "yes": one author's radio says sign_off,
another's approved.
The decision question fixes the names. It is a single-choice question with the field key decision, whose
three options carry the option keys approve, decline and changes. Its labels stay yours to reword
and translate; the keys underneath never move. When the recipient picks one, the request ends with an outcome. Any radio
keyed decision whose options carry those three keys counts — the preset just sets them for you.
> The outcome is read from the question whose field key is decision, and only when the chosen option's key is one of the
> three. A radio you build by hand with options labelled Approve, Decline and Changes derives exactly those keys, so it works without the
> preset; a radio with other labels works once you type the three keys in the Keys table.
>
These three values are a public contract, like a field key: an automation, an agent, and a spreadsheet formula all read them.{' '} Add a fourth option and picking it is an ordinary answer, not a verdict — that request completes with no outcome, rather than with a value your receiver has never heard of.
Branch on data.request.outcome. status says whether the request finished; outcome says what
the recipient decided. An expired or canceled request has a status and no outcome, and so does a completed request on a form without a
decision question.
The MCP tool is editor_insertDecisionQuestion, taking a title and the three labels in the form's language. An agent that
cannot host a callback endpoint polls request_get instead and reads outcome when the status leaves{' '}
pending. Requests on the MCP server →
> Every request comes back with a url. You can send it yourself — in your own email, a Slack message, an SMS — or ask
> formbase to email it. Sending it yourself works on every plan. Letting formbase send invitations and reminders requires a{' '}
> Pro or Business plan; a Free account can have formbase email its first 10 invitations to try it (see{' '}
> free invitations).
>
Create a request with delivery: "email" and a recipient email address, and formbase sends the{' '}
request invitation: a short email carrying a button that opens the request link.
You author it once per form, not once per request. In the editor, open Settings → E-mail Notifications and scroll to the{' '} Requests group at the bottom:
There is no free-text message from the caller — an automation cannot inject a paragraph into this email. What it can do is supply values: mention a context field or a prefilled field in the subject or body and each recipient gets their own version. That keeps the copy under your control while still reading as if it were written for them.
> 💡 **Translate it** >
> If the form has published languages, the invitation follows the request's language. Translate the email copy alongside the
> rest of the form — see Translating form content.
>
requests.remind carries the same link and counts against the eight-reminder cap. On
Free, where reminders aren't available, copy the request's link and send it yourself.
A reminder schedule is an ordered list of idle offsets — 1 day, 3 days, 1 week — after which formbase emails someone who has gone quiet. One schedule serves two kinds of target: a public-link respondent sitting on an unfinished draft, and a request recipient who has not completed.
It lives in Settings → E-mail Notifications → Send reminders. That switch is the master: turn it off and neither channel gets the form's schedule.
An automation can pass its own reminders when creating a request — ["2d","5d"] for a schedule of its own, or an
empty list to switch reminders off for that one request. An explicit schedule wins even over the form's master switch, because a caller
that passed one asked for reminders on this request specifically.
Leave reminders out and the request inherits the form's schedule, if the master switch is on and the request has a recipient
address.
You do not have to wait for the next step. Send reminder in the request drawer — or requests.remind from an
automation — queues one immediately. The automatic schedule is untouched: the next scheduled reminder still lands when it was going to.
Two floors apply: at least ten minutes between manual reminders, and the same overall ceiling of eight per request.
Every request has a hard end. When it passes, the link stops working, the status becomes expired, and your automation is told through the callback — so a workflow that has been parked for a month resumes instead of hanging forever.
expiresAt as a millisecond timestamp to set your own.
expiresAt within a quarter of an
hour. The link itself stops opening the moment the expiry passes.
All three arrive at the same URL, so branch on type before assuming there are answers. That is the whole point of firing on
every ending: a workflow parked on a customer resumes whether they answered, ignored you, or were called off.
data.request is always there — including your externalId, metadata, and context,
unchanged. It carries the timestamp of whichever ending happened (completedAt, expiredAt, or{' '}
canceledAt with an optional cancelReason).
outcome is present only when the recipient answered a decision question —{' '}
approve, decline, or changes.
form, submission, answers and display appear on completion only, in exactly the
shape a submission webhook carries. form.snapshotId is the exact
published version the recipient answered; submission.pdfUrl is a URL only when the form retains a submission PDF, and null
otherwise.
test is true when the request was created in test mode —
branch on it, or drop the event.
answers is keyed by field key, with repeating groups nested as one object per instance.
A choice answer is the option key from fields.list, not its label; the label is in display,
under the same key.
Content-Type: application/json with User-Agent: formbase, and carries{' '}
X-formbase-Event-Id, X-formbase-Event-Type and X-formbase-Signature — so you can dedupe and route
before parsing.
> id is stable across every retry and every replay of the same event. If your receiver might act twice on the same id — a
> duplicate invoice, a duplicate ticket — remember the ids you have already handled.
>
Every callback carries a signature header, X-formbase-Signature: t={unix seconds},sha256={hex}. The hex
is an HMAC-SHA256 of the timestamp, a dot, and the raw request body, computed with your workspace's{' '}
request signing secret.
Two rules, whatever language you use:
crypto.timingSafeEqual, hmac.compare_digest — never with ==.
One secret per workspace signs every callback from it. Find it on OAuth and API Keys in the workspace sidebar, in the{' '}
Request signing secret card. It is masked by default; Reveal secret shows it and the copy button copies
it. It is not a one-time value — you can come back and read it again. The secret is minted the first time it is needed, so a workspace
that has never opened that card and never created a request with a callbackUrl has none yet.
> Only the workspace owner can regenerate the secret, and the moment they do, the old one stops working — including for callbacks that are > already being retried. Update your receiver first, then regenerate. There is no window where both secrets are accepted. >
A callback gets eight attempts: the first, then seven retries at least 1, 2, 4, 8, 16, 32 and 60 minutes apart. formbase
looks for due retries every 30 minutes, so a retry can come up to half an hour after its gap ends, and the last attempt comes about four
hours after the request ended. Every attempt carries the same bytes and the same id: the payload is frozen at the moment the
request ended, so a retry describes what happened then, not what the request looks like now. The destination URL and the signing secret
are read at each attempt, not frozen with it.
If the budget runs out — your receiver was down for the afternoon — the callback is not lost. The request gets a{' '}
Callback failed badge, the workspace owner is emailed once with the host, the reason and the attempt count, and the
answers stay readable through requests.get. To push it again, open the request in the{' '}
Requests page and press Replay, or call requests.replayCallback.
It re-sends the same frozen payload with the same id, which is exactly what a receiver that deduplicates wants.
A callback URL belongs to one request. When every request on a form should reach the same receiver, subscribe once instead: the formbase
apps for Zapier and n8n do this for you, and webhooks.create does it from code with request_completed,{' '}
request_expired or request_canceled as the event type. A subscription receives this same envelope, signed with
its own secret rather than the workspace request signing secret, with its own event id and its own retry budget. A request that has both a
callback URL and a matching subscription fires twice, once to each. Replay re-sends the callback only; a subscription
retries on its own and pauses after five failed attempts.
> Workflow tools hand you a hard-to-guess resume URL and it is tempting to treat that as proof. It is a bearer secret — it can leak into > logs, and it does not tell you the body was not tampered with. Verify the signature in the resumed branch as well. >
Click Requests in the sidebar, between Forms and Trash. Each card is one request: the recipient, the form it belongs to, its status, and — for a pending one — where it has got to.
Sort by Created, Last activity, or Name — click the field again to flip the direction. Search matches the recipient name, the recipient email address, and the external id. Filter by status (Pending, Completed, Expired, Canceled), by outcome (Approved, Declined, Changes requested), by form, or by{' '} Callback failed when you are hunting for deliveries to replay. Test requests are hidden until you tick{' '} Show test requests in the same filter.
Two shortcuts land you here pre-filtered: Open Requests on the Share sheet's Requests card, and the "pending requests" link above a form's submissions list.
Click a card to open the drawer. Its address bar keeps the request id, so you can share the link with a colleague or bookmark it.
> It is derived from the request's own timestamps plus its delivery attempts. Delivery rows are cleaned up after 30 days, so an old > request's timeline thins back to the milestones — created, opened, completed — while the email and callback lines drop away. >
Cancel, replay, and copy link work on every plan. Cancelling asks first; after it, the recipient sees a withdrawn notice instead of the form. Everything else acts immediately and confirms with a toast.
Try it yourself on the Share sheet's Requests card creates a request in{' '} test mode from the Manual tab's draft and shows you its link. Nothing is emailed: open the link yourself to walk through the form as the recipient would. The request shows in this list, with a Test badge, once you tick Show test requests.
Every rejection carries two things: a code for the kind of failure, and a details.reason for the specific cause.
Branch on the code; read the reason to know what to fix. Where it helps, details also names the offending field,
the keys that would have been accepted, or the option keys a choice question takes.
The request methods use four codes: VALIDATION_ERROR (the call was wrong), CONFLICT (the request is in the wrong
state, or an idempotency key was reused), NOT_FOUND, and UPGRADE_REQUIRED (a plan gate or the monthly
allowance). Calling too fast returns RATE_LIMITED instead, with retryAfterMs — see{' '}
the rate limit.
Open the request in the Requests page and read the timeline. The first invitation line tells you which case you are in.
> ℹ️ **No timeline entry at all** >
> Then no email was ever asked for. The request was created with delivery: "none" — deliver the link yourself, or create a
> new request with delivery: "email".
>
Invitations and reminders share a budget of ten emails per day per form and recipient address, and a request never emails its recipient more than nine times in its life — one invitation and up to eight reminders.
The request drawer's Callback section shows the URL and the outcome. Callback failed after N attempts means formbase tried and gave up — eight attempts over about four hours.
> Almost always the raw body. If you parse the JSON and re-serialize it before hashing, the bytes differ and the signature will never > match. Hash the body exactly as it arrived. The other common cause is a regenerated signing secret that the receiver has not picked up — > there is no grace period. >
requests.create began refusing a key with UNKNOWN_FIELD_KEY. A published field key disappeared: someone
retyped it, or deleted the question and added a new one in its place. Retitling is safe; both of those are not. Type the old key on the
field (toolbar key icon → Keys) and publish again. Publish warns before this happens — see{' '}
When a published key is about to disappear.
fields.list{' '}
marks them prefillable: false.
idempotencyKey. Pass the execution
id as the key.