Retrieving Loans for your Borrowers

When you wish to fetch your borrowers' Loan objects, you'll use our List Borrower Loans API endpoint.

The response is a simple object with a loans key, which provides an array of Loan objects:

{
  "loans": [
    {Loan},
    {Loan}
  ]
}

Creating Loans for your Borrowers

There are four ways to build up Loan objects for a Borrower, in order of convenience and accuracy:

1. Use Nexus and let us do the heavy lifting (recommended)
2. Upload a base64-encoded National Student Loan Data System (NSLDS) MyStudentData (MSD) file
3. POST an array of LoanPayload objects
4. POST data retrieved via Plaid Liabilities as an array of LoanPayload objects

Use Nexus for accurate, up-to-date Loan data

Nexus is our easy-to-use, drop-in JavaScript widget that walks your borrowers through directly linking their Servicer accounts with their Borrower records you've already created via our API.

When you present Nexus to your borrowers, they will authenticate with all of their Servicer accounts, and we will build their entire loan portfolio with the most accurate and up-to-date information available.

👍

Get started with Nexus in 1 day

Check out our One-day Integration Guide for more information on how to integrate Nexus in your app today.

Upload an MSD file with federal loan data

If you cannot use Nexus in your workflows at this time, we recommend creating loans via MSD file uploads, as it gives us info on the Borrower's entire portfolio of federal student loans. It also provides richer data on the loans themselves, which results in better Repayment and Forgiveness calculations.

The downside of MSD files is that they do not include private loans, and there are currently some outstanding questions raised by the in-progress Scam Bill regarding accessing this information on behalf of your borrowers.

To upload an MSD file, you'll use the Create Loans for a Borrower API endpoint with a LoansFilePayload.

❗️

MSD Upload Gotchas

1. When an MSD file is uploaded, our system will destroy all existing loans created by a previous MSD upload and create new ones from the current upload. Loans created via API will not be deleted, however. The thinking is that a user can continue to idempotently refresh their federal student loans without affecting private loans created separately via API.

2. Our system does not respect the File Request Date in the MSD file. It is perfectly legal to upload an earlier version of an MSD file. Doing so will result in existing MSD-created loans to be destroyed, even if their data is more up to date.

3. MSD files must be uploaded as a LoansFilePayload, in which the MSD file itself is provided as a base64-encoded string value.

4. If your use case includes private loans, you must ask your Borrower to supply their private loan information or gather that data via another source (such as Nexus or Plaid). MSD files only provide federal student loan data.

Use loan data collected from borrowers

Loan objects can be manually created by asking your Borrower to fill out a series of fields to gather info about the Loan—name, monthly payment, original principal, Repayment Plan, and more.

When POSTing an array of LoanPayload objects, it’s important to send over all of the Borrower's federal loans, including those that have a zero balance and are paid in full, as their types can affect Repayment Options.

🚧

Beware of relying on your borrowers for accurate Loan data

We don't recommend relying on your borrowers providing their Loan data via forms, as it is very tedious, especially for those who may have many loans. More importantly, it is quite error-prone to rely entirely on your Borrower providing accurate and up-to-date information on their loan portfolio.

Check out our One-day Integration Guide to learn how Nexus can take care of the heavy lifting for you and your borrowers.

Use loan data from Plaid

Some of our Partners use the Plaid /liabilities endpoint to gather the data needed to create Loans for their borrowers. This data should be passed in to our regular Create Loans endpoint.

For Enrollment processing, we require a Servicer Name for each loan. The Servicer is the same as the Institution that Plaid fetches loan data from. Examples include Navient, Nelnet, and Fedloan for federal loans, and Wells Fargo for private loans.

We also accept an external_id you can use to keep track of which Loans in Payitoff correspond to the loan info you receive from subsequent syncs with Plaid. We recommend using Plaid's account_id property as the external_id for a Payitoff Loan—so be sure to send that in your LoanPayload when you create Loans.

Below is a table mapping PIO loan attributes to what you'll receive from Plaid. Please consult Plaid's documentation for more info.

PIO <> Plaid Loan data mapping

🚧

A couple notes about Plaid data mapping

A Plaid Liabilities response includes a liabilities.student property, which is an array of loan data objects. The Plaid Property in the mapping table above indicates the property of each object within the liabilities.student array, and each object property within the array is indicated as ls[].<property>.

NOTE: You may spot a minimum_payment_amount property in Plaid's response. We advise against using this value, as it returns data inconsistently across Servicers.