Forms

The Forms API allows you to retrieve information about forms, surveys, and assessments created in your organisation. Forms are used for applications, surveys, progress reports, scorecards, and session plans.

List Forms

Retrieve a paginated list of forms with optional filtering.

Endpoint

GET /api/v1/forms

Query Parameters

Pagination:

• limit (number, default: 100, max: 250) - Maximum number of forms to return
• offset (number, default: 0) - Number of forms to skip for pagination

Filtering:

• type (string) - Filter by form type:
  • application - Application forms
  • survey - Survey forms
  • anonymous - Anonymous surveys
  • progress-report - Progress report forms
  • scorecard - Assessment scorecards
  • session-plan - Session planning forms
• isArchived (boolean) - Filter by archive status
• formFor (string) - Filter by who the form is for:
  • Members
  • Volunteers
  • Partners

Response

{
  "forms": [
    {
      "formId": "form_abc123",
      "name": "Client Intake Survey",
      "type": "survey",
      "managedBy": "org123",
      "description": "Initial assessment survey for new clients",
      "questionCount": 15,
      "sections": [
        {
          "title": "Personal Information",
          "description": "Basic contact details",
          "id": "section_1"
        },
        {
          "title": "Support Needs",
          "description": "Understanding your requirements",
          "id": "section_2"
        }
      ],
      "settings": {
        "isArchived": false,
        "isAnonymous": false,
        "individualMode": true,
        "requiresLogin": false,
        "coverPage": true,
        "afterSubmitMessage": "Thank you for completing this survey.",
        "hideQuestionNumbers": false,
        "calculateOverallScore": false,
        "scoreDirection": "ascending"
      },
      "linkedFormId": null,
      "assessmentFormId": null,
      "allowMultipleApplications": false,
      "deadline": "2025-03-31T23:59:59.000Z",
      "schemaForm": false,
      "formFor": "Members",
      "addPersonPublic": false,
      "created": "2025-01-01T10:00:00.000Z",
      "updated": "2025-01-15T14:30:00.000Z"
    }
  ],
  "offset": 0,
  "limit": 100,
  "total": 25
}

Example Requests

List all forms:

curl -X GET "https://app.plinth.org.uk/api/v1/forms" \
  -H "x-api-key: sk_your_api_key"

Filter by type:

curl -X GET "https://app.plinth.org.uk/api/v1/forms?type=survey" \
  -H "x-api-key: sk_your_api_key"

Filter active forms for members:

curl -X GET "https://app.plinth.org.uk/api/v1/forms?isArchived=false&formFor=Members" \
  -H "x-api-key: sk_your_api_key"

Get Single Form

Retrieve a specific form by ID, including full question details.

Endpoint

GET /api/v1/forms/:formId

Path Parameters

• formId (string, required) - The unique identifier of the form

Response

{
  "form": {
    "formId": "form_abc123",
    "name": "Client Intake Survey",
    "type": "survey",
    "managedBy": "org123",
    "description": "Initial assessment survey for new clients",
    "sections": [
      {
        "title": "Personal Information",
        "description": "Basic contact details",
        "id": "section_1"
      },
      {
        "title": "Support Needs",
        "description": "Understanding your requirements",
        "id": "section_2"
      }
    ],
    "questions": [
      {
        "questionId": "q_001",
        "title": "What is your full name?",
        "type": "text",
        "section": 0,
        "required": true,
        "order": 1,
        "options": [],
        "description": "",
        "outcome": null,
        "validation": {
          "minAllowed": null,
          "maxAllowed": null,
          "wordCount": null
        },
        "hasConditions": false
      },
      {
        "questionId": "q_002",
        "title": "How did you hear about us?",
        "type": "select",
        "section": 0,
        "required": true,
        "order": 2,
        "options": [
          { "label": "Word of mouth", "value": "word_of_mouth" },
          { "label": "Social media", "value": "social_media" },
          { "label": "Website", "value": "website" },
          { "label": "Referral", "value": "referral" },
          { "label": "Other", "value": "other" }
        ],
        "description": "Select the option that best applies",
        "outcome": null,
        "validation": {},
        "hasConditions": false
      },
      {
        "questionId": "q_003",
        "title": "Please describe your support needs",
        "type": "textarea",
        "section": 1,
        "required": false,
        "order": 3,
        "options": [],
        "description": "Tell us about what support you're looking for",
        "outcome": "support_needs",
        "validation": {
          "wordCount": 500
        },
        "hasConditions": true
      }
    ],
    "settings": {
      "isArchived": false,
      "isAnonymous": false,
      "individualMode": true,
      "requiresLogin": false,
      "coverPage": true,
      "afterSubmitMessage": "Thank you for completing this survey.",
      "hideQuestionNumbers": false,
      "calculateOverallScore": false,
      "scoreDirection": "ascending"
    },
    "created": "2025-01-01T10:00:00.000Z",
    "updated": "2025-01-15T14:30:00.000Z"
  }
}

Example Request

curl -X GET "https://app.plinth.org.uk/api/v1/forms/form_abc123" \
  -H "x-api-key: sk_your_api_key"

Response Fields

Form Object (List)

Question Object

Question Types

Forms support the following question types:

Text Input Types

Selection Types

Specialised Input Types

Media & File Types

Display Types (Non-Interactive)

Settings Object

Error Responses