NAV Navbar
java go typescript python

Introduction

Rightfoot's API generates student debt beneficiary accounts and transfers funds to their loans.

We have language bindings for Java, Go, Python and TypeScript. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right. If SDKs/libraries are desired for other languages, we are happy to develop them based on demand.

Authentication

import com.rightfoot.client.RightfootClient;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
from rightfoot import Rightfoot

api = Rightfoot('secure-private-key')
import { Rightfoot } from 'rightfoot';

const api = new Rightfoot('secure-private-key');

Make sure to replace secure-private-key with your API key.

Rightfoot uses API keys to allow access to the API. You can register a new Rightfoot API key by contacting us at info@rightfoot.com.

Rightfoot expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: secure-private-key

Onboarding a New Application

To request a new Rightfoot API key, contact us at info@rightfoot.com. Rightfoot will facilitate the onboarding process to:

Beneficiaries

Beneficiaries are the end-users, which receive credits to their loans via use of these APIs. As appropriate for the given product consuming these APIs, beneficiaries are created and managed to attach loan accounts to and issue payment instructions to benefit.

Create a New Beneficiary

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.CreateBeneficiaryRequest;
import com.rightfoot.client.CreateBeneficiaryResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final CreateBeneficiaryRequest request = new CreateBeneficiaryRequest(
    "Person", "Doe", "foo-bar-baz");
final CreateBeneficiaryResponse response = api.beneficiaries.create(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.CreateBeneficiaryRequest{
  FirstName: "Person",
  LastName: "Doe",
  PlatformID: "foo-bar-baz"
}
response, err := api.Beneficiaries.Create(request)
from rightfoot import Rightfoot, CreateBeneficiaryRequest

api = Rightfoot('secure-private-key')
request = CreateBeneficiaryRequest(
    firstName="Person", lastName="Doe", platformId="foo-bar-baz")
response = api.beneficiaries.create(request)
print(response)
import { Rightfoot, CreateBeneficiaryRequest} from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = new CreateBeneficiaryRequest(
    "Person", "Doe", "foo-bar-baz");
api.beneficiaries.create(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

This endpoint creates a new beneficiary.

HTTP Request

POST https://production.api.rightfoot.com/v1/beneficiaries

Body Parameters

Key Type Required Description
firstName String Yes The given name of the beneficiary.
lastName String Yes The family name of the beneficiary.
platformId String No A unique identifier for the consuming product used as a customizable foreign key.

Response

{
  "beneficiary": {
    "uuid": "12345678-abcd-1234-abcd-12345678abcd",
    "firstName": "Person",
    "lastName": "Doe",
    "platformId": "foo-bar-baz",
    "emailAddress": null,
    "dateOfBirth": null,
    "phoneNumber": null
  }
}

This create API responds with the created Beneficiary.

Key Type Nullable? Description
beneficiary Object<Beneficiary> No The created beneficiary with provided fields populated.

Loan Linking

Beneficiaries need to link their loans to Rightfoot's API platform to complete their onboarding process. Beneficiaries can be onboarded by way of two alternatives depending on the product's requirements: 1) Rightfoot-managed onboarding or 2) white-labeled experience.

Rightfoot-Managed Experience

In a Rightfoot-managed experience, beneficiaries are invited to join the Rightfoot platform to link their loans and manage their debt. In this situation, contact information for the user is required. The user will receive an email with a password reset link, inviting the user to create an account, which will be linked to the created beneficiary.

Additionally, Rightfoot will capture any required demographic information required for paydown, such as date of birth and phone number. Otherwise, these are needed to be provided by API call.

In this solution, only the /v1/beneficiaries/invite API needs to be called. The /v1/beneficiaries/demographics API can be optionally called prior to invite, and the user will not be requested for this information on the Rightfoot managed platform.

White-Labeled Solution

Consuming product uses Rightfoot's public Plaid key, allowing beneficiaries the ability to log into their loans using Plaid Link or directly against Plaid's API. This has the advantage of an experience completely controlled by the consuming product but requiring greater development effort and sacrificing management dashboards for beneficiaries to optimize their debt repayment.

In this solution, the /v1/beneficiaries/demographics API needs to be called and then the /v1/beneficiaries/addPlaidToken API needs to be called for as many accounts as are attached in the consuming product's experience.

Invite Beneficiary to Onboard and Manage

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.InviteBeneficiaryRequest;
import com.rightfoot.client.InviteBeneficiaryResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final UUID uuid = UUID.fromString("12345678-abcd-1234-abcd-12345678abcd");
final InviteBeneficiaryRequest request = InviteBeneficiaryRequest.withUUID(
    uuid, "foo@bar.baz");
final InviteBeneficiaryResponse response = api.beneficiaries.invite(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.InviteBeneficiaryRequest{
  UUID: "Person",
  Email: "foo@bar.baz"
}
response, err := api.Beneficiaries.Invite(request)
from rightfoot import Rightfoot, InviteBeneficiaryRequest

api = Rightfoot('secure-private-key')
request = InviteBeneficiaryRequest(
    uuid="12345678-abcd-1234-abcd-12345678abcd", emailAddress="foo@bar.baz")
response = api.beneficiaries.invite(request)
print(response)
import { Rightfoot, InviteBeneficiaryRequest} from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = InviteBeneficiaryRequest.withUUID(
    "12345678-abcd-1234-abcd-12345678abcd", "foo@bar.baz");
api.beneficiaries.invite(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

This endpoint invites a beneficiary via email to create an account on the Rightfoot platform to complete onboarding.

HTTP Request

POST https://production.api.rightfoot.com/v1/beneficiaries/invite

Body Parameters

Parameter Type Required Description
uuid String No* Unique identifier generated by Rightfoot.
platformId String No* A unique identifier for the consuming product used as a customizable foreign key.
emailAddress String Yes The email address of an invited beneficiary.

Response

{
  "beneficiary": {
    "uuid": "12345678-abcd-1234-abcd-12345678abcd",
    "firstName": "Person",
    "lastName": "Doe",
    "platformId": "foo-bar-baz",
    "emailAddress": "foo@bar.baz",
    "dateOfBirth": null,
    "phoneNumber": null
  }
}

This invite API responds with the updated Beneficiary.

Key Type Nullable? Description
beneficiary Object<Beneficiary> No The created beneficiary with set fields populated.

Set Beneficiary Demographics


import com.google.i18n.phonenumbers.Phonenumber;
import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.UpdateDemographicsRequest;
import com.rightfoot.client.UpdateDemographicsResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final Phonenumber.PhoneNumber phoneNumber =
    PhoneNumberUtil.getInstance().parse(phoneNumber,  "US")
final UpdateDemographicsRequest request = UpdateDemographicsRequest.withUUID(
    "12345678-abcd-1234-abcd-12345678abcd", LocalDate.of(1991, 2, 29),
    phoneNumber);
final UpdateDemographicsResponse response = api.updateDemographics(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.UpdateDemographicsRequest{
  UUID: "Person",
  Date: "1991-02-29",
  PhoneNumber: "+1 555 555 5555"
}
response, err := api.Beneficiaries.UpdateDemographics(request)
from datetime import date
import phonenumbers
from rightfoot import Rightfoot, UpdateDemographicsRequest

api = Rightfoot('secure-private-key')
phoneNumber = phonenumbers.parse("+1 555 555 5555")
request = UpdateDemographicsRequest(
    uuid="12345678-abcd-1234-abcd-12345678abcd", date=date(1991, 2, 29),
    phoneNumber=phoneNumber)
response = api.beneficiaries.updateDemographics(request)
print(response)
import { Rightfoot, UpdateDemographicsRequest } from 'rightfoot';
import { parsePhoneNumber } from 'libphonenumber-js';

const api = Rightfoot('secure-private-key');
const phoneNumber = parsePhoneNumber('+1 555 555 5555');
const request = new UpdateDemographicsRequest(
    "12345678-abcd-1234-abcd-12345678abcd", new Date(1991, 2, 29), phoneNumber);
api.beneficiaries.updateDemographics(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

This endpoint sets the required demographics on a beneficiary in order to pay down their student debt. Not required to be called if using a Rightfoot-managed experience.

HTTP Request

POST https://production.api.rightfoot.com/v1/beneficiaries/updateDemographics

Body Parameters

Key Type Required Description
last4SSN String Yes Last 4 digits of beneficiary's Social Security Number.
dateOfBirth String Yes Birth date for the beneficiary formatted as YYYY-MM-DD.
phoneNumber String Yes Phone number for the beneficiary formatted internationally with spacing such as +1 555 555 5555.

Response

{
  "uuid": "12345678-abcd-1234-abcd-12345678abcd",
  "firstName": "Person",
  "lastName": "Doe",
  "platformId": "foo-bar-baz",
  "emailAddress": null,
  "dateOfBirth": "1991-02-29",
  "phoneNumber": "+15555555555"
}

This invite API responds with the updated Beneficiary.

Key Type Nullable? Description
beneficiary Object<Beneficiary> No The updated beneficiary with set fields populated.

Connect Plaid Loan

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.AddPlaidLoanRequest;
import com.rightfoot.client.AddPlaidLoanResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final AddPlaidLoanRequest request = AddPlaidLoanRequest.withUUID(
    "12345678-abcd-1234-abcd-12345678abcd", "plaid-token");
final AddPlaidLoanResponse response = api.beneficiaries.addPlaidToken(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.AddPlaidLoanRequest{
  UUID: "Person",
  PlaidPublicToken: "plaid-token"
}
response, err := api.Beneficiaries.AddPlaidToken(request)
from datetime import date
import phonenumbers
from rightfoot import Rightfoot, AddPlaidLoanRequest

api = Rightfoot('secure-private-key')
phoneNumber = phonenumbers.parse("+1 555 555 5555")
request = AddPlaidLoanRequest(
    uuid="12345678-abcd-1234-abcd-12345678abcd",
    plaidPublicToken="plaid-token")
response = api.beneficiaries.addPlaidToken(request)
print(response)
import { Rightfoot, AddPlaidLoanRequest } from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = new AddPlaidLoanRequest(
    "12345678-abcd-1234-abcd-12345678abcd", "plaid-token");
api.beneficiaries.addPlaidToken(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

This endpoint connects an authenticated Plaid account using our Plaid public key 1773c898604f2bd4d68ecbbc8504f9. Rightfoot binds the loan accounts, exchanging the public key in the background, maintaining loan records.

HTTP Request

POST https://production.api.rightfoot.com/v1/beneficiaries/addPlaidToken

Body Parameters

Parameter Type Required Description
uuid String No* Unique identifier generated by Rightfoot.
platformId String No* A unique identifier for the consuming product used as a customizable foreign key.
plaidPublicToken String Yes Public token obtained from Plaid using Rightfoot's Plaid public key.

Response

{
  "uuid": "12345678-abcd-1234-abcd-12345678abcd",
  "firstName": "Person",
  "lastName": "Doe",
  "platformId": "foo-bar-baz",
  "emailAddress": null,
  "dateOfBirth": "1991-02-29",
  "phoneNumber": "+15555555555"
}

This invite API responds with the updated Beneficiary.

Key Type Nullable? Description
beneficiary Object<Beneficiary> No The updated beneficiary with set fields populated.

Beneficiary Schema

The Beneficiary type represents an end-user receiving funds in their loan accounts.

Key Type Nullable? Description
uuid String No Unique identifier generated by Rightfoot.
platformId String Yes, if not provided. A unique identifier for the consuming product used as a customizable foreign key.
firstName String No The given name of the beneficiary.
lastName String No The family name of the beneficiary.
emailAddress String Yes, if not yet set. The email address of an invited beneficiary.
dateOfBirth String Yes, if not yet set. Birth date for the beneficiary formatted as YYYY-MM-DD.
phoneNumber String Yes, if not yet set. Phone number for the beneficiary formatted internationally with spacing such as +1 555 555 5555.

Payments

Payments are issued per-beneficiary with individual requests for transfer. They pay down the beneficiary's highest interest loan first, in order to minimize capitalized interest.

Payment transfers have direct costs associated with them but can be batched based on the consuming product's configuration. See PaymentBatchingOptions.

Issue Payment

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.IssuePaymentRequest;
import com.rightfoot.client.IssuePaymentResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final IssuePaymentRequest request = IssuePaymentRequest.withUUID(
    "12345678-abcd-1234-abcd-12345678abcd", new BigDecimal("500.00"));
final IssuePaymentResponse response = api.payments.issuePayment(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.IssuePaymentRequest{
  UUID: "12345678-abcd-1234-abcd-12345678abcd",
  Amount: 50000
}
response, err := api.Payments.IssuePayment(request)
from rightfoot import Rightfoot, IssuePaymentRequest

api = Rightfoot('secure-private-key')
request = IssuePaymentRequest(
    uuid="12345678-abcd-1234-abcd-12345678abcd", paymentAmount=50000)
response = api.payments.issuePayment(request)
print(response)
import { Rightfoot, IssuePaymentRequest } from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = new IssuePaymentRequest(
    "12345678-abcd-1234-abcd-12345678abcd", 50000);
api.payments.issuePayment(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

This endpoint issues a request to transfer funds from the consuming application's funding source to the beneficiary's loan account.

HTTP Request

POST https://production.api.rightfoot.com/v1/payments

Body Parameters

Parameter Type Required Description
beneficiaryUuid String No* Unique identifier generated by Rightfoot for beneficiary.
beneficiaryPlatformId String No* A unique identifier for the consuming product used as a customizable foreign key.
paymentAmount Integer Yes Amount to pay to beneficiary's student loans, in cents USD.
paymentDate String No Date (UTC) to initiate the payout in the future formatted as YYYY-MM-DD. If unset, follows batching rules for application.

Response

{
  "payment": {
    "uuid": "12345678-abcd-1234-abcd-12345678abcd",
    "status": "PENDING",
    "description": null
  }
}

This payment issuance API responds with the created payment.

Parameter Type Nullable? Description
payment Object<Payment> No The created payment object.

Check Payment Status

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.GetPaymentRequest;
import com.rightfoot.client.GetPaymentResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final GetPaymentRequest request =
    new GetPaymentRequest("12345678-abcd-1234-abcd-12345678abcd");
final GetPaymentResponse response = api.payments.get(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.GetPaymentRequest{
  UUID: "12345678-abcd-1234-abcd-12345678abcd"
}
response, err := api.Payments.Get(request)
from rightfoot import Rightfoot, PaymentStatusRequest

api = Rightfoot('secure-private-key')
request = PaymentStatusRequest(uuid="12345678-abcd-1234-abcd-12345678abcd")
response = api.payments.get(request)
print(response)
import { Rightfoot, GetPaymentRequest } from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = new GetPaymentRequest(
    "12345678-abcd-1234-abcd-12345678abcd");
api.payments.get(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

This endpoint retrieves an existing payment, updated with the latest status of its processing along with error information.

HTTP Request

GET https://production.api.rightfoot.com/v1/payments/{uuid}

Query Parameters

Parameter Type Required Description
uuid String Yes Unique identifier generated by Rightfoot for the payment.

Response

{
  "payment": {
    "uuid": "12345678-abcd-1234-abcd-12345678abcd",
    "status": "COMPLETED",
    "description": null
  }
}

This payment status API responds with the current state of the Payment object.

Parameter Type Nullable? Description
payment Object<Payment> No The created payment object.

Payment Schema

Parameter Type Nullable? Description
uuid String No Unique identifier generated by Rightfoot for payment.
status Enum<PaymentStatus> No Status of the payment.
description String Yes In the case of errors or other variants, provides a description of the failed state.

PaymentStatus Enum

Value Description
PENDING Payment request has been issued.
ACCEPTED Payment request accepted by processors. Will update over several days until payment is completed.
COMPLETED Payments verified to have been disbursed.
RETURNED Payment is more than balance and note necessary.
FAILED An irrecoverable error in processing has occurred.

Application Management

While the application is provisioned on the Rightfoot developer console, the application can be reconfigured by API.

Get Application

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.GetApplicationRequest;
import com.rightfoot.client.GetApplicationResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final GetApplicationRequest request = new GetApplicationRequest();
final GetApplicationResponse response = api.application.get(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.GetApplicationRequest{}
response, err := api.Application.Get(request)
from rightfoot import Rightfoot, GetApplicationRequest

api = Rightfoot('secure-private-key')
request = GetApplicationRequest()
response = api.application.get(request)
print(response)
import { Rightfoot, GetApplicationRequest } from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = new GetApplicationRequest();
api.application.get(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

Retrieves the Application backed by the requesting API keys.

HTTP Request

GET https://production.api.rightfoot.com/v1/application

Query Parameters

No parameters in request.

Response

{
  "application": {
    "paymentBatchingOption": "WEEKLY_APPLICATION"
  }
}

This payment status API responds with the Application object.

Parameter Type Nullable? Description
application Object<Application> No The current application object.

Rotating API Keys

import com.rightfoot.client.RightfootClient;
import com.rightfoot.client.RotateAPIKeyRequest;
import com.rightfoot.client.RotateAPIKeyResponse;

final RightfootClient api = new Rightfoot.builder()
    .apiKey("secure-private-key")
    .build();

final RotateAPIKeyRequest request = new RotateAPIKeyRequest();
final RotateAPIKeyResponse response = api.application.rotateAPIKey(request);
import (
    "rightfoot"
)

api := rightfoot.NewClient("secure-private-key")
request := rightfoot.RotateAPIKeyRequest{}
response, err := api.Application.RotateAPIKey(request)
from rightfoot import Rightfoot, RotateAPIKeyRequest

api = Rightfoot('secure-private-key')
request = RotateAPIKeyRequest()
response = api.application.rotateAPIKey(request)
print(response)
import { Rightfoot, RotateAPIKeyRequest } from 'rightfoot';

const api = Rightfoot('secure-private-key');
const request = new RotateAPIKeyRequest();
api.application.rotateAPIKey(request).subscribe(
    (response) => { console.log(response); },
    (err) => { console.error(err); });

Generates a new API key invalidating the current API key in 24hours.

HTTP Request

POST https://production.api.rightfoot.com/v1/application/rotateAPIKey

Body Parameters

No parameters in request.

Response

{
  "apiKey": "new-secure-private-key"
}

This payment status API responds with the Application object.

Parameter Type Nullable? Description
application Object<Application> No The current application object.

Application Schema

Parameter Type Nullable? Description
paymentBatchingOption Object<PaymentBatchingOptions> No The batching behavior for the application.

PaymentBatchingOptions Enum

Value Description
NONE All payments are charged against funding source immediately and initiated through payment processor.
DAILY_BENEFICIARY All payment requests for a given beneficiary are batched together each day.
DAILY_APPLICATION All payment requests for all beneficiaries are batched together each day.
WEEKLY_BENEFICIARY All payment requests for a given beneficiary are batched together each week on Monday.
WEEKLY_APPLICATION All payment requests for all beneficiaries are batched together each week on Monday.
MONTHLY_BENEFICIARY All payment requests for a given beneficiary are batched together each month on the first day of the month.
MONTHLY_APPLICATION All payment requests for all beneficiaries are batched together each month on the first day of the month.

Errors

The Rightfoot API uses the following error codes across all endpoints:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is not permitted to the requested account.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- The endpoint requested does not support that method.
406 Not Acceptable -- You requested a format that isn't json.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many things! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.