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 columns: authorizer_unique_id, phone_number, zip_code, plus payment info (see below) and one of ssn / ein.

​
Payment Information Types

You must provide either bank account information or debit card information (approved customers only) per row:

​
Bank Account Information

  • Required columns: account_number, routing_number, and either ssn or ein

​
Debit Card Information

  • Required columns: debit_card_number, cvv, expiration_year, expiration_month, and either ssn or ein
  • Optional: routing_number (if linked to a bank account)
  • Note: Debit card balance checks require prior approval

​
Supported Columns

ColumnDescription
authorizer_unique_idAlphanumeric unique ID, provided by the lender
first_name, last_nameAuthorizer name
street_address_line1, street_address_line2, city, state, zip_code, countryAddress fields
phone_numberAuthorizer phone number
date_of_birthMM/DD/YYYY
ssn, einTax ID (one required)
account_number, routing_numberBank account info
debit_card_number, cvv, expiration_month, expiration_yearDebit card info
user_idOptional integer user ID
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.