GET

balances

csv

Retrieve Balance Results (CSV)

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

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

fetch('https://api.rightfoot.com/v1/balances/csv', 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/csv",
  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/csv"

	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/csv")

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

"Authorizer ID,Batch ID,Institution,Phone,Zip,Balance,Status,Creator,Timestamp,meta_customer_ref\nauthz-001,8ac1f4a6-1234-4abc-9d3e-001122334455,Bank of America,+15551234567,10001,2843.51,SUCCESS,jane.doe@acme.com,2026-05-17T19:24:12+00:00,CR-9981\nauthz-002,8ac1f4a6-1234-4abc-9d3e-001122334455,Wells Fargo,,90210,,NO_MATCH,,2026-05-17T19:25:03+00:00,\n"

{
  "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": "<string>",
  "status_code": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "suggestion": "<string>"
  },
  "documentation_url": "<string>"
}

{
  "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 (CSV)

Download balance results for one or more batches as a CSV file. The CSV includes the same columns produced by the Bigfoot dashboard download (Institution, Phone, Zip, Creator) in addition to the core fields returned by Retrieve Balance Results.

This endpoint returns a richer field set than GET /v1/balances. Use it when you need the full dashboard-style export. For paginated JSON per row, use GET /v1/balances.

Multiple batches in a single export

Repeat the batch_ids query parameter to fetch multiple batches in one CSV. All batches must belong to the authenticated requester — if any do not, the request is rejected with 403 and no file is returned.

curl -X GET 'https://api.rightfoot.com/v1/balances/csv?batch_ids=8ac1f4a6-1234-4abc-9d3e-001122334455&batch_ids=12c4d6ee-aaaa-4abc-9d3e-bbbbccccdddd' \
  -H 'Authorization: Bearer rf_live_...' \
  -o balances.csv

import requests

def download_balances_csv(batch_ids, api_key, output_path="balances.csv"):
    url = "https://api.rightfoot.com/v1/balances/csv"
    params = [("batch_ids", bid) for bid in batch_ids]
    headers = {"Authorization": f"Bearer {api_key}"}

    with requests.get(url, params=params, headers=headers, stream=True) as response:
        response.raise_for_status()
        with open(output_path, "wb") as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)

    return output_path

import fs from "node:fs";

async function downloadBalancesCsv(batchIds, apiKey, outputPath = "balances.csv") {
  const params = new URLSearchParams();
  for (const id of batchIds) {
    params.append("batch_ids", id);
  }

  const response = await fetch(
    `https://api.rightfoot.com/v1/balances/csv?${params.toString()}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
  }

  const csv = await response.text();
  fs.writeFileSync(outputPath, csv);
  return outputPath;
}

Response

Returns text/csv; charset=utf-8 with Content-Disposition: attachment; filename="batch-export-<timestamp>.csv". The CSV contains a header row followed by one row per balance result. The first nine columns are fixed; additional meta_<key> columns are appended alphabetically when any authorizer in the result set has metadata.

Column	Description
`Authorizer ID`	Your authorizer’s unique identifier.
`Batch ID`	The batch this result belongs to.
`Institution`	Full name of the financial institution.
`Phone`	Authorizer phone number, if known.
`Zip`	Authorizer zip code, if known.
`Balance`	Account balance in USD (decimal). Empty when unavailable.
`Status`	One of `SUCCESS`, `NO_MATCH`, `ACCOUNT_CLOSED`, `BANK_UNSUPPORTED`, `RETRIEVAL_FAILED`, `RETRY_LIMIT`, `PROCESSING_ERROR`.
`Creator`	Display name of the dashboard user who submitted the request. Empty for API submissions.
`Timestamp`	ISO-8601 timestamp (UTC) when the result was recorded.
`meta_<key>`	One column per metadata key set on any authorizer in the result.

Example response

Authorizer ID,Batch ID,Institution,Phone,Zip,Balance,Status,Creator,Timestamp,meta_customer_ref
authz-001,8ac1f4a6-1234-4abc-9d3e-001122334455,Bank of America,+15551234567,10001,2843.51,SUCCESS,jane.doe@acme.com,2026-05-17T19:24:12+00:00,CR-9981
authz-002,8ac1f4a6-1234-4abc-9d3e-001122334455,Wells Fargo,,90210,,NO_MATCH,,2026-05-17T19:25:03+00:00,

Errors

Status	Cause
`400`	Missing `batch_ids` or one of the values is not a valid UUID.
`401`	Missing or invalid API key.
`403`	One or more requested batches don’t belong to the authenticated requester.
`500`	Internal server error.

Best Practices

Stream to disk - CSV exports can be large; use -o (cURL) or stream the response body rather than buffering it in memory
Match by Authorizer ID - Pair rows back to your records using the Authorizer ID column, which mirrors the authorizer_unique_id you submitted
Check Status per row - An empty Balance paired with a non-SUCCESS Status indicates the balance check failed for that authorizer

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

batch_ids

string<uuid>[]

required

One or more batch IDs to export. Repeat the parameter to fetch multiple batches in a single CSV (?batch_ids=<id1>&batch_ids=<id2>). All batches must belong to the authenticated requester.

Response

CSV file containing one row per balance result.

The response is of type string.

⌘I

Retrieve Balance Results (CSV)

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

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

fetch('https://api.rightfoot.com/v1/balances/csv', 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/csv",
  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/csv"

	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/csv")

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

"Authorizer ID,Batch ID,Institution,Phone,Zip,Balance,Status,Creator,Timestamp,meta_customer_ref\nauthz-001,8ac1f4a6-1234-4abc-9d3e-001122334455,Bank of America,+15551234567,10001,2843.51,SUCCESS,jane.doe@acme.com,2026-05-17T19:24:12+00:00,CR-9981\nauthz-002,8ac1f4a6-1234-4abc-9d3e-001122334455,Wells Fargo,,90210,,NO_MATCH,,2026-05-17T19:25:03+00:00,\n"

{
  "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": "<string>",
  "status_code": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "suggestion": "<string>"
  },
  "documentation_url": "<string>"
}

{
  "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 (CSV)

Retrieve Balance Results (CSV)

Multiple batches in a single export

Response

Example response

Errors

Best Practices

Authorizations

Query Parameters

Response

​Retrieve Balance Results (CSV)

​Multiple batches in a single export

​Response

​Example response

​Errors

​Best Practices

Authorizations

Query Parameters

Response

Retrieve Balance Results (CSV)

Multiple batches in a single export

Response

Example response

Errors

Best Practices