POST

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."
  ]
}

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)

Column	Format
`authorizer_unique_id`	Alphanumeric, must be unique within the CSV
`phone_number`	Exactly 10 digits, no separators (e.g. `5551234567`)
`ssn` or `ein`	At least one. `ssn`: 9 digits or `XXX-XX-XXXX`. `ein`: 9–10 digits or `XX-XXXXXXX`.

Bank-Account Mode

Provide account_number:

Column	Required?	Format
`account_number`	required	Free-form string
`routing_number`	required	9 digits

Debit-Card Mode

Provide debit_card_number (approved customers only):

Column	Required?	Format
`debit_card_number`	required	16 digits
`cvv`	optional	3–4 digits
`expiration_month`	optional	Integer 1–12
`expiration_year`	optional	4 digits
`routing_number`	optional	9 digits

Submitting both account_number and debit_card_number on the same row is rejected. Pick one mode per row.

Always Optional (any row)

Column	Format
`first_name`, `last_name`	Free-form
`street_address_line1`, `street_address_line2`, `city`, `state`, `country`	Free-form
`zip_code`	5 digits or `ZZZZZ-NNNN`. Required for Discover (routing number `031100649`).
`date_of_birth`	`MM/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

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

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.

Show child attributes

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.

Retrieve Balance ResultsRetrieve processed balances for a batch

⌘I

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."
  ]
}

​Submit Balance Check (CSV)

​Key Information

​CSV Format

​Always Required (every row)

​Bank-Account Mode

​Debit-Card Mode

​Always Optional (any row)

​Validation Behavior

Authorizations

Query Parameters

Body

Response

Submit Balance Check (CSV)

Key Information

CSV Format

Always Required (every row)

Bank-Account Mode

Debit-Card Mode

Always Optional (any row)

Validation Behavior