Cash Flow Analytics

Book summary

This 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.

It offers quicker analytics generation, more granular and accurate transaction categories (including improved revenue and expense calculations), and a more concise structure.

Async processing

This 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.

Async 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 Async job status API to retrieve the result when the job is complete.

get/v2/book/{book_uuid}/summary

Request

Base URL
https://api.ocrolus.com
URL
https://api.ocrolus.com/v2/book/{book_uuid}/summary
Auth
OAuth 2
Client credentials
Token URL: https://auth.ocrolus.com/oauth/token

Path parameters

book_uuidstring uuid required

The unique identifier of the <glossary:Book> that contains the bank statements you'd like to have analyzed.

Query parameters

exclude_bank_account_pksstring

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.

exclude_monthsstring

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.

asyncboolean

When true, runs the request as a background job and returns a job_id immediately instead of the analytics payload. Required for Books with more than 100,000 transactions. Books exceeding 1,000,000 transactions are rejected with 422 (error code 1100).

Response

Success

book_pkinteger

A unique numerical identifier for a <glossary:Book>, commonly referred to as the Book primary key (Book pk).

book_namestring

The name of the Book used for the analytics calculation.

txn_countinteger

The number of transactions considered for analytics calculation.

naics4_codeinteger

A 4-digit North American Industry Classification System (NAICS) code that represents the industry of the Book.

naics_descriptionstring

The description of the 4-digit NAICS code, indicating the industry classification of the Book category.

📘 In Books with multiple businesses or fragmented merchant activity, the widget may show the following statuses as applicable:

Pending - Industry Data: Classification is in progress.

Unable to find a unique SMB merchant: The system is not able to find a unique merchant mapped to the documents in the Book.

Not Available: The system has found a unique merchant, but this merchant does not have industry classification data.

naics6_codestring

A six-digit NAICS code that provides a more granular industry classification for the merchant. This code refines the broader NAICS category and is commonly used for detailed industry analysis, peer comparisons, and benchmarking.

naics6_descriptionstring

A human-readable description of the six-digit NAICS code that specifies the merchant's exact industry segment within the broader NAICS classification.

naics_overrideboolean

Shows if the 4-digit NAICS code was overridden by the lender.

mcc_codestring

A four-digit code assigned by payment networks that classifies a merchant based on the primary type of goods or services they provide. Merchant Category Code (MCC) are commonly derived from card transaction data and are used for transaction categorization, risk assessment, and analytics.

❗️ This field is deprecated. Always returns 999999

mcc_descriptionstring

A human-readable description of the MCC that explains the merchant's primary business activity as defined by the card network.

❗️ > This field is deprecated.

sic_codestring

A four-digit Standard Industrial Classification (SIC) code that identifies the merchant's primary business activity using the legacy SIC system. SIC codes are derived from bank statement data and are used for industry classification, regulatory reporting, and analytics.

❗️ This field is deprecated. Always returns 999999

sic_descriptionstring

A human-readable description of the SIC code that explains the merchant's primary business activity as defined by the legacy SIC system.

❗️ This field is deprecated.

book_mismatch_severity'LOW' | 'MEDIUM' | 'HIGH' | 'NO MISMATCHES FOUND'

The severity of mismatches detected in the Book, such as discrepancies between uploaded documents and extracted data. > 📘 This attribute is in beta. If you encounter any bug, please reach out to support@ocrolus.com.

daily_balancesobject

Daily ending balances keyed by date. Each key is a date in YYYY-MM-DD format and the value is the ending balance for that date.

daily_cash_flowsobject

Daily cash flows keyed by date. Each key is a date in YYYY-MM-DD format and the value is the net cash flow for that date, calculated as the difference between total credits and total debits.

average_daily_cash_flownumber

The average value in daily_cash_flows.

net_cash_flows_by_monthobject

The cash flows resulting from the difference between total credits and total debits, categorized by calendar month. Each key is a month in YYYY-MM format.

minimum_balance_by_monthobject

The minimum daily balance grouped by calendar month. Each key is a month in YYYY-MM format.

maximum_balance_by_monthobject

The maximum daily balance grouped by calendar month. Each key is a month in YYYY-MM format.

average_daily_balancenumber

The average amount in daily_balances.

average_daily_balance_by_monthobject

The average daily balance grouped by calendar month. Each key is a month in YYYY-MM format.

average_daily_balance_weekdaynumber

The average daily balance on weekdays.

average_daily_balance_weekday_by_monthobject

The average daily balance on weekdays grouped by calendar month. Each key is a month in YYYY-MM format.

total_daysinteger

Total number of days for which analytics is calculated.

negative_balances_by_monthobject

Dates with negative ending balances grouped by calendar month. Each key is a month in YYYY-MM format and the value is an array of date strings in YYYY-MM-DD format.

negative_balances_count_by_monthobject

Count of negative ending balances grouped by calendar month. Each key is a month in YYYY-MM format.

negative_balances_weekday_by_monthobject

Dates with negative ending balances on weekdays grouped by calendar month. Each key is a month in YYYY-MM format and the value is an array of date strings in YYYY-MM-DD format.

negative_balances_weekday_count_by_monthobject

Count of weekdays with negative ending balances grouped by calendar month. Each key is a month in YYYY-MM format.

cash_balance_trend_30dnumber

Daily cash balance trend of 30 days. The calculation formula is ((Mean cash balance over first 15 days ) - (Mean cash balance over last 15 days) ) / standard deviation of cash balance over the period.

cash_balance_trend_60dnumber

Daily cash balance trend of 60 days. The calculation formula is ((Mean cash balance over first 30 days ) - (Mean cash balance over last 30 days) ) / standard deviation of cash balance over the period.

cash_balance_trend_90dnumber

Daily cash balance trend of 90 days. The calculation formula is ((Mean cash balance over first 45 days ) - (Mean cash balance over last 45 days) ) / standard deviation of cash balance over the period.

cash_flow_trend_30dnumber

Daily cash flow trend of 30 days. The calculation formula is ((Mean cash flow over first 15 days ) - (Mean cash flow over last 15 days) ) / standard deviation of cash flow over the period.

cash_flow_trend_60dnumber

Daily cash flow trend of 60 days. The calculation formula is ((Mean cash flow over first 30 days ) - (Mean cash flow over last 30 days) ) / standard deviation of cash flow over the period.

cash_flow_trend_90dnumber

Daily cash flow trend of 90 days. The calculation formula is ((Mean cash flow over first 45 days ) - (Mean cash flow over last 45 days) ) / standard deviation of cash flow over the period.

average_txn_size_by_monthobject

The average transaction size grouped by month. Each key is the first day of the month in YYYY-MM-DD format.

average_deposits_by_monthobject

The average deposit size grouped by calendar month. Each key is a month in YYYY-MM format.

expense_by_monthobject

Expenses grouped by calendar month. Each key is a month in YYYY-MM format. Values are negative.

withdrawals_by_monthobject

Withdrawals grouped by calendar month. Each key is a month in YYYY-MM format. Values are negative.

revenue_by_monthobject

Revenue grouped by calendar month. Each key is a month in YYYY-MM format.

revenue_deduction_by_monthobject

Revenue deductions grouped by calendar month. Each key is a month in YYYY-MM format.

deposits_by_monthobject

Deposits grouped by calendar month. Each key is a month in YYYY-MM format.

outside_source_deposits_by_monthobject

Outside source deposits grouped by calendar month. Each key is a month in YYYY-MM format.

large_deposits_by_monthobject

Total amount of large deposits grouped by calendar month. Each key is a month in YYYY-MM format.

debt_consolidator_inflows_by_monthobject

Debt consolidator inflows grouped by calendar month. Each key is a month in YYYY-MM format.

debt_consolidator_outflows_by_monthobject

Debt consolidator outflows grouped by calendar month. Each key is a month in YYYY-MM format.

factoring_inflows_by_monthobject

Factoring inflows grouped by calendar month. Each key is a month in YYYY-MM format.

factoring_outflows_by_monthobject

Factoring outflows grouped by calendar month. Each key is a month in YYYY-MM format.

payroll_inflows_by_monthobject

Payroll inflows grouped by calendar month. Each key is a month in YYYY-MM format.

payroll_outflows_by_monthobject

Payroll outflows grouped by calendar month. Each key is a month in YYYY-MM format. Values are negative.

insurance_inflows_by_monthobject

Insurance inflows grouped by calendar month. Each key is a month in YYYY-MM format.

insurance_outflows_by_monthobject

Insurance outflows grouped by calendar month. Each key is a month in YYYY-MM format.

venmo_zelle_cashapp_inflows_by_monthobject

Venmo/Zelle/Cash App inflows grouped by calendar month. Each key is a month in YYYY-MM format.

venmo_zelle_cashapp_outflows_by_monthobject

Venmo/Zelle/Cash App outflows grouped by calendar month. Each key is a month in YYYY-MM format.

atm_inflows_by_monthobject

Automated teller machine (ATM) inflows grouped by calendar month. Each key is a month in YYYY-MM format.

atm_outflows_by_monthobject

Automated teller machine (ATM) outflows grouped by calendar month. Each key is a month in YYYY-MM format. Values are negative.

tolls_inflows_by_monthobject

Toll inflows grouped by calendar month. Each key is a month in YYYY-MM format.

tolls_outflows_by_monthobject

Toll outflows grouped by calendar month. Each key is a month in YYYY-MM format.

paypal_inflows_by_monthobject

PayPal inflows grouped by calendar month. Each key is a month in YYYY-MM format.

paypal_outflows_by_monthobject

PayPal outflows grouped by calendar month. Each key is a month in YYYY-MM format.

equipment_lease_inflows_by_monthobject

Equipment lease inflows grouped by calendar month. Each key is a month in YYYY-MM format.

equipment_lease_outflows_by_monthobject

Equipment lease outflows grouped by calendar month. Each key is a month in YYYY-MM format.

checks_inflows_by_monthobject

Check inflows grouped by calendar month. Each key is a month in YYYY-MM format.

checks_outflows_by_monthobject

Check outflows grouped by calendar month. Each key is a month in YYYY-MM format.

txn_four_zeros_inflows_by_monthobject

Transactions with four zeros inflows grouped by calendar month. Each key is a month in YYYY-MM format.

txn_four_zeros_outflows_by_monthobject

Transactions with four zeros outflows grouped by calendar month. Each key is a month in YYYY-MM format.

txn_five_zeros_inflows_by_monthobject

Transactions with five zeros inflows grouped by calendar month. Each key is a month in YYYY-MM format.

txn_five_zeros_outflows_by_monthobject

Transactions with five zeros outflows grouped by calendar month. Each key is a month in YYYY-MM format.

probable_recurring_txns_inflows_by_monthobject

Recurring transactions inflows grouped by calendar month. Each key is a month in YYYY-MM format.

probable_recurring_txns_outflows_by_monthobject

Recurring transactions outflows grouped by calendar month. Each key is a month in YYYY-MM format.

fintech_loan_inflows_by_monthobject

Fintech loan inflows grouped by calendar month. Each key is a month in YYYY-MM format.

fintech_loan_outflows_by_monthobject

Fintech loan outflows grouped by calendar month. Each key is a month in YYYY-MM format.

bank_loan_inflows_by_monthobject

Bank loan inflows grouped by calendar month. Each key is a month in YYYY-MM format.

bank_loan_outflows_by_monthobject

Bank loan outflows grouped by calendar month. Each key is a month in YYYY-MM format.

other_loan_inflows_by_monthobject

Other loan inflows grouped by calendar month. Each key is a month in YYYY-MM format.

other_loan_outflows_by_monthobject

Other loan outflows grouped by calendar month. Each key is a month in YYYY-MM format.

fintech_mca_inflows_by_monthobject

Fintech MCA (Merchant Cash Advance) inflows grouped by calendar month. Each key is a month in YYYY-MM format.

fintech_mca_outflows_by_monthobject

Fintech MCA (Merchant Cash Advance) outflows grouped by calendar month. Each key is a month in YYYY-MM format.

bank_cash_advance_inflows_by_monthobject

Bank cash advance inflows grouped by calendar month. Each key is a month in YYYY-MM format.

bank_cash_advance_outflows_by_monthobject

Bank cash advance outflows grouped by calendar month. Each key is a month in YYYY-MM format.

debit_card_inflows_by_monthobject

Debit card inflows grouped by calendar month. Each key is a month in YYYY-MM format.

debit_card_outflows_by_monthobject

Debit card outflows grouped by calendar month. Each key is a month in YYYY-MM format. Values are negative.

credit_card_inflows_by_monthobject

Credit card inflows grouped by calendar month. Each key is a month in YYYY-MM format.

credit_card_outflows_by_monthobject

Credit card outflows grouped by calendar month. Each key is a month in YYYY-MM format.

merchant_service_inflows_by_monthobject

Merchant service inflows grouped by calendar month. Each key is a month in YYYY-MM format.

merchant_service_outflows_by_monthobject

Merchant service outflows grouped by calendar month. Each key is a month in YYYY-MM format.

sba_inflows_by_monthobject

SBA inflows grouped by calendar month. Each key is a month in YYYY-MM format.

sba_outflows_by_monthobject

SBA outflows grouped by calendar month. Each key is a month in YYYY-MM format.

remote_inflows_by_monthobject

Remote inflows grouped by calendar month. Each key is a month in YYYY-MM format.

remote_outflows_by_monthobject

Remote outflows grouped by calendar month. Each key is a month in YYYY-MM format.

benefits_inflows_by_monthobject

Benefit inflows grouped by calendar month. Each key is a month in YYYY-MM format.

benefits_outflows_by_monthobject

Benefit outflows grouped by calendar month. Each key is a month in YYYY-MM format.

card_rewards_inflows_by_monthobject

Card reward inflows grouped by calendar month. Each key is a month in YYYY-MM format.

card_rewards_outflows_by_monthobject

Card reward outflows grouped by calendar month. Each key is a month in YYYY-MM format.

crypto_inflows_by_monthobject

Crypto inflows grouped by calendar month. Each key is a month in YYYY-MM format.

crypto_outflows_by_monthobject

Crypto outflows grouped by calendar month. Each key is a month in YYYY-MM format.

gambling_inflows_by_monthobject

Gambling inflows grouped by calendar month. Each key is a month in YYYY-MM format.

gambling_outflows_by_monthobject

Gambling outflows grouped by calendar month. Each key is a month in YYYY-MM format. Values are negative.

investment_inflows_by_monthobject

Investment inflows grouped by calendar month. Each key is a month in YYYY-MM format.

investment_outflows_by_monthobject

Investment outflows grouped by calendar month. Each key is a month in YYYY-MM format.

reversed_inflows_by_monthobject

Reversed inflows grouped by calendar month. Each key is a month in YYYY-MM format.

reversed_outflows_by_monthobject

Reversed outflows grouped by calendar month. Each key is a month in YYYY-MM format.

state_tax_inflows_by_monthobject

State tax inflows grouped by calendar month. Each key is a month in YYYY-MM format.

state_tax_outflows_by_monthobject

State tax outflows grouped by calendar month. Each key is a month in YYYY-MM format.

payroll_tax_inflows_by_monthobject

Payroll tax inflows grouped by calendar month. Each key is a month in YYYY-MM format.

payroll_tax_outflows_by_monthobject

Payroll tax outflows grouped by calendar month. Each key is a month in YYYY-MM format.

internal_transfer_inflows_by_monthobject

Internal transfer inflows grouped by calendar month. Each key is a month in YYYY-MM format.

internal_transfer_outflows_by_monthobject

Internal transfer outflows grouped by calendar month. Each key is a month in YYYY-MM format.

merchant_service_transfer_inflows_by_monthobject

Merchant service transfer inflows grouped by calendar month. Each key is a month in YYYY-MM format.

merchant_service_transfer_outflows_by_monthobject

Merchant service transfer outflows grouped by calendar month. Each key is a month in YYYY-MM format.

wire_transfer_inflows_by_monthobject

Wire transfer inflows grouped by calendar month. Each key is a month in YYYY-MM format.

wire_transfer_outflows_by_monthobject

Wire transfer outflows grouped by calendar month. Each key is a month in YYYY-MM format.

other_transfer_inflows_by_monthobject

Other transfer inflows grouped by calendar month. Each key is a month in YYYY-MM format.

other_transfer_outflows_by_monthobject

Other transfer outflows grouped by calendar month. Each key is a month in YYYY-MM format.

truck_stop_inflows_by_monthobject

Truck stop inflows grouped by calendar month. Each key is a month in YYYY-MM format.

truck_stop_outflows_by_monthobject

Truck stop outflows grouped by calendar month. Each key is a month in YYYY-MM format.

federal_tax_inflows_by_monthobject

Federal tax inflows grouped by calendar month. Each key is a month in YYYY-MM format.

federal_tax_outflows_by_monthobject

Federal tax outflows grouped by calendar month. Each key is a month in YYYY-MM format.

bank_branch_inflows_by_monthobject

Bank branch inflows grouped by calendar month. Each key is a month in YYYY-MM format.

bank_branch_outflows_by_monthobject

Bank branch outflows grouped by calendar month. Each key is a month in YYYY-MM format.

credit_builder_inflows_by_monthobject

Credit builder inflows grouped by calendar month. Each key is a month in YYYY-MM format.

credit_builder_outflows_by_monthobject

Credit builder outflows grouped by calendar month. Each key is a month in YYYY-MM format.

expense_count_by_monthobject

Expense counts grouped by calendar month. Each key is a month in YYYY-MM format.

withdrawals_count_by_monthobject

Withdrawal counts grouped by calendar month. Each key is a month in YYYY-MM format.

revenue_count_by_monthobject

Revenue counts grouped by calendar month. Each key is a month in YYYY-MM format.

deposits_count_by_monthobject

Deposit counts grouped by calendar month. Each key is a month in YYYY-MM format.

nsf_fee_count_by_monthobject

Non-sufficient funds (NSF) fees count grouped by calendar month. Each key is a month in YYYY-MM format.

nsf_divisornumber nullable

Calculated amount for a single NSF fee. The common divisor is defined as the least common multiple (in 0.50 increments) of amount values corresponding to transactions with nsf = True. This multiple must fall between 25 and 60 (inclusive) otherwise nsf_divisor = null and no scaling occurs.

nsf_raw_fee_count_by_monthobject

Non-sufficient funds (NSF) fee count (NOT including common divisor logic) grouped by calendar month. Each key is a month in YYYY-MM format.

overdraft_fee_count_by_monthobject

Overdraft fees count grouped by calendar month. Each key is a month in YYYY-MM format.

overdraft_divisornumber nullable

Calculated amount for a single overdraft fee. The common divisor is defined as the least common multiple (in 0.50 increments) of amount values corresponding to transactions with overdraft = True. This multiple must fall between 25 and 60 (inclusive) otherwise overdraft_divisor = null and no scaling occurs.

overdraft_raw_fee_count_by_monthobject

Overdraft fee count (NOT including common divisor logic) grouped by calendar month. Each key is a month in YYYY-MM format.

returned_item_deposit_count_by_monthobject

Returned item deposit count grouped by calendar month. Each key is a month in YYYY-MM format.

returned_item_withdrawal_count_by_monthobject

Returned item withdrawal count grouped by calendar month. Each key is a month in YYYY-MM format.

num_fintech_loan_sourcesinteger

Number of unique fintech loan sources detected in this Book.

num_fintech_mca_sourcesinteger

Number of unique fintech MCA sources detected in this Book.

number_of_docs_in_bookinteger

The total count of <glossary:Document>s uploaded to this <glossary:Book>.

number_of_docs_processedinteger

The total count of <glossary:Document>s in this <glossary:Book> that completed verification.

book_uuidstring

Universally unique identifier (UUID) for the <glossary:Book>.

Example response

{
  "business_verification_data": {
    "website": "https://www.jillscoffee.com"
  },
  "cash_flow_at_a_glance": {
    "average_deposit_count": 42,
    "average_monthly_revenue": 32383.6,
    "average_monthly_expense": 39418.2
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.