API Reference

All endpoints require the x-api-key header.

POST/api/applications/initiate

Initiate Application

Creates an applicant record and a loan application in one call. Returns a Mono Connect widgetUrl you should present to your user so they can link their bank account.

Request Body

Field	Type	Required	Description
firstName	string	Yes	Applicant's first name (2–100 chars). Must match their bank account name.
lastName	string	Yes	Applicant's last name (2–100 chars). Must match their bank account name.
email	string	Yes	Valid email address for the applicant.
phone	string	No	Phone number (10–15 chars). Optional.
bvn	string	No	11-digit BVN. Enables credit bureau lookup during analysis.
amount	number	Yes	Loan amount in Naira (smallest unit — kobo not required).
tenor	number	Yes	Loan tenor in months (e.g. 6, 12, 24).
interestRate	number	Yes	Monthly interest rate as a percentage (e.g. 5.0 for 5%).
purpose	string	No	Loan purpose description. Optional.

Sample Request

curl

curl -X POST https://api.mono-parser.shop/api/applications/initiate \
  -H "Content-Type: application/json" \
  -H "x-api-key: mp_live_your_secret_key" \
  -d '{
    "firstName": "Olusegun",
    "lastName": "Adeyemi",
    "email": "olusegun.adeyemi@example.com",
    "phone": "08012345678",
    "bvn": "22345678901",
    "amount": 500000,
    "tenor": 12,
    "interestRate": 5.0,
    "purpose": "Business expansion"
  }'

Response

json

{
  "applicationId": "357ab3ce-55ce-4f73-82c9-dab3136c7885",
  "applicantId": "54cbd45f-bf8e-4add-8d0c-adb5efe705c1",
  "widgetUrl": "https://connect.withmono.com/?key=...&reference=...",
  "status": "PENDING_LINKING"
}

Store both IDs. Present the widgetUrl to the applicant — it is for their browser, not your server.

POST/api/applications/:id/link-account

Link Account

Re-generates a fresh Mono Connect widget URL for an existing application. Use this when an applicant needs to re-link their account (e.g. the session expired, they closed the widget without completing, or you want to link an additional account).

Path Parameter

Field	Type	Required	Description
:id	string (UUID)	Yes	The applicationId returned from the initiate endpoint.

Sample Request

curl

curl -X POST https://api.mono-parser.shop/api/applications/357ab3ce-55ce-4f73-82c9-dab3136c7885/link-account \
  -H "x-api-key: mp_live_your_secret_key"

Response

json

{
  "applicationId": "357ab3ce-55ce-4f73-82c9-dab3136c7885",
  "widgetUrl": "https://connect.withmono.com/?key=...&reference=...",
  "status": "PENDING_LINKING"
}

This endpoint will return an error if the application is already in a terminal state (COMPLETED or FAILED). You cannot re-link accounts after a final decision has been issued. Start the process again by calling the initiate endpoint to create a new application.

POST/api/applications/:id/finalize-linking

Finalize Linking

Signals that the applicant has finished linking all their bank accounts. This locks the application from further account linking and makes it eligible for analysis. Once called, we fire the application.ready_for_analysis webhook when all enrichment is confirmed complete.

Path Parameter

Field	Type	Required	Description
:id	string (UUID)	Yes	The applicationId returned from the initiate endpoint.

Sample Request

curl

curl -X POST https://api.mono-parser.shop/api/applications/357ab3ce-55ce-4f73-82c9-dab3136c7885/finalize-linking \
  -H "x-api-key: mp_live_your_secret_key"

Response

json

{
  "applicationId": "357ab3ce-55ce-4f73-82c9-dab3136c7885",
  "status": "LINKED",
  "message": "Linking finalized. Analysis will be available once all accounts are enriched."
}

Call after all accounts have fired account.enrichment_ready.

POST/api/applications/:id/analyze

Analyze Application

Queues the loan analysis job. The scoring engine reads all enriched bank data from our database and sends the decision to your webhook URL.

Path Parameter

Field	Type	Required	Description
:id	string (UUID)	Yes	The applicationId. Use the value from the account.enrichment_ready webhook for the best result.

Sample Request

curl

curl -X POST https://api.mono-parser.shop/api/applications/357ab3ce-55ce-4f73-82c9-dab3136c7885/analyze \
  -H "x-api-key: mp_live_your_secret_key"

Response

json

{
  "applicationId": "357ab3ce-55ce-4f73-82c9-dab3136c7885",
  "status": "PROCESSING",
  "message": "Analysis queued."
}

Call this only after receiving application.ready_for_analysis. This event fires after you have called /finalize-linking and all linked accounts are enriched. Calling /analyze before this will return a 400 error.