HomeGuidesAPI Reference

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 <<glossary:Adjusted Gross Income>>

  • `filing_status` — their <<glossary:Tax Filing Status>>

  • `family_size` — the <<glossary: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.