Ocrolus Cash Flow Analytics API
The Cash Flow Analytics API from Ocrolus — 10 operation(s) for cash flow analytics.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands Cash Flow Analytics API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Cash Flow Analytics
paths:
/v2/book/{book_uuid}/income/bank-statement-v2:
get:
summary: Bank statement income calculator
operationId: bsic
tags:
- Cash Flow Analytics
description: 'This API retrieves the bank statement income calculator output in JSON format. You can also access this through the Dashboard. To learn more, see [Bank Statement Income Calculator](https://docs.ocrolus.com/docs/bank-statement-income-calculator).
'
parameters:
- name: book_uuid
in: path
required: true
description: 'The unique identifier of the <<glossary:Book>> that contains the bank statements you''d like to have analyzed.
'
schema:
type: string
format: uuid
example: 3927d5b7-ca34-4882-b23f-0ce40d40027c
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
title: Success
properties:
book_uuid:
type: string
format: uuid
description: Unique identifier for the book.
example: ef199503-ef03-4fc1-a05f-2ad14416821d
calculated_at:
type: string
format: date-time
description: Timestamp indicating when the income calculation was performed.
example: '2026-06-30T06:22:04.791742-04:00'
bank_statement_income:
type: array
description: List of income calculation results, one entry per account.
items:
type: object
properties:
account:
type: object
description: Details of the bank account associated with the income calculation.
properties:
pk:
type: integer
description: Primary key of the account.
example: 435388
account_number:
type: string
description: The account number.
example: '381007628285'
holder_name:
type: string
description: Name of the account holder.
example: ZOHEB SAIT
deposits:
type: array
description: List of deposit transactions identified in the bank statement.
items:
type: object
properties:
pk:
type: integer
description: Primary key of the deposit transaction.
example: 2255891820
date:
type: string
format: date
description: Date of the deposit.
example: '2017-03-24'
description:
type: string
description: Description or memo of the deposit transaction.
example: INTEREST EARNED
amount:
type: number
description: Deposit amount.
example: 0.01
page_doc_pk:
type: integer
description: Primary key of the page document the transaction was extracted from.
example: 18034747
period_pk:
type: integer
description: Primary key of the period this transaction belongs to.
example: 1034191
period_uuid:
type: string
format: uuid
description: UUID of the period this transaction belongs to.
example: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude:
type: boolean
description: Indicates whether this deposit is excluded from the income calculation.
example: true
is_large:
type: boolean
description: Indicates whether this deposit is flagged as a large deposit.
example: false
is_payroll:
type: boolean
description: Indicates whether this deposit is identified as payroll income.
example: false
is_internal_transfer:
type: boolean
description: Indicates whether this deposit is an internal transfer between accounts.
example: false
is_recurring:
type: boolean
description: Indicates whether this deposit is a recurring transaction.
example: false
expenses:
type: array
description: List of expense transactions identified in the bank statement.
items:
type: object
nsf_transactions:
type: array
description: List of non-sufficient funds (NSF) transactions.
items:
type: object
calculations:
type: object
description: Aggregated income calculation results for the account.
properties:
nsf_count:
type: integer
description: Total number of NSF transactions.
example: 0
statement_summary:
type: array
description: Month-by-month summary of statement activity.
items:
type: object
properties:
begin_date:
type: string
format: date
description: Start date of the statement period.
example: '2017-03-01'
end_date:
type: string
format: date
description: End date of the statement period.
example: '2017-03-24'
total_deposits:
type: number
description: Total qualifying deposits for this period.
example: 0
total_nsf_count:
type: integer
description: Number of NSF transactions in this period.
example: 0
beginning_balance:
type: number
description: Account balance at the start of the period.
example: 1354.81
ending_balance:
type: number
description: Account balance at the end of the period.
example: 1379.82
statement_status:
type: boolean
description: Indicates whether the statement period is valid and complete.
example: true
period_pk:
type: integer
nullable: true
description: Primary key of the period, if applicable.
example: null
large_deposit_summary:
type: object
description: Summary of large deposit detection and thresholds.
properties:
average_deposit:
type: number
description: Average deposit amount across all transactions.
example: 12.51
percentage_amount:
type: number
description: Percentage threshold used to determine large deposits.
example: 50
deposit_threshold:
type: number
description: Calculated dollar threshold above which a deposit is flagged as large.
example: 18.76
threshold_base:
type: string
description: The basis used to calculate the large deposit threshold.
example: AVERAGE_DEPOSIT
large_deposit_count:
type: integer
description: Number of deposits flagged as large.
example: 3
large_deposit_amount:
type: number
description: Total dollar amount of all large deposits.
example: 75
large_deposit_txn_pks:
type: array
description: List of primary keys for transactions flagged as large deposits.
items:
type: integer
example:
- 2255891823
- 2255891822
- 2255891821
total_deposit_summary:
type: object
description: Breakdown of total, included, and excluded deposit amounts.
properties:
deposits:
type: number
description: Total deposit amount across all transactions.
example: 75.03
included_deposits:
type: number
description: Total deposit amount included in the income calculation.
example: 0
excluded_deposits:
type: number
description: Total deposit amount excluded from the income calculation.
example: 75.03
total_included_months:
type: integer
description: Number of months included in the income calculation.
example: 4
qualifying_income_average:
type: number
description: Average monthly qualifying income based on included deposits.
example: 0
recurring_counterparty_depositors:
type: array
description: List of recurring counterparties identified as depositors.
items:
type: object
recurring_counterparty_expensers:
type: array
description: List of recurring counterparties identified as expensers.
items:
type: object
recurring_transactions:
type: array
description: List of transactions identified as recurring.
items:
type: object
properties:
pk:
type: integer
description: Primary key of the recurring transaction.
example: 2255891823
date:
type: string
format: date
description: Date of the recurring transaction.
example: '2017-03-01'
description:
type: string
description: Description or memo of the recurring transaction.
example: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount:
type: number
description: Amount of the recurring transaction.
example: 25
total_withdrawls:
type: number
description: Total withdrawal amount across all transactions.
example: 0
total_expense_summary:
type: object
description: Breakdown of total, included, and excluded expense amounts.
properties:
expenses:
type: number
description: Total expense amount across all transactions.
example: 0
included_expenses:
type: number
description: Total expense amount included in the income calculation.
example: 0
excluded_expenses:
type: number
description: Total expense amount excluded from the income calculation.
example: 0
overdraft_transactions:
type: array
description: List of overdraft transactions identified in the bank statement.
items:
type: object
monthly_statement_summary:
type: object
nullable: true
description: Monthly aggregated statement summary, if available.
example: null
negative_balance_day_summary:
type: object
description: Summary of days the account carried a negative balance.
properties:
total_negative_balance_days:
type: integer
description: Total number of days the account balance was negative.
example: 0
monthly_breakdown:
type: array
description: Month-by-month breakdown of negative balance days.
items:
type: object
examples:
Success:
value:
book_uuid: ef199503-ef03-4fc1-a05f-2ad14416821d
calculated_at: '2026-06-30T06:22:04.791742-04:00'
bank_statement_income:
- account:
pk: 435388
account_number: '381007628285'
holder_name: ZOHEB SAIT
deposits:
- pk: 2255891820
date: '2017-03-24'
description: INTEREST EARNED
amount: 0.01
page_doc_pk: 18034747
period_pk: 1034191
period_uuid: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude: true
is_large: false
is_payroll: false
is_internal_transfer: false
is_recurring: false
- pk: 2255891823
date: '2017-03-01'
description: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount: 25
page_doc_pk: 18034747
period_pk: 1034191
period_uuid: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude: true
is_large: true
is_payroll: false
is_internal_transfer: true
is_recurring: false
- pk: 2255891819
date: '2017-02-21'
description: INTEREST EARNED
amount: 0.01
page_doc_pk: 18034747
period_pk: 1034191
period_uuid: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude: true
is_large: false
is_payroll: false
is_internal_transfer: false
is_recurring: false
- pk: 2255891822
date: '2017-02-01'
description: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount: 25
page_doc_pk: 18034747
period_pk: 1034191
period_uuid: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude: true
is_large: true
is_payroll: false
is_internal_transfer: true
is_recurring: false
- pk: 2255891818
date: '2017-01-24'
description: INTEREST EARNED
amount: 0.01
page_doc_pk: 18034747
period_pk: 1034191
period_uuid: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude: true
is_large: false
is_payroll: false
is_internal_transfer: false
is_recurring: false
- pk: 2255891821
date: '2017-01-03'
description: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount: 25
page_doc_pk: 18034747
period_pk: 1034191
period_uuid: 12d358a4-dac9-4f11-ade4-09d03ed23e79
exclude: true
is_large: true
is_payroll: false
is_internal_transfer: true
is_recurring: false
expenses: []
nsf_transactions: []
calculations:
nsf_count: 0
statement_summary:
- begin_date: '2017-03-01'
end_date: '2017-03-24'
total_deposits: 0
total_nsf_count: 0
beginning_balance: 1354.81
ending_balance: 1379.82
statement_status: true
period_pk: null
- begin_date: '2017-02-01'
end_date: '2017-02-28'
total_deposits: 0
total_nsf_count: 0
beginning_balance: 1329.8
ending_balance: 1354.81
statement_status: true
period_pk: null
- begin_date: '2017-01-01'
end_date: '2017-01-31'
total_deposits: 0
total_nsf_count: 0
beginning_balance: 1304.79
ending_balance: 1329.8
statement_status: true
period_pk: null
- begin_date: '2016-12-23'
end_date: '2016-12-31'
total_deposits: 0
total_nsf_count: 0
beginning_balance: 1304.79
ending_balance: 1304.79
statement_status: true
period_pk: null
large_deposit_summary:
average_deposit: 12.51
percentage_amount: 50
deposit_threshold: 18.76
threshold_base: AVERAGE_DEPOSIT
large_deposit_count: 3
large_deposit_amount: 75
large_deposit_txn_pks:
- 2255891823
- 2255891822
- 2255891821
total_deposit_summary:
deposits: 75.03
included_deposits: 0
excluded_deposits: 75.03
total_included_months: 4
qualifying_income_average: 0
recurring_counterparty_depositors: []
recurring_counterparty_expensers: []
recurring_transactions:
- pk: 2255891823
date: '2017-03-01'
description: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount: 25
- pk: 2255891822
date: '2017-02-01'
description: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount: 25
- pk: 2255891821
date: '2017-01-03'
description: ONLINE SCHEDULED TRANSFER FROM CHK 4172 CONFIRMATION
amount: 25
total_withdrawls: 0
total_expense_summary:
expenses: 0
included_expenses: 0
excluded_expenses: 0
overdraft_transactions: []
monthly_statement_summary: null
negative_balance_day_summary:
total_negative_balance_days: 0
monthly_breakdown: []
'400':
description: Txn Limit Exceeded
content:
application/json:
examples:
Txn Limit Exceed:
$ref: '#/components/examples/TxnLimitExceeded'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'403':
description: Permission Error
content:
application/json:
examples:
No Permission:
$ref: '#/components/examples/BookPermissionError'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'404':
description: Book Not Found Error
content:
application/json:
examples:
Book not found:
$ref: '#/components/examples/BookNotFoundError'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'425':
description: Analytics Still Processing
content:
application/json:
examples:
Book not found:
$ref: '#/components/examples/TxnTagsProcessingError'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/paths/~1v2~1analytics~1jobs~1%7Bjob_id%7D/get/responses/500/content/application~1json/schema'
examples:
internal_server_error:
$ref: '#/paths/~1v2~1analytics~1jobs~1%7Bjob_id%7D/get/responses/500/content/application~1json/examples/internal_server_error'
/v2/book/{book_uuid}/income/bank-statement-v2/xlsx:
get:
summary: Bank statement income calculator (Excel)
operationId: bsic-excel
tags:
- Cash Flow Analytics
description: 'This API retrieves the bank statement income calculator in an Excel format.
---
Visit our [guide](https://docs.ocrolus.com/docs/bank-statement-income-calculator) for more information.
The output of this endpoint is intended for manual review, as opposed to automated consumption by your application.
> 🚧
> The response will have a MIME type of `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, hence there is no JSON response schema. See [here](https://docs.google.com/spreadsheets/d/1IeElDLJWQ-YZRmR_zO0OD6ltFnyOPIOQ/edit?usp=sharing&ouid=108945757603422712879&rtpof=true&sd=true) for an example output.
'
parameters:
- name: book_uuid
in: path
required: true
description: 'The unique identifier of the <<glossary:Book>> that contains the bank statements you''d like to have analyzed.
'
schema:
type: string
format: uuid
example: 3927d5b7-ca34-4882-b23f-0ce40d40027c
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
examples:
ExampleSpreadsheet:
summary: Success
externalValue: https://docs.google.com/spreadsheets/d/1IeElDLJWQ-YZRmR_zO0OD6ltFnyOPIOQ/edit?usp=sharing&ouid=108945757603422712879&rtpof=true&sd=true
'400':
description: Txn Limit Exceeded
content:
application/json:
examples:
Txn Limit Exceed:
$ref: '#/components/examples/TxnLimitExceeded'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'403':
description: Permission Error
content:
application/json:
examples:
No Permission:
$ref: '#/components/examples/BookPermissionError'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'404':
description: Book Not Found Error
content:
application/json:
examples:
Book not found:
$ref: '#/components/examples/BookNotFoundError'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
'425':
description: Analytics Still Processing
content:
application/json:
examples:
Book not found:
$ref: '#/components/examples/TxnTagsProcessingError'
schema:
$ref: '#/paths/~1v2~1book~1%7Bbook_uuid%7D~1summary/get/responses/400/content/application~1json/schema'
/v2/book/{book_uuid}/summary:
get:
summary: Book summary
operationId: Book-summary
tags:
- Cash Flow Analytics
description: "\nThis API retrieves the Cash Flow Analytics summary of a Book in JSON format. It provides daily balances, bank account PII, and time series for all transaction categories at the <<glossary:Book>> and bank account level. \n\nIt offers quicker analytics generation, more granular and accurate transaction categories (including improved revenue and expense calculations), and a more concise structure.\n\n---\n\n### Async processing \n\nThis API supports asynchronous processing. To get the asynchronous result, add `async=true` in the query parameter to run the request as a background job and receive a `job_id` immediately instead of waiting for the full response inline. When `async=true`, the endpoint returns `202 Accepted` with a `job_id` instead of the analytics payload.\n\nAsync mode is required for Books with more than 100,000 transactions. Books exceeding 1,000,000 transactions are rejected with `422` (error code `1100`). Once submitted, poll\n[Async job status](https://docs.ocrolus.com/reference/async-job-status) API to retrieve the result when the job is complete.\n"
parameters:
- name: book_uuid
in: path
required: true
description: 'The unique identifier of the <<glossary:Book>> that contains the bank statements you''d like to have analyzed.
'
schema:
type: string
format: uuid
example: 3927d5b7-ca34-4882-b23f-0ce40d40027c
- name: exclude_bank_account_pks
in: query
required: false
description: 'Bank account primary key(s) to exclude from analytics calculations in the book summary. The underlying data remains in the system and is not deleted.
> 📘 This parameter is in beta. If you encounter any bug, please reach out to [support@ocrolus.com](mailto:support@ocrolus.com).
'
schema:
type: string
example: '9662788'
- name: exclude_months
in: query
required: false
description: 'Months (in YYYY-MM format) of transaction to exclude from analytics calculations in the book summary. The underlying data remains in the system and is not deleted.
> 📘 This parameter is in beta. If you encounter any bug, please reach out to [support@ocrolus.com](mailto:support@ocrolus.com).
'
schema:
type: string
example: 2025-01
- $ref: '#/components/parameters/AsyncParameter'
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
# --- truncated at 32 KB (516 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ocrolus/refs/heads/main/openapi/ocrolus-cash-flow-analytics-api-openapi.yml