Skip to main content
POST
/
v1
/
balance_requests
/
csv
Submit a batch of authorizers via CSV upload
curl --request POST \
  --url https://api.rightfoot.com/v1/balance_requests/csv \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'
{
  "batch_id": "5d3c6bbb-fc1a-46a4-93da-1ce4a54b0d83",
  "submitted_at": "2024-09-17T10:00:00Z",
  "message": "Batch has been successfully submitted and is pending processing.",
  "failed_authorizers": [
    {
      "authorizer_unique_id": "5e6f7g8h",
      "error": "Invalid routing number for authorizer(s). Routing number must be 9 digits long.",
      "account_type": "ACCOUNT_NUMBER",
      "row_number": 4
    }
  ],
  "warnings": [
    "File was not UTF-8 encoded and was decoded using Latin-1. Some characters may appear incorrectly. For best results, save your CSV as UTF-8."
  ]
}

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.

​
Submit Balance Check (CSV)

Upload a CSV file of authorizers for balance checks. This endpoint is the file-upload counterpart to Submit Balance Check — use it when your authorizer list is already exported as a spreadsheet.
Debit Card Information: Balance requests using debit card information is currently restricted to approved customers only. If you would like to learn more, please reach out to us at sales@rightfoot.com.

​
Key Information

Batch Size Limit: Maximum 5,000 rows per CSV
Content-Type: multipart/form-data with the file part as text/csv
Encoding: UTF-8 preferred. Files exported from Excel on Windows are decoded as Latin-1 with a warnings entry on the response.
Validation: Per-row validation runs synchronously at request time. Failures are returned inline in the response.

​
CSV Format

The header row must use the column names below. Required and optional columns differ slightly depending on whether you submit bank-account or debit-card info — provide exactly one per row, never both.

​
Always Required (every row)

ColumnFormat
authorizer_unique_idAlphanumeric, must be unique within the CSV
phone_numberExactly 10 digits, no separators (e.g. 5551234567)
ssn or einAt least one. ssn: 9 digits or XXX-XX-XXXX. ein: 9–10 digits or XX-XXXXXXX.

​
Bank-Account Mode

Provide account_number:
ColumnRequired?Format
account_numberrequiredFree-form string
routing_numberrequired9 digits

​
Debit-Card Mode

Provide debit_card_number (approved customers only):
ColumnRequired?Format
debit_card_numberrequired16 digits
cvvoptional3–4 digits
expiration_monthoptionalInteger 1–12
expiration_yearoptional4 digits
routing_numberoptional9 digits
Submitting both account_number and debit_card_number on the same row is rejected. Pick one mode per row.

​
Always Optional (any row)

ColumnFormat
first_name, last_nameFree-form
street_address_line1, street_address_line2, city, state, countryFree-form
zip_code5 digits or ZZZZZ-NNNN. Required for Discover (routing number 031100649).
date_of_birthMM/DD/YYYY. If provided, all three components must be present and year must be ≥ 1900.
meta_*Any column prefixed with meta_ is collected into a per-row metadata object (the meta_ prefix is stripped).

​
Validation Behavior

Validation runs in-process at request time — no PII is staged on the batch row.
  • Mixed result (some rows valid, some invalid): the batch is created with the valid subset, and per-row failures are returned inline in failed_authorizers.
  • All rows invalid: the request returns 400 Bad Request with the per-row failures in error.details.failed_authorizers. No batch is created.
  • Empty file or wrong content type: the request returns 400 Bad Request before any rows are read.

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

​
email
string<email>

Optional. Email address to notify when the batch completes.

​
webhookUrl
string<uri>

Optional. Webhook URL to notify when the batch completes.

Body

multipart/form-data
​
file
file
required

CSV file containing authorizer rows. Must be sent as text/csv.

Response

Created

​
batch_id
string
required

Unique identifier for the submitted batch.

​
submitted_at
string<date-time>
required

Timestamp indicating when the batch was submitted.

​
message
string
required

Confirmation message or additional information.

​
failed_authorizers
object[]

List of authorizers that failed validation or processing.

​
warnings
string[]

Non-fatal warnings raised while parsing the input (e.g., non-UTF-8 CSV files decoded as Latin-1). Only set for CSV uploads.