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. For each borrower, send either a single collectable_amount or a list of obligations — for example, each past-due installment of a loan — that Rightfoot collects separately from the same bank account. 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.

​
Collecting several obligations separately

Some borrowers owe more than one amount at once — say two past-due installments of $100, one that was already presented and returned and one coming due. Instead of a single collectable_amount, send each as an obligation, and Rightfoot monitors and collects each one on its own. Send exactly one of collectable_amount or obligations for a borrower. A borrower with both or neither, or with two obligations sharing an id, fails validation, and the whole request is rejected with a 400.

​
How obligations are collected

  • One balance check covers them all. Every obligation draws on the same bank account, so Rightfoot reads the balance once and decides every obligation from that reading.
  • In priority order, until the balance runs out. An obligation is collected when the balance covers it, everything ahead of it, and your reserve. With a $100 reserve, a $500 balance collects both $100 installments above; a $250 balance collects only loan-123:inst-2.
  • Each obligation is collected whole, as its own payment. An obligation is never split to fit the balance or combined with another, so a returned payment is always re-presented at its original amount. If one does not fit, a smaller one behind it can still be collected.
  • One payment at a time per account. While a payment for any of the borrower’s obligations is still at the bank, nothing new is collected for that borrower. Obligations decided together from the same balance check go out together.
  • Retries are counted per obligation. Each obligation that comes back returned is retried within NACHA’s limit for that payment, independently of the others.

​
The push carries the full set

Each push replaces the borrower’s obligations:
  • An obligation you send again is updated in place — its amount, priority and metadata are refreshed, and it keeps its retry history.
  • An obligation left out of the push stops being collected. This is how you take an installment back — for example on the day you re-present it yourself.
  • Switching a borrower between collectable_amount and obligations replaces one with the other; Rightfoot never collects both.
To stop one obligation without sending the whole borrower, see Remove Borrowers from Monitoring.
An obligation left out of a push and sent again in a later one is collected again. Keep an obligation out of your file for as long as Rightfoot should not collect it.

​
Per-borrower policy overrides

Your collection policy decides when a balance is high enough to collect: the reserve that must stay in the account after a payment, and the minimum payment Rightfoot submits. policy_overrides changes either for one borrower; anything you leave out follows your policy.
Unknown fields are rejected rather than ignored, so a misspelling cannot quietly loosen a rule. The overrides are replaced on every push: send them each time, or the borrower returns to your policy.

​
How Rightfoot collects

Omit charge_instrument entirely and Rightfoot collects by ACH from the bank account you supplied. That is the common case.
If collection runs through your own Stripe account, charge_instrument is required on every borrower. Rightfoot charges the payment method you name; there is no fallback to the bank account, since that account is read for its balance rather than debited.
To have something else charged instead, supply exactly one of:

token

A token held by your payment processor, for a card or a bank account. Preferred — the card or bank details behind it stay with your processor. The token on its own is enough.

card

Raw card details, stored securely by Rightfoot. Use this only when you cannot produce a processor token.
token_type is optional but worth sending. Processors issue one token format for both kinds — Stripe uses pm_ for cards and bank accounts alike — so Rightfoot cannot tell from the value which it holds. Omitting it records the kind as unknown; Rightfoot does not guess one.
Raw card details take no token_type or last4: Rightfoot derives the last four from the number it stores, so it describes the card actually held. Sending either alongside card is rejected. The routing and account number stay required whichever instrument collects — they are what Rightfoot reads the balance from. 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.

​
Results for obligations

A borrower sent with obligations also carries an obligations array in their result, one entry per obligation in the order you sent them, each with its own outcome, reason and message. The borrower’s own outcome sums them up:
  • enrolled if any obligation started being collected,
  • otherwise updated if any was applied to monitoring already running,
  • otherwise held, with the first obligation’s reason.
So a borrower can be enrolled while one of their obligations is held — for example an installment below your minimum payment. Read the obligation results to see which.
A borrower sent with collectable_amount has no obligations in their result.

​
Held borrowers

A held borrower’s details are kept. Monitoring did not start, for the reason given. With obligations, the same reasons apply to each obligation.

​
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[]