Skip to main content
GET
/
v1
/
balances
Retrieve processed balances for a batch
curl --request GET \
  --url https://api.rightfoot.com/v1/balances \
  --header 'Authorization: Bearer <token>'
{
  "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"
}

​
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:
CodeDescription
0Success - Balance retrieved successfully
3000No tax ID match
3001No SSN match
3100No date of birth match
3200Account closed
3300Institution not supported
3310Institution currently in testing
3400No match with provided authorizer information
9000Other 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"&nextPageToken={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

​
Best Practices

  1. Poll periodically - If processing is not complete, poll every 30-60 seconds
  2. Handle pagination - Always check has_more and use next_page_token for complete results
  3. Process status codes - Check balance_status_code to understand failed balance checks
  4. 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.

​
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.