Account Statement Analysis

POST/api/v1/financial/transactions/pdf

Turn a customer’s bank-statement PDF into structured financial insight — income, spending, cash-flow and affordability signals. A two-step flow: upload the statement to get an account ID, then fetch the analysis.

Headers

Header	Required	Description
`Authorization`	Yes	Your app’s secret key, sent as-is — not `Bearer`.
`AppId`	Yes	The App ID from your dashboard.
`Content-Type`	Yes	`multipart/form-data` for the upload (set automatically when you attach the file).

Body parameters

Parameter	Type	Required	Description
`bank_code`	string	Yes	The bank code for the statement’s account. See Fetch Banks.
`statement`	file	Yes	The customer’s statement of account, as a PDF document.

Step 2 — Financial analysis

Call GET /api/v1/financial/analysis with the account_id from step 1 to retrieve the analysis.

Parameter	Type	Required	Description
`account_id`	string	Yes	The `acct_id` returned in step 1.

The entity groups results into five objects: accountBreakdown (balances, monthly/weekly averages, statement period), expenseBreakdown (spend by category), fundsManagement (cash-flow, loan and gambling signals), inflowBreakdown (salary and additional income) and transactionRoutineBreakdown (transaction ranges and recency). Response trimmed below for readability.

200 — /api/v1/financial/analysis

{
  "entity": {
    "accountBreakdown": {
      "TotalCreditEntry": 306935.75,
      "TotalDebitMade": 321986.57,
      "averageMonthlyCredits": 25577.98,
      "averageMonthlyDebits": 20124.16,
      "closingBalance": 0,
      "firstDateInStatement": "2021-04-12",
      "lastDateInStatement": "2022-07-03",
      "numberOfTransactingMonths": 6,
      "periodInStatement": "April - July"
    },
    "expenseBreakdown": {
      "mostFrequentExpenseCategory": "atm_and_pos_transactions",
      "averageMonthlyTotalExpenses": 53555.55,
      "totalExpenseOnAirtimeAndData": 13200,
      "totalExpenseOnTransfer": 70155.02
    },
    "fundsManagement": {
      "accountActivity": 0.1,
      "accountSweep": "No",
      "gamblingStatus": "No Gambling Transactions Found",
      "overallInflowToOutflowAmount": "Negative Cash Flow",
      "totalLoanAmount": 0
    },
    "inflowBreakdown": {
      "aSalaryEarner": "No",
      "AdditionalIncome": "Yes",
      "averageAdditionalIncome": 9166.67,
      "netAverageMonthlySalary": 0
    },
    "transactionRoutineBreakdown": {
      "lastCreditReceived": "2022-03-04",
      "lastDebitMade": "2022-07-03",
      "mostFrequentTransactionRange": "<10000",
      "totalAmountOfTransactions": 129
    }
  }
}

Errors

Code	Meaning
`400`	Bad request — missing `bank_code`/`statement`, or an unreadable PDF.
`401`	Unauthorized — check your key and `AppId` (no `Bearer` prefix).
`402`	Insufficient wallet balance. Fund your wallet.
`424`	Failed dependency — the analysis source could not process the statement.
`429`	Too many requests — back off and retry.

curl -X POST "https://api.dojah.io/api/v1/financial/transactions/pdf" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}" \
  -F "bank_code=011" \
  -F "statement=@statement.pdf"

import fs from "fs";

const form = new FormData();
form.append("bank_code", "011");
form.append("statement", new Blob([fs.readFileSync("statement.pdf")]), "statement.pdf");

const res = await fetch("https://api.dojah.io/api/v1/financial/transactions/pdf", {
  method: "POST",
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    AppId: process.env.DOJAH_APP_ID,
  },
  body: form,
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.dojah.io/api/v1/financial/transactions/pdf",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    data={ "bank_code": "011" },
    files={ "statement": open("statement.pdf", "rb") },
)
data = res.json()

{
  "entity": {
    "acct_id": "1234a5b6-20bb-4e16-b711-56c5bd7a3c90"
  }
}

Get started

Core concepts

API Endpoints

Widget SDKs

API clients

Account Statement Analysis

Headers

Body parameters

Step 2 — Financial analysis

Errors

​Headers

​Body parameters

​Step 2 — Financial analysis

​Errors

Headers

Body parameters

Step 2 — Financial analysis

Errors