Ocrolus API

Ocrolus API Documentation

Welcome to Ocrolus' API Documentation. You'll find comprehensive guides and documentation here to help you get started with the Ocrolus API. Let's jump right in!

Getting Started with Bank Statements

Upload, capture, and analyze a bank statement.

This tutorial demonstrates how to upload, capture and analyze a sample bank statement (see below). If you prefer, you may choose to use your own bank statement, but keep in mind that many of the examples will refer to the sample provided.

Using the Code Samples

πŸ“˜

To run test requests:

  1. In your account, create a basic authentication header.
  2. Copy the cURL examples below.
    • Replace the basic authentication example (--header 'Authorization: Basic ZGV2ZWxvcGVyQG9jcm9sdXMuY29tOm15UGFzc3dvcmQ=') with your basic authentication header.
    • Replace any parameters as indicated in the steps.

Upload

Uploading a document consists of two parts:

  1. Create a book
  2. Add the document to your book

Create a Book to Contain Your Bank Statement

Prior to 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 New Book endpoint.
    • Include your basic authentication header
    • Include the name of your book in the body of the request. In the example below the book is called 'Bank Statement Example Book'

Example Request:

curl --request POST \
    --url https://api.ocrolus.com/v1/book/add \
    --header 'Content-Type: application/json'
    --header 'Authorization: Basic ZGV2ZWxvcGVyQG9jcm9sdXMuY29tOm15UGFzc3dvcmQ=' \
    --data '{
        "name": "Bank Statement Example Book"
    }'

A successful response will include the book's primary key. This is the unique identifier used to access the book in other requests.

Example 200 Response:

{
    "status": 200, 
    "message" : "OK",
    "response": {
        "name": "Bank Statement Example Book",
        "created": "2016-08-15T10:03:06Z",
        "pk": 10399,
        "is_public" : false,
        "owner_email" : "[email protected]",
        "uuid": "8dc88eed-2b6f-414a-82f2-a99bd181cf6e"
    }
}
  1. Note the book's primary key (response.pk). 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.

Example Request

curl --request POST \
    --url https://api.ocrolus.com/v1/book/upload \
    --header 'Content-Type: multipart/form-data' \
    --header 'Authorization: Basic ZGV2ZWxvcGVyQG9jcm9sdXMuY29tOm15UGFzc3dvcmQ=' \
    --form 'pk=10399' \
    --form '[email protected]/path/to/Sam Bobley_bankstatement.pdf'

Example 200 Response

{
    "status": 200,
    "message": "OK",
    "response": {
        "uploaded_docs": [
            {
                "created_ts": "2020-11-19T05:10:01Z",
                "uuid": "d0b00100-daae-4541-b416-72c0551eaf03",
                "checksum": "cc03d3d69e108a6a3904ed9b5678259b",
                "page_count": 3,
                "pk": 123456,
                "id": 123456,
                "name": "Sam Bobley_bankstatement.pdf"
            }
        ]
    }
}

Check the Status of Your Book's Documents (Optional)

For testing purposes, it can be helpful check the status of the documents in your book. This step is optional. Its use is discouraged in a production workflow. Each document may have one statuses 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 basic 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: Basic ZGV2ZWxvcGVyQG9jcm9sdXMuY29tOm15UGFzc3dvcmQ=' \
    --data '{
        "pk": "10399"
    }'

A successful response will return an array containing information about each document in the book.

Example 200 Response

{
    "status": 200,
    "message": "OK",
    "response": {
        "name": "Bank Statement Example Book",
        "created": "2016-08-15T10:03:06Z",
        "is_shared_or_public_book": true,
        "docs": [
            {
                "status": "VERIFYING",
                "name": "Sam Bobley_bankstatement.pdf",
                "pk": 123456,
                "md5": "abcdefgh257ce4ae53ffbac4eb6c53ab",
                "pages": 2
            }
        ],
        "owner_email": "[email protected]",
        "is_public": true,
        "pk": 10399,
        "id": 10399
    }
}
  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) or primary key (pk))

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

Note: Turnaround time for document upload depends on several factors, including document quality and 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 example bank statement you can view full transaction list or a transaction snippet:

  1. Send a GET request to the Transactions endpoint.
  2. Include your basic 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/transaction \
    --header 'Authorization: Basic bGluZGFicmVhbm5lQGdtYWlsLmNvbTplYXN5cGFzc3dvcmQxMjM0NQ==' \
    --header 'Content-Type: application/json' \
    --data '{
        "book_pk" : "10399"
    }'

Example 200 Response

{
    "status": 200,
    "message": "OK",
    "response": {
        "bank_accounts": {
            "4282936": {
                "holder_state": "NY",
                "bank_name": "BANK OF AMERICA",
                "book_uuid": "53dcadb2-f6e9-4e22-8980-5c2a50209d0d",
                "holder_address_1": "101 Greenwich St",
                "account_type": "SAVINGS",
                "name": "900090009 BANK OF AMERICA SAVINGS",
                "holder_country": "US",
                "account_category": "PERSONAL ACCOUNT",
                "account_holder": "Sam Bobley",
                "holder_zip": "10006",
                "activity_info": {
                    "active": [
                        {
                            "start": {
                                "year": 2020,
                                "day": 17,
                                "month": 1
                            },
                            "end": {
                                "year": 2020,
                                "day": 13,
                                "month": 2
                            }
                        }
                    ],
                    "missing": []
                },
                "account_number": "900090009",
                "book_pk": 7400940,
                "holder_address_2": "FI 23",
                "pk": 4282936,
                "holder_city": "New York",
                "id": 4282936,
                "periods": [
                    {
                        "secondary_recon_error_reason": null,
                        "begin_date": "01/17/2020",
                        "bank_account_pk": 4282936,
                        "end_date": "02/13/2020",
                        "pk": 13604680,
                        "primary_recon_error_reason": null,
                        "begin_balance": "529.96",
                        "end_balance": "554.96",
                        "uploaded_doc_pk": 13928705
                    }
                ]
            },
            "4282844": {
                "holder_state": "",
                "bank_name": "BANK OF AMERICA",
                "book_uuid": "53dcadb2-f6e9-4e22-8980-5c2a50209d0d",
                "holder_address_1": "101 Greenwich St",
                "account_type": "CHECKING",
                "name": "900090009 BANK OF AMERICA CHECKING",
                "holder_country": "",
                "account_category": "BUSINESS ACCOUNT",
                "account_holder": "Sam Bobley",
                "holder_zip": "",
                "activity_info": {
                    "active": [
                        {
                            "start": {
                                "year": 2020,
                                "day": 17,
                                "month": 1
                            },
                            "end": {
                                "year": 2020,
                                "day": 13,
                                "month": 2
                            }
                        }
                    ],
                    "missing": []
                },
                "account_number": "900090009",
                "book_pk": 7400940,
                "holder_address_2": "FI 23",
                "pk": 4282844,
                "holder_city": "New York",
                "id": 4282844,
                "periods": [
                    {
                        "secondary_recon_error_reason": "Invalid Amount(s) Or Balance(s)",
                        "begin_date": "01/17/2020",
                        "bank_account_pk": 4282844,
                        "end_date": "02/13/2020",
                        "pk": 13604512,
                        "primary_recon_error_reason": "Potential Fraud",
                        "begin_balance": "4339.68",
                        "end_balance": "10530.87",
                        "uploaded_doc_pk": 13928705
                    }
                ]
            }
        },
        "txns": [
            {
                "comment": "",
                "page_idx": 2,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "INSIKT INC DES:DEPOSIT 10:350209 CAPGEMINI AMERICA INC CO ID:11775843 PPD",
                "explanation": "",
                "amount": "3433.13",
                "page_doc_pk": 98913855,
                "has_probable_transfers": false,
                "pk": 1449437831,
                "txn_date": "01/17/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    232,
                    2664,
                    3762,
                    2748
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "BANK OF AMERICA CREDIT CARD Bill Payment",
                "explanation": "",
                "amount": "-1510.00",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437825,
                "txn_date": "01/24/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    1764,
                    3751,
                    1846
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "BKOFAMERICA ATM 01 /24 #000007230 WITHDRWL CANOGA PARK CANOGA PARK CA",
                "explanation": "",
                "amount": "-200.00",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437822,
                "txn_date": "01/24/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    888,
                    3753,
                    970
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "AMERICAN EXPRESS DES:ACH PMT ID:W1674 INDN:SIRISHA CHIGURUPATI CO\nID:1133133497 WEB",
                "explanation": "",
                "amount": "-293.13",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437826,
                "txn_date": "01/25/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    1881,
                    3753,
                    2034
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "Automatic Transfer to CHK 8976 Confirmation# 1327975029",
                "explanation": "",
                "amount": "-25.00",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437828,
                "txn_date": "01/25/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    232,
                    2256,
                    3752,
                    2339
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "AMERICAN EXPRESS DES:ACH PMT ID:W0914 INDN:SIRISHA CHIGURUPATI CO\nID:1133133497 WEB",
                "explanation": "",
                "amount": "-184.46",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437827,
                "txn_date": "01/25/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    2069,
                    3785,
                    2222
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "CITI CARD ONLINE DES:PAYMENT ID:132867132295963 INDN:SIRISHA CHIGURUPATI CO\nID:CITICTP WEB",
                "explanation": "",
                "amount": "-1954.90",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437829,
                "txn_date": "01/28/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    2374,
                    3752,
                    2526
                ]
            },
            {
                "comment": "",
                "page_idx": 2,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "/20 INSIKT INC DES:DEPOSIT 10:350209 INDN:CHIGURUPATI SIRISHA CO 10:11775843 PPD",
                "explanation": "",
                "amount": "3547.66",
                "page_doc_pk": 98913855,
                "has_probable_transfers": false,
                "pk": 1449437833,
                "txn_date": "01/31/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    232,
                    2900,
                    3750,
                    2983
                ]
            },
            {
                "comment": "",
                "page_idx": 2,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "INSIKT INC DES:DEPOSIT 10:350209 INDN:CHIGURUPATI SIRISHA CO ID:11775843 PPD",
                "explanation": "",
                "amount": "3664.67",
                "page_doc_pk": 98913855,
                "has_probable_transfers": false,
                "pk": 1449437832,
                "txn_date": "01/31/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    232,
                    2782,
                    3751,
                    2866
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "SMART AND FINA 02/02 #000929704 PURCHASE SMART AND FINAL SIMI VALLEY CA",
                "explanation": "",
                "amount": "-53.31",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437823,
                "txn_date": "02/04/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    1005,
                    3755,
                    1087
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "BKOFAMERICA ATM 02/05 #000005706 WITHDRWL CANOGA PARK CANOGA PARK CA",
                "explanation": "",
                "amount": "-400.00",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437824,
                "txn_date": "02/05/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    233,
                    1122,
                    3752,
                    1205
                ]
            },
            {
                "comment": "",
                "page_idx": 3,
                "bank_account_pk": 4282844,
                "tags": {},
                "description": "MOSAIC DES:SURE PAY ID:15140049758*R1 INDN:KISHORE GARIKAPATI CO\nID:CSCSM59063 PPD",
                "explanation": "",
                "amount": "-78.91",
                "page_doc_pk": 98913854,
                "has_probable_transfers": false,
                "pk": 1449437830,
                "txn_date": "02/07/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    232,
                    2562,
                    3752,
                    2714
                ]
            },
            {
                "comment": "",
                "page_idx": 4,
                "bank_account_pk": 4282936,
                "tags": {},
                "description": "Ol /25/20 Automatic Transfer from CHK 6139 Confirmation# 132797 5029 25.00",
                "explanation": "",
                "amount": "25.00",
                "page_doc_pk": 98913853,
                "has_probable_transfers": true,
                "pk": 1449437834,
                "txn_date": "01/25/2020",
                "uploaded_doc_pk": 13928705,
                "bbox": [
                    181,
                    2548,
                    3789,
                    2642
                ]
            }
        ],
        "uploaded_docs": {
            "13928705": {
                "status": "VERIFICATION_COMPLETE",
                "pk": 13928705,
                "name": "Sam Bobley_bankstatement.pdf",
                "pages": 6
            }
        },
        "tags": {}
    }
}

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. To do so, follow the steps below:

  1. Send a GET request to the Analytics (JSON) endpoint.
  2. Include your basic 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/summary \
    --header 'Authorization: Basic bGluZGFicmVhbm5lQGdtYWlsLmNvbTplYXN5cGFzc3dvcmQxMjM0NQ==' \
    --header 'Content-Type: application/json' \
    --data '{
        "pk" : "10399"
    }'

Example 200 Response

{
    "status": 200,
    "message": "OK",
    "response": {
        "name": "Bank Statement Example Book",
        "average_daily_balance": null,
        "average_by_month": {},
        "estimated_revenue_by_month": {},
        "bank_accounts": [],
        "average_deposit_by_month": {},
        "pk": 10399,
        "average_daily_balance_by_month": null
    }
}

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

Updated 26 days ago


Getting Started with Bank Statements


Upload, capture, and analyze a bank statement.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.