On Demand Balance Checks
Submit Balance Check
Submit a batch of authorizers for balance checks
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"
}
'import requests
url = "https://api.rightfoot.com/v1/balance_requests"
payload = {
"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"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};
fetch('https://api.rightfoot.com/v1/balance_requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rightfoot.com/v1/balance_requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rightfoot.com/v1/balance_requests"
payload := strings.NewReader("{\n \"authorizers\": [\n {\n \"authorizer_unique_id\": \"1a2b3c4d\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"street_address_line1\": \"123 Main St\",\n \"city\": \"Anytown\",\n \"state\": \"CA\",\n \"zip_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"5551234567\",\n \"date_of_birth\": {\n \"day\": 1,\n \"month\": 1,\n \"year\": 1980\n },\n \"ssn\": \"123456789\",\n \"ein\": \"987654321\",\n \"account_number\": \"1234567890\",\n \"routing_number\": \"021000021\"\n }\n ],\n \"webhook_url\": \"https://api.example.com/webhook/balance-batch-complete\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rightfoot.com/v1/balance_requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"authorizers\": [\n {\n \"authorizer_unique_id\": \"1a2b3c4d\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"street_address_line1\": \"123 Main St\",\n \"city\": \"Anytown\",\n \"state\": \"CA\",\n \"zip_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"5551234567\",\n \"date_of_birth\": {\n \"day\": 1,\n \"month\": 1,\n \"year\": 1980\n },\n \"ssn\": \"123456789\",\n \"ein\": \"987654321\",\n \"account_number\": \"1234567890\",\n \"routing_number\": \"021000021\"\n }\n ],\n \"webhook_url\": \"https://api.example.com/webhook/balance-batch-complete\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rightfoot.com/v1/balance_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"authorizers\": [\n {\n \"authorizer_unique_id\": \"1a2b3c4d\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"street_address_line1\": \"123 Main St\",\n \"city\": \"Anytown\",\n \"state\": \"CA\",\n \"zip_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"5551234567\",\n \"date_of_birth\": {\n \"day\": 1,\n \"month\": 1,\n \"year\": 1980\n },\n \"ssn\": \"123456789\",\n \"ein\": \"987654321\",\n \"account_number\": \"1234567890\",\n \"routing_number\": \"021000021\"\n }\n ],\n \"webhook_url\": \"https://api.example.com/webhook/balance-batch-complete\"\n}"
response = http.request(request)
puts response.read_body{
"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)."
}
]
}{
"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"
}{
"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"
}{
"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"
}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 eitherssnorein
Debit Card Information
- Required:
debit_card_number,cvv,expiration_year,expiration_month, and eitherssnorein - Optional:
routing_number(if linked to a bank account) - Note: Debit card balance checks require prior approval
Authorizations
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
Maximum array length:
1000Payment details using a bank account. Requires account number, routing number, and either SSN or EIN.
- Bank Account Information
- Debit Card Information
Show child attributes
Show child attributes
Optional. Provide a webhook URL to receive notification when the batch is complete.
Response
Created
Unique identifier for the submitted batch.
Timestamp indicating when the batch was submitted.
Confirmation message or additional information.
List of authorizers that failed validation or processing.
Show child attributes
Show child attributes
Non-fatal warnings raised while parsing the input (e.g., non-UTF-8 CSV files decoded as Latin-1). Only set for CSV uploads.
Was this page helpful?
⌘I
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"
}
'import requests
url = "https://api.rightfoot.com/v1/balance_requests"
payload = {
"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"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
})
};
fetch('https://api.rightfoot.com/v1/balance_requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rightfoot.com/v1/balance_requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rightfoot.com/v1/balance_requests"
payload := strings.NewReader("{\n \"authorizers\": [\n {\n \"authorizer_unique_id\": \"1a2b3c4d\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"street_address_line1\": \"123 Main St\",\n \"city\": \"Anytown\",\n \"state\": \"CA\",\n \"zip_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"5551234567\",\n \"date_of_birth\": {\n \"day\": 1,\n \"month\": 1,\n \"year\": 1980\n },\n \"ssn\": \"123456789\",\n \"ein\": \"987654321\",\n \"account_number\": \"1234567890\",\n \"routing_number\": \"021000021\"\n }\n ],\n \"webhook_url\": \"https://api.example.com/webhook/balance-batch-complete\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rightfoot.com/v1/balance_requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"authorizers\": [\n {\n \"authorizer_unique_id\": \"1a2b3c4d\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"street_address_line1\": \"123 Main St\",\n \"city\": \"Anytown\",\n \"state\": \"CA\",\n \"zip_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"5551234567\",\n \"date_of_birth\": {\n \"day\": 1,\n \"month\": 1,\n \"year\": 1980\n },\n \"ssn\": \"123456789\",\n \"ein\": \"987654321\",\n \"account_number\": \"1234567890\",\n \"routing_number\": \"021000021\"\n }\n ],\n \"webhook_url\": \"https://api.example.com/webhook/balance-batch-complete\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rightfoot.com/v1/balance_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"authorizers\": [\n {\n \"authorizer_unique_id\": \"1a2b3c4d\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"street_address_line1\": \"123 Main St\",\n \"city\": \"Anytown\",\n \"state\": \"CA\",\n \"zip_code\": \"12345\",\n \"country\": \"US\"\n },\n \"phone_number\": \"5551234567\",\n \"date_of_birth\": {\n \"day\": 1,\n \"month\": 1,\n \"year\": 1980\n },\n \"ssn\": \"123456789\",\n \"ein\": \"987654321\",\n \"account_number\": \"1234567890\",\n \"routing_number\": \"021000021\"\n }\n ],\n \"webhook_url\": \"https://api.example.com/webhook/balance-batch-complete\"\n}"
response = http.request(request)
puts response.read_body{
"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)."
}
]
}{
"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"
}{
"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"
}{
"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"
}