External bank statement

External bank statement API reference

Public API for analyzing a statement JSON URL via Midax. Results arrive on your callbackUrl and/or by polling analysisId.

See also: External decisioning, Decision matrices (staff).

Swagger tag: External Bank Statement, Webhooks.

1. Concepts

Piece	What it does
External bank statement	Analyze a statement JSON URL via Midax; you get results on your callbackUrl (and/or poll by analysisId).
External decisioning	Score a payload against an active Forms decision matrix (separate page).
Decision matrices	Staff-authored scoring + decision bands (separate page). Must be isActive: true for external evaluate.

2. Auth

API group	Auth
/external-bank-statement/*	Public — pass orgKey in body
/webhooks/external-bank-statement	Public — Midax callback into your system

3. Response envelope

{
  "status": "success",
  "message": "Human-readable message",
  "data": {}
}

Errors follow NestJS exception format (statusCode, message, error).

4. Enums

Enum	Values
ExternalBankStatementAnalysisStatus	PENDING, PROCESSING, COMPLETED, FAILED

5. External bank statement

Base path: /external-bank-statement

5.1 Start analysis

POST /external-bank-statement/analyze

Creates/updates a tracking row and calls Midax. Midax POSTs the finished analysis to callbackUrl (caller-owned).

Behaviour

Condition	Result
Same analysisId is PROCESSING and started < 24h ago	Return existing processing row (no new Midax call)
Same analysisId is COMPLETED and rerun is not true	Return cached completed analysis
New id, failed, expired processing, or rerun: true	Create/update → call Midax

Request body (StartExternalBankStatementAnalysisDto)

Field	Type	Required	Notes
orgKey	string (2–120)	Yes	Organisation key / orgRef for Midax billing & public key
analysisId	string (2–120)	Yes	Unique id for this job
statementJsonUrl	URL	Yes	Absolute URL to JSON array of transactions (naira)
accountName	string	Yes	Max 200
accountNumber	string	Yes	Max 32
bank	string	Yes	Max 120
callbackUrl	URL	Yes	Absolute URL Midax will POST when done
appId	string	No	Your tracking id
mobileUserId	string	No	Your tracking id
rerun	boolean	No	Default false. Force fresh Midax run (rebill)

{
  "orgKey": "acme",
  "analysisId": "loan-app-12345",
  "statementJsonUrl": "https://storage.example.com/statements/abc.json",
  "accountName": "Jane Doe",
  "accountNumber": "0123456789",
  "bank": "Access Bank",
  "callbackUrl": "https://your-app.com/webhooks/bank-statement-analysis",
  "appId": "APP-2026-01-01-001",
  "mobileUserId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "rerun": false
}

Response data

{
  "message": "Analysis submitted for processing",
  "analysisId": "loan-app-12345",
  "status": "PROCESSING",
  "midaxJobStatus": "PROCESSING",
  "accountDetails": null,
  "analysis": null,
  "startedAt": "2026-09-03T12:00:00.000Z",
  "completedAt": null,
  "errorMessage": null
}

When the server returns immediately completed / cache hit:

{
  "message": "Cached analysis returned",
  "analysisId": "loan-app-12345",
  "status": "COMPLETED",
  "midaxJobStatus": "COMPLETED",
  "accountDetails": {
    "accountName": "Jane Doe",
    "accountNumber": "0123456789",
    "bank": "Access Bank"
  },
  "analysis": [
    {
      "month": "2026-07",
      "totalCredit": 450000,
      "totalDebit": 380000
    }
  ],
  "startedAt": "2026-09-03T12:00:00.000Z",
  "completedAt": "2026-09-03T12:00:12.000Z",
  "errorMessage": null
}

5.2 Get status by analysisId

GET /external-bank-statement/:analysisId

Response data is the same shape as start-analysis data (status, analysis, timestamps, errorMessage).