Introduction to Lendsqr’s custom form builders

A custom form builder is a tool that allows lenders to design and configure the specific questions borrowers must answer when applying for a loan or service on their platform. Rather than relying on a fixed set of default fields, lenders can build forms that match the exact data they need and attach those forms to specific loan products.

Introduction

Consider this: A microfinance lender in East Africa offers three different loan products — one for salaried employees, one for small business owners, and one for students. Each product requires completely different information from the borrower. The salary product needs employment details and payslip uploads. The business product needs a trading name, sector, and revenue figures. The student product needs enrollment status and guarantor details. Rather than using one generic form that overwhelms borrowers with irrelevant questions, the lender builds a separate custom form for each product. Completion rates improve, and the credit team gets exactly the data they need for each application type.

This is what Lendsqr’s custom form builder makes possible: a tailored onboarding experience that works for your product, not against it.

Lendsqr’s custom forms are written in a structured data format that gives lenders full control over input types, validation rules, page flow, and the order in which questions are presented to borrowers.

Read more: Why Lendsqr is Africa’s most affordable loan management software

Understanding the JSON Structure

Custom forms on Lendsqr are built using a structured data format organized into several components. Understanding how these fit together makes it much easier to build forms that work correctly the first time.

1. Meta Section

This section defines the form’s metadata:

  • name: The form’s name.
  • description: A brief explanation of the form’s purpose.
  • version: The form’s version.
  • url: The platform link where the form is hosted.
  • status: Indicates if the form is active.
"meta": {
  "name": "Test Org Inc.",
  "description": "Customized application flow for Test Org Inc.",
  "version": "1.0",
  "url": "https://test-org.lsq.app",
  "status": "active"
}

2. Pages

The pages array contains multiple sections of the form. Each page has:

  • name: The page identifier.
  • title: The page title displayed to borrowers.
  • description: A summary of the page.
  • actions: Buttons like “Continue” or “Cancel” to guide borrowers.
{
  "name": "Education",
  "title": "Education Details",
  "description": "Provide your education details.",
  "actions": [
    { "type": "continue", "label": "Continue" },
    { "type": "cancel", "label": "Cancel", "message": "Are you sure you want to cancel?" }
  ]
}

3. Sections

Each page contains sections grouped logically. A section includes:

  • name: The section identifier.
  • description: A brief introduction.
  • fields: The input fields borrowers must complete.

4. Fields

Fields define the actual input elements. Key attributes include:

  • id: Unique identifier.
  • name: Field name.
  • type: Input type (e.g., short_text, select, number, date).
  • label: Field label displayed to users.
  • description: A short explanation of the field.
  • validation: Rules borrowers must follow.
  • options (optional): Predefined choices for select fields.

Example:

{
  "id": "institution",
  "name": "Institution",
  "type": "short_text",
  "label": "Institution Name",
  "description": "Input your institution name",
  "validation": {
    "required": true,
    "minimum_length": 1,
    "maximum_length": 256
  }
}

5. Validations

You can enforce specific rules to ensure proper data collection:

  • required: Ensures the field is mandatory.
  • minimum_length / maximum_length: Controls text input length.
  • minimum / maximum: Sets numeric limits.
  • allowed: Specifies allowable file formats (for uploads).
  • multi_select: Determines if multiple options can be selected.

6. Actions

Define how users navigate the form:

  • Continue: Moves to the next page.
  • Cancel: Discards current entries with a confirmation prompt.
  • Submit: Finalizes the form.
"actions": [
  { "type": "continue", "label": "Continue" },
  { "type": "submit", "label": "Submit" }
]

Available input types

Lendsqr’s custom form builder supports a range of input types to cover the different kinds of data you may need to collect.

1. Short Text:

for single-line text responses such as names or employer details

"type": "short_text"

2. Select:

For dropdown or multiple-choice fields where borrowers choose from a predefined list

"type": "select",
"options": [
  { "label": "High School", "value": "High School" },
  { "label": "Bachelors Degree", "value": "Bachelors Degree" }
]

3. Number:

For numeric inputs such as income or loan amount preferences

"type": "number",
"validation": { "minimum": 1, "maximum": 100000 }

4. Date:

For date inputs such as date of birth or employment start date

"type": "date"

5. Phone: 

For phone number inputs

{
  "id": "phone_number",
  "name": "Phone Number",
  "type": "phone",
  "label": "Phone Number",
  "description": "Enter your phone number",
  "validation": { "required": true }
}

6. Email:

For capturing email addresses

{
  "id": "email",
  "name": "Email Address",
  "type": "email",
  "label": "Email Address",
  "description": "Enter your email address",
  "validation": {
    "required": true,
    "minimum_length": 5,
    "maximum_length": 256
  }
}

7. Image Upload: 

For uploading images like IDs or photos.

{
  "id": "profile_picture",
  "name": "Profile Picture",
  "type": "upload",
  "label": "Upload Your Profile Picture",
  "description": "Upload a clear image of yourself",
  "validation": {
    "required": false,
    "allowed": "jpg,png",
    "maximum_length": 5
  }
}

8. Document Upload:

For uploading documents such as payslips or bank statements.

{
  "id": "income_proof",
  "name": "Proof of Income",
  "type": "upload",
  "label": "Upload Proof of Income",
  "description": "Upload a document proving your income (e.g., payslip or bank statement)",
  "validation": {
    "required": true,
    "allowed": "pdf,jpg,png",
    "maximum_length": 10
  }
}

9. Uniform resource locator: For links or references

"type": "url"

Example Form in JSON

Below is a simplified example of a form:

{
  "meta": {
    "name": "Application Form",
    "description": "Capture customer's details",
    "version": "1.0",
    "status": "active"
  },
  "pages": [
    {
      "name": "Personal Information",
      "title": "Customer Details",
      "description": "Provide personal information",
      "actions": [
        { "type": "continue", "label": "Next" },
        { "type": "cancel", "label": "Cancel", "message": "Are you sure?" }
      ],
      "sections": [
        {
          "name": "Basic Info",
          "description": "Provide your basic details",
          "fields": [
            {
              "id": "full_name",
              "name": "Full Name",
              "type": "short_text",
              "label": "Your Full Name",
              "description": "Enter your full legal name",
              "validation": { "required": true, "minimum_length": 2, "maximum_length": 100 }
            },
            {
              "id": "dob",
              "name": "Date of Birth",
              "type": "date",
              "label": "Your Date of Birth",
              "validation": { "required": true }
            }
          ]
        }
      ]
    }
  ]
}

Read more: How to add Custom Loan Forms to a loan product

Common errors and how to fix them

If a custom form is not displaying correctly or failing to submit, the most common causes are:

  • A field is missing its required id or type attribute — every field must have both for the form to render
  • A select field has been configured without any options — this produces an empty dropdown borrowers cannot interact with
  • An upload field’s allowed value contains spaces (e.g. “pdf, jpg” instead of “pdf,jpg”) — file format values must be comma-separated without spaces
  • The form’s status in the meta section is not set to active — inactive forms will not be presented to borrowers
  • Duplicate id values across fields — each field must have a unique identifier within the form

Best practices for building custom forms

  1. Write clear, plain-language labels and descriptions for every field so borrowers understand exactly what they are being asked to provide
  2. Use validation rules consistently — if a field is required, mark it explicitly rather than leaving borrowers to guess
  3. Group fields into logical sections to reduce cognitive load and improve form completion rates
  4. Keep each page focused on a single topic, such as employment details or identity information, rather than mixing unrelated questions
  5. Update the version number in the meta section each time you make meaningful changes, so you can trace which version of the form a borrower completed
  6. Test the form against a staging account before attaching it to a live loan product to confirm all fields, validations, and page navigation work as expected

Read more: How to create custom forms using Lendsqr’s Drag-and-Drop form builder

See also

Was this page helpful?

On this page