Form requests API
Use these authenticated operations to fill in an internal form, review requests,
and create projects after the configured approval. Use a generated user token
bound to the form’s organisation. The same operations are available through
MCP’s API bridge.
MCP write calls require confirm: true after the user authorises the change.
The user needs active workspace membership. A form’s published audience controls submission; its reviewer assignments control review. Form managers can administer review, while general submission-read permission alone does not permit decisions. Client-scoped sessions cannot use these workspace operations. Form design and publication remain in Studio, outside this API.
Operations
Section titled “Operations”Paths below start at /api/v1/form-requests.
| Method and path | Use |
|---|---|
GET /available?organizationId=ID |
List accessible forms with canSubmit and canReview flags. |
GET /:id/fill |
Read the published internal form’s fields. |
POST /:id/fill/lookup |
Load approved options with { "fieldKey": "client" }. |
POST /:id/fill/upload |
Upload a permitted file as multipart fieldKey and file. |
POST /:id/internal-submit |
Submit { "answers": { "title": "Summer launch" } }, using the actual field keys. |
GET /:id/review |
Read form metadata and workflow for review. |
GET /:id/submissions |
List authorised submissions; optional status, limit and offset. |
GET /submissions/:id |
Read original answers, recipients, events and available workflow. |
POST /submissions/:id/recipients/:rowId/decision |
Record { "decision": "approved" } or "rejected". |
POST /submissions/:id/transition |
Move to a permitted status with { "toStatus": "approved", "reason": "Reviewed" }. |
POST /submissions/:id/create-project |
Retry an authorised project action that attaches the submitted form. |
A decision records a reviewer’s vote. A transition moves the request and runs its configured actions after the approval policy is met. Use the returned workflow rather than assuming every form uses the same status names.
Review through the shared approvals inbox
Section titled “Review through the shared approvals inbox”A submitted request with internal reviewers and an upcoming approval transition
creates a shared approval as part of the submission. The submission fails if its
required approval cannot be saved. Any reviewer uses policy any; explicit
sequential and parallel policies retain their rules. The authenticated submitter
is the requester, but their submission does not automatically cast a vote.
Use the Approvals API or the named MCP approval tools
to read and decide the approval. Its subjectType is form_submission and its
subjectId identifies the submission. Read GET /submissions/:id for the actual
answers and permitted workflow. An approved vote and a completed workflow are
separate: use the configured transition to run project actions. An Any reviewer
transition returns 409 while its approval is pending or closed without approval.
Delegated or reassigned approvers can read and act on their exact assigned request with current workspace membership and approval access. This does not grant access to the form-wide list or editor. Submitters can read their own exact request as viewers. Financial visibility continues to apply to the answers.
Check project creation
Section titled “Check project creation”A successful transition does not guarantee every action succeeded. Read the
submission events: action_run can include payload.projectId; action_failed
records an unsuccessful action. Correct the cause before retrying. Retrying a
project action that attaches the submitted form reuses its existing project.
The retry operation cannot bypass an outstanding approval. Older actions that
only map answers into a separate record form do not support this retry operation.
Read GET /api/v1/projects/:id/intake-form for the created project’s original
form and answers. The response has an intake object containing formId,
submissionId, versionId, referenceCode, submittedAt, definition,
answers and financiallyRedacted, or null when there is no source request.
Project visibility applies. Financial values and dependent fields are omitted
when the user lacks the required financial access. The original answers are
read-only and remain available after the form is unpublished.
Refusals
Section titled “Refusals”- Unpublished or missing internal forms return
404. - A user outside the audience or reviewer assignment receives
403. - Invalid requests return
400; invalid answers return422with validation findings. - An inactive membership can invalidate the credential before the operation runs.
- A form from another organisation cannot be accessed with this organisation’s token.
See Forms Engine for the publishing and approval workflow, and project record tools for separate editable project details forms.