> For the complete documentation index, see [llms.txt](https://midatechnologies.gitbook.io/mida-developer-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://midatechnologies.gitbook.io/mida-developer-portal/midaforms/forms.md).

# Forms

Each form is built from one or more sections. The title on each section must be one of these values (case-insensitive on input; stored as uppercase):

<table><thead><tr><th width="207">Value</th><th>Typical use</th></tr></thead><tbody><tr><td>PERSONAL</td><td>Individual applicant details (name, BVN, email, phone, etc.)</td></tr><tr><td>CORPORATE</td><td>Business / company details</td></tr><tr><td>LOAN</td><td>Loan amount, purpose, tenure</td></tr><tr><td>CREDIT</td><td>Credit bureau selection and consent</td></tr><tr><td>ADDRESS</td><td>Residential or business address</td></tr><tr><td>DOCUMENTS</td><td>File uploads and supporting documents</td></tr><tr><td>IDCARD</td><td>Identity document capture and verification</td></tr></tbody></table>

1. #### PERSONAL.

#### Used for: applicationType: INDIVIDUAL

#### Purpose: Captures the individual applicant's identity and contact details. BVN validation, face match, and credit bureau checks pull data from here.<br>

2. CORPORATE.

Used for: applicationType: CORPORATE.&#x20;

Purpose: Captures business/company information. CAC validation and corporate credit checks read from here.<br>

3. LOAN

Used for: All forms (section is mandatory)

Purpose: Captures the loan request details. Used for workflow routing, offer letters, and auto-decision DTI calculations.<br>

4. CREDIT

Used for: Both individual and corporate

Purpose: Credit bureau consent and bureau selection. Triggers credit checks on final submission.<br>

5. ADDRESS

Used for: Both (often separate from homeAddress in PERSONAL)

Purpose: Structured residential or business address with optional proof-of-address upload.<br>

6. DOCUMENTS

Used for: Both

Purpose: Supporting document uploads (payslips, bank statements, CAC documents, etc.). Each file is reviewed individually during application review.<br>

7. IDCARD

Used for: Both

Purpose: Identity document capture and verification (passport, NIN, driver's license). Triggers ID verification API on submit.

## Create forms

#### Field description

<table><thead><tr><th width="48">#</th><th width="204">Field</th><th width="225">Description</th><th width="194">Type</th><th data-type="checkbox">isOptional?</th></tr></thead><tbody><tr><td>1</td><td>name</td><td>Form display name</td><td>string</td><td>false</td></tr><tr><td>2</td><td>formSlug</td><td>URL slug (kebab-case of name; unique per org)</td><td>string</td><td>false</td></tr><tr><td>3</td><td>description</td><td>Form description</td><td>string</td><td>false</td></tr><tr><td>4</td><td>productId</td><td>Linked loan product ID</td><td>UUID</td><td>false</td></tr><tr><td>5</td><td>applicationType</td><td>INDIVIDUAL or CORPORATE</td><td>enum</td><td>false</td></tr><tr><td>6</td><td>repaymentInstruction</td><td>MIDA_COLLECT_PAYGATE, PAYSTACK, or REMITTA</td><td>enum</td><td>false</td></tr><tr><td>7</td><td>submissionType</td><td>USER_LED and/or AGENT_LED</td><td>string []</td><td>false</td></tr><tr><td>8</td><td>sections</td><td>At least one section (see sections below)</td><td>array</td><td>false</td></tr><tr><td>9</td><td>isPublished</td><td>Publish immediately on create (default: false)</td><td>boolean</td><td>true</td></tr><tr><td>10</td><td>enableOfferLetter</td><td>Enable offer letter (default: false)</td><td>boolean</td><td>true</td></tr><tr><td>11</td><td>enableAutoDecision</td><td>Enable auto-decisioning (default: false)</td><td>boolean</td><td>true</td></tr><tr><td>12</td><td>expiryDate</td><td>Must be a future date if provided</td><td>ISO date</td><td>true</td></tr><tr><td>13</td><td>loanOfficerId</td><td>Assigned loan officer user ID</td><td>string</td><td>true</td></tr><tr><td>14</td><td>offerLetterName</td><td>Inline offer letter name (required if enableOfferLetter is checked)</td><td>string</td><td>true</td></tr><tr><td>15</td><td>templateHtml</td><td>Inline offer letter HTML</td><td>string</td><td>true</td></tr><tr><td>16</td><td>templateVariables</td><td>Variables used in the template</td><td>string[]</td><td>true</td></tr><tr><td>17</td><td>attachOfferLetterId</td><td>Attach an existing offer letter instead</td><td>UUID</td><td>true</td></tr><tr><td>18</td><td>attachDecisionMatrixId</td><td>Attach an existing decision matrix</td><td>UUID</td><td>true</td></tr></tbody></table>

#### API Url

```
POST {base url}/integrations/v1/forms
```

#### Sample

```
{
    "name": "testing agent led",
    "description": "testing",
    "organizationId": "mida",
    "expiryDate": null,
    "productId": "6c1f1468-032a-4d08-bfff-fcee1aada4f8",
    "formSlug": "testing-agent-led",
    "applicationType": "INDIVIDUAL",
    "repaymentInstruction": "MIDA_COLLECT_PAYGATE",
    "isPublished": true,
    "submissionType":["AGENT_LED"],
    "sections": [
        {
            "title": "PERSONAL",
            "order": 1,
            "fields": [
                {
                    "label": "Surname",
                    "type": "TEXT",
                    "name": "surname",
                    "isRequired": false,
                    "isUniqueIdentifier": false,
                    "order": 1
                },
                {
                    "label": "First Name",
                    "type": "TEXT",
                    "name": "firstName",
                    "isRequired": false,
                    "order": 2
                },
                {
                    "label": "dob",
                    "type": "DATE",
                    "name": "dob",
                    "isRequired": false,
                    "order": 3,
                    "repeaterConfig": {
                        "maxAge": 65,
                        "minAge": 18
                    }
                },
                {
                    "label": "Personal Email",
                    "type": "EMAIL",
                    "name": "personalEmail",
                    "isRequired": false,
                    "order": 5
                },
                {
                    "label": "BVN",
                    "type": "NUMBER",
                    "name": "bvn",
                    "isRequired": false,
                    "isUniqueIdentifier": false,
                    "order": 6
                },
                {
                    "label": "NIN",
                    "type": "NUMBER",
                    "name": "nin",
                    "isRequired": false,
                    "order": 7
                },
                {
                    "label": "Phone",
                    "type": "TEL",
                    "name": "phone",
                    "isRequired": false,
                    "order": 9
                }
            ]
        },
        {
            "title": "CORPORATE",
            "order": 2,
            "fields": [
                {
                    "type": "TEXT",
                    "label": "Business Name",
                     "name": "businessName",
                    "fieldKey": "field-1754663652048",
                    "isRequired": false,
                    "order": 1
                },
                {
                    "type": "TEXT",
                    "label": "CAC Registrationss",
                     "name": "cacRegistration",
                    "isUniqueIdentifier":true,
                    "fieldKey": "field-1754663688118",
                    "isRequired": true,
                    "order": 2
                }
            ]
        },
        {
            "title": "DOCUMENTS",
            "order": 3,
            "fields": [
                {
                    "label": "Documents",
                    "type": "DOCUMENTINFO",
                    "name": "documents",
                    "isRequired": true,
                    "order": 1,
                }
            ]
        },
        {
            "title": "CREDIT",
            "order": 4,
            "fields": [
                {
                    "label": "Credit Bureau Check",
                    "type": "REPEATER",
                    "name": "cbc",
                    "isRequired": true,
                    "order": 1,
                }
            ]
        },
        {
            "title": "LOAN",
            "order": 5,
            "fields": [
            		{
                    "fieldKey": "field-3344455600-876",
                    "label": "PURPOSE",
                    "type": "DROPDOWN",
                    "isRequired": true,
                    "order": 1,
                    "repeaterConfig": {},
                    "name": "purpose"
                },
                {
                    "label": "Amount",
                    "type": "NUMBER",
                    "name": "amount",
                    "isRequired": true,
                    "order": 2,
                    "repeaterConfig": {},
                }
            ]
        },
        {
            "title": "ADDRESS",
            "order": 6,
            "fields": [
                {
                    "label": "Home Address",
                    "type": "TEXT",
                    "name": "homeAddress",
                    "isRequired": true,
                    "order": 1,
                }
            ]
        },
        {
            "title": "IDCARD",
            "order": 7,
            "fields": [
                {
                    "label": "DOCUMENT INFORMATION",
                    "type": "IDCARD",
                    "name": "documentInfo",
                    "isRequired": true,
                    "order": 1,
                    "repeaterConfig": {
                        "documentTypes": [
                            "INTL PASSPRT",
                            "DOC"
                        ]
                    },
                }
            ]
        }
    ]
}

```

### Update loan form <a href="#update-loan-product" id="update-loan-product"></a>

```
PUT {base url}/integrations/v1/forms/:id 
```

Send only fields to update (same shape as create, all optional).

#### Publish / unpublish&#xD;

```
PUT {base url}/integrations/v1/forms/publish
```

#### Sample

<table><thead><tr><th width="166">Field</th><th width="152">Type</th><th>Description</th><th data-type="checkbox">isOptional?</th></tr></thead><tbody><tr><td>formId</td><td>UUID</td><td>Form to publish or unpublish</td><td>false</td></tr><tr><td>isPublished</td><td>boolean</td><td>true to publish, false to unpublish (default: false)</td><td>true</td></tr></tbody></table>