HomeGuidesAPI Reference
Guides

Guidance (beta)

Suggest Edits

Payitoff provides the ability for Consumers to better mange their debt via our Guidance API. Once all of a Consumer's Debts have been added via the Debt API or via Nexus, a single endpoint can suggest best next steps to better manage paying down their debts. A series of questions in the response help to improve the accuracy of the guidance provided.

🚧

This is under construction. The API capabilities and it’s Response will continue to change.

👍

If you'd like to join our beta program, please reach out to [email protected]

Providing Guidance

First a Consumer must be created via the consumer endpoint and their debts must be added via the debts endpoint or link via Nexus.

For a complete step-by-step guide please see How To: Use the Guidance API (beta) .

The actual call to guidance via the consumer's UUID is:

Here is an example response:

// GET /api/v3.0.0/consumers/:uuid/guidance
{
	"data": {
		"actions": {
			"avalanche": {
				"description": "Makes minimum payments toward the relevant debts, applying any surplus toward the debt with the highest APR",
				"result": "PAID_OFF",
				"monthly_payment": "1831.00",
				"total_cost": "115151.92",
				"time_to_payoff": 212
			},
			"cc_consolidation": {
				"description": "Apply for a personal consolidation loan to pay off that amount in credit-card debt",
				"result": "PAID_OFF",
				"monthly_payment": "1882.51",
				"total_cost": "121382.79",
				"time_to_payoff": 212
			},
			"idr_enrollment": {
				"description": "Enroll eligible student loans in the SAVE repayment plan",
				"result": "WONT_PAY_OFF",
				"monthly_payment": "1271.00",
				"total_cost": "1610063.71",
				"time_to_payoff": 1200
			},
			"snowball": {
				"description": "Pay off debts in order of smallest balance to largest",
				"result": "PAID_OFF",
				"monthly_payment": "1831.00",
				"total_cost": "115615.79",
				"time_to_payoff": 212
			},
			"student_loan_refinance": {
				"description": "Consolidate private student loans at a better APR",
				"result": "WONT_PAY_OFF",
				"monthly_payment": "1831.00",
				"total_cost": "1648443.69",
				"time_to_payoff": 1200
			}
		},
		"questions": [
			{
				"type": "DECIMAL",
				"text": "What is your current adjusted-gross income (AGI)?",
				"question": "AGI"
			},
			{
				"type": "DECIMAL",
				"text": "What is the APR of your Auto at HSBC AUTO FINANCE with balance $16,136.00?",
				"question": "APR",
				"debt_uuid": "aad5fd9f-9039-40a0-80f0-d046b567ce70"
			},
			{
				"type": "DECIMAL",
				"text": "What is the APR of your Student loan at NELNET with balance $6,523.00?",
				"question": "APR",
				"debt_uuid": "768e7067-c471-4f7b-84f7-24d0101e410a"
			},
			{
				"type": "BOOLEAN",
				"text": "Are you overdue on any of your debts?",
				"question": "ANY_OVERDUE_DEBTS"
			}
		],
		"best_current_forecast": {
			"summary": {
				"result": "PAID_OFF",
				"monthly_payment": "1322.51",
				"total_cost": "76413.72",
				"time_to_payoff": 238
			},
			"actions": [
				"CC_CONSOLIDATION",
				"IDR_ENROLLMENT",
				"STUDENT_LOAN_REFINANCE",
				"AVALANCHE"
			]
		}
	}
}

The first section of the response outlines the various actions simulated. For each action there is a description of what the action does, whether or not this action will pay off the debt or not, how much the new total debt monthly payment will be, the new total debt amount and the number of months required to pay it off.

Next is a list of questions to improve the accuracy of the guidance simulation. Knowing the exact APR of a loan or a consumers's AGI, for example, will lead to more accurate guidance. See the following section on how to answer the questions posed in the output.

Finally the best_current_forecast contains the list of actions in the order they should be applied and the a similar action summary which is the result of applying the multiple actions.

Answering Questions

For more accurate guidance, it is useful to have exact information instead of estimated values. To answer a question posed in the guidance response, simply PATCH to the same endpoint with the format outlined here:

Here is a sample request:

// PATCH /api/v3.0.0/consumers/:uuid/guidance
{
  "data": {
    "answers": [
      {
        "question": "APR",
        "answer": "9.56",
        "debt_uuid": "9dcf2a15-e3c9-4d75-ad20-df2f69478f4d"
    	},
      {
        "question": "AGI",
        "answer": "39000.00"
      }
    ]
  }
}

Updated 3 months ago