> ## 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.
# Retrieve Balance Results
> Retrieve processed balances for a batch
# 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:
```python Python theme={null}
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
```
```javascript JavaScript theme={null}
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
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)
## OpenAPI
````yaml GET /v1/balances
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/balances:
get:
tags:
- General Availability
summary: Retrieve processed balances for a batch
operationId: get_balances
parameters:
- in: query
name: batchId
required: true
schema:
type: string
description: The ID of the batch to retrieve balances for
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of balances to return per page. Maximum is 100.
- in: query
name: nextPageToken
schema:
type: string
description: >-
A token to use as the cursor. Retrieves balances starting after this
token.
responses:
'200':
description: Balances retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BatchBalancesResponse'
example:
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
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
BatchBalancesResponse:
type: object
properties:
batch_id:
type: string
description: Unique identifier of the batch.
total_processed:
type: integer
description: Total number of authorizers processed in the batch.
balances:
type: array
description: List of balance records for each authorizer.
items:
$ref: '#/components/schemas/BalanceRecord'
has_more:
type: boolean
description: Indicates if more records are available after this page.
next_page_token:
type: string
description: Token to pass into the next request to fetch more balances.
example:
batch_id: batch_12345ABCDE
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
BalanceRecord:
type: object
properties:
authorizer_unique_id:
type: string
description: Unique identifier for the authorizer.
balance:
type: number
format: float
nullable: true
description: The balance amount. `null` if the balance couldn't be retrieved.
balance_status_code:
$ref: '#/components/schemas/RequestStatusCode'
status_code:
$ref: '#/components/schemas/RequestStatusCode'
deprecated: true
description: >-
Deprecated in favor of `balance_status_code` to avoid confusion with
HTTP status codes.
timestamp:
type: string
format: date-time
description: Timestamp of when the balance was retrieved.
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
RequestStatusCode:
type: integer
enum:
- 0
- 3000
- 3100
- 3200
- 3300
- 3310
- 3400
- 9000
description: |
Status code representing the outcome of the request.
| Code | Description |
|-------|---------------------------------------------------|
| 0 | Success. |
| 3000 | No tax ID 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. |
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
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
Unauthorized:
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.
documentation_url: https://api.rightfoot.com/docs
NotFound:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
example:
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
InternalServerError:
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 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
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.
````