> ## 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 (CSV) > Download balance results for one or more batches as a CSV file # 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](/api-reference/stable/get-balances). 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. ```bash cURL theme={null} 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 ``` ```python Python theme={null} 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 ``` ```javascript JavaScript theme={null} 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-.csv"`. The CSV contains a header row followed by one row per balance result. The first nine columns are fixed; additional `meta_` 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_` | One column per metadata key set on any authorizer in the result. | ### Example response ```csv theme={null} 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 1. **Stream to disk** - CSV exports can be large; use `-o` (cURL) or stream the response body rather than buffering it in memory 2. **Match by `Authorizer ID`** - Pair rows back to your records using the `Authorizer ID` column, which mirrors the `authorizer_unique_id` you submitted 3. **Check `Status` per row** - An empty `Balance` paired with a non-`SUCCESS` `Status` indicates the balance check failed for that authorizer ## OpenAPI ````yaml GET /v1/balances/csv 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/csv: get: tags: - General Availability summary: Retrieve Balance Results (CSV) description: > Download balance results for one or more batches as a CSV file. Returns the same columns produced by the Bigfoot dashboard download in addition to the core fields returned by `GET /v1/balances`. operationId: get_balances_csv parameters: - in: query name: batch_ids required: true schema: type: array items: type: string format: uuid style: form explode: true description: >- One or more batch IDs to export. Repeat the parameter to fetch multiple batches in a single CSV (`?batch_ids=&batch_ids=`). All batches must belong to the authenticated requester. responses: '200': description: CSV file containing one row per balance result. headers: Content-Disposition: schema: type: string description: >- Attachment header, e.g. `attachment; filename="batch-export-.csv"`. content: text/csv: schema: type: string example: > 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, '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Forbidden — one or more requested batches don't belong to the authenticated requester. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '500': $ref: '#/components/responses/InternalServerError' components: 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 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 schemas: 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 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. ````