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
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.
For historical reasons, the request payload required when creating and updating a
Borrowervia our v1 API has a different shape than the response object. Thus, you must use a
BorrowerPayloadfor your API request payloads, and expect a
Borrowerobject as the response.
This discrepancy will be corrected in API v2.
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— Tax Filing Status from their last federal income tax return
family_size— the Family Size claimed on their taxes
state_of_residence— the state in which they reside
For running an
Assessment that will consider
spouse information, please see the
Spouses section below.
For testing purposes and initial integration guidance, these 4 fields, along with
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.
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.
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.
If you would like a
Borrower spouse and
spouse_agi to be considered in Assessment operations, you must update your
Borrower with a
When creating or updating a
Borrower and providing a
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.
spouse_agi is the only field on the spouse that can be updated through the borrower they're married to (i.e. the Update Borrower endpoint with the borrower's
uuid). The spouse's name, SSN, and phone number—which are all required to enroll in an IDR plan—must be updated through the spouse (technically a "borrower" themselves) by using the Update Borrower endpoint with the borrower's
spouse_id, i.e. the spouse's unique
If a borrower's spouse has federal loans, you can get an accurate assessment calculation by asking the borrower for the Spouse Loan Balance and then:
- Creating a new borrower (the spouse) via the API with the same
- Creating a Direct loan manually and setting the outstanding principal to be the Spouse Loan Balance entered by the borrower. All other fields can be mocked, since only the balance is used in the calculation. Having the most accurate information will provide the best results but if you must mock, we recommend using these values:
loan_type— Direct Stafford Unsubsidized
Spouse Loan Balance
Spouse Loan Balance
- Updating the original borrower with the spouse ID of the newly created spouse record
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
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 4 months ago