HomeGuidesAPI Reference

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`](🔗) as the response.

This discrepancy will be corrected in API v2.

### Schema Definition

`address``object`[`Address`](🔗)An `Address` object.
`agi``number``float`The `Borrower`'s <<glossary:Adjusted Gross Income>>.
`children``integer``int32`The number of children (including unborn) the borrower has.
Is this person collecting unemployment? _Defaults to`false`._ **Required for Enrollment.**
`dependents``integer``int32`The number of non-children dependents who receive more than half their support from the borrower.
`email``string``email`The `Borrower`'s email address.
If `Borrower` is employed, the name of their employer.
`employer_start_date``string``date`If `Borrower` is employed, date on which they began working for their employer.
State where Employer is located (state code).
`extra_monthly_payment``number``float`The amount of additional payment, if any, the borrower wishes to make on their loan(s).
`family_size``integer``int32`Number of family members, including the Borrower, their spouse, their children (even unborn), and any other dependents who receive more than half of their support from the `Borrower`. _Defaults to `1`._
`filing_status``string``single` `head_of_household` `married_filing_jointly` `married_filing_separately`Federal tax filing status of `Borrower`. _Defaults to `single`._
`Borrower` first name.
`income_certification``object`[`IncomeCertificationPayload`](🔗)If adding/updating supporting documentation for Income Certification, supply an `IncomeCertificationPayload`.
`income_growth``number``float`Expected income growth per year, as a percentage. _Defaults to `5.0`._
`Borrower` last name.
`new_borrower_date``string``date`The date on which the `Borrower` first took out student loans.
`Borrower` phone number.
Instructs Payitoff to include PSLF forgiveness in Assessment calculations. _Defaults to `null`._
`residence``string``maxLength: 2`2-letter US state code indicating what state the `Borrower` legally resides in.
`spouse_agi``number``float`If the `Borrower` has a spouse, the spouse's <<glossary:Adjusted Gross Income>>. **NOTE:** `family_size` should be at least `2` if providing `spouse_agi` to be included in Assessment calculations. You should also choose one of the `married_*` `filing_status` values.
`spouse_id``integer``int64`If you wish to have a borrower and their spouse represented in the API and connected for Assessment operations, first create one of the married borrowers via API, then supply their Borrower ID as the other borrower's `spouse_id`. The married borrowers will be connected. **NOTE:** _Don't forget to update `family_size` and `filing_status`._
`Borrower` Social Security Number. **Required for Enrollment.**
`state_of_residence``string``maxLength: 2`2-letter US state code indicating what state the `Borrower` legally resides in.
`student_status``string``unknown` `withdrawn` `leave_of_absence` `quarter_time` `three_quarter_time` `less_than_half` `less_than_half_time` `half_time` `full_time` `graduated``Borrower`'s student status.
`student_status_effective_date``string``date`The date on which the current `student_status` went into effect.
Instructs Payitoff to include TCLI forgiveness in Assessment calculations. _Defaults to `null`._
`teaching_level``string``elementary` `middle` `secondary`If `Borrower` is a teacher, what level of education they teach.
If `Borrower` is a teacher, the state where employing school is located.
`teaching_subject``string``english` `math` `other` `science` `special_education`If `Borrower` is a teacher, the subject they teach.
Is this person unemployed? _Defaults to `false`._ **Required for Enrollment.**

### Example