API Documentation

Introduction

Welcome to the Ocrolus API! The Ocrolus API allows you to upload your bank documents for processing and returns all the transactions and analytic data in easily parseable JSON.

The input for the Ocrolus API is HTML form data and the output is a JSON object. The Ocrolus API always returns 200 OK as the Status-Code. To check for errors, look within the response JSON for the status field as within the example below.

{
  "status": 400,
  "message": "Authentication failed",
  "code": 1200,
  "response": null
}

Tutorial

The following tutorial shows how to create a collection of documents; upload a bank document and receive transaction and analytic data upon completion of document processing. The following examples use curl.

Requirements

Before starting this tutorial, make sure you have your Ocrolus-issued API key and API secret. The Ocrolus API uses Basic HTTP Authentication (RFC 7617) so you need to Base64 encode your credentials in the following format, 'Your API Key:Your API Secret' and then set the Authorization Header to 'Basic Your Base64 encoded credentials'. Sending data to the server is done in JSON format.

Create Collection of Documents

The Ocrolus API stores your bank documents in a collection called a book. To create a book, which will store uploaded documents thereafter, send the Authorization Header as above and the name you want to use for the book to https://www.perfectaudit.com/api/v1/book/add. To make a book accessible to all organization members, set is_public to "true"

Example Request

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw=="  \
    -d '{"name" : "Test Book", "is_public" : "false"}' \
    https://www.perfectaudit.com/api/v1/book/add

Example Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "name": "Test Book",
    "created": "08/15/2016",
    "pk": 10399,
    "is_public" : false,
    "owner_email" : "developer@ocrolus.com"
  }
}

The pk returned from the server is a unique id that corresponds to your book and should be stored somewhere so you can perform further actions on the book.

Upload PDF's to your Book

At this time, the Ocrolus API exclusively supports PDF as the file type of uploaded bank statements. To upload bank statements, send the Authorization Header as above and send the pk of a book you previously created and the file you want to upload as a HTML multipart form (not a JSON) to https://www.perfectaudit.com/api/v1/book/upload.

Example Request

$ curl -X POST \ 
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -F 'pk=10399' \
    -F 'upload=@../bank-statement.pdf' \ 
    https://www.perfectaudit.com/api/v1/book/upload

Example Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {}
}

Get Book Information

While your documents' transactional data won't be immediately available after uploading, you can get important information regarding the status by sending the Authorization Header as above and the pk of the book to https://www.perfectaudit.com/api/v1/book/info

Example Request

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"pk" : "10399"}' \
    https://www.perfectaudit.com/api/v1/book/info

Example Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
        "name": "Test Book",
        "created": "08/15/2016",
        "bank_accounts": { },
        "docs": [
            {
                "pages": 3,
                "status": "VERIFYING",
                "name": "bank-statement.pdf",
                "pk": 8597,
            }
        ],
        "pk": 10399,
        "is_public" : false,
        "owner_email" : "developer@ocrolus.com"
  }
}

As you can see from the following response, the document we uploaded has a pk of 8597, has 3 pages, is named after the file you uploaded and is currently undergoing verification. The document pk should be stored so that you can check that the system has completed document processing and you are able to fetch the analytic data.

Set Book to Public or Private

You can control the visibility and access of a book uploaded using the API by setting it as private or public. Making a book public will make it accessible and visible to all members in your organization.

You can change whether a book is public or private using https://www.perfectaudit.com/api/v1/book/update. If a book is public, you can set it to private by changing the is_public argument to "false"

Example Request

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"pk" : "10399", "is_public" : "true"}' \
    https://www.perfectaudit.com/api/v1/book/update

Example Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
        "name": "Test Book",
        "created": "08/15/2016",
        "pk": 10399,
        "is_public" : true,
        "owner_email" : "developer@ocrolus.com"
  }
}

Poll for Book Completion

To check when all your documents have finished verification, use the book/info request or register a webhook. You can get notified when a document in your book has completed processing using webhooks, and use the book/info call to verify all documents have completed processing instead of polling repeadelty.

If you choose to poll, we recommend polling at a frequency of 1 to 5 minutes. When the document status of all your documents is `VERFICATION_COMPLETE', analytic and transaction data can be retrieved by following the next part of the tutorial.

Get Transaction and Analytic Data

Once your documents have finished processing, you can retrieve all transactions and analytic data from the statements. To get the transaction data, send the Authorization Header as above and the pk of the book to https://www.perfectaudit.com/api/v1/transaction.

Example Request

$ curl \
    -H "Content-Type: application/json" \ 
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"book_pk" : "10399"}' \ 
    https://www.perfectaudit.com/api/v1/transaction
 

Example Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "bank_accounts": {
      "7538": {
        "name": "Test Bank Checking",
        "activity_info": {
          "active": [
            {
              "start": {
                "year": 2014,
                "month": 3
              },
              "end": {
                "year": 2014,
                "month": 4
              }
            }
          ],
          "missing": []
        },
        "date_min_max": {
          "max_txn_date": "04/11/2014",
          "min_txn_date": "03/28/2014"
        },
        "book_pk": 10399,
        "pk": 7538,
        "account_type": "Checking",
        "account_holder": "Jane Doe",
        "account_number": "00000000",
        "holder_zip": "10005",
        "holder_state": "NY",
        "holder_city": "New York",
        "holder_address_1": "44 Wall Street" ,
        "holder_address_2": "Suite 703",
        "periods": [
          {
            "pk" : 1050,
            "begin_date" : "03/28/2014",
            "end_date" : "04/11/2014",
            "begin_balance" : "5000.00",
            "end_balance" : "1000.00"
          }
        ]
      }
    },
    "txns": [
      {
        "page_idx": 1,
        "is_recurring": false,
        "bank_account_pk": 7538,
        "amount": "1302.89",
        "bbox": [112, 1600, 2359, 1661],
        "txn_date": "03/28/2014",
        "page_doc_pk": 300492,
        "pk": 642713,
        "uploaded_doc_pk": 8598,
        "description": "Test Description"
      },
    ...
    ],
    "uploaded_docs": {
      "8598": {
        "name": "bank-statement.pdf",
        "pages": 3
      }
    }
  }
}

The transaction response also includes metadata on the bank accounts in the book, including periods when the bank accounts are active as well as missing periods. To get the analytic data from the book, send the Authorization Header as above and the book pk to https://www.perfectaudit.com/api/v1/book/summary.

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"pk" : "10399"}' \ 
    https://www.perfectaudit.com/api/v1/book/summary

Example Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "average_by_month": {
      "03/2014": "695.78",
      "04/2014": "658.02"
    },
    "average_daily_balance_weekday": "1273.91",
    "average_daily_balance_weekday_by_month": {
      "11/2016": "1279.77",
      "10/2016": "1254.76",
      "09/2016": "1229.76",
      "12/2016": "1304.78"
    },
    "pk": 10399,
    "name": "Case Size",
    "bank_accounts": [
      {
        "average_by_month": { 
          "03/2014": "695.78", 
          "04/2014": "658.02"
        },
        "average_daily_balance" : "5365.29",
      
      "average_daily_balance_weekday": "1273.91",
      "average_daily_balance_weekday_by_month": {
          "11/2016": "1279.77",
          "10/2016": "1254.76",
          "09/2016": "1229.76",
          "12/2016": "1304.78"
      },
    
        "average_deposit_by_month": { 
          "03/2014": "695.78",
          "04/2014": "658.02"
        },
        "daily_balances" : {
          "03/28/2014" : "675.88",
          "04/05/2014" : "-534.66",
          "03/29/2014" : "100.53"
        },
        "nsf_transactions": [], 
        "deposit_max_by_month": {
          "03/2014": [ 
            { 
              "amount": "1302.89", 
              "bank_account_pk": 7538,
              "bbox": [
                112,
                1600,
                2359,
                1661
              ],
              "description": "Test Description",
              "page_doc_pk": 300492,
              "page_idx": 1,
              "pk": 642713,
              "txn_date": "03/28/2014",
              "uploaded_doc_pk": 8598
            }
          ],
          "04/2014": [{...}]
        },
        "deposit_min_by_month": {
          "03/2014": [ 
            { 
              "amount": "88.66", 
              "bank_account_pk": 7538,
              "bbox": [
                112,
                1674,
                2360,
                1734
              ],
              "description": "Test Description",
              "page_doc_pk": 300492,
              "page_idx": 1,
              "pk": 642714,
              "txn_date": "03/31/2014",
              "uploaded_doc_pk": 8598
            },
          ]
          "04/2014": [{...}]
        },
        "interbank_transactions": [], 
        "name": "Test Bank Checking", 
        "negative_balances_by_month" : { 
          "03/2014": [], 
          "04/2014": []
        },

        "negative_balances_by_month_weekday": {
          "11/2016": [],
          "10/2016": [],
          "09/2016": [],
          "12/2016": []
        },


        "outside_source_deposits": [, 
          {
            "amount": "88.66",
            "bank_account_pk": 7538,
            "bbox": [
              112,
              1674,
              2360,
              1734
            ],
            "description": "Test Description",
            "page_doc_pk": 300492,
            "page_idx": 1,
            "pk": 642714,
            "txn_date": "03/31/2014",
            "uploaded_doc_pk": 8598
          },
          {...},
          {...},
          {...},
          {...}
        ],
        "period_balance_mismatches" : [], 
        "pk": 7538, 
        "round_number_txns": [], 
        "alternative_lender_transactions": [], 
        "total_days" : 30,
        "activity_info": {
          "active": [
            {
              "start": {
                "year": 2014,
                "month": 3
              },
              "end": {
                "year": 2014,
                "month": 4
              }
            }
          ],
          "missing": []
        },
        "date_min_max": {
          "max_txn_date": "04/11/2014",
          "min_txn_date": "03/28/2014"
        },
        "book_pk": 10399,
        "account_type": "Checking" ,
        "account_holder": "Jane Doe",
        "account_number": "00000000",
        "holder_zip": "10005",
        "holder_state": "NY",
        "holder_city": "New York",
        "holder_address_1": "44 Wall Street" ,
        "holder_address_2": "Suite 703",
        "periods": [
          { 
            "pk" : 1050,
            "begin_date" : "03/28/2014",
            "end_date" : "04/11/2014",
            "begin_balance" : "5000.00",
            "end_balance" : "1000.00",
            "period_month_days": {
              "03/2014": 2,
              "04/2014": 24
            },
            "period_month_txns": {
              "03/2014": 5,
              "04/2014": 43
            }
          }
        ]
        "average_daily_balance_by_month" : {
          "03/2014": "4410.29",
          "04/2014": "1200.82"
        },
        "estimated_revenue_by_month" : {
          "03/2014": "114410.19",
          "04/2014": "121200.42"
        }

      }
    ],
    "average_deposit_by_month": {
      "03/2014": "695.78",
      "04/2014": "658.02"
    },
    "average_daily_balance_by_month" : {
      "03/2014": "4410.29",
      "04/2014": "1200.82"
    },
    "estimated_revenue_by_month" : {
      "03/2014": "114410.19",
      "04/2014": "121200.42"
    }
  }
}

An explanation of analytic data returned by the JSON can be found in the Endpoint Reference section.

Delete document/PDF

You can delete a uploaded document/PDF using https://www.perfectaudit.com/api/v1/document/remove call. Note that you cannot delete a document while it is in Queued, Processing or Verifying status.

Deleting a document will permanently delete all transactions and other associated data with the document and is not reversible.

You will need to pass in the document pk as doc_id param, which you can find from the book info call.

Example Request

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw=="  -d '{"doc_id" : "10000"}'  \
    https://www.perfectaudit.com/api/v1/document/remove

Delete book

You can delete a book using https://www.perfectaudit.com/api/v1/book/remove. Note that you cannot remove a book while it has a document in Queued, Processing or Verifying status.

Deleting a book will permanently delete all associated documents and data on our platform and is not reversible.

Example Request

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw=="  -d '{"book_id" : "10293"}' \
    https://www.perfectaudit.com/api/v1/book/remove

Webhooks

Use webhooks to be notified when a document completes verification. Note that the webhook endpoint is called for every document in the book as soon as it completes verification. To check if all the documents in the book have completed verification, please call the book_info api when you receive this callback to obtain status of all documents in the book.

Configuring your webhook settings

Provide a internet accessible url that our system will invoke in the webhook_endpoint parameter. The endpoint must support POST requests and accept JSON content below (Content-Type: application/json)

$ curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw=="  -d '{"webhook_endpoint" : "https://requestb.in/1ei794c1"}' \
    https://www.perfectaudit.com/api/v1/account/settings/update/webhook_endpoint

The body of the request you will be receive as a POST request to your endpoint is in the below format


{
  "status": "VERIFICATION_COMPLETE",
  "book_pk": 11917,
  "uploaded_doc_pk": 57733
}
        

Test your webhook endpoint

Ensure we are able to connect to your endpoint by using the below API call. Calling this API will immediately invoke the endpoint you provided with the above call (with test values). If we are able to connect successfully you should see a response similar to the example below

$ curl  \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw=="   \
    https://www.perfectaudit.com/api/v1/account/settings/test_webhook_endpoint
Example response

{
"status": 200,
"message": "OK",
"response": {
    "message": "Success calling webhook endpoint",
    "resp_code": 200
 }
}

Endpoint Reference

The following endpoints input and/or output is better specified below.

Book Data

https://www.perfectaudit.com/api/v1/book/info

To get information about a particular book that you have created, follow the steps in the tutorial. The full explanation of the JSON response is outlined below:

Commented Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "name": "Test Book", // Name of the book
    "created": "08/15/2016", // Creation date of the book
    "bank_accounts": { // An object of all the bank accounts present in the 
                       // book where every key is the bank account pk 
      "7538": { // pk of the bank account
        "name": "Test Bank Checking", // Name of the bank account
        "activity_info": { // An object containing values concerning the 
                           // activity or nonactivity the bank account
          "active": [ // An array of date ranges when the bank account had 
                      // transaction activity
            {
              "start": { // The beginning of the date range
                "year": 2014,
                "month": 3
              },
              "end": { // The end of the date range
                "year": 2014,
                "month": 4
              }
            }
          ],
          "missing": [] // An array of date ranges when the bank account had 
                        // no transactional data similarly structured to the 
                        // active object
        },
        "date_min_max": { // An object containing the earliest and latest 
                          // transaction date in the bank account
          "max_txn_date": "04/11/2014", // Latest date with transactional 
                                        // activity
          "min_txn_date": "03/28/2014" // Earliest date with transactional 
                                       // activity
        },
        "book_pk": 9452, // pk of the book
        "pk": 7538, // pk of the bank account
        "account_type": "Checking", // Type of bank account
        "account_holder": "Jane Doe", // Holder of bank account
        "account_number": "00000000", // Bank account number
        "holder_zip": "10005", // Zipcode of bank account holder
        "holder_state": "NY", // State of bank account holder
        "holder_city": "New York", // City of bank account holder
        "holder_address_1": "44 Wall Street", // Line 1 of address of bank account holder
        "holder_address_2": "Suite 703", // Line 2 of address of bank account holder
        "periods": [ // Array of bank account statement periods
          {
            "pk" : 1050, // Period pk
            "begin_date" : "03/28/2014", // Beginning date of statement period
            "end_date" : "04/11/2014", // Ending date of statement period
            "begin_balance" : "5000.00", // Beginning balance of statement period
            "end_balance" : "1000.00" // Ending balance of statement period,
          }
        ]
      }
    },
    "docs": [ // An array of all the documents uploaded to the book
      { // Every document is an object
        "pages": 3, // Pages in the document
        "status": "VERIFYING", // Document status, see the table beneath this 
                               // response to see the individual meanings
        "name": "bank-statement.pdf", // Name of the document
        "pk": 8597, // pk of the document
      }
    ],
    "pk": 10399, // pk of the book
    "is_public" : false, // Is book accessible to everyone in organization
    "owner_email" : "developer@ocrolus.com" // Email of account that created book
  }
}

Document Status Descriptions

Document Status Description
QUEUED Document is queued for processing
FAILED Document has failed processing, most likely due to invalid format or file error
VERIFYING Document is being verified
VERIFICATION_COMPLETE Document has finished verification
DELETING Document is deleting
DELETED Document has been deleted
REJECTED Document has been rejected during verification, most likely due to invalid statement type

Transaction Data

https://www.perfectaudit.com/api/v1/transaction

To get all transaction data from a book whose documents have finished verification, follow the steps in the tutorial. The full explanation of the JSON response is outlined below:

Commented Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "bank_accounts": { // An object of all the bank accounts present in the 
                       // book where every key is the bank account pk 
      "7538": { // pk of the bank account
        "name": "Test Bank Checking", // Name of the bank account
        "activity_info": { // An object containing values concerning the 
                           // activity or nonactivity the bank account
          "active": [ // An array of date ranges when the bank account had 
                      // transactions
            {
              "start": { // The beginning of the date range
                "year": 2014,
                "month": 3
              },
              "end": { // The end of the date range
                "year": 2014,
                "month": 4
              }
            }
          ],
          "missing": [] // An array of date ranges when the bank account had 
                        // no transactional data similiarly structured to the 
                        // active object
        },
        "date_min_max": { // An object containing the earliest and latest 
                          // transaction date in the bank account
          "max_txn_date": "04/11/2014", // Latest date with transactional 
                                        // activity
          "min_txn_date": "03/28/2014" // Earliest date with transactional 
                                       // activity
        },
        "book_pk": 9452, // pk of the book
        "pk": 7538, // pk of the bank account
        "account_type": "Checking", // Type of bank account
        "account_holder": "Jane Doe", // Holder of bank account
        "account_number": "00000000", // Bank account number
        "holder_zip": "10005", // Zipcode of bank account holder
        "holder_state": "NY", // State of bank account holder
        "holder_city": "New York", // City of bank account holder
        "holder_address_1": "44 Wall Street", // Line 1 of address of bank account holder
        "holder_address_2": "Suite 703", // Line 2 of address of bank account holder
        "periods": [ // Array of bank account statement periods
          {
            "pk" : 1050, // Period pk
            "begin_date" : "03/28/2014", // Beginning date of statement period
            "end_date" : "04/11/2014", // Ending date of statement period
            "begin_balance" : "5000.00", // Beginning balance of statement period
            "end_balance" : "1000.00" // Ending balance of statement period,
          }
        ]
      }
    },
    "txns": [ // An array of objects representing the transactions in the book
      { // A transaction object
        "page_idx": 1, // The page on which the transaction is found
        "bank_account_pk": 7538, // pk of bank account the transaction 
                                 // belongs to
        "amount": "1302.89", // Monetary amount of the transaction
        "bbox": [112, 1600, 2359, 1661], // Coordinates of the transaction on 
                                         // the page
        "txn_date": "03/28/2014", // Date of the transaction, if date is 
                                  // "01/01/1970" then no date was found
        "pk": 642713, // pk of the transaction
        "uploaded_doc_pk": 8598, // pk of the document the transaction 
                                 // belongs to
        "description": "Test Description" 
                // Description of the transaction as it appears on the 
                // bank statement
      },
    ...
    ],
    "uploaded_docs": { // An object containing all the documents in the book, 
                       // for which the keys are the pks of the documents
      "8598": { // pk of the document
        "name": "bank-statement.pdf", // Name of the document
        "pages": 3 // Pages in the document
      }
    }
  }
}

 

Transaction Snippet

https://www.perfectaudit.com/api/v1/transaction/snippet

To get an image of the transaction, use the above endpoint to get a Base64 encoded image.

Example Request

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"pk" : "642713" }'  \ 
    # PK from the transaction object 
    # returned from `/transaction` or `/book/summary`
    https://www.perfectaudit.com/api/v1/transaction/snippet

Commented Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "b64snippet": "...", // A base64 encoded PNG
    "bbox": [111, 1903, 2359, 1967] // Array of pixel coordinates 
                                    // [Left, Top, Right, Bottom]
  }
}

 

Analytics Data

https://www.perfectaudit.com/api/v1/book/summary

To get the analytics data from a book whose documents have finished verification, follow the steps in the tutorial. The explanation of the JSON response is outlined below:

Commented Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {
    "average_by_month": { // An object containing the average transaction 
                          // amount by month for the whole book, for which the 
                          // keys are the months
      "03/2014": "695.78", // Ex. The average amount for March, 2014 is 695.78
      "04/2014": "658.02"
    },
    "average_daily_balance": "5365.29", // The average daily balance of all the
                                        //  bank accounts in the book (all days including weekends)
    "average_daily_balance_weekday": "1273.91", // The average daily balance of all the
                                                // bank accounts in the book
                                                // calculated taking into account only weekdays
                                                // see extra_fields section

    "pk": 10399, // pk of the book
    "name": "Test Book", // Name of the Book
    "bank_accounts": [ // An array containing objects representating the bank 
                       // account information
      {
        "average_by_month": { // An object containing the average transaction 
                              // amount by month for the bank account, for 
                              // which the keys are the months
          "03/2014": "695.78", // Ex. The average amount for March, 2014 is 
                               // 695.78
          "04/2014": "658.02"
        },
        "average_daily_balance" : "5365.29", // The average daily balance of 
                                             // the bank account (calculation includes weekends)
        "average_daily_balance_weekday" : "5365.29", // The average daily balance of
                                             // the bank account (calculation excludes weekends)
                                             // see extra_fields section
        "average_deposit_by_month": { // An object containing the average 
                                      // deposit by month for the bank account,
                                      // for which the keys are the months
          "03/2014": "695.78",
          "04/2014": "658.02"
        },
        "daily_balances" : { // An object containing the daily balances by day
                            // for the bank account, for which the keys are the dates
          "03/28/2014" : "675.88", // Ex. The daily balance on March 3rd, 2014 was 675.88
          "04/05/2014" : "-534.66",
          "03/29/2014" : "100.53"
        },
        "nsf_transactions": [], // Array of transactions that are likely to be 
                                // NSF transactions
        "nsf_count" : 0, // Number of non-sufficient funds or overdraft fees/charges 
                         // applied to the account
                         // see extra_fields section
        "deposit_max_by_month": { // An object containing the maximum deposit
                                   // transactions by month for the bank 
                                   // account, for which the keys are the 
                                   // months
          "03/2014": [ // An array of the maximum deposit transactions 
                       // in March, 2014
            { // Ex. A transaction object for maximum deposit in March, 2014.
              "amount": "1302.89", // Ex. The greatest deposit amount for 
                                   // March, 2014 is 1302.89
              "bank_account_pk": 7538,
              "bbox": [
                112,
                1600,
                2359,
                1661
              ],
              "description": "Test Description",
              "page_doc_pk": 300492,
              "page_idx": 1,
              "pk": 642713,
              "txn_date": "03/28/2014",
              "uploaded_doc_pk": 8598
            }
          ],
          "04/2014": [{...}]
        },
        "deposit_min_by_month": { // An object containing the minimum deposit
                                   // transactions by month for the bank 
                                   // account, for which the keys are the 
                                   // months
          "03/2014": [ // An array of the minimum deposit transactions 
                       // in March, 2014
            { // Ex. A transaction object for minimum deposit in 
                       // March, 2014.
              "amount": "88.66", // The least deposit amount for March, 2014 is
                                 // 88.66
              "bank_account_pk": 7538,
              "bbox": [
                112,
                1674,
                2360,
                1734
              ],
              "description": "Test Description",
              "page_doc_pk": 300492,
              "page_idx": 1,
              "pk": 642714,
              "txn_date": "03/31/2014",
              "uploaded_doc_pk": 8598
            },
          ]
          "04/2014": [{...}]
        },
        "interbank_transactions": [], // Array of transactions that are from 
                                      // other bank accounts
        "name": "Test Bank Checking", // Name of the Bank Account
        "negative_balances_by_month" : { // An object containing arrays of days
                                         // with a negative balance by month,
                                         // for which the keys are the months
          "03/2014": [], // Ex. There were 0 days in March, 2014 with a 
                         // negative balance
          // An example entry outlined below
          // "03/2014" : ["03/17/2014", "03/25/2014"]
          "04/2014": []
        },
        "negative_balances_by_month_weekday" : { // An object containing arrays of days
                                         // with a negative balance by month,
                                         // for which the keys are the months
                                        // (calculation includes only weekdays)
                                        // see extra_fields section
          "03/2014": [], // Ex. There were 0 days in March, 2014 with a
                         // negative balance
          // An example entry outlined below
          // "03/2014" : ["03/17/2014", "03/25/2014"]
          "04/2014": []
        },

        "outside_source_deposits": [, // List of deposits that are likely
                                           // to be deposits from bank accounts
                                           // not in the book
          {
            "amount": "88.66",
            "bank_account_pk": 7538,
            "bbox": [
              112,
              1674,
              2360,
              1734
            ],
            "description": "Test Description",
            "page_doc_pk": 300492,
            "page_idx": 1,
            "pk": 642714,
            "txn_date": "03/31/2014",
            "uploaded_doc_pk": 8598
          },
          {...},
          {...},
          {...},
          {...}
        ],
        "period_balance_mismatches" : [], // A array that contains cases where
                                          // the ending balance of a billing 
                                          // period and the starting balance of
                                          // the next billing period don't 
                                          // match
        // An example of a period balance mismatch object
        // {
        //    "end_date" : "07/09/2016", // Ending date of a billing period
        //    "end_balance" : "100.00", // Ending balance of a billing period
        //    "begin_date" : "07/10/2016", // Beginning date of next billing 
        //                                 // period
        //    "begin_balance" : "200.00" // Beginning balance of next billing 
        //                               // period
        // }
        "pk": 7538, // pk of Bank Account
        "round_number_txns": [], // Array of transactions whose amounts end in
                                 // two zeros, i.e. 100, 1,000, 56,000
        "alternative_lender_transactions": [], // Array of transactions that
                                               // are likely from or to 
                                               // alternative lenders
        "total_days" : 30,
        "book_pk": 9452, // pk of the book
        "account_type": "Checking", // Type of bank account
        "account_holder": "Jane Doe", // Holder of bank account
        "account_number": "00000000", // Bank account number
        "holder_zip": "10005", // Zipcode of bank account holder
        "holder_state": "NY", // State of bank account holder
        "holder_city": "New York", // City of bank account holder
        "holder_address_1": "44 Wall Street", // Line 1 of address of bank account  holder
        "holder_address_2": "Suite 703", // Line 2 of address of bank account holder
        "periods": [ // Array of bank account statement periods
          {
            "pk" : 1050, // Period pk
            "begin_date" : "03/28/2014", // Beginning date of statement period
            "end_date" : "04/11/2014", // Ending date of statement period
            "begin_balance" : "5000.00", // Beginning balance of statement period
            "end_balance" : "1000.00", // Ending balance of statement period
            "period_month_days": {
              "03/2014": 2,
              "04/2014": 24
            },
            "period_month_txns": {
              "03/2014": 5,
              "04/2014": 43
            }
          }
        ],
        "average_daily_balance_by_month" : { // An object containing the
                                             // average daily balance by month 
                                             // for the bank account, for which 
                                             // the keys are the months
          "03/2014": "4410.29", // Ex. The average daily balance for 
                                // March, 2014 is 4410.29
          "04/2014": "1200.82"
        }
        "average_daily_balance_weekday_by_month": { // The average daily balance by month for the
          "11/2016": "1279.77",                     // the bank account calculated excluding weekends
          "10/2016": "1254.76",                      // see extra_fields section
          "09/2016": "1229.76",
          "12/2016": "1304.78"
        },
        "estimated_revenue_by_month" : { // An object containing the
                                // estimated revenue per month
                                // for the bank account, for which
                                // the keys are the months
          "03/2014": "114410.19", // Please reach out to us for questions on how
          "04/2014": "121200.42"  // this is calculated
        }
      }
    ],
    "average_deposit_by_month": { // An object containing the average deposits
                                  // by month for the whole book, for which 
                                  // the keys are the months
      "03/2014": "695.78", // Ex. The average deposit for March, 2014 is 695.78
      "04/2014": "658.02"
    },
    "average_daily_balance_by_month" : { // An object containing the average
                                         // daily balance by month for the
                                         // whole book, for which the keys
                                         // are the months
      "03/2014": "4410.29", // Ex. The average daily balance for March, 2014
                            // is 4410.29
      "04/2014": "1200.82"
    },
    "average_daily_balance_by_month_weekday" : { // An object containing the average
                                         // daily balance by month for the
                                         // whole book, for which the keys
                                         // are the months. This field calculates based on weekdays only
      "03/2014": "4410.29", // Ex. The average daily balance for March, 2014
                            // is 4410.29
      "04/2014": "1200.82"
    },
    "estimated_revenue_by_month" : { // An object containing the
                                // estimated revenue per month
                                // for the whole book, for which
                                // the keys are the months
          "03/2014": "114410.19", // Please reach out to us for questions on how
          "04/2014": "121200.42"  // this is calculated
    }
} }

 

Extra fields for Analytics

There are a few optional fields that aren't returned by default in the analytics response above, and you can request it to be returned in the response by passing in the list of extra fields in the extra_fields parameter as below. The paramter can be one field or a list of comma seperated values.

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"pk" : "10399", "extra_fields": "FIELD_NAME_FROM_BELOW,FIELD_NAME_FROM_BELOW2"}' \
    https://www.perfectaudit.com/api/v1/book/summary

Revenue Transactions

To obtain the list of all deposit transactions used in calculating the revenue, request extra_field estimated_revenue_txns_list

To obtain the breakdown of transactions in each bucket used in calculating the revenue, request extra_field estimated_revenue_by_month_calc_txns

The response will include an additional field estimated_revenue_by_month_calc_txns for each bank_account. This field has 5 properties, each is a list of transactions of that bucket. The 5 buckets are deposits, deducted_specific_terms_txns, deducted_alternative_lender_txns and deducted_transfer_deposit_txns.

To learn more about how we calculate revenue please contact us.

Weekday Balances

To obtain additional fields with balances calculated based only on weekdays, request extra_fields with value as weekday_balances

The response will include these additional fields:

For the entire book:
average_daily_balance_weekday
average_daily_balance_weekday_by_month

And for each bank account
average_daily_balance_weekday,
average_daily_balance_weekday_by_month
negative_balances_by_month_weekday

Probable Recurring Transactions

As a failsafe against transaction description discrepancies, we've also designed a feature that detects and lists all recurring payments.
The feature works by detecting recurring sets of transactions of the exact same dollar amount, so long as that dollar amount is greater than $10. Date is also factored into the equation - transactions of the same dollar amount must be within 45 days of each other to be considered as recurrences. These recurring sets of transactions are presented in groups, making it easy to identify payment patterns. It maybe valuable to you have a backstop method for identifying alternative lender transactions/other debt.

To get this data, pass extra_fields with value probable_recurring_txns

Mercant Cash Advance Transactions (MCA)

To obtain a list of Merchant Cash Advance transactions, pass in extra_fields with value merchant_cash_advance_lender_txns. You will get a new field with list of MCA transactions in the response.

Debt Consolidator Transactions

To obtain a list of Debt Consolidators transactions, pass in extra_fields with value debt_consolidator_txn. You will get a new field with list of Debt Consolidator transactions in the response.

Factoring Company Transactions

To obtain a list of Factoring Company transactions, pass in extra_fields with value factor_txns. You will get a new field with list of Factoring Company transactions in the response.

NSF Count

To obtain the number of non-sufficient funds or overdraft fees/charges applied to the bank account, pass in extra_fields with value nsf_count. You will get a new field with the NSF Count in the response.

Book List

https://www.perfectaudit.com/api/v1/books

To get a list of books that have been created, use the above endpoint.

Example Request

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    https://www.perfectaudit.com/api/v1/books

Commented Response

{
  "status": 200, 
  "msg" : "OK",
  "response": [
    {
       "name" : "Test Book", // Name of the book
       "created" : "08/15/2016", // Creation date of the book
       "pk" : 10399, // pk of the book
       "is_public" : false, // Is book accessible to everyone in organization
       "owner_email" : "developer@ocrolus.com" // Email of account that created book 
    },
    {
       "name" : "Test Book 2", // Name of the book
       "created" : "08/16/2016", // Creation date of the book
       "pk" : 10400, // pk of the book
       "is_public" : false, // Is book accessible to everyone in organization
       "owner_email" : "developer@ocrolus.com" // Email of account that created book 
    }
  ]
}

 

Additional Document Verification

https://www.perfectaudit.com/api/v1/document/verification/request/additional

To send a document for additional verification, use the above endpoint. Sending the comment is optional.

Example Request

$ curl \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic dGVzdDZAb2Nyb2x1cy5jb206dGVzdGluZw==" \
    -d '{"pk" : "8597"}' \
    -d '{"comment" : "Sending for Additional Verification"}' \
    https://www.perfectaudit.com/api/v1/books

Commented Response

{
  "status": 200, 
  "msg" : "OK",
  "response": {}
}