> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Statement Analysis

> Analyse a customer's bank-statement PDF with the Dojah API — upload the statement to get an account ID, then fetch income, expense and cash-flow insight.

<div className="dj-endpoint">
  <span className={`dj-method dj-method-post`}>POST</span>
  <code>/api/v1/financial/transactions/pdf</code>
</div>

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](/api-reference/financial-credit/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.

```json 200 — /api/v1/financial/analysis theme={null}
{
  "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](/api-reference/core-concepts/wallet-billing). |
| `424` | Failed dependency — the analysis source could not process the statement.                      |
| `429` | Too many requests — back off and retry.                                                       |

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```

  ```js Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json POST /api/v1/financial/transactions/pdf theme={null}
  {
    "entity": {
      "acct_id": "1234a5b6-20bb-4e16-b711-56c5bd7a3c90"
    }
  }
  ```
</ResponseExample>