> ## 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)

> Submit a batch of authorizers for balance checks via CSV upload

# Submit Balance Check (CSV)

Upload a CSV file of authorizers for balance checks. This endpoint is the file-upload counterpart to [Submit Balance Check](/api-reference/stable/submit-balance-request) — use it when your authorizer list is already exported as a spreadsheet.

<Note>
  **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](mailto:sales@rightfoot.com).
</Note>

## Key Information

<Card>
  <div>
    **Batch Size Limit:** Maximum 5,000 rows per CSV
  </div>

  <div>
    **Content-Type:** `multipart/form-data` with the file part as `text/csv`
  </div>

  <div>
    **Encoding:** UTF-8 preferred. Files exported from Excel on Windows are decoded as Latin-1 with a `warnings` entry on the response.
  </div>

  <div>
    **Validation:** Per-row validation runs synchronously at request time. Failures are returned inline in the response.
  </div>
</Card>

## 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     |

<Note>
  Submitting both `account_number` and `debit_card_number` on the same row is rejected. Pick one mode per row.
</Note>

### 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

<Warning>
  Validation runs in-process at request time — no PII is staged on the batch row.
</Warning>

* **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.


## OpenAPI

````yaml POST /v1/balance_requests/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/balance_requests/csv:
    post:
      tags:
        - General Availability
      summary: Submit a batch of authorizers via CSV upload
      description: >
        Upload a CSV of authorizers for balance checks. The file is validated
        synchronously at request time — per-row failures are returned inline in
        the response body.


        **Batch Size Limit:** The maximum batch size is 5,000 rows per CSV.


        **Content-Type:** `multipart/form-data` with the file part as
        `text/csv`.


        **Encoding:** UTF-8 is preferred. Files exported from Excel on Windows
        are also accepted; if a non-UTF-8 file is decoded as Latin-1, a
        `warnings` entry is included in the response.


        **CSV Columns:** The header row must use the column names below.
        Required and optional fields differ slightly depending on whether you
        submit bank-account info or debit-card info.


        **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 |


        Provide exactly one of `account_number` or `debit_card_number` per row —
        providing both is rejected.


        **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 (prefix stripped). |


        **Debit Card Information:** Balance requests using debit card
        information are restricted to approved customers only.
      operationId: submit_balance_request_csv
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          description: Optional. Email address to notify when the batch completes.
        - in: query
          name: webhookUrl
          schema:
            type: string
            format: uri
          description: Optional. Webhook URL to notify when the batch completes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    CSV file containing authorizer rows. Must be sent as
                    `text/csv`.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreatedResponse'
              example:
                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.
        '400':
          description: >
            Bad Request — returned when the upload is rejected before
            submission. Possible causes: invalid `Content-Type`, empty file, CSV
            contains no valid rows, or every row failed validation. When all
            rows failed validation, `error.details` contains the per-row
            `failed_authorizers` list and any decoding `warnings`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                status: error
                status_code: 400
                error:
                  code: BAD_REQUEST
                  message: No valid authorizers in the batch.
                  timestamp: '2024-09-16T12:00:00Z'
                  suggestion: >-
                    All rows failed validation; correct the errors below and
                    re-upload.
                  details:
                    failed_authorizers:
                      - authorizer_unique_id: 1a2b3c4d
                        error: >-
                          Invalid routing number for authorizer(s). Routing
                          number must be 9 digits long.
                        account_type: ACCOUNT_NUMBER
                        row_number: 2
                      - authorizer_unique_id: 9i0j1k2l
                        error: Missing date of birth for authorizer(s).
                        account_type: ACCOUNT_NUMBER
                        row_number: 3
                documentation_url: https://api.rightfoot.com/docs
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    BatchCreatedResponse:
      type: object
      required:
        - batch_id
        - submitted_at
        - message
      properties:
        batch_id:
          type: string
          description: Unique identifier for the submitted batch.
        submitted_at:
          type: string
          format: date-time
          description: Timestamp indicating when the batch was submitted.
        message:
          type: string
          description: Confirmation message or additional information.
        failed_authorizers:
          type: array
          description: List of authorizers that failed validation or processing.
          items:
            type: object
            properties:
              authorizer_unique_id:
                type: string
                description: Unique identifier for the authorizer that failed.
              error:
                $ref: '#/components/schemas/AuthorizerValidationError'
              account_type:
                type: string
                description: >-
                  The payment information type for the failed row (e.g.,
                  `ACCOUNT_NUMBER`, `DEBIT_CARD`).
              row_number:
                type: integer
                description: >-
                  1-indexed source row number from the uploaded CSV (header is
                  row 1, first data row is row 2). Only set for CSV uploads.
        warnings:
          type: array
          description: >-
            Non-fatal warnings raised while parsing the input (e.g., non-UTF-8
            CSV files decoded as Latin-1). Only set for CSV uploads.
          items:
            type: string
    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
    AuthorizerValidationError:
      type: string
      enum:
        - Missing authorizer unique ID for authorizer(s).
        - Missing zip code for authorizer(s).
        - >-
          Invalid ZIP code for authorizer(s). Must be 5 digits or in 5+4 format
          (e.g., 94107 or 94107-1234).
        - Missing day of birth for authorizer(s).
        - Missing month of birth for authorizer(s).
        - Missing year of birth for authorizer(s).
        - >-
          Invalid phone number for authorizer(s). Phone number must be 10 digits
          long without dashes and parentheses.
        - Missing phone number for authorizer(s).
        - Missing date of birth for authorizer(s).
        - SSN must be of type string for authorizer(s).
        - Invalid SSN for authorizer(s).
        - EIN must be of type string for authorizer(s).
        - Invalid EIN for authorizer(s).
        - Number must be of type string for authorizer(s).
        - Missing Account Number or Debit Card Number for authorizer(s).
        - Account number must be of type string for authorizer(s).
        - Debit card number must be of type string for authorizer(s).
        - Invalid debit card number for authorizer(s). Must be 16 digits.
        - CVV must be of type string for authorizer(s).
        - Invalid CVV for authorizer(s). Must be 3 or 4 digits.
        - Invalid expiration month for authorizer(s). Must be between 1 and 12.
        - Invalid expiration year for authorizer(s). Must be 4 digits.
        - >-
          Invalid routing number for authorizer(s). Routing number must be 9
          digits long.
        - Missing routing number for authorizer(s).
        - Missing SSN or EIN for authorizer(s).
        - >-
          Provide either Account Number or Debit Card Number for authorizer(s),
          not both.
        - Duplicate authorizer unique ID not allowed.
      description: >
        Validation error messages for authorizer data submitted in balance
        requests.


        | Error | Description |

        |-------|-------------|

        | Missing authorizer unique ID for authorizer(s). | The
        authorizer_unique_id field was not provided. |

        | Missing zip code for authorizer(s). | ZIP code is required for certain
        institutions (e.g., Discover). |

        | Invalid ZIP code for authorizer(s). Must be 5 digits or in 5+4 format
        (e.g., 94107 or 94107-1234). | ZIP code format is invalid. |

        | Missing day of birth for authorizer(s). | The day field in
        date_of_birth was not provided. |

        | Missing month of birth for authorizer(s). | The month field in
        date_of_birth was not provided. |

        | Missing year of birth for authorizer(s). | The year field in
        date_of_birth was not provided. |

        | Invalid phone number for authorizer(s). Phone number must be 10 digits
        long without dashes and parentheses. | Phone number format is invalid. |

        | Missing phone number for authorizer(s). | The phone_number field was
        not provided. |

        | Missing date of birth for authorizer(s). | The date_of_birth object
        was not provided. |

        | SSN must be of type string for authorizer(s). | SSN was provided as a
        non-string type. |

        | Invalid SSN for authorizer(s). | SSN format is invalid. Must be 9
        digits or XXX-XX-XXXX format. |

        | EIN must be of type string for authorizer(s). | EIN was provided as a
        non-string type. |

        | Invalid EIN for authorizer(s). | EIN format is invalid. Must be 9-10
        digits or XX-XXXXXXX format. |

        | Number must be of type string for authorizer(s). | Card number was
        provided as a non-string type. |

        | Missing Account Number or Debit Card Number for authorizer(s). |
        Neither account_number nor debit_card_number was provided. |

        | Account number must be of type string for authorizer(s). | Account
        number was provided as a non-string type. |

        | Debit card number must be of type string for authorizer(s). | Debit
        card number was provided as a non-string type. |

        | Invalid debit card number for authorizer(s). Must be 16 digits. |
        Debit card number format is invalid. |

        | CVV must be of type string for authorizer(s). | CVV was provided as a
        non-string type. |

        | Invalid CVV for authorizer(s). Must be 3 or 4 digits. | CVV format is
        invalid. |

        | Invalid expiration month for authorizer(s). Must be between 1 and 12.
        | Expiration month is out of range. |

        | Invalid expiration year for authorizer(s). Must be 4 digits. |
        Expiration year format is invalid. |

        | Invalid routing number for authorizer(s). Routing number must be 9
        digits long. | Routing number format is invalid. |

        | Missing routing number for authorizer(s). | Routing number is required
        when using account_number. |

        | Missing SSN or EIN for authorizer(s). | Neither SSN nor EIN was
        provided. |

        | Provide either Account Number or Debit Card Number for authorizer(s),
        not both. | Both account_number and debit_card_number were provided. |

        | Duplicate authorizer unique ID not allowed. | The same
        authorizer_unique_id appears multiple times in the batch. |
  responses:
    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
  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.

````