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 Full Extraction (Beta)

Ocrolus' Paystub Full Extraction gives you complete insight into borrower's paystubs. With full extraction, you get the entire look at a borrower's earnings and deductions, giving you the ability to split out bonuses and commissions from normal cash flow. Additionally, our large library of canonical descriptions provides a consistent and standard output from a variety of source formats. Finally, the net pay distribution allows you to compare deposit amounts against bank statement transactions, giving you confidence in your lending decision.

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. Save the book_uuid for later use.
  • Upload a PDF Paystub to the book, referencing the {book_uuid} in the URL. Save the doc_uuid for use when pulling the results.
  • Retrieve the paystub JSON results by using the Doc Paystub Data endpoint, referencing the doc_uuid in the URL.
  • Alternatively, get all paystubs in a book by using the Book Paystub Data endpoint, referencing the book_uuid in the URL.
  • We recommend registering for webhook notifications, which let you know exactly when a document has completed processing.

Paystub Data Structure

The Paystub Full Extraction output diagram is below.

The composite data type Paystub, consists of several fields and composite data types. The items in blue denote a composite data type; for example, the Net Pay object consists of an array of Pay Distribution objects and a single Total object.

Details about the composite data structures can be found on the Paystub composite data type page.

Sample Paystub

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

Sample JSON Response

{
  "book_uuid": "60299d7a-fc4d-11ea-adc1-0242ac120002",
  "doc_uuid": "5ed38d6c-8d8b-47ba-b773-214d6ad4cc6e",
  "doc_page_numbers": [
    1
  ],
  "uuid": "1f0cc882-54b5-4bea-88ac-bbc23ab867e6",
  "employer": {
    "name": "COOL PAYSTUB COMPANY",
    "address": {
      "line1": "100 UNIVERSITY ST",
      "line2": null,
      "city": "OXFORD",
      "state_code": "VA",
      "postal_code": "11234"
    }
  },
  "employee": {
    "name": "LYRA BELACQUA",
    "address": {
      "line1": "121 WILLSWORLD LANE",
      "line2": null,
      "city": "OTHERWORLD",
      "state_code": "VA",
      "postal_code": "11234"
    },
    "marital_status": "MARRIED",
    "taxpayer_id": {
      "id_type": "SSN",
      "last_4_digits": "1234"
    }
  },
  "employment_details": {
    "hire_date": null,
    "annual_salary": {
      "amount": null,
      "currency": null
    }
  },
  "paystub_details": {
    "pay_period_start_date": "2018-12-01",
    "pay_period_end_date": "2018-12-15",
    "pay_date": "2018-12-18",
    "paystub_provider": null,
    "pay_frequency": null
  },
  "net_pay": {
    "distribution_details": [
      {
        "description": "CHECKING ACCOUNT ####1111",
        "bank_name": null,
        "account_number": "1111",
        "bank_account_type": "CHECKING",
        "current_pay": {
          "amount": "1190.32",
          "currency": "USD"
        }
      },
      {
        "description": "SAVINGS ACCOUNT ####2222",
        "bank_name": null,
        "account_number": "2222",
        "bank_account_type": "SAVINGS",
        "current_pay": {
          "amount": "70.00",
          "currency": "USD"
        }
      }
    ],
    "total": {
      "description": "TOTAL NET PAY",
      "canonical_description": "NET PAY",
      "current_pay": {
        "amount": "1260.32",
        "currency": "USD"
      },
      "ytd_pay": {
        "amount": null,
        "currency": null
      }
    }
  },
  "earnings": {
    "subtotals": [
      {
        "description": "REGULAR",
        "canonical_description": "REGULAR PAY",
        "current_pay": {
          "amount": "1917.00",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "46008.00",
          "currency": "USD"
        },
        "current_hours": "0",
        "current_rate": null
      },
      {
        "description": "BONUS",
        "canonical_description": "BONUS PAY",
        "current_pay": {
          "amount": "0.00",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "18405.39",
          "currency": "USD"
        },
        "current_hours": "0.00",
        "current_rate": null
      }
    ],
    "totals": [
      {
        "description": "GROSS PAY",
        "canonical_description": "GROSS PAY",
        "current_pay": {
          "amount": "1917.00",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "64413.39",
          "currency": "USD"
        },
        "current_hours": "0.00"
      }
    ]
  },
  "deductions": {
    "sub_totals": [
      {
        "description": "SOC SEC EE",
        "canonical_description": "SOCIAL SECURITY",
        "current_pay": {
          "amount": "118.85",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "3993.63",
          "currency": "USD"
        }
      },
      {
        "description": "MED EE",
        "canonical_description": "MEDICARE",
        "current_pay": {
          "amount": "27.79",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "933.99",
          "currency": "USD"
        }
      },
      {
        "description": "FEDERAL WH",
        "canonical_description": "FEDERAL WITHHOLDING",
        "current_pay": {
          "amount": "154.02",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "5461.61",
          "currency": "USD"
        }
      },
      {
        "description": "ILLINOIS WH",
        "canonical_description": "NOT_FOUND",
        "current_pay": {
          "amount": "93.90",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "3126.08",
          "currency": "USD"
        }
      },
      {
        "description": "401K-LN",
        "canonical_description": "NOT_FOUND",
        "current_pay": {
          "amount": "241.12",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "5792.92",
          "currency": "USD"
        }
      },
      {
        "description": "401-K",
        "canonical_description": "NOT_FOUND",
        "current_pay": {
          "amount": "20.00",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "1260.00",
          "currency": "USD"
        }
      }
    ],
    "totals": [
      {
        "description": "TAXES",
        "canonical_description": "TAXES",
        "current_pay": {
          "amount": "394.56",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "13515.31",
          "currency": "USD"
        }
      },
      {
        "description": "DEDUCTIONS",
        "canonical_description": "NOT_FOUND",
        "current_pay": {
          "amount": "262.12",
          "currency": "USD"
        },
        "ytd_pay": {
          "amount": "7052.92",
          "currency": "USD"
        }
      }
    ]
  }
}

Updated 6 days ago

Paystub Full Extraction (Beta)


Suggested Edits are limited on API Reference Pages

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