--- title: Ocrolus API Integration on Truto slug: ocrolus category: Accounting canonical: "https://truto.one/integrations/detail/ocrolus/" --- # Ocrolus API Integration on Truto **Category:** Accounting **Status:** Beta ## Unified APIs ### Unified User Directory API - **Users** — The User object represents a User. ## MCP-ready AI tools Truto exposes 67 tools for Ocrolus that AI agents can call directly. - **list_all_ocrolus_books** — List Ocrolus books with optional filtering by name, keyword search, or external ID. Returns: pk, book_uuid, name, book_class, book_type, is_public, xid, created. Results are returned in descending order by default. - **create_a_ocrolus_book** — Create a new Book in Ocrolus for organizing and processing documents. Returns: pk, book_uuid, name, book_class, book_type, is_public, xid, created. Required: name. - **get_single_ocrolus_book_by_id** — Get information about a specific Ocrolus Book by UUID or primary key. Returns: pk, book_uuid, name, book_class, book_type, is_public, xid, created. Required: book_uuid or pk (mutually exclusive). - **ocrolus_books_get_status** — Get the processing status of an Ocrolus Book by UUID or primary key. Returns: pk, book_uuid. Required: book_uuid or pk (mutually exclusive). - **update_a_ocrolus_book_by_id** — Update an existing Ocrolus Book's name, processing class, type, visibility, or external ID. Returns: pk, book_uuid, name, book_class, book_type, is_public, xid, created. Required: book_uuid or pk (mutually exclusive). - **delete_a_ocrolus_book_by_id** — Delete an Ocrolus Book by providing either its primary key or UUID. Returns an empty 204 response on success. Required: book_id or book_uuid (mutually exclusive). - **ocrolus_books_get_classification_summary** — Get the document classification summary for an Ocrolus Book. Returns a classification summary object with form type breakdowns and duplicate detection results. Required: book_uuid. - **ocrolus_books_get_form_data** — Get form data extracted from documents in an Ocrolus Book. Returns the captured form field values for the specified Book. Required: book_uuid or pk (mutually exclusive). - **ocrolus_books_get_summary** — Get the analytics summary for an Ocrolus Book containing bank statement transactions. Returns: job_id. Required: book_uuid. Books with more than 100,000 transactions require async=true; books exceeding 1,000,000 transactions are rejected. - **ocrolus_books_get_fraud_signals** — Get fraud detection signals for an Ocrolus Book. Returns the fraud analysis results including dashboard_url. Required: book_uuid. - **ocrolus_documents_upload_pdf** — Upload a PDF file to an Ocrolus Book for processing as a typed document. Returns: status, message, response. Required: upload, book_uuid, form_type. book_uuid and pk are mutually exclusive. Max 200 MB or 3000 pages per document. - **ocrolus_documents_upload_mixed_pdf** — Upload a mixed PDF to an Ocrolus Book for automatic document classification. Returns: status, message, response. Required: upload, book_uuid. book_uuid and pk are mutually exclusive. Max 200 MB or 3000 pages per document. - **ocrolus_documents_upload_json** — Upload a Plaid or Finicity JSON file to an Ocrolus Book for analytics or reconciliation processing. Returns: status, message, response, grant_type. Required: either pk or uuid (the Book identifier) and upload (the JSON file). The upload_intent parameter controls whether transactions are added for analytics or matched against existing bank statement data for mismatch detection. - **ocrolus_documents_import_plaid_asset_report** — Import a Plaid Asset Report into an Ocrolus Book, creating a new Document from the provided asset report copy token. Returns the standard Ocrolus response envelope with status, message, and a response object containing the import result. Required: pk, audit_copy_token. - **delete_a_ocrolus_document_by_id** — Delete a Document from an Ocrolus Book by doc_uuid or doc_id. Exactly one of doc_uuid or doc_id must be provided (mutually exclusive). Returns an empty 204 response on success. - **ocrolus_documents_download** — Download an Ocrolus document file by its doc_uuid. Returns the raw binary file content of the document (content-type specific, e.g. PDF). Required: doc_uuid. - **ocrolus_documents_get_fraud_signals** — Get fraud detection signals for a single Ocrolus document by uploaded_doc_uuid. Returns: doc_analysis, dashboard_url. Required: uploaded_doc_uuid. - **ocrolus_documents_get_mixed_document_classification_summary** — Retrieve the document classification summary for a mixed (multi-document) upload, showing how each page or sub-document was classified. - **ocrolus_image_groups_finalize** — Mark an uploaded image group as complete in Ocrolus, constructing a Document from the uploaded images. Returns: status, message, response. Supply either book_uuid or pk (mutually exclusive). - **ocrolus_image_groups_upload_image** — Upload an image file to an Ocrolus Book as part of an image group. Returns: status, message, response. Required: upload. Supply either book_uuid or pk (mutually exclusive). Maximum file size 200 MB. - **ocrolus_detect_get_visualization** — Retrieve an Ocrolus Detect visualization by its UUID. Returns a content-type-specific response — a PNG image by default, or JSON data when an application/json accept header is supplied. Required: visualization_id. - **list_all_ocrolus_transactions** — List Ocrolus transactions for a Book or Document after processing has completed. Returns transaction records extracted from processed bank statements. Filter by Book identifier (book_uuid or book_pk, mutually exclusive) or Document identifier (uploaded_doc_uuid or uploaded_doc_pk, mutually exclusive). - **ocrolus_transactions_list_enriched** — List enriched transactions for an Ocrolus Book, including enrichment tags, categories, and counterparties. Returns: job_id, pending_plaid_transactions, tags, categories, counterparties. Required: book_uuid. Async mode is required for Books with over 100,000 transactions; Books exceeding 1,000,000 transactions are rejected. - **ocrolus_cash_flow_get_features** — Get cash flow features analytics for an Ocrolus Book by book_uuid, analyzing all bank statements in the Book. Returns the cash flow features analytics payload, or job_id when async is enabled. Required: book_uuid. Async is required for Books with more than 100,000 transactions; Books exceeding 1,000,000 transactions are rejected. - **ocrolus_cash_flow_get_risk_score** — Get the cash flow risk score for an Ocrolus Book by book_uuid. Returns the risk score analytics payload, or job_id when async is enabled. Required: book_uuid. Async is required for Books with more than 100,000 transactions; risk score must be enabled for the organization. - **ocrolus_cash_flow_get_benchmarking** — Get benchmarking analytics for an Ocrolus Book by book_uuid, comparing the Book's cash flow metrics against a peer group filtered by geography, industry level, and time window. Returns benchmark analytics data for the Book. Required: book_uuid. Peer group must contain at least 30 Books. - **ocrolus_cash_flow_get_job_status** — Poll the status of an asynchronous analytics job (e.g. a cash flow risk score or benchmarking request that returned a job ID because it was submitted with async=true). Returns a presigned result URL once complete. - **ocrolus_income_get_summary** — Get an Ocrolus income summary for a Book, filtered by underwriting guideline. Returns: attributes. Required: book_uuid. The guideline parameter defaults to FANNIE_MAE and supports FANNIE_MAE, FREDDIE_MAC, FHA, VA, and USDA. - **ocrolus_income_get_calculations** — Get Ocrolus income calculations for a Book, filtered by underwriting guideline. Returns: attributes. Required: book_uuid. The guideline parameter defaults to FANNIE_MAE and supports FANNIE_MAE, FREDDIE_MAC, FHA, VA, and USDA. - **ocrolus_income_calculate_self_employed_fm** — Calculate self-employed income for a borrower in an Ocrolus Book using Fannie Mae guidelines. Returns: attributes (the calculated self-employed income data object). Required: book_uuid, borrower_uuid, business_uuid, meta_info. The income_guideline parameter defaults to FANNIE_MAE. - **ocrolus_income_get_bsic** — Get Bank Statement Income Calculator (BSIC) analytics for an Ocrolus Book. Returns: attributes. Required: book_uuid. Returns 425 when analytics are still processing. - **ocrolus_income_get_bsic_excel** — Download Bank Statement Income Calculator (BSIC) analytics for an Ocrolus Book as an Excel spreadsheet file. Required: book_uuid. Returns a binary .xlsx file with BSIC analysis data; returns 425 when analytics are still processing. - **ocrolus_income_configure_entity** — Configure the borrower/entity details required for income calculation on a book, including employment start date and income type (wage earner or self-employed). - **ocrolus_income_update_guideline** — Set the underwriting guideline used for income calculations on a book (e.g. Fannie Mae, Freddie Mac, FHA, VA, USDA, or conventional). - **ocrolus_webhooks_configure** — Configure an Ocrolus webhook endpoint with a URL and list of events to subscribe to. The event list replaces all existing subscriptions. Returns: webhook_uuid, url, event_names. Required: url, event. - **get_single_ocrolus_webhook_by_id** — Get a single Ocrolus webhook by id. Returns: webhook_uuid, url, event_names. Required: id. - **ocrolus_webhooks_get_configuration** — Get the current Ocrolus webhook configuration details. Returns: webhook_uuid, url, event_names. - **update_a_ocrolus_webhook_by_id** — Update an Ocrolus webhook's event subscriptions by uuid. The event list replaces all existing subscriptions. Returns: webhook_uuid, url, event_names. Required: webhook_uuid, webhook.event_names. - **ocrolus_webhooks_test** — Test the configured Ocrolus webhook endpoint by sending a test request to verify connectivity. Returns: webhook_endpoint. - **ocrolus_webhooks_test_org** — Test a specific Ocrolus org-level webhook by replaying a given event to verify the endpoint receives it. Returns: webhook_endpoint. Required: webhook_uuid, event_uuid. - **ocrolus_webhooks_list_events** — List events subscribed to a specific Ocrolus webhook. Returns: event_uuid, event_name. Required: webhook_uuid. - **ocrolus_webhooks_bulk_delete** — Delete an Ocrolus webhook by uuid. Returns: webhook_uuid, url, event_names. Required: webhook_uuid. - **create_a_ocrolus_webhook** — Register a new org-level webhook subscription for one or more event types. This is distinct from the legacy single-endpoint account configuration (see configure) and supports multiple concurrent subscriptions. - **list_all_ocrolus_webhooks** — List all org-level webhook subscriptions configured for the account. - **ocrolus_webhooks_rotate_secret** — Rotate the signing secret for an org-level webhook subscription. Use this to periodically refresh credentials or respond to a suspected leak. - **ocrolus_auth_grant_token** — Retrieve a JWT-compliant access token from Ocrolus for use with all other API endpoints. Returns: access_token, token_type, expires_in. Required: grant_type, client_id, client_secret. Tokens expire after 24 hours (86,400 seconds); refreshing every 12 hours is recommended. - **list_all_ocrolus_users** — List users belonging to the authenticated organization account. - **ocrolus_users_create_invitation** — Invite a new user to join the organization account by email. The invitation is valid for 7 days. - **ocrolus_users_list_invitations** — List pending invitations sent to prospective users of the organization account. - **ocrolus_business_get_identifier** — Retrieve the business identifier and display name associated with a book. Use this to resolve a book_uuid into a business_id for use with other business endpoints. - **get_single_ocrolus_business_by_id** — Retrieve full metadata for a business, including industry classification, loan history, and addresses. A business aggregates data across multiple books belonging to the same underlying entity. - **ocrolus_business_list_transactions** — List deduplicated, enriched transactions across all books belonging to a business. Unlike the book-scoped transactions endpoint, this aggregates and deduplicates transactions across the business's entire book history. - **ocrolus_business_get_summary** — Retrieve a financial summary for a business, aggregated across its books, over an optional date range. - **create_a_ocrolus_tag** — [Beta] Create a custom transaction tag for categorizing transactions in analytics and cash flow reporting. - **list_all_ocrolus_tags** — [Beta] List available transaction tags, optionally filtered by tag type (system or custom). - **get_single_ocrolus_tag_by_id** — [Beta] Retrieve a single transaction tag by its UUID. - **update_a_ocrolus_tag_by_id** — [Beta] Update an existing custom transaction tag's name, description, color, or customization. - **delete_a_ocrolus_tag_by_id** — [Beta] Delete a custom transaction tag. System tags cannot be deleted. - **ocrolus_tags_list_revenue_deduction_tags** — [Beta] List the tags currently configured to be treated as revenue deductions in cash flow and analytics calculations. - **ocrolus_tags_update_revenue_deduction_tags** — [Beta] Replace the full list of tags treated as revenue deductions in cash flow and analytics calculations. - **ocrolus_tags_update_book_transaction_tags** — [Beta] Override the tags assigned to specific transactions within a book, identified by their transaction primary key. - **create_a_ocrolus_book_copy_job** — Create book copy jobs (Encore) to share up to 50 books at a time from your organization to another organization on the Ocrolus network. - **list_all_ocrolus_book_copy_jobs** — List book copy jobs (Encore) for the organization, filtered by direction (outbound or inbound) and optionally by counterparty organization. - **ocrolus_book_copy_jobs_accept** — Accept an inbound book copy job (Encore), optionally renaming the book as it's added to your organization. - **ocrolus_book_copy_jobs_reject** — Reject an inbound book copy job (Encore), declining to add the shared book to your organization. - **ocrolus_book_copy_jobs_get_settings** — Retrieve the Encore book-copy settings for the organization, including which organizations are allowed to send or receive book copies. - **ocrolus_book_copy_jobs_run_kickouts** — Automatically accept or reject pending inbound book copy jobs according to the organization's configured auto-accept rules. ## How it works 1. **Link your customer's Ocrolus account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Ocrolus.** The Proxy API is a 1-to-1 mapping of the Ocrolus API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate self-employed mortgage income calculations** — Loan origination platforms can offer instant, Fannie Mae-compliant income figures pulled directly from borrower tax returns and bank statements, cutting underwriting cycles from days to hours. - **Detect tampered financial documents at intake** — SMB and consumer lending platforms can automatically flag altered bank statements and forged pay stubs during application submission, routing high-risk files to manual review with visual fraud evidence embedded in the UI. - **Unify Plaid data with uploaded bank statements** — Financial CRMs and lending platforms can offer credit analysts a single deduplicated, enriched transaction ledger that reconciles open banking feeds with paper statements — surfacing mismatches and revenue deduction tags. - **Benchmark SMB applicants against industry peers** — SMB lending platforms can score cash flow risk and compare applicants against geography and industry peer groups, giving credit teams objective context alongside the raw financials. - **Broker-to-lender loan package handoff** — Broker portals and wholesale lending networks can securely transfer processed borrower Books between Ocrolus accounts, eliminating redundant re-processing when packages move downstream. ## What you can build - **Drop-and-process document intake** — Let users upload a single mixed PDF of borrower documents and automatically classify, split, and extract structured data from W-2s, pay stubs, tax returns, and bank statements. - **Embedded fraud investigation view** — Surface tampering signals per document and embed Ocrolus's visualization dashboard in an iframe so investigators can inspect manipulated pixels without leaving your product. - **Fannie Mae / Freddie Mac income widget** — Display pre-calculated self-employed income figures adhering to FM, Freddie Mac, FHA, VA, or USDA guidelines directly inside a loan file view. - **Bank Statement Income Calculator (BSIC) reports** — Generate downloadable BSIC calculations and Excel exports based on extracted deposits, ready to attach to loan files or share with underwriters. - **Cash flow risk scoring and benchmarking** — Ship an SMB underwriting panel that scores applicant cash flow health and benchmarks it against peer books in the same industry and geography. - **Event-driven processing status UI** — Configure Ocrolus webhooks through Truto to drive real-time status indicators, completion notifications, and downstream automations without polling. ## FAQs ### How does authentication work for Ocrolus through Truto? Ocrolus uses OAuth-style token grants. Truto handles the token exchange and refresh lifecycle for your end users so you never store or rotate Ocrolus credentials yourself — your users connect their Ocrolus account once and Truto manages the session. ### Can we receive real-time processing events instead of polling for status? Yes. You can configure webhooks per connected account using the webhook management tools (create, update, rotate secret, test) exposed through Truto. Ocrolus will push events like document classification and processing completion so you can react without polling status endpoints. ### Does the integration support both document uploads and open banking data? Yes. You can upload PDFs, mixed PDFs, and image groups, and also ingest Plaid-style JSON asset reports or Finicity data into the same Book. Ocrolus handles deduplication and enrichment across sources so downstream transaction and cash flow queries return a unified view. ### Which underwriting guidelines are supported for income calculation? The self-employed income calculation endpoint supports Fannie Mae, Freddie Mac, FHA, VA, and USDA guidelines. You can also retrieve the Bank Statement Income Calculator (BSIC) results as structured data or as an Excel export. ### How do we share processed Books between two Ocrolus accounts (e.g., broker to lender)? Use the book copy job tools to create, list, accept, reject, or run kickouts on transfers. This lets a broker-facing SaaS hand off fully processed Books to a downstream lender's Ocrolus account without re-uploading or re-processing the underlying documents. ### Can we manage users and invitations inside our product? Yes. Through the Unified User Directory API and Ocrolus-specific user tools, you can list users, create invitations, and track invitation status — enabling you to provision underwriters or analysts into the connected Ocrolus workspace from your own admin UI. ## Related reading - [Connect Ocrolus to ChatGPT: Analyze Documents & Detect Fraud](https://truto.one/blog/connect-ocrolus-to-chatgpt-analyze-documents-detect-fraud/) — Learn how to build a managed MCP server to connect Ocrolus to ChatGPT. Automate document classification, detect fraud signals, and analyze cash flows. - [Connect Ocrolus to Claude: Automate Cash Flow & Risk Assessment](https://truto.one/blog/connect-ocrolus-to-claude-automate-cash-flow-risk-assessment/) — Learn how to connect Ocrolus to Claude using a managed MCP server. Automate document parsing, risk scoring, and cash flow analysis without writing custom connectors. - [Connect Ocrolus to AI Agents: Sync Transactions & Verify Income](https://truto.one/blog/connect-ocrolus-to-ai-agents-sync-transactions-verify-income/) — Learn how to connect Ocrolus to AI agents using Truto's unified tool layer. Build autonomous workflows for income verification, fraud detection, and transaction parsing.