HomeGuidesAPI Reference

Enroll via Nexus

After creating a consumer and their debts, you can embed Nexus.studentLoanEnroll into your website! Below is the Enroll flow your Consumer will go through:

Steps to Implementation


1. Create Consumer via API

Since you are leveraging your existing data set to determine whether the consumer qualifies for a lower monthly payment, you’ll want to create a consumer via the API then use the UUID in the response to create debts.

The following consumer fields are required for the most accurate assessment and will be required for eventual enrollment:

  • agi — their Adjusted Gross Income
  • filingStatus — Tax Filing Status from their last federal income tax return
    • If married filing jointly, we will need the consumer’s spouse’s agi
    • if married filing jointly, we will need the consumer’s spouse’s federalLoanBalance
  • familySize — the Family Size claimed on their taxes
  • firstName - First name of consumer
  • lastName - Last name of consumer
  • phone - consumer phone number
  • address - Address of the consumer
  • maritalStatus - Marital Status of the consumer

2. Manage Debts via API

The Consumer must have student loan Debts in order to take advantage of enrolling in student loan repayment options. Create those student loan debts via GraphQL.

Required fields to create your Student Loan Debt:

  • balance - Loan Balance
  • openedOn - Disbursement Date
  • originalPrincipal - Disbursement Amount
  • studentLoanServicerName - Servicer Name
  • type - The type of Debt, i.e. STUDENT_LOAN

If you have these Optional inputs on Debts, please include them:

  • apr - APR
  • term - Term in Months



minimumPayment (Monthly Payment) is required to get a comparison on a monthly payment but not required for eligibility or enrollment.


3. Fetch Repayment Options via API

RepaymentOption object returns all the financial details of a given Repayment Plan that allows you to provide a consumer the ability to compare various Repayment Plans against their current Repayment Plan, and choose a Plan that works best for their goals and needs.

With your consumer and loans successfully created, you're ready to fetch available Repayment Options.


4. Enroll via Nexus

After embedding our widget the consumer can go through the enrollment flow.

Here to Help: Checking Enrollment-Readiness for a Consumer

The enrollmentMissingFields field is available on the consumer in GraphQL to check if all the consumer fields required to launch Nexus.studentLoanEnroll are present. If the consumer is ready to launch Nexus.studentLoanEnroll, you'll see "enrollmentMissingFields": []. If not, it will communicate what fields are missing that you will need to update via the GraphQL API.

query {
  consumer(uuid: "5943cd2b-c7a5-4f0b-a607-dbf3e869de3d") {

Example response for a consumer missing fields required for enrollment:

  "data": {
    "consumer": {
      "enrollmentMissingFields": [

Be sure to check this before you send Consumer to Nexus.studentLoanEnroll workflow.

Launch Nexus.studentLoanEnroll:

Nexus.studentLoanEnroll expects to receive a single options object as a parameter.


As a reminder, a plan where the consumer is eligible must be included in the options before an Enrollment can be launched.

We recommend adding an onEvent callback to receive any errors and be notified of your consumers activity within Nexus. If your consumer is missing any required fields for enrollment, you will find out from an init_failed event sent to the onEvent callback.

The code below will launch the Nexus widget:

  // e.g. 'save', 'paye', 'ibr', 'icr', etc.
  plan: 'save',
  // a callback to be notified of errors or other important events within the Nexus widget
  onEvent: handleEvent,

Nexus Events

The following events may be sent to your onEvent callback as the consumer progresses through Nexus.studentLoanEnroll:

init_failedThe Nexus workflow could not be launched due to an error, such as required data missing.e.g. {reason: "fields_missing", fields: "family_size"}
workflow_startedThe Nexus workflow was launched without error.none
workflow_finishedThe consumer finished the workflow.The enrollment key has details about the enrollment request and its status (see below)
quitThe borrower closed Nexus before enrolling in a repayment plan.none

When your borrower completes an enrollment the below is an example of the event sent to your onEvent callback:

  nexusEvent: {
    name: "workflow_finished",
    workflow: "enroll",
    consumer: { uuid: "dceea28c-2245-41a8-a558-fef1643f99b2" },
    metadata: {
      enrollment: {
        created_at: "2021-05-07T16:36:12.051603Z",
        estimated_approval_date: "2023-12-15",
        id: 23,
        repayment_plan: {
          description: "Saving on a Valuable Education (SAVE)",
          type: "save",
        status: {
          updated_at: "2021-05-07T16:36:12.055132Z",
          description: "Submission in Progress",
          type: "pending",
        uuid: "c399298f-47ef-4fab-85b3-6244fca22448",