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):

Value	Typical use
PERSONAL	Individual applicant details (name, BVN, email, phone, etc.)
CORPORATE	Business / company details
LOAN	Loan amount, purpose, tenure
CREDIT	Credit bureau selection and consent
ADDRESS	Residential or business address
DOCUMENTS	File uploads and supporting documents
IDCARD	Identity document capture and verification

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.

1. CORPORATE.

Used for: applicationType: CORPORATE.

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

1. 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.

1. CREDIT

Used for: Both individual and corporate

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

1. ADDRESS

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

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

1. DOCUMENTS

Used for: Both

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

1. 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

isOptional?

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

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

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

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

Publish / unpublish

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

Sample

Field	Type	Description	isOptional?
formId	UUID	Form to publish or unpublish
isPublished	boolean	true to publish, false to unpublish (default: false)