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

You must replace secure-private-key with your personal API 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:

Perform KYC verification of your business for compliance purposes.
Connect a funding source/bank account for drawing payments against.

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.

*Either uuid or platformId must be provided.

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`.

*Either uuid or platformId must be provided.

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.

*Either uuid or platformId must be provided.

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.

*Either beneficiaryUuid or beneficiaryPlatformId must be provided.

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.

Introduction

Authentication

Onboarding a New Application

Beneficiaries

Create a New Beneficiary

HTTP Request

Body Parameters

Response

Loan Linking

Rightfoot-Managed Experience

White-Labeled Solution

Invite Beneficiary to Onboard and Manage

HTTP Request

Body Parameters

Response

Set Beneficiary Demographics

HTTP Request

Body Parameters

Response

Connect Plaid Loan

HTTP Request

Body Parameters

Response

Beneficiary Schema

Payments

Issue Payment

HTTP Request

Body Parameters

Response

Check Payment Status

HTTP Request

Query Parameters

Response

Payment Schema

PaymentStatus Enum

Application Management

Get Application

HTTP Request

Query Parameters

Response

Rotating API Keys

HTTP Request

Body Parameters

Response

Application Schema

PaymentBatchingOptions Enum

Errors

`Beneficiary` Schema

`Payment` Schema

`PaymentStatus` Enum

`Application` Schema

`PaymentBatchingOptions` Enum