Borrowers

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 API POST, PUT, and PATCH requests

For 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 a BorrowerPayload for your API request payloads, and expect a Borrower 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 Income
• filing_status — their Tax Filing Status
• family_size — the Family Size claimed on their taxes
• state_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

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

For historical reasons, FinancialDetails are returned as a nested object under the financial_details property. Future versions of the API will resolve this discrepancy.