Borrowers
All you need to know about Borrowers
and the Payitoff API
A Borrower
is a person who has one or more federal student loans.
Borrowers
can be created with very little data. We recommend always supplying a first_name
and last_name
when you create a Borrower
, if only so you'll be able to tell your Borrowers
apart when you're integrating our API and Nexus into your products and workflows.
Use
BorrowerPayload
for APIPOST
,PUT
, andPATCH
requestsFor historical reasons, the request payload required when creating and updating a
Borrower
via our v1 API has a different shape than the response object. Thus, you must use aBorrowerPayload
for your API request payloads, and expect aBorrower
object as the response.This discrepancy will be corrected in API v2.
Assessments
To perform an Assessment for a Borrower
, the minimum required fields you should supply in your BorrowerPayload
are as follows:
agi
— their Adjusted Gross Incomefiling_status
— their Tax Filing Statusfamily_size
— the Family Size claimed on their taxesstate_of_residence
— the state in which they reside
For testing purposes and initial integration guidance, these 4 fields, along with first_name
and last_name
will be sufficient. However, we recommend providing as much information as possible in a production environment. Certain actions, like Enrollments, require more data about the Borrower
, and providing that information up front can save you—and your Borrowers
—time, eliminating slower and awkward experiences by minimizing the API calls you must make.
PSLF
A qualifying employer is necessary to determine PSLF eligibility and track PSLF-eligible payments. You can use the PSLF Employer Search API endpoint to check if Borrower
employers qualify for PSLF eligibility.
Social Security Numbers
All SSNs submitted via API—and collected by Nexus—are encrypted and stored securely. For security purposes and the protection of your Borrower
, SSN values are not returned in Borrower
response objects.
Spouses
If you would like a Borrower
spouse and spouse_agi
to be considered in Assessment operations, you must update your Borrower
with a filing_status
of married_filing_jointly
or married_filing_separately
.
When creating or updating a Borrower
and providing a spouse_agi
, filing_status
must not be single
, otherwise our system will ignore the spouse_agi
when performing certain operations for which spouse_agi
is important and otherwise considered.
IncomeCertifications
IncomeCertifications
When uploading IncomeCertifications
via API, please note that the parameter is singular in the request body and requires a IncomeCertificationPayload
payload, but plural in the Borrower
response object and returns an IncomeCertification
object . We currently support uploading only a single IncomeCertification
at a time. If multiple IncomeCertifications
are uploaded over subsequent requests, we will only use the most recent one.
We will support a future case where multiple IncomeCertifications
may be uploaded, and a subset chosen by the Borrower
as the documentation to submit with an Enrollment Request. Thus, to avoid future API changes, the Borrower
response object returns income_certifications
as an array
.
FinancialDetails
FinancialDetails
For historical reasons, FinancialDetails
are returned as a nested object under the financial_details
property. Future versions of the API will resolve this discrepancy.
Updated over 3 years ago