> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rightfoot.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit Balance Check
> Submit a batch of authorizers for balance checks
# 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](mailto: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
## OpenAPI
````yaml POST /v1/balance_requests
openapi: 3.1.0
info:
title: Rightfoot API
description: >-
Submit a batch of authorizers for balance checks, retrieve processed
balances, and check the status of a batch.
version: 0.3.0-alpha
servers:
- url: https://api.rightfoot.com
security:
- BearerAuth: []
tags:
- name: General Availability
description: |
**General Availability** indicates that the endpoint is production-ready.
- name: Early Access
description: >
**Early Access** indicates that the endpoint is available for early access
customers and is being actively refined.
- name: In Development
description: >
**In Development** indicates that the endpoint is currently being built
and will be available in an upcoming release.
paths:
/v1/balance_requests:
post:
tags:
- General Availability
summary: Submit a batch of authorizers for balance checks
description: >
**Note:** 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.
**Batch Size Limit:** The maximum batch size is 1,000 authorizers per
request.
**SLA:** 1 hour
**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.
**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 danielle@rightfoot.com or
tristan@rightfoot.com.
operationId: submit_balance_request
requestBody:
content:
application/json:
schema:
type: object
properties:
authorizers:
type: array
maxItems: 1000
items:
$ref: '#/components/schemas/Authorizer'
webhook_url:
type: string
format: uri
description: >-
Optional. Provide a webhook URL to receive notification when
the batch is complete.
required:
- authorizers
example:
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
responses:
'201':
description: Created
headers:
Location:
schema:
type: string
description: URL of the created batch resource
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCreatedResponse'
example:
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).
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
status: error
status_code: 400
error:
code: BAD_REQUEST
message: >-
Invalid batch size. The maximum batch size is 1,000
authorizers per request.
timestamp: '2024-09-16T12:00:00Z'
suggestion: >-
Please reduce the number of authorizers in your batch and
try again.
batch_id: null
documentation_url: https://api.rightfoot.com/docs
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
status: error
status_code: 401
error:
code: UNAUTHORIZED
message: Invalid API key provided.
timestamp: '2024-09-16T12:01:00Z'
suggestion: Please check your API key.
batch_id: null
documentation_url: https://api.rightfoot.com/docs
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
status: error
status_code: 500
error:
code: INTERNAL_SERVER_ERROR
message: An unexpected error occurred while processing your request.
timestamp: '2024-09-16T12:06:00Z'
suggestion: >-
Please try again later. If the problem persists, contact our
support team.
batch_id: null
documentation_url: https://api.rightfoot.com/docs
components:
schemas:
Authorizer:
type: object
required:
- authorizer_unique_id
- address
- phone_number
- date_of_birth
properties:
authorizer_unique_id:
type: string
description: Alphanumeric unique ID for an authorizer, provided by the lender.
first_name:
type: string
description: The authorizer's first name.
last_name:
type: string
description: The authorizer's last name.
address:
type: object
required:
- zip_code
properties:
street_address_line1:
type: string
description: Address line 1 (e.g., street, PO Box, or company name).
street_address_line2:
type: string
description: Address line 2 (e.g., apartment, suite, unit, or building).
city:
type: string
description: City, district, suburb, town, or village.
state:
type: string
description: State, county, province, or region.
zip_code:
type: string
description: >-
ZIP or postal code. Must be 5 digits or in 5+4 format (e.g.,
94107 or 94107-1234).
pattern: ^\d{5}(?:-\d{4})?$
country:
type: string
description: Two-letter country code.
phone_number:
type: string
description: The authorizer's phone number
date_of_birth:
type: object
description: Object containing day, month, and year of birth
required:
- day
- month
- year
properties:
day:
type: integer
description: The day of birth, between 1 and 31.
month:
type: integer
description: The month of birth, between 1 and 12.
year:
type: integer
description: The four-digit year of birth.
ssn:
type: string
description: The authorizer's Social Security Number, in string form
ein:
type: string
description: The authorizer's Employer Identification Number, in string form
anyOf:
- title: Bank Account Information
description: >-
Payment details using a bank account. Requires account number,
routing number, and either SSN or EIN.
type: object
properties:
account_number:
type: string
description: The account number for the bank account, in string form.
routing_number:
type: string
pattern: ^\\d{9}$
description: The routing number for the bank account.
ssn:
type: string
description: Either SSN or EIN is required.
ein:
type: string
description: Either SSN or EIN is required.
required:
- account_number
- routing_number
- title: Debit Card Information
description: >-
Payment details using a debit card. Requires debit card number, cvv,
expiration, and either SSN or EIN. Routing number is optional.
Account number is not applicable and will not appear.
type: object
properties:
debit_card_number:
type: string
description: A sixteen digit debit card number.
pattern: ^\\d{16}$
cvv:
type: string
description: 3 or 4 digit CVV for the debit card.
pattern: ^\\d{3,4}$
expiration_year:
type: integer
description: Four-digit expiration year of the debit card.
expiration_month:
type: integer
description: Expiration month of the debit card (1-12).
minimum: 1
maximum: 12
routing_number:
type: string
pattern: ^\\d{9}$
description: >-
(Optional) The routing number for the bank account, if debit
card is linked to one.
ssn:
type: string
description: Either SSN or EIN is required.
ein:
type: string
description: Either SSN or EIN is required.
required:
- debit_card_number
BatchCreatedResponse:
type: object
required:
- batch_id
- submitted_at
- message
properties:
batch_id:
type: string
description: Unique identifier for the submitted batch.
submitted_at:
type: string
format: date-time
description: Timestamp indicating when the batch was submitted.
message:
type: string
description: Confirmation message or additional information.
failed_authorizers:
type: array
description: List of authorizers that failed validation or processing.
items:
type: object
properties:
authorizer_unique_id:
type: string
description: Unique identifier for the authorizer that failed.
error:
$ref: '#/components/schemas/AuthorizerValidationError'
account_type:
type: string
description: >-
The payment information type for the failed row (e.g.,
`ACCOUNT_NUMBER`, `DEBIT_CARD`).
row_number:
type: integer
description: >-
1-indexed source row number from the uploaded CSV (header is
row 1, first data row is row 2). Only set for CSV uploads.
warnings:
type: array
description: >-
Non-fatal warnings raised while parsing the input (e.g., non-UTF-8
CSV files decoded as Latin-1). Only set for CSV uploads.
items:
type: string
ApiErrorResponse:
type: object
properties:
status:
type: string
description: Status of the error, either "error" or "success"
status_code:
type: integer
description: HTTP status code of the error
error:
type: object
properties:
code:
type: string
description: Error code (e.g., "RESOURCE_NOT_FOUND")
message:
type: string
description: Detailed error message.
details:
type: string
description: Additional details about the error
timestamp:
type: string
format: date-time
description: Time the error occurred
suggestion:
type: string
description: Suggested action to resolve the error
documentation_url:
type: string
format: uri
description: URL to the documentation for the error
AuthorizerValidationError:
type: string
enum:
- Missing authorizer unique ID for authorizer(s).
- Missing zip code for authorizer(s).
- >-
Invalid ZIP code for authorizer(s). Must be 5 digits or in 5+4 format
(e.g., 94107 or 94107-1234).
- Missing day of birth for authorizer(s).
- Missing month of birth for authorizer(s).
- Missing year of birth for authorizer(s).
- >-
Invalid phone number for authorizer(s). Phone number must be 10 digits
long without dashes and parentheses.
- Missing phone number for authorizer(s).
- Missing date of birth for authorizer(s).
- SSN must be of type string for authorizer(s).
- Invalid SSN for authorizer(s).
- EIN must be of type string for authorizer(s).
- Invalid EIN for authorizer(s).
- Number must be of type string for authorizer(s).
- Missing Account Number or Debit Card Number for authorizer(s).
- Account number must be of type string for authorizer(s).
- Debit card number must be of type string for authorizer(s).
- Invalid debit card number for authorizer(s). Must be 16 digits.
- CVV must be of type string for authorizer(s).
- Invalid CVV for authorizer(s). Must be 3 or 4 digits.
- Invalid expiration month for authorizer(s). Must be between 1 and 12.
- Invalid expiration year for authorizer(s). Must be 4 digits.
- >-
Invalid routing number for authorizer(s). Routing number must be 9
digits long.
- Missing routing number for authorizer(s).
- Missing SSN or EIN for authorizer(s).
- >-
Provide either Account Number or Debit Card Number for authorizer(s),
not both.
- Duplicate authorizer unique ID not allowed.
description: >
Validation error messages for authorizer data submitted in balance
requests.
| Error | Description |
|-------|-------------|
| Missing authorizer unique ID for authorizer(s). | The
authorizer_unique_id field was not provided. |
| Missing zip code for authorizer(s). | ZIP code is required for certain
institutions (e.g., Discover). |
| Invalid ZIP code for authorizer(s). Must be 5 digits or in 5+4 format
(e.g., 94107 or 94107-1234). | ZIP code format is invalid. |
| Missing day of birth for authorizer(s). | The day field in
date_of_birth was not provided. |
| Missing month of birth for authorizer(s). | The month field in
date_of_birth was not provided. |
| Missing year of birth for authorizer(s). | The year field in
date_of_birth was not provided. |
| Invalid phone number for authorizer(s). Phone number must be 10 digits
long without dashes and parentheses. | Phone number format is invalid. |
| Missing phone number for authorizer(s). | The phone_number field was
not provided. |
| Missing date of birth for authorizer(s). | The date_of_birth object
was not provided. |
| SSN must be of type string for authorizer(s). | SSN was provided as a
non-string type. |
| Invalid SSN for authorizer(s). | SSN format is invalid. Must be 9
digits or XXX-XX-XXXX format. |
| EIN must be of type string for authorizer(s). | EIN was provided as a
non-string type. |
| Invalid EIN for authorizer(s). | EIN format is invalid. Must be 9-10
digits or XX-XXXXXXX format. |
| Number must be of type string for authorizer(s). | Card number was
provided as a non-string type. |
| Missing Account Number or Debit Card Number for authorizer(s). |
Neither account_number nor debit_card_number was provided. |
| Account number must be of type string for authorizer(s). | Account
number was provided as a non-string type. |
| Debit card number must be of type string for authorizer(s). | Debit
card number was provided as a non-string type. |
| Invalid debit card number for authorizer(s). Must be 16 digits. |
Debit card number format is invalid. |
| CVV must be of type string for authorizer(s). | CVV was provided as a
non-string type. |
| Invalid CVV for authorizer(s). Must be 3 or 4 digits. | CVV format is
invalid. |
| Invalid expiration month for authorizer(s). Must be between 1 and 12.
| Expiration month is out of range. |
| Invalid expiration year for authorizer(s). Must be 4 digits. |
Expiration year format is invalid. |
| Invalid routing number for authorizer(s). Routing number must be 9
digits long. | Routing number format is invalid. |
| Missing routing number for authorizer(s). | Routing number is required
when using account_number. |
| Missing SSN or EIN for authorizer(s). | Neither SSN nor EIN was
provided. |
| Provide either Account Number or Debit Card Number for authorizer(s),
not both. | Both account_number and debit_card_number were provided. |
| Duplicate authorizer unique ID not allowed. | The same
authorizer_unique_id appears multiple times in the batch. |
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >
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.
````