HomeGuidesAPI Reference
Guides

Managing Debts

The API features described below can be used to add a consumer's debts to the Payitoff system in order to enable further actions like generating paydown schedules. You will also find ways to retrieve debts. Both debts created by this API and those created by our Javascript widget Nexus will be listed here.

Suggest Edits

Create a Debt

In addition to debts that are creating by linking, debts may be created via GraphQL mutations.

mutation($consumerId: UUID4!, $input: DebtInput!) {
  createDebt(consumerId: $consumerId, input: $input) {
    accountNumber
    apr
    balance
    balanceEnteringRepayment
    guarantor
    lastPaymentAmount
    lastPaymentOn
    lender
    minimumPayment
    openedOn
    originalPrincipal
    outstandingInterest
    paymentDueOn
    repaymentBeginDate
    studentLoanServicerName
    standing
    subType
    term
    type
    uuid
  }
}

The variables to create a debt should include the following example values:

{
  "consumerId": "98a24c00-9262-4fe7-9871-3fe354dcd574", 
  "input": {
    "accountNumber": "34657687263",
    "apr": 12.5,
    "balance": 50000.00,
    "balanceEnteringRepayment": 75000.00,
    "guarantor": "US Department of ED",
    "lastPaymentAmount": 473.43,
    "lastPaymentOn": "2024-02-26",
    "lender": "University of Learning",
    "minimumPayment": 150.00,
    "openedOn": "2019-08-03",
    "originalPrincipal": 63000.00,
    "outstandingInterest": 3265.49,
    "paymentDueOn": "2024-03-26",
    "repaymentBeginDate": "2024-01-26",
    "studentLoanServicerName": "Nelnet",
    "standing": "IN_REPAYMENT",
    "subType": "Direct Stafford Subsidized",
    "term": 120,
    "type": "STUDENT_LOAN"
  }
}

*Please note: studentLoanServicerName may only be set when type is set to STUDENT_LOAN. When working with student loans, in order to receive the best Guidance, we suggest using the following values for the subType field:

"Direct Stafford Subsidized (SULA Eligible)"  
"Direct Stafford Subsidized"  
"Direct Stafford Unsubsidized"  
"Direct PLUS for Graduate/Professional"  
"Direct PLUS Parent"  
"Direct Consolidation Unsubsidized"  
"Direct Consolidation Subsidized"  
"Direct Consolidation PLUS"  
"Direct Unsubsidized (TEACH)"  
"Direct Consolidation Subsidized (SULA Eligible)"  
"National Defense"  
"Perkins Expanded Lending"  
"Federally Insured Student (FISL)"  
"FFEL PLUS for Graduate/Professional"  
"Income-Contingent (ICL)"  
"National Direct Student (NDSL)"  
"FFEL PLUS Parent"  
"Federal Perkins"  
"FFEL Refinanced"  
"FFEL Stafford Subsidized"  
"Supplemental (SLS)"  
"FFEL Stafford Unsubsidized"  
"Private"

Update a Debt

Any debt may be updated via a mutation. Be aware that if a debt created by linking is updated via API, those updates may be overwritten the next time the debt is synced if conflicting data is received.

mutation($consumerId: UUID4!, $debtId: UUID4!, $input: DebtInput!) {
  updateDebt(consumerId: $consumerId, debtId: $debtId, input: $input) {
    accountNumber
    apr
    balance
    balanceEnteringRepayment
    guarantor
    lastPaymentAmount
    lastPaymentOn
    lender
    minimumPayment
    openedOn
    originalPrincipal
    outstandingInterest
    paymentDueOn
    repaymentBeginDate
    studentLoanServicerName
    standing
    subType
    term
    type
    uuid
  }
}

The variables to update a debt may include the following example values:

{
  "consumerId": "fff7ff9f-0f2b-4d99-89ec-40d237b95d4d", 
  "debtId": "908c2df0-70ec-42e0-ac21-bdf26b7c4419", 
   "input": {
    "accountNumber": "34657687263",
    "apr": 12.5,
    "balance": 50000.00,
    "balanceEnteringRepayment": 75000.00,
    "guarantor": "US Department of ED",
    "lastPaymentAmount": 473.43,
    "lastPaymentOn": "2024-02-26",
    "lender": "University of Learning",
    "minimumPayment": 150.00,
    "openedOn": "2019-08-03",
    "originalPrincipal": 63000.00,
    "outstandingInterest": 3265.49,
    "paymentDueOn": "2024-03-26",
    "repaymentBeginDate": "2024-01-26",
    "studentLoanServicerName": "Aidvantage",
    "standing": "IN_REPAYMENT",
    "subType": "Direct Stafford Subsidized",
    "term": 120,
    "type": "STUDENT_LOAN"
  }
}

Delete a Debt

Debts created via GraphQL can be deleted via GraphQL. Debts created via linking may not be deleted via GraphQL.

mutation($consumerId: UUID4!, $debtId: UUID4!) {
  deleteDebt(consumerId: $consumerId, debtId: $debtId) {
    apr
    balance
    minimumPayment
    term
    type
    uuid
  }
}

The variables to delete a debt should include the following example values:

{
  "consumerId": "fff7ff9f-0f2b-4d99-89ec-40d237b95d4d", 
  "debtId": "908c2df0-70ec-42e0-ac21-bdf26b7c4419"
}

List a Consumer's Debts

query($consumerId: UUID4!, $types: [DebtType]) {
  consumer(uuid: $consumerId) {
    debts(types: $types) {
      accountNumber
      amountPastDue
      apr
      balance
      balanceEnteringRepayment
      creditLimit
      estimatedMinimumPayment
      guarantor
      institutionName
      lastActivityOn
      lastPaymentAmount
      lastPaymentOn
      lender
      mask
      minimumPayment
      ninetyDayCounter
      openedOn
      originalPrincipal
      outstandingInterest
      paymentDueOn
      paymentFrequency
      payoffBalance
      payoffQuoteDate
      reportedOn
      responsibility
      repaymentBeginDate
      sixtyDayCounter
      standing
      studentLoanServicerName
      subType
      term
      thirtyDayCounter
      type
      uuid
    }
  }
}

Example variables:

{
  "consumerId": "df8f7e1b-62f0-4297-a6bc-042ac371ad72",
  "types": ["STUDENT_LOAN","CREDIT_CARD"]
}

Retrieving Linked Debts

When looking at Debts that have been linked via Nexus, please note that minimum_payment will never be populated from linking. However, the estimated_minimum_payment field may often contain an amount corresponding to the scheduled monthly payment for that debt.

Types 🚧

Explore our complete GraphQL schema in the GraphiQL UI available at https://payitoff-sandbox.io/api/graphql-playground (just click the "< Docs" tab at right).

Updated 6 months ago