Skip to main content
POST
/
v1
/
balance_requests
Submit a batch of authorizers for balance checks
curl --request POST \
  --url https://api.rightfoot.com/v1/balance_requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "authorizers": [
    {
      "authorizer_unique_id": "1a2b3c4d",
      "first_name": "John",
      "last_name": "Doe",
      "address": {
        "street_address_line1": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip_code": "12345",
        "country": "US"
      },
      "phone_number": "5551234567",
      "date_of_birth": {
        "day": 1,
        "month": 1,
        "year": 1980
      },
      "ssn": "123456789",
      "ein": "987654321",
      "account_number": "1234567890",
      "routing_number": "021000021"
    }
  ],
  "webhook_url": "https://api.example.com/webhook/balance-batch-complete"
}
'
{
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83",
  "submitted_at": "2024-09-17T10:00:00Z",
  "message": "Batch has been successfully submitted and is pending processing.",
  "failed_authorizers": [
    {
      "authorizer_unique_id": "5e6f7g8h",
      "error": "Invalid routing number for authorizer(s). Routing number must be 9 digits long."
    },
    {
      "authorizer_unique_id": "9i0j1k2l",
      "error": "Missing date of birth for authorizer(s)."
    }
  ]
}

​
Submit Balance Check

Submit a batch of authorizers for balance checks. This endpoint allows you to submit up to 1,000 authorizers in a single request to retrieve their current account balances.
Debit Card Information: Balance requests using debit card information is currently restricted to approved customers only. If you would like to learn more, please reach out to us at sales@rightfoot.com.

​
Key Information

Batch Size Limit: Maximum 1,000 authorizers per request
Idempotency: Requests are cached for 24 hours based on the request body hash. Submitting an identical batch within this period will return the same response without reprocessing

​
Important Notes

We ask that you schedule the API call with sufficient time prior to ACH cut-offs to retrieve the balance results and omit authorizers with insufficient balances for the loan payment.

​
Payment Information Types

You must provide either bank account information or debit card information (approved customers only):

​
Bank Account Information

  • Required: account_number, routing_number, and either ssn or ein

​
Debit Card Information

  • Required: debit_card_number, cvv, expiration_year, expiration_month, and either ssn or ein
  • Optional: routing_number (if linked to a bank account)
  • Note: Debit card balance checks require prior approval

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
​
authorizers
(Bank Account Information · object | Debit Card Information · object)[]
required
Maximum array length: 1000

Payment details using a bank account. Requires account number, routing number, and either SSN or EIN.

​
webhook_url
string<uri>

Optional. Provide a webhook URL to receive notification when the batch is complete.

Response

Created

​
batch_id
string
required

Unique identifier for the submitted batch.

​
submitted_at
string<date-time>
required

Timestamp indicating when the batch was submitted.

​
message
string
required

Confirmation message or additional information.

​
failed_authorizers
object[]

List of authorizers that failed validation or processing.

​
warnings
string[]

Non-fatal warnings raised while parsing the input (e.g., non-UTF-8 CSV files decoded as Latin-1). Only set for CSV uploads.