> 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/external-bank-statement.md).

# 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

```json
{
  "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)          |

```json
{
  "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**

```json
{
  "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:

```json
{
  "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`).