Skip to main content
POST
Enroll or update borrowers in payment monitoring

​
Enroll and Update Borrowers

Enroll a batch of borrowers in a single call. Rightfoot stores each borrower, monitors their balance, and acts once there is enough in the account to collect. This is also the update route: send a borrower you have already enrolled and their details and amount are refreshed in place. There is no separate update call. Send up to 1000 borrowers per request.

​
Send your whole file, every day

This endpoint is an upsert — re-sending a borrower is how you update them. Someone already being monitored comes back as updated: their details are refreshed and the collectable_amount in that request is applied to the monitor they already have. That means you do not need to track what you have already sent, or which borrowers changed. Push your full delinquent file on whatever cadence suits you and let the response tell you what happened to each borrower. To stop monitoring a borrower altogether, use Remove Borrowers from Monitoring.

​
What a re-send changes

This is what to use when a borrower pays you directly and the amount you will accept drops: send them again with the lower collectable_amount.
An update applies to the next payment, not to one already in flight. If Rightfoot has a payment out at the bank for this borrower, that payment runs to its original amount, and the new amount is picked up only if it comes back.
An unchanged re-send is reported updated as well. Rightfoot cannot tell “re-sent unchanged” from “re-sent with edits” — the stored details are encrypted and cannot be read back to compare — so read updated as “this borrower is monitored against the amount you just sent”, not as “something about them changed”.

​
Monitoring lapses if you stop sending

Monitoring expires 30 days after it starts. Sending a borrower again after their monitoring has expired starts fresh monitoring, using the collectable_amount in that request. Re-sending a borrower who is still being monitored updates them but does not extend that window — the 30 days run from when monitoring started, not from your last push. Your regular push is therefore what keeps monitoring alive. If a borrower drops out of your file, monitoring for them lapses within 30 days.

​
What you send for each borrower

The identity and bank account fields are the same ones the balance endpoints accept, so an existing integration can reuse its serialization.
Keep authorizer_unique_id stable for the life of the loan. Monitoring history accumulates against it. An identifier that changes between pushes resets that history, and monitoring quietly degrades rather than failing.

​
The bank account is always required

account_number and routing_number are required for every borrower, including those you intend to charge by card. They are what Rightfoot uses to read the balance, and no charge instrument substitutes for them.

​
The amount is a ceiling, in cents

collectable_amount is an integer number of cents — 42500 is $425.00. Rightfoot treats it as a ceiling, and will not attempt more than that in a single payment.

​
How Rightfoot collects

Omit charge_instrument entirely and Rightfoot collects by ACH from the bank account you supplied. That is the common case. To have a card charged instead, supply exactly one of:

processor_token

A token held by your payment processor. Preferred — no sensitive card data leaves your systems. Send card_last4 alongside it.

card

Raw card details, stored securely by Rightfoot. Use this only when you cannot produce a processor token.
card_last4 is required with processor_token. The token itself is opaque to Rightfoot, so the last four digits are what confirm the card belongs to the account being monitored — a card drawing on a different account would make the balance Rightfoot reads meaningless.
Each borrower in the same request can use a different option. Only the charge_instrument differs — the identity and bank account fields are the same either way.
These snippets show only the fields that differ. Identity fields (first_name, last_name, phone_number, date_of_birth, address, and ssn or ein) are required on every borrower — see the full example above.

​
Reading the response

The response is 207, and every borrower you sent has an entry in results, in the order you sent them. Check each outcome rather than relying on the status code — one bad record never blocks the rest of the batch.
already_enrolled is no longer returned. It stays in the response as a count that is always 0 so that an integration parsing the old shape keeps working — a re-sent borrower is reported updated instead.

​
Held borrowers

A held borrower’s details are kept. Monitoring simply did not start, because Rightfoot cannot reach their bank.

​
Failed borrowers

chunk_failed and monitor_open_failed are both safe to retry — re-sending a borrower who did enroll returns updated and re-applies the same amount, rather than creating anything twice.

Authorizations

​
Authorization
string
header
required

Authentication to the API is performed via Bearer Token Authentication. Provide your API key as the bearer token in the Authorization header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Body

application/json
​
borrowers
object[]
required

The borrowers to enroll. Up to 1000 per request.

Required array length: 1 - 1000 elements

One borrower to enroll. The identity and bank account fields match the Authorizer schema used by the balance endpoints, so an existing integration can reuse the same serialization.

Response

Batch processed. Every borrower in the request has an entry in results; inspect each outcome rather than relying on the status code.

Counts plus one result per borrower, in the order you sent them.

​
enrolled
integer

Borrowers now stored, with monitoring newly started.

​
updated
integer

Borrowers who were already being monitored. Their details were refreshed and the amount in this request applied to their existing monitor.

​
already_enrolled
integer

Always 0. Kept so the response shape stays stable for integrations parsing it; a re-sent borrower is reported under updated instead.

​
held
integer

Borrowers stored but not monitored.

​
failed
integer

Borrowers whose details from this request were not stored.

​
results
object[]