GET

balances

Retrieve processed balances for a batch

curl --request GET \
  --url https://api.rightfoot.com/v1/balances \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.rightfoot.com/v1/balances', 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/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rightfoot.com/v1/balances"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.rightfoot.com/v1/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83",
  "total_processed": 3,
  "balances": [
    {
      "authorizer_unique_id": "1286672",
      "balance": -83.68,
      "timestamp": "2024-08-09T18:10:44Z",
      "balance_status_code": 0,
      "status_code": 0
    },
    {
      "authorizer_unique_id": "1258580",
      "balance": 3851.09,
      "timestamp": "2024-08-09T17:51:34Z",
      "balance_status_code": 0,
      "status_code": 0
    },
    {
      "authorizer_unique_id": "1258831",
      "balance": null,
      "timestamp": "2024-08-09T17:55:25Z",
      "balance_status_code": 3300,
      "status_code": 3300
    }
  ],
  "has_more": true,
  "next_page_token": "eyJ0ZXN0IjogImN1cnNvciJ9"
}

{
  "status": "error",
  "status_code": 400,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Batch ID was not provided in the request.",
    "timestamp": "2024-09-16T12:00:00Z",
    "suggestion": "Please provide a valid batch ID in the request URL."
  },
  "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."
  },
  "documentation_url": "https://api.rightfoot.com/docs"
}

{
  "status": "error",
  "status_code": 404,
  "error": {
    "code": "NOT_FOUND",
    "message": "The specified batch ID does not exist.",
    "timestamp": "2024-09-16T12:09:00Z",
    "suggestion": "Please check the batch ID."
  },
  "documentation_url": "https://api.rightfoot.com/docs"
}

{
  "status": "error",
  "status_code": 500,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred while retrieving the balances.",
    "timestamp": "2024-09-16T12:11:00Z",
    "suggestion": "Please try again later. If the problem persists, contact our support team."
  },
  "documentation_url": "https://api.rightfoot.com/docs"
}

Retrieve Balance Results

Retrieve processed balance results for a previously submitted batch. This endpoint supports pagination to handle large result sets efficiently.

Balance Status Codes

The balance_status_code field indicates the outcome of the balance check:

Code	Description
`0`	Success - Balance retrieved successfully
`3000`	No tax ID match
`3001`	No SSN match
`3100`	No date of birth match
`3200`	Account closed
`3300`	Institution not supported
`3310`	Institution currently in testing
`3400`	No match with provided authorizer information
`9000`	Other error

A null balance with a non-zero status code indicates that the balance check failed for the specified reason.

Pagination

For batches with more results than the specified limit, use pagination:

import requests

def get_all_balances(batch_id, api_key):
    balances = []
    next_page_token = None
    
    while True:
        url = f"https://api.rightfoot.com/v1/balances?batchId={batch_id}&limit=100"
        if next_page_token:
            url += f"&next_page_token={next_page_token}"
        
        headers = {"Authorization": f"Bearer {api_key}"}
        response = requests.get(url, headers=headers)
        data = response.json()
        
        balances.extend(data['balances'])
        
        if not data['has_more']:
            break
            
        next_page_token = data['next_page_token']
    
    return balances

async function getAllBalances(batchId, apiKey) {
  let balances = [];
  let nextPageToken = null;
  
  while (true) {
    let url = `https://api.rightfoot.com/v1/balances?batchId=${batchId}&limit=100`;
    if (nextPageToken) {
      url += `&nextPageToken=${nextPageToken}`;
    }
    
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    const data = await response.json();
    balances = balances.concat(data.balances);
    
    if (!data.has_more) {
      break;
    }
    
    nextPageToken = data.next_page_token;
  }
  
  return balances;
}

Best Practices

Poll periodically - If processing is not complete, poll every 30-60 seconds
Handle pagination - Always check has_more and use next_page_token for complete results
Process status codes - Check balance_status_code to understand failed balance checks
Implement retries - Add exponential backoff for transient errors (5xx status codes)

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.

Query Parameters

batchId

string

required

The ID of the batch to retrieve balances for

limit

integer

default:100

The number of balances to return per page. Maximum is 100.

Required range: 1 <= x <= 100

nextPageToken

string

A token to use as the cursor. Retrieves balances starting after this token.

Response

Balances retrieved successfully

batch_id

string

Unique identifier of the batch.

total_processed

integer

Total number of authorizers processed in the batch.

balances

object[]

List of balance records for each authorizer.

Show child attributes

has_more

boolean

Indicates if more records are available after this page.

next_page_token

string

Token to pass into the next request to fetch more balances.

⌘I

Retrieve processed balances for a batch

curl --request GET \
  --url https://api.rightfoot.com/v1/balances \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.rightfoot.com/v1/balances', 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/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rightfoot.com/v1/balances"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.rightfoot.com/v1/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83",
  "total_processed": 3,
  "balances": [
    {
      "authorizer_unique_id": "1286672",
      "balance": -83.68,
      "timestamp": "2024-08-09T18:10:44Z",
      "balance_status_code": 0,
      "status_code": 0
    },
    {
      "authorizer_unique_id": "1258580",
      "balance": 3851.09,
      "timestamp": "2024-08-09T17:51:34Z",
      "balance_status_code": 0,
      "status_code": 0
    },
    {
      "authorizer_unique_id": "1258831",
      "balance": null,
      "timestamp": "2024-08-09T17:55:25Z",
      "balance_status_code": 3300,
      "status_code": 3300
    }
  ],
  "has_more": true,
  "next_page_token": "eyJ0ZXN0IjogImN1cnNvciJ9"
}

{
  "status": "error",
  "status_code": 400,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Batch ID was not provided in the request.",
    "timestamp": "2024-09-16T12:00:00Z",
    "suggestion": "Please provide a valid batch ID in the request URL."
  },
  "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."
  },
  "documentation_url": "https://api.rightfoot.com/docs"
}

{
  "status": "error",
  "status_code": 404,
  "error": {
    "code": "NOT_FOUND",
    "message": "The specified batch ID does not exist.",
    "timestamp": "2024-09-16T12:09:00Z",
    "suggestion": "Please check the batch ID."
  },
  "documentation_url": "https://api.rightfoot.com/docs"
}

{
  "status": "error",
  "status_code": 500,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred while retrieving the balances.",
    "timestamp": "2024-09-16T12:11:00Z",
    "suggestion": "Please try again later. If the problem persists, contact our support team."
  },
  "documentation_url": "https://api.rightfoot.com/docs"
}

Getting Started

On Demand Balance Checks

Monitoring

Webhooks

Retrieve Balance Results

Retrieve Balance Results

Balance Status Codes

Best Practices

Authorizations

Query Parameters

Response

​Retrieve Balance Results

​Balance Status Codes

​Pagination

​Best Practices

Authorizations

Query Parameters

Response

Retrieve Balance Results

Balance Status Codes

Pagination

Best Practices