Skip to content

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.

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.

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.

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.

  • Unpublished or missing internal forms return 404.
  • A user outside the audience or reviewer assignment receives 403.
  • Invalid requests return 400; invalid answers return 422 with 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.