Consumers

A Consumer is an end-user of Payitoff. They will typically have Debts and seek money-saving guidance on repayment options for those debts, for example enrolling in an Income-Driven Repayment (IDR) plan for their federal student loans, taking out a low-interest personal loan to consolidate high-interest credit card debt, or optimizing their credit card repayment with a snowball strategy.

Creating and Updating Consumers

Before you can help a Consumer take any of these actions, you'll first add them to Payitoff. Consumers can be created without any data (they can always be updated later), but we recommend supplying any you have (for example first_name and last_name or phone so you can tell them apart. Regardless, when a Consumer is created they'll be assigned a uuid, their unique identifier within Payitoff, to find them later on.

Next steps:

• Create a Consumer via our REST API
• Update a Consumer via our REST API

our Nexus.linkDebts and Nexus.guidance (among others) can create a consumer automatically (and return their uuid in a callback) as they guide consumers through connecting their debts. You can then use that UUID in the API to find out more info and take action.

Addresses

Some actions, like finding out student loan repayment options, can provide more accurate results when we know the state a Consumer lives in. Others, like actually enrolling in an Income-Driven Repayment plan, require the consumer's full mailing address. For these reasons, when specifying a consumer's address you have two options:

1. Provide only the state.
2. Provide the full mailing address comprising at least street1, city, state, and zipcode (street2 and street3 are optional)

Providing an incomplete mailing address that includes more than just the state will return a validation error. If you attempt an action that requires a full mailing address but haven't provided one, we'll also return a validation error.

Social Security Numbers

All SSNs submitted via API—and collected by Nexus—are encrypted and stored securely. For security purposes and the protection of your Consumer, SSN values are not returned via the API once provided.

Spouse Details

Some actions, like enrolling in a federal student loan repayment plan, require information about a Consumer's spouse if they are married and file taxes jointly with their spouse. To make this easy, our REST API allows specifying all relevant spouse data when creating or updating a consumer, under the spouse key, for example:

// PATCH /api/v3.0.0/consumers/:uuid
{
  "data": {
    "spouse": {
      "date_of_birth": "2003-02-02",
      "federal_student_loan_balance": "50000.00",
      "first_name": "Henry",
      "has_taxable_income": true,
      "last_name": "Jones"
    }
  }
}

Querying Consumers

Once you have created some Consumers, you can retrieve them again via a GET endpoint:

• Return Consumers via our REST API

There are two parameters which can be set to limit the Consumer returned:

• external_id - This is a pattern used to match a Consumer's external ID. This can either be an entire ID or a substring and any Consumer matching that pattern will be returned
• created_at - This can take either ASC or DESC to sort the resulting list of Consumers by the date on which they were created. By default the list of matching consumers is sorted descending, returning the most recently created Consumer first.