​
Overview

Forms allow collecting data from users (including external users without an Obeya Cloud account) and automatically creating items on a board from submissions. The form builder is powered by form.io.

​
List Forms

List all forms associated with a board. 
GET /api/trpc/forms.list?input={"json":{"boardId":"brd_01HXK5..."}}
Response: 
{
  "result": {
    "data": {
      "json": {
        "forms": [
          {
            "id": "frm_01HXK5QJBN3YZXM8KJP2RSNV4C",
            "boardId": "brd_01HXK5...",
            "name": "Bug Report",
            "description": "Submit a bug report",
            "status": "published",
            "publicUrl": "https://acme.obeya.cloud/forms/frm_01HXK5...",
            "submissionCount": 34,
            "fieldCount": 8,
            "requireAuth": false,
            "createdBy": "usr_01HXK5...",
            "createdAt": "2026-02-20T10:00:00.000Z",
            "updatedAt": "2026-03-10T14:00:00.000Z"
          }
        ]
      }
    }
  }
}

​
Get Form

Retrieve a form with its field definitions and column mappings. 
GET /api/trpc/forms.get?input={"json":{"id":"frm_01HXK5..."}}
Response: 
{
  "result": {
    "data": {
      "json": {
        "id": "frm_01HXK5QJBN3YZXM8KJP2RSNV4C",
        "boardId": "brd_01HXK5...",
        "name": "Bug Report",
        "description": "Submit a bug report for the platform",
        "status": "published",
        "schema": {
          "components": [
            {
              "type": "textfield",
              "key": "title",
              "label": "Bug Title",
              "validate": { "required": true }
            },
            {
              "type": "textarea",
              "key": "description",
              "label": "Description",
              "validate": { "required": true }
            },
            {
              "type": "select",
              "key": "severity",
              "label": "Severity",
              "data": {
                "values": [
                  { "label": "Critical", "value": "critical" },
                  { "label": "Major", "value": "major" },
                  { "label": "Minor", "value": "minor" },
                  { "label": "Trivial", "value": "trivial" }
                ]
              }
            },
            {
              "type": "file",
              "key": "screenshots",
              "label": "Screenshots",
              "multiple": true
            }
          ]
        },
        "mappings": [
          { "formField": "title", "columnId": null, "target": "item_name" },
          { "formField": "description", "columnId": null, "target": "item_description" },
          { "formField": "severity", "columnId": "col_01HXK5...", "target": "column" },
          { "formField": "screenshots", "columnId": "col_01HXK6...", "target": "column" }
        ],
        "settings": {
          "successMessage": "Thank you! Your bug report has been submitted.",
          "redirectUrl": null,
          "notifyOnSubmit": ["usr_01HXK5..."],
          "groupId": "grp_01HXK5...",
          "requireAuth": false,
          "allowMultiple": true
        },
        "publicUrl": "https://acme.obeya.cloud/forms/frm_01HXK5...",
        "createdAt": "2026-02-20T10:00:00.000Z"
      }
    }
  }
}

​
Create Form

Create a new form linked to a board. 
POST /api/trpc/forms.create
Request: 
{
  "json": {
    "boardId": "brd_01HXK5...",
    "name": "Feature Request",
    "description": "Submit a feature request",
    "schema": {
      "components": [
        {
          "type": "textfield",
          "key": "title",
          "label": "Feature Title",
          "validate": { "required": true }
        },
        {
          "type": "textarea",
          "key": "description",
          "label": "Describe the feature"
        },
        {
          "type": "select",
          "key": "priority",
          "label": "How important is this?",
          "data": {
            "values": [
              { "label": "Must have", "value": "critical" },
              { "label": "Nice to have", "value": "low" }
            ]
          }
        }
      ]
    },
    "mappings": [
      { "formField": "title", "target": "item_name" },
      { "formField": "description", "target": "item_description" },
      { "formField": "priority", "columnId": "col_01HXK5...", "target": "column" }
    ],
    "settings": {
      "groupId": "grp_01HXK5...",
      "requireAuth": false,
      "successMessage": "Thank you for your suggestion!"
    }
  }
}

​
Update Form

POST /api/trpc/forms.update

{
  "json": {
    "id": "frm_01HXK5...",
    "name": "Updated Feature Request Form",
    "status": "published"
  }
}
StatusDescription
draftForm is not accessible to respondents
publishedForm is live and accepting submissions
closedForm is visible but no longer accepting submissions

​
Delete Form

POST /api/trpc/forms.delete

{
  "json": {
    "id": "frm_01HXK5..."
  }
}
Deleting a form does not delete items created from its submissions. The items remain on the board.

​
List Submissions

View submissions for a specific form. 
GET /api/trpc/forms.submissions.list?input={"json":{"formId":"frm_01HXK5..."}}
Input Parameters:
ParameterTypeRequiredDescription
formIdstringYesForm ID
cursorstringNoPagination cursor
limitnumberNoResults per page (default: 50)
statusstringNoFilter: new, reviewed, archived
Response: 
{
  "result": {
    "data": {
      "json": {
        "submissions": [
          {
            "id": "sub_01HXK5...",
            "formId": "frm_01HXK5...",
            "data": {
              "title": "Add dark mode support",
              "description": "It would be great to have a dark mode option...",
              "priority": "critical"
            },
            "itemId": "itm_01HXK5...",
            "status": "new",
            "submittedBy": null,
            "submittedAt": "2026-03-19T14:30:00.000Z"
          }
        ],
        "nextCursor": null
      }
    }
  }
}
The submittedBy field is null for anonymous submissions (when requireAuth is false). When authentication is required, it contains the submitting user’s ID.

​
Submit Form (Public)

Submit a form response. This endpoint is publicly accessible for published forms that do not require authentication. 
POST https://acme.obeya.cloud/api/forms/frm_01HXK5.../submit
Content-Type: application/json

{
  "title": "Mobile app crashes on login",
  "description": "The app crashes when I try to log in with Google OAuth...",
  "severity": "critical",
  "screenshots": ["file_01HXK5..."]
}
Response: 
{
  "success": true,
  "message": "Thank you! Your bug report has been submitted.",
  "submissionId": "sub_01HXK5..."
}