Guides
Ocrolus.comStart free trialRaise a request

Getting started with bank statements

Upload, capture, and analyze a bank statement.

Suggest Edits

This tutorial demonstrates how to upload, capture, and analyze a sample bank statement (see below). Upon completion of this tutorial, you will have detailed information and analysis about the bank statement in structured data. You may use your own bank statement to complete this tutorial, but for examples, refer to the sample bank statement below.

Sample bank statement.pdf
drive.google.comdrive.google.com
Sample bank statement.pdf

This tutorial assumes a working knowledge of curl.

Setting up authentication

Before you use the Ocrolus API, you'll need to create a set of authentication credentials with the following steps:

  1. Log in to the Ocrolus Dashboard.
  2. Navigate to the API Credentials tab.
  3. Add a new pair of credentials with the Add OAuth 2.0 API Credentials button.
  4. Follow the instructions given in the window that pops up.

You can find a full description of this process here.

Using the code samples

📘

To run test requests:

  1. Login to your account and create a authentication header.
  2. Copy the cURL examples below.
    • Replace the authentication example (--header 'Authorization: Bearer ZGV2ZWxvcGVyQG9jcm9sdXMuY29tOm15UGFzc3dvcmQ=') with your authentication header.
    • Replace any other parameters as indicated.

Upload

Uploading a document consists of two parts:

  1. Create a Book
  2. Add bank statement to your Book

Create a Book

Before uploading documents with Ocrolus, you must create a Book. Books are used to contain multiple documents, allowing you to store and analyze multiple documents as a unit.

To create a new Book, follow the steps below:

  1. Send a POST request to the Create a Book endpoint.
    • Include your authentication header
    • Include the name of your Book in the body of the request. In the example below the Book is called Sample bank statement.

Example request

curl --location 'https://api.ocrolus.com/v1/book/add' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVDRnR4MXFtcGprYzdzT2FDUUZiVCJ9.eyJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9hY2NvdW50X3BrIjoiMTg5NzYiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9vcmdfaW5mb19wayI6IjQwMDUiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9lbWFpbCI6ImtzaW5naDErZGVtb0BvY3JvbHVzLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5vY3JvbHVzLmNvbS8iLCJzdWIiOiI5aHppYTRJUDRxYTlQTGFzT25BYUw2ZzNVM014b3JPOEBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkub2Nyb2x1cy5jb20vIiwiaWF0IjoxNjc3ODE3OTcxLCJleHAiOjE2Nzc5MDQzNzEsImF6cCI6IjloemlhNElQNHFhOVBMYXNPbkFhTDZnM1UzTXhvck84IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.eH8l6z0F8W5BPCEG0yVz919lYgQ_c9GUMheR096-UTcQCaxorjNjq567vY-f95yKdajBvsa_1SX6VB48bBA9MUDjGZwRY2oqfyuza2ola1CHb0ktn2Y2VEEukjgvvtR4AftaRnlSGzmWxA6MfZM-NdUVXfCtR8JpnqsK48PfclwvFX3r9FqOQkFmO5xmrbGcz2z0Dbkl6quKziiAM4d-mFt6_iJKQgmlQGE9R1FZGOkQ8kRzE2TjY9WFvoRzHamKqOnE6aa5sEb9ABl-MVZl-txSYlsFmyM6q9UXSvuzBUhyJStpW0L3Nhc9_qYSB-wNB--Sejb1E_fBcG7hDvPFUQ' \
--form 'is_public="true"' \
--form 'name="Sample bank statement"'
  1. A successful response will include the Book UUID key. This is the unique identifier used to access the Book in other requests.

Example 200 response

{
    "status": 200,
    "response": {
        "name": "Sample bank statement",
        "created": "2023-03-03T04:36:31Z",
        "created_ts": "2023-03-03T04:36:31Z",
        "pk": 30219565,
        "owner_email": "[email protected]",
        "is_public": true,
        "uuid": "19aab921-25a5-4beb-a59e-ac72320061d6",
        "id": 30219565
    },
    "message": "OK"
}
  1. Note the Book UUID (response.uuid) value. It will be used in the next step.

Add bank statement to your Book

Once the Book has successfully been created, you are ready to start adding documents. To upload the example bank statement to your Book, follow the steps below:

  1. Download the example bank statement.
  2. Send a POST request to the Upload PDF to Book endpoint.
    • Include your authentication header.
    • Include the bank statement as form data in the request payload. (See our multipart/form-data Payloads tutorial if you need help formatting this request).
    • Include the Book UUID (book_uuid) value as form data in the payload.

Example request

curl --location 'https://api.ocrolus.com/v1/book/upload' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVDRnR4MXFtcGprYzdzT2FDUUZiVCJ9.eyJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9hY2NvdW50X3BrIjoiMTg5NzYiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9vcmdfaW5mb19wayI6IjQwMDUiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9lbWFpbCI6ImtzaW5naDErZGVtb0BvY3JvbHVzLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5vY3JvbHVzLmNvbS8iLCJzdWIiOiI5aHppYTRJUDRxYTlQTGFzT25BYUw2ZzNVM014b3JPOEBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkub2Nyb2x1cy5jb20vIiwiaWF0IjoxNjc3ODE3OTcxLCJleHAiOjE2Nzc5MDQzNzEsImF6cCI6IjloemlhNElQNHFhOVBMYXNPbkFhTDZnM1UzTXhvck84IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.eH8l6z0F8W5BPCEG0yVz919lYgQ_c9GUMheR096-UTcQCaxorjNjq567vY-f95yKdajBvsa_1SX6VB48bBA9MUDjGZwRY2oqfyuza2ola1CHb0ktn2Y2VEEukjgvvtR4AftaRnlSGzmWxA6MfZM-NdUVXfCtR8JpnqsK48PfclwvFX3r9FqOQkFmO5xmrbGcz2z0Dbkl6quKziiAM4d-mFt6_iJKQgmlQGE9R1FZGOkQ8kRzE2TjY9WFvoRzHamKqOnE6aa5sEb9ABl-MVZl-txSYlsFmyM6q9UXSvuzBUhyJStpW0L3Nhc9_qYSB-wNB--Sejb1E_fBcG7hDvPFUQ' \
--form 'upload=@"/Users/ocrolus/Downloads/Sample bank statement.pdf"' \
--form 'book_uuid="19aab921-25a5-4beb-a59e-ac72320061d6"'
  1. A successful response will return an array containing information about the document uploaded to the Book.

Example 200 response

{
    "status": 200,
    "response": {
        "uploaded_docs": [
            {
                "pk": 52386256,
                "uuid": "4ad17d9e-1963-44c3-b709-2c5c80b9d667",
                "name": "Sample bank statement.pdf",
                "page_count": 3,
                "checksum": "b1dcf0608555e1309cec2e9afda5205c",
                "created_ts": "2023-03-03T05:09:18Z",
                "id": 52386256
            }
        ]
    },
    "message": "OK"
}

Check document status (optional)

For testing purposes, it can be helpful to check the status of the documents uploaded in your Book. This step is optional. Its use is discouraged in a production workflow. Each document may have one status included in the Document Status table:

To check the status of your document, follow the steps below.

  1. Send a GET request to the Book Status endpoint.
  2. Include your authentication header.
  3. Include the Book's primary key in the body of your request.

Example request

curl --request GET \
    --url https://api.ocrolus.com/v1/book/status \
    --header 'Content-Type: application/json'
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVDRnR4MXFtcGprYzdzT2FDUUZiVCJ9.eyJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9hY2NvdW50X3BrIjoiMTg5NzYiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9vcmdfaW5mb19wayI6IjQwMDUiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9lbWFpbCI6ImtzaW5naDErZGVtb0BvY3JvbHVzLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5vY3JvbHVzLmNvbS8iLCJzdWIiOiI5aHppYTRJUDRxYTlQTGFzT25BYUw2ZzNVM014b3JPOEBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkub2Nyb2x1cy5jb20vIiwiaWF0IjoxNjc3ODE3OTcxLCJleHAiOjE2Nzc5MDQzNzEsImF6cCI6IjloemlhNElQNHFhOVBMYXNPbkFhTDZnM1UzTXhvck84IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.eH8l6z0F8W5BPCEG0yVz919lYgQ_c9GUMheR096-UTcQCaxorjNjq567vY-f95yKdajBvsa_1SX6VB48bBA9MUDjGZwRY2oqfyuza2ola1CHb0ktn2Y2VEEukjgvvtR4AftaRnlSGzmWxA6MfZM-NdUVXfCtR8JpnqsK48PfclwvFX3r9FqOQkFmO5xmrbGcz2z0Dbkl6quKziiAM4d-mFt6_iJKQgmlQGE9R1FZGOkQ8kRzE2TjY9WFvoRzHamKqOnE6aa5sEb9ABl-MVZl-txSYlsFmyM6q9UXSvuzBUhyJStpW0L3Nhc9_qYSB-wNB--Sejb1E_fBcG7hDvPFUQ' \
    --data '{
        "pk": "30219565"
    }'
  1. A successful response will return an array containing information about each document in the Book.

Example 200 response

{
    "status": 200,
    "response": {
        "name": "Sample bank statement",
        "created": "2023-03-03T04:36:31Z",
        "created_ts": "2023-03-03T04:36:31Z",
        "pk": 30219565,
        "owner_email": "[email protected]",
        "is_public": true,
        "uuid": "19aab921-25a5-4beb-a59e-ac72320061d6",
        "id": 30219565,
        "is_shared_or_public_book": true,
        "docs": [
            {
                "pk": 52386256,
                "name": "Sample bank statement.pdf",
                "uuid": "4ad17d9e-1963-44c3-b709-2c5c80b9d667",
                "pages": 3,
                "md5": "b1dcf0608555e1309cec2e9afda5205c",
                "status": "VERIFICATION_COMPLETE",
                "image_group_pk": null,
                "mixed_uploaded_doc_pk": null
            }
        ],
        "mixed_docs": [],
        "book_status": "VERIFIED"
    },
    "message": "OK"
}
  1. Find the desired document in the documents array.
    a. See the array of documents in the response (response.docs)
    b. Find the bank statement in the array. (You can do this by finding the object with the correct name (name), primary key (pk), or Book UUID (uuid)).

In the example above, our document is the first item in the array. This means you can check the status by looking at the value in response.docs[0].status.

📘

How long?

Turnaround time for document upload depends on several factors, including document quality, document source, and whether fraud or suspicious activity is detected. In general, analytics data will be ready to download within a few minutes.

Capture

Extract data from the uploaded documents. For the sample bank statement, you can view the full transaction list using the Enriched Transactions endpoint.

The steps below demonstrate how to request the full transaction list:

  1. Send a GET request to the Transactions endpoint.
  2. Include your authentication header.
  3. Include the Book's primary key in the body of your request.

Example request

curl --request GET \
     --url https://api.ocrolus.com/v2/book/19aab921-25a5-4beb-a59e-ac72320061d6/enriched_txns \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVDRnR4MXFtcGprYzdzT2FDUUZiVCJ9.eyJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9hY2NvdW50X3BrIjoiMTg5NzYiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9vcmdfaW5mb19wayI6IjQwMDUiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9lbWFpbCI6ImtzaW5naDErZGVtb0BvY3JvbHVzLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5vY3JvbHVzLmNvbS8iLCJzdWIiOiI5aHppYTRJUDRxYTlQTGFzT25BYUw2ZzNVM014b3JPOEBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkub2Nyb2x1cy5jb20vIiwiaWF0IjoxNjc3ODE3OTcxLCJleHAiOjE2Nzc5MDQzNzEsImF6cCI6IjloemlhNElQNHFhOVBMYXNPbkFhTDZnM1UzTXhvck84IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.eH8l6z0F8W5BPCEG0yVz919lYgQ_c9GUMheR096-UTcQCaxorjNjq567vY-f95yKdajBvsa_1SX6VB48bBA9MUDjGZwRY2oqfyuza2ola1CHb0ktn2Y2VEEukjgvvtR4AftaRnlSGzmWxA6MfZM-NdUVXfCtR8JpnqsK48PfclwvFX3r9FqOQkFmO5xmrbGcz2z0Dbkl6quKziiAM4d-mFt6_iJKQgmlQGE9R1FZGOkQ8kRzE2TjY9WFvoRzHamKqOnE6aa5sEb9ABl-MVZl-txSYlsFmyM6q9UXSvuzBUhyJStpW0L3Nhc9_qYSB-wNB--Sejb1E_fBcG7hDvPFUQ'
  1. A successful response will return an array of transactions from the document.

Example 200 response

{
    "status": 200,
    "response": {
        "book_uuid": "19aab921-25a5-4beb-a59e-ac72320061d6",
        "enriched_transactions": [
          {
            "txn_pk": 4009436003,
            "txn_date": "2021-04-30",
            "description": "PAYMENT CARD",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": -1000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": false,
            "equipment_lease": false,
            "expense": true,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": false,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": true,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009436002,
            "txn_date": "2021-04-28",
            "description": "ACCOUNT TRANSFER OUT",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": -1000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": false,
            "equipment_lease": false,
            "expense": true,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": true,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": true,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009436001,
            "txn_date": "2021-04-25",
            "description": "PAYMENT - CAR LOAN",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": -1000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": false,
            "equipment_lease": false,
            "expense": true,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": true,
            "other_transfer": false,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": true,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009436000,
            "txn_date": "2021-04-22",
            "description": "PAYMENT - WATER UTILITY",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": -1000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": false,
            "equipment_lease": false,
            "expense": true,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": false,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": true,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009435999,
            "txn_date": "2021-04-21",
            "description": "PAYMENT - ELECTRICITY",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": -1000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": false,
            "equipment_lease": false,
            "expense": true,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": false,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": true,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009435998,
            "txn_date": "2021-04-20",
            "description": "CHEQUE DEPOSIT",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": 3000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": true,
            "equipment_lease": false,
            "expense": false,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": false,
            "outside_source_deposits": true,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": true,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": false,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009435997,
            "txn_date": "2021-04-19",
            "description": "ACCOUNT TRANSFER IN",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": 3000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": true,
            "equipment_lease": false,
            "expense": false,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": false,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": true,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": true,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": false,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          },
          {
            "txn_pk": 4009435996,
            "txn_date": "2021-04-17",
            "description": "PAYMENT - INSURANCE",
            "bank_account_pk": 14359008,
            "uploaded_doc_pk": 56253658,
            "uploaded_doc_name": "Sample bank statement.pdf",
            "amount": -1000,
            "atm": false,
            "bank_branch": false,
            "bank_cash_advance": false,
            "bank_loan": false,
            "bank": false,
            "benefits": false,
            "card_rewards": false,
            "checks": false,
            "counterparty": null,
            "credit_builder": false,
            "credit_card": false,
            "crypto": false,
            "debit_card": false,
            "debt_consolidator": false,
            "deposits": false,
            "equipment_lease": false,
            "expense": true,
            "factoring": false,
            "federal_tax": false,
            "fintech_loan": false,
            "fintech_loan_source": null,
            "fintech_mca": false,
            "fintech_mca_source": null,
            "fintech": false,
            "gambling": false,
            "insurance": true,
            "internal_transfer": false,
            "investment": false,
            "merchant_service_transfer": false,
            "merchant_service": false,
            "nsf": false,
            "nsf_paid_or_negative_balance": false,
            "nsf_returned_or_not_paid": false,
            "other_loan": false,
            "other_transfer": false,
            "outside_source_deposits": false,
            "overdraft": false,
            "paypal": false,
            "payroll_tax": false,
            "payroll": false,
            "probable_recurring_txns": true,
            "remote": false,
            "returned_item": false,
            "revenue_deduction_other": false,
            "revenue_deduction": false,
            "revenue": false,
            "reversed": false,
            "sba": false,
            "state_tax": false,
            "tolls": false,
            "truck_stop": false,
            "txn_five_zeros": true,
            "txn_four_zeros": true,
            "venmo_zelle_cashapp": false,
            "wire_transfer": false,
            "withdrawals": true,
            "comment": null,
            "is_noteworthy": false,
            "page_idx": 0
          }
        ],
        "total": 8,
        "number_of_docs_in_book": 1,
        "number_of_docs_processed": 1,
        "uploaded_docs": [
          {
            "pk": 56193560,
            "uuid": "3927d5b7-ca34-4882-b23f-0ce40d40027c",
            "status": "VERIFICATION_COMPLETE",
            "pages": 1,
            "mixed_uploaded_doc_pk": 11602174,
            "mixed_uploaded_doc_uuid": "0c1446f2-6037-4d66-bb01-d9d2bf3f0886",
            "rejection_reason": null
          }
          
        ]
      },
    "message": "OK"
 }

Analyze

View analytics on the extracted data from uploaded documents.

📘

Note:

The steps below demonstrate how to download analytics synchronously. If desired, you may also download analytics asynchronously. Make sure you have set up webhooks.

Download analyzed bank statement data

Once the uploaded data has been analyzed by Ocrolus, you can download the results. You may download data in JSON or XSV format.

The following example shows how to download analytics in JSON format.

  1. Send a GET request to the Analytics (JSON) endpoint.
  2. Include your authentication header.
  3. Include the Book's uuid key in the path parameter of your request.

Example request

curl --request GET \
     --url https://api.ocrolus.com/v2/book/book_uuid/income/bank-statement-v2 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVDRnR4MXFtcGprYzdzT2FDUUZiVCJ9.eyJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9hY2NvdW50X3BrIjoiMTg5NzYiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9vcmdfaW5mb19wayI6IjQwMDUiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9lbWFpbCI6ImtzaW5naDErZGVtb0BvY3JvbHVzLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5vY3JvbHVzLmNvbS8iLCJzdWIiOiI5aHppYTRJUDRxYTlQTGFzT25BYUw2ZzNVM014b3JPOEBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkub2Nyb2x1cy5jb20vIiwiaWF0IjoxNjc3ODE3OTcxLCJleHAiOjE2Nzc5MDQzNzEsImF6cCI6IjloemlhNElQNHFhOVBMYXNPbkFhTDZnM1UzTXhvck84IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.eH8l6z0F8W5BPCEG0yVz919lYgQ_c9GUMheR096-UTcQCaxorjNjq567vY-f95yKdajBvsa_1SX6VB48bBA9MUDjGZwRY2oqfyuza2ola1CHb0ktn2Y2VEEukjgvvtR4AftaRnlSGzmWxA6MfZM-NdUVXfCtR8JpnqsK48PfclwvFX3r9FqOQkFmO5xmrbGcz2z0Dbkl6quKziiAM4d-mFt6_iJKQgmlQGE9R1FZGOkQ8kRzE2TjY9WFvoRzHamKqOnE6aa5sEb9ABl-MVZl-txSYlsFmyM6q9UXSvuzBUhyJStpW0L3Nhc9_qYSB-wNB--Sejb1E_fBcG7hDvPFUQ'
  1. A successful response will return the analytics.

Example 200 response

{
    "status": 200,
    "response": {
        "book_uuid": "19aab921-25a5-4beb-a59e-ac72320061d6",
        "calculated_at": "2023-12-15T12:42:49.722279-05:00",
        "bank_statement_income": [
            {
                "account": {
                    "account_number": "111234567890",
                    "holder_name": "ALEXANDER HAMILTON"
                },
                "deposits": [
                    {
                        "date": "2021-04-20",
                        "description": "CHEQUE DEPOSIT",
                        "amount": 3000,
                        "exclude": false,
                        "is_large": false
                    },
                    {
                        "date": "2021-04-19",
                        "description": "ACCOUNT TRANSFER IN",
                        "amount": 3000,
                        "exclude": true,
                        "is_large": false
                    },
                    {
                        "date": "2021-04-06",
                        "description": "CHEQUE DEPOSIT",
                        "amount": 3000,
                        "exclude": false,
                        "is_large": false
                    },
                    {
                        "date": "2021-04-04",
                        "description": "ACCOUNT TRANSFER IN",
                        "amount": 3000,
                        "exclude": true,
                        "is_large": false
                    }
                ],
                "nsf_transactions": [],
                "calculations": {
                    "nsf_count": 0,
                    "statement_summary": [
                        {
                            "begin_date": "2021-04-16",
                            "end_date": "2021-04-30",
                            "total_deposits": 3000,
                            "total_nsf_count": 0,
                            "beginning_balance": 10000,
                            "ending_balance": 10000
                        },
                        {
                            "begin_date": "2021-04-01",
                            "end_date": "2021-04-15",
                            "total_deposits": 3000,
                            "total_nsf_count": 0,
                            "beginning_balance": 10000,
                            "ending_balance": 10000
                        }
                    ],
                    "large_deposit_summary": {
                        "average_deposit": 3000,
                        "percentage_amount": 50,
                        "deposit_threshold": 4500
                    },
                    "total_deposit_summary": {
                        "deposits": 12000,
                        "included_deposits": 6000,
                        "excluded_deposits": 6000
                    },
                    "total_included_months": 2,
                    "qualifying_income_average": 3000
                }
            }
        ]
    },
    "message": "OK"
}

📘

Is it ready yet?

If you are having trouble downloading analytics data, please make sure you have allowed sufficient time for Ocrolus to analyze your document. Document analysis generally takes a few minutes, although factors such as document quality, source, and suspected fraud or suspicious activity can cause analysis to take longer.

Detect

Check if any sign of suspected fraud is detected on the uploaded documents. Detect will process only bank statements, pay stubs, and W-2s. It will run as the last step during the document processing phase.

📘

Note:

Ensure that you have configured webhooks to react on Ocrolus events. To know more about how to configure webhooks, see Configure webhooks.

Download detect-processed bank statement data

After Detect processes the document, you can check the results using API or Ocrolus Dashboard. You can check the results and get visualizations at the Book or document level using the following set of endpoints:

To get the Detect outcomes at the Book level:

  1. Send a GET request using Book Level Signals endpoint.
  2. Include your authentication header.
  3. Include the Book UUID value in the body of your request.

Example request

curl --location 'https://api.ocrolus.com/v2/detect/book/19aab921-25a5-4beb-a59e-ac72320061d6/signals' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImVDRnR4MXFtcGprYzdzT2FDUUZiVCJ9.eyJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9hY2NvdW50X3BrIjoiMTg5NzYiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9vcmdfaW5mb19wayI6IjQwMDUiLCJodHRwczovL2NsYWltcy5vY3JvbHVzLmNvbS9lbWFpbCI6ImtzaW5naDErZGVtb0BvY3JvbHVzLmNvbSIsImlzcyI6Imh0dHBzOi8vYXV0aC5vY3JvbHVzLmNvbS8iLCJzdWIiOiI5aHppYTRJUDRxYTlQTGFzT25BYUw2ZzNVM014b3JPOEBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkub2Nyb2x1cy5jb20vIiwiaWF0IjoxNjc3ODE3OTcxLCJleHAiOjE2Nzc5MDQzNzEsImF6cCI6IjloemlhNElQNHFhOVBMYXNPbkFhTDZnM1UzTXhvck84IiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIn0.eH8l6z0F8W5BPCEG0yVz919lYgQ_c9GUMheR096-UTcQCaxorjNjq567vY-f95yKdajBvsa_1SX6VB48bBA9MUDjGZwRY2oqfyuza2ola1CHb0ktn2Y2VEEukjgvvtR4AftaRnlSGzmWxA6MfZM-NdUVXfCtR8JpnqsK48PfclwvFX3r9FqOQkFmO5xmrbGcz2z0Dbkl6quKziiAM4d-mFt6_iJKQgmlQGE9R1FZGOkQ8kRzE2TjY9WFvoRzHamKqOnE6aa5sEb9ABl-MVZl-txSYlsFmyM6q9UXSvuzBUhyJStpW0L3Nhc9_qYSB-wNB--Sejb1E_fBcG7hDvPFUQ'
  1. A successful response will return the detected outcomes.

Example 200 response

{
    "book_uuid": "19aab921-25a5-4beb-a59e-ac72320061d6",
    "doc_analysis": [
        {
            "uploaded_doc_uuid": "4ad17d9e-1963-44c3-b709-2c5c80b9d667",
            "uploaded_doc_type": "BANK_STATEMENT",
            "detect_status": "COMPLETED",
            "form_analysis": [
                {
                    "form_type": "BANK_STATEMENT",
                    "form_uuid": "4ad17d9e-1963-44c3-b709-2c5c80b9d667",
                    "signals": [
                        {
                            "identifier": "account_type_edits",
                            "display_name": "Account Type Edits",
                            "signal_count": 1,
                            "page_number": 1,
                            "supporting_data": [
                                {
                                    "values": [
                                        {
                                            "key": "field_name",
                                            "value": "accountInfo:accountType",
                                            "data_type": "str"
                                        },
                                        {
                                            "key": "tampered_text",
                                            "value": "SUMMARY",
                                            "data_type": "str"
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "visualizations": [
                        {
                            "page_number": 1,
                            "page_visualizations": [
                                {
                                    "visual_type": "tamper_overview",
                                    "display_name": "Tamper Overview",
                                    "description": "Tampered fields are highlighted in red.",
                                    "image_url": "https://api.ocrolus.com/v2/detect/visualization/3722a2a1-fdd9-4fc1-9681-f38fdc98ce5b"
                                },
                                {
                                    "visual_type": "added_fonts",
                                    "display_name": "Added Fonts",
                                    "description": "Text that was added to the document is highlighted in red.",
                                    "image_url": "https://api.ocrolus.com/v2/detect/visualization/644cc4ac-404c-42a2-a8ef-6d5f437faf46"
                                }
                            ]
                        },
                        {
                            "page_number": 2,
                            "page_visualizations": [
                                {
                                    "visual_type": "tamper_overview",
                                    "display_name": "Tamper Overview",
                                    "description": "Tampered fields are highlighted in red.",
                                    "image_url": "https://api.ocrolus.com/v2/detect/visualization/8d4054ab-dec3-4e22-811a-ae208b984f34"
                                }
                            ]
                        },
                        {
                            "page_number": 3,
                            "page_visualizations": [
                                {
                                    "visual_type": "tamper_overview",
                                    "display_name": "Tamper Overview",
                                    "description": "Tampered fields are highlighted in red.",
                                    "image_url": "https://api.ocrolus.com/v2/detect/visualization/5ccf2524-1d10-41fb-b02f-2e58875edce7"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

For further details, see Getting signals at the document level and Getting individual visualizations topics.

Updated about 1 month ago