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.