HomeGuidesAPI Reference
Guides

Using Nexus onEvents

Get visibility into a Consumer's journey through Nexus in real time.

Payitoff allows a Consumer to unlock their debts (with just a phone number, zip code, and DOB), receive Guidance, and take steps to improve their situation using our Nexus widget. To better understand a Consumer’s journey through these pre-designed workflows, the below onEvent callbacks are available for visibility into a Consumer’s successes and failures.

onEvent Callback

When Nexus transmits an event, your onEvent callback will be called with one an argument, a JavaScript object with a top-level property nexusEvent containing an object with the details of the event:

{
  nexusEvent: {
    name: "workflow_started",
    workflow: "link_to_enroll"
    happened_at: "2024-07-02T14:39:12.205906Z", 
    consumer: {
       uuid: "ddfe568c-2245-41a8-a558-fef1643f99b2"
     },
     metadata: {varies per event, see table below}
  }
}

The Events

nexusEvent.nameDescriptionnexusEvent.metadataWorkflows Supported
workflow_startedThe Nexus workflow was launched without error.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_enroll Nexus.student_loan_link, Nexus.refi
identity_verification_startYour consumer has provided their phone, DOB, and zip code.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
otp_send_attempt_via_smsConsumer has requested an OTP and the request has been initiated.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
otp_send_via_sms_malfunctionedThe OTP failed to send due to a failure on our end OR our vendor’s end. Please reach out to us for further assistance.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
otp_send_via_sms_successfulThe OTP code was successfully sent to the consumer.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
otp_verified_via_smsConsumer has successfully input the OTP code and verified their mobile number.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
otp_invalid_code_enteredConsumer has input the incorrect OTP code that was sent to their mobile device. Please reach out to us for further assistance.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
otp_verification_malfunctionedThe OTP code was not verified due to a failure on our end OR our vendor’s end. Please reach out to us for further assistance.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
consumer_identity_retrieved_successfullyConsumer identity has been retrieved successfully.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
consumer_identity_failedUnable to find consumer identity (with the data provided).noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
consumer_identity_malfunctionedUnable to find the consumer identity due to a failure on our end OR our vendor’s end. Please reach out to us for further assistance.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
identity_verification_completeIdentity verification has ended in success or failure. Please see events above.status: "success, failed"Nexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
debts_not_linked_due_to_freezeAlthough the consumer’s identity was verified, we could not retrieve their debts due to a credit freeze.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
debts_not_foundAlthough the consumer’s identity was verified no debts were found.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
debts_linkedThe consumer’s debts have been retrieved successfully. The metadata shows the consumer’s aggregated active debt counts, for more detail please see further documentation on how to list a consumers debts ."debts_found": {"student_loan": 4, "mortgage": 1}Nexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
debts_link_malfunctionedAlthough the consumer’s identity was verified, we could not retrieve their debts due to a failure on our end OR our vendor’s end. Please reach out to us for further assistance.noneNexus.guidance , Nexus.link_debts Nexus.link_to_enroll , Nexus.student_loan_link
workflow_finishedThe consumer finished the workflow.The enrollment key has details about the enrollment request and its status (see below)Nexus.link_to_enroll , Nexus.student_loan_enroll, Nexus.student_loan_link , Nexus.refi
quitThe consumer closed Nexus before enrolling in a repayment plan. Note: unlike other workflows, Nexus.guidance has no "end", so the quit event does not necessarily mean exiting prematurely. Instead, consumers must quit to close Nexus even after successfully linking debts and applying for a consolidation loan.noneall workflows
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"}Nexus.student_loan_enroll
debt_account_linkedThe consumer logged into a debt account to fetch additional details about debts with that lender.noneNexus.guidance
consolidation_incompleteThe consumer began an application for a debt-consolidation loan but did not finish it.noneNexus.guidance
consolidation_offers_unavailableThe consumer began an application for a debt-consolidation loan but did not receive offers from a lender.noneNexus.guidance
consolidation_offer_selectedThe consumer selected a consolidation loan offer and was directed to the lender's site to submit the pre-filled application.noneNexus.guidance

Workflow finished events

Depending on the workflow, the metadata contained in the workflow_finished event will differ. Here is an example for the link_to_enroll workflow. See the table below for specific workflow metadata.

{
  nexusEvent: {
    name: "workflow_finished",
    workflow: "link_to_enroll",
    consumer: { uuid: "dceea28c-2245-41a8-a558-fef1643f99b2" },
    happened_at: "2024-07-02T14:39:12.205906Z", 
    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",
      },
    },
  },
}
workflowmetadata
Nexus.link_to_enrollSee metadata in js example above.
Nexus.refi{ offer: {
id: "d1fb8aad-813e-4b8f-af36-49bcb4b509d3",
lender: "Arkansas Student Loan Authority"
},
submission: {
id: "aff108cb-73d6-4273-a2e9-ddee97f033a8",
loans: [
"966a98cd-821e-4064-8ae3-82185abc97c8",
"cc2102b3-bd1d-4fba-8cbe-680b121b41ac",
"6e6b4aa9-087f-473d-93dc-386722e9886a"
]}
Nexus.student_loan_enrollSee metadata in js example above.
Nexus.student_loan_linknone