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!

Paystub Standard Extraction

Ocrolus' Paystub Standard Extraction gives you the information you need to verify a borrower's income.

Paystubs can be uploaded as both PDFs and images. Both upload endpoints require the form_type parameter with value PAYSTUB_01.

Usage Guide

To upload a paystub to Ocrolus, follow the below pattern:

  • Create a new book to hold one or more paystubs and other related forms.
  • Upload a PDF or image of the paystub with the form_type parameter set to PAYSTUB_01. Repeat as necessary with additional paystubs or other form types.
  • Retrieve the paystub JSON results by using the Doc Form Data endpoint, or retrieve all forms from the book by using the Book Form Data endpoint.
  • You may check the status of the documents within a book with the Book Status endpoint, but we recommend registering for webhook notifications, which let you know exactly when a document has completed processing.

Standard Fields Captured

JSON Attribute

Data Type

Description

paystub-Part1-General:employeeName

Text

Name of the employee that is the subject of the paystub.

paystub-Part1-General:employeeAddress:addressLine1

Text

Address Line 1 of the employee.

paystub-Part1-General:employeeAddress:addressLine2

Text

Address Line 2 of the employee.

paystub-Part1-General:employeeAddress:city

Text

City of the employee.

paystub-Part1-General:employeeAddress:state

Text

State the employee resides in. Formatted as a 2 character state code.

paystub-Part1-General:employeeAddress:zip

Text

5 digit zip code in which employee resides.

paystub-Part1-General:nameOfEmployer/Company

Text

Name of the employer issuing the paystub.

paystub-Part2-Dates:payPeriod(BeginningDate)

Date

The beginning date of the pay period covered by the paystub.

paystub-Part2-Dates:payPeriod(EndingDate)

Date

The ending date of the pay period covered by the paystub.

paystub-Part2-Dates:payDate

Date

The date payment was issued.

paystub-Part3-Earnings:grossPay(Current)

Money

The total pay issued by the employer to the employee for the current pay period covered by the paystub.

paystub-Part3-Earnings:grossPay(Ytd)

Money

The total pay issued by the employer to the employee from the beginning of the year, including the current pay period.

paystub-Part3-Earnings:netPay(Current)

Money

The total amount received by the employee for the current pay period covered by the paystub.

paystub-Part3-Earnings:netPay(Ytd)

Money

The total amount received by the employee from the beginning of the year, including the current pay period.

Validation Responses

The following validation responses are returned in the JSON result if any of the validation rules are not met.

Validation Rule

Validation Response

paystub-Part2-Dates:payPeriod(BeginningDate) < paystub-Part2-Dates:payPeriod(EndingDate)

Beginning Date should be earlier than Ending Date. User should verify document.

paystub-Part2-Dates:payPeriod(EndingDate) > paystub-Part2-Dates:payPeriod(BeginningDate)

Ending Date should be later than Beginning Date. User should verify document.

paystub-Part2-Dates:payDate > paystub-Part2-Dates:payPeriod(BeginningDate)

Pay Date should be later than Beginning Date. User should verify document.

paystub-Part3-Earnings:grossPay(Current) <= paystub-Part3-Earnings:grossPay(Ytd)

Gross Pay (Current) should be less than or equal to Gross Pay (YTD). User should verify document.

paystub-Part3-Earnings:grossPay(Ytd) >= paystub-Part3-Earnings:grossPay(Current)

Gross Pay (YTD) should be more than or equal to Gross Pay (Current). User should verify document.

paystub-Part3-Earnings:netPay(Current) < paystub-Part3-Earnings:grossPay(Current)

Net Pay (Current) should be less than Gross Pay (Current). User should verify document.

paystub-Part3-Earnings:netPay(Ytd) < paystub-Part3-Earnings:grossPay(Ytd)

Net Pay (YTD) should be less than Gross Pay (YTD). Please review.

paystub-Part3-Earnings:netPay(Ytd) >= paystub-Part3-Earnings:netPay(Current)

Net Pay (YTD) should be more than or equal to Net Pay (Current). Please review.

Sample Paystub

The below Ocrolus Sample PDF (input) matches the below Sample JSON Result (output).

Sample JSON Result

{
  "form_config_pk": 6634,
  "form_type": "PAYSTUB_01",
  "pk": 5342402,
  "raw_fields": {
    "paystub-Part1-General:employeeAddress:addressLine1": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "121 WILLSWORLD LANE"
    },
    "paystub-Part1-General:employeeAddress:addressLine2": {
      "alias_used": null,
      "is_empty": true,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": ""
    },
    "paystub-Part1-General:employeeAddress:city": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "OTHERWORLD"
    },
    "paystub-Part1-General:employeeAddress:state": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "VA"
    },
    "paystub-Part1-General:employeeAddress:zip": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "11234"
    },
    "paystub-Part1-General:employeeName": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "LYRA BELACQUA"
    },
    "paystub-Part1-General:nameOfEmployer/Company": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "COOL PAYSTUB COMPANY"
    },
    "paystub-Part2-Dates:payDate": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "12/18/2018"
    },
    "paystub-Part2-Dates:payPeriod(BeginningDate)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "12/01/2018"
    },
    "paystub-Part2-Dates:payPeriod(EndingDate)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "12/15/2018"
    },
    "paystub-Part3-Earnings:grossPay(Current)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "1917.00"
    },
    "paystub-Part3-Earnings:grossPay(Ytd)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "64413.39"
    },
    "paystub-Part3-Earnings:netPay(Current)": {
      "alias_used": null,
      "is_empty": false,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": "1260.32"
    },
    "paystub-Part3-Earnings:netPay(Ytd)": {
      "alias_used": null,
      "is_empty": true,
      "page_doc_pk": 79327626,
      "source_filename": "Ocrolus Sample PDF - Paystub.pdf",
      "value": ""
    }
  },
  "tables": []
}

Updated about a month ago

Paystub Standard Extraction


Suggested Edits are limited on API Reference Pages

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