Title: How to Process CSV and XLSX Bank Statements Through an API
Canonical URL: https://bankstatement.ai/blog/how-to-process-csv-and-xlsx-bank-statements-through-an-api
Updated: 2026-08-05
Category: accounting-embedded-workflows

# How to Process CSV and XLSX Bank Statements Through an API

## TL;DR

- The same documented API can process CSV and XLSX bank statements, subject to a 25 MB per-file limit.
- Format support does not prove that every spreadsheet layout will normalize correctly. Test authorized, representative fixtures from your actual intake channels.
- Preflight each file for supported type, size, processing authorization, and readable transaction content.
- Submit the file, poll the asynchronous job, retrieve the completed result, and review each normalized transaction’s date, description, and amount.
- Compare equivalent CSV and XLSX fixtures for row counts, debit and credit signs, dates, descriptions, amounts, and ambiguous rows.
- Results and exports expire after seven days, so retrieve required artifacts and store approved records in time.

A `.csv` or `.xlsx` extension identifies a file format; it does not establish that the transaction data is safe to release into a finance workflow. Two spreadsheets can represent the same bank activity while differing in headings, date types, amount signs, blank rows, or workbook structure. Treat eligibility for submission and correctness of the normalized result as separate questions, with explicit gates before and after processing.

## Key Takeaways

- The documented offering accepts PDF, CSV, and XLSX bank statements up to 25 MB per file.
- CSV and XLSX support does not imply universal layout support or identical output from different source files.
- Keep bearer tokens on your server and proxy browser or mobile requests through your backend.
- Use asynchronous job states correctly: completion permits inspection, not automatic release.
- Verify counts, signs, dates, descriptions, amounts, and ambiguous rows against expected transactions.
- Save records your organization is authorized and required to retain before the seven-day expiry.

## Define the spreadsheet-processing contract

Start by naming the objects your ingestion layer handles. This prevents “normalization” from becoming an unsupported promise that all spreadsheets will emerge identically.

A **CSV** is a delimited spreadsheet input. Your application must define which delimiters, encodings, quoting patterns, blank lines, headings, and date or number representations it accepts. The available evidence does not establish product-wide rules for those variations.

An **XLSX** file is a workbook input. Your preflight policy should determine how to handle multiple worksheets, formulas, merged cells, hidden content, blank rows, date systems, and damaged workbook structures. Do not present those application decisions as documented API behavior.

The **REST API** is the submission and retrieval interface. **JSON** is the normalized, application-readable result form. For this workflow, the required transaction entities are the **date**, **description**, and **amount**. Your comparison rules must also preserve or predictably translate the debit and credit convention so that each amount retains its financial meaning.

A **verification summary** is conversion-level metadata. It can direct attention to a result that needs closer review, but it is not field-level confidence and cannot prove that an individual date, description, amount, or sign is correct.

Two related terms keep the test precise:

- **Input equivalence** means the CSV and XLSX fixtures intentionally represent the same canonical transactions.
- **Output identity** means their returned transactions match under predefined comparison rules.

You construct input equivalence and test output identity. Even a successful comparison applies only to the tested fixtures and acceptance rules.

## Gate 1: Validate each CSV or XLSX before submission

[bankstatement.ai documents support for PDF, CSV, and XLSX bank statements up to 25 MB](https://bankstatement.ai/). Keep this workflow focused on CSV and XLSX, reject unsupported types before job creation, and reject any file above the documented limit.

Apply the following application-owned checks:

1. **Confirm authorization.** Record that the user or connected organization has the right to process the statement. The service terms require that right and warn that extracted results still require review.

2. **Identify the expected format.** Consider the declared type, filename, and content your parser can recognize. The supplied evidence does not establish whether the API relies on MIME type, extension, file signature, or content inspection, so do not attribute a specific detection method to the product.

3. **Open or parse the spreadsheet.** Confirm that a CSV can be parsed under your accepted rules or that an XLSX file can be opened as a workbook. Your implementation must define its treatment of password protection, formulas, multiple worksheets, merged cells, and unsupported structures.

4. **Look for usable transaction content.** Flag empty files, header-only sheets, blank workbooks, broken workbook structures, and files without usable transaction rows. The exact rejection criteria are implementation-dependent; document them for your intake channels.

5. **Create a restrained preflight record.** Useful fields include an internal source ID, declared or detected type, byte size, authorization confirmation, parse outcome, and rejection reason. Do not place statement contents in routine operational logs.

Keep API credentials out of the client-facing intake surface. The [API documentation](https://bankstatement.ai/docs/api) directs developers to retain bearer tokens server-side and proxy browser or mobile requests through the application backend.

Passing this gate means that a file is eligible for submission. It does not mean its transactions are correct.

## Submit, poll, and retrieve one normalized result

Use `convert` mode for transaction rows. Submit the validated CSV or XLSX from your backend with bearer authentication.

![CSV and XLSX files pass validation, API processing, and transaction review before approved storage.](https://files.trafficwins.com/generated-images/0371334e-670e-4ffe-a66a-c61eca5d47f4/b187012c-aa9a-5bba-9d7f-a76a4a2ac3f4/680dfe04-edd5-4302-b16a-6f6d5405134f/d457f35a-259c-4ce4-888d-972dabfdbc67/inline-1.png)


The minimum asynchronous sequence is:

1. Submit the accepted file.
2. Expect HTTP 202 and a job ID after successful job creation.
3. Store the job ID against your internal source record.
4. Poll until the job reaches `complete` or `failed`.
5. Retrieve normalized JSON or request an export only after completion.
6. Send the returned transactions through the post-result gate.

Do not release transaction data while processing remains incomplete. For a failed job, retain enough nonsensitive application metadata to explain its disposition without copying statement contents into routine logs.

The documentation also identifies HTTP 402 when more pages are needed and HTTP 429 with `retryAfterSeconds` when rate limits apply. Recognize these responses in your client, but keep the design of any retry scheduler outside this spreadsheet-validation procedure.

## Worked comparison: test equivalent CSV and XLSX fixtures

Use a matched-fixture test to decide whether the two formats are safe for your intended workload. This is a reproducible procedure, not a report of observed results; no executed fixtures or dated findings were supplied.

![CSV and XLSX results are each compared with the same canonical transaction set across five release checks.](https://files.trafficwins.com/generated-images/0371334e-670e-4ffe-a66a-c61eca5d47f4/b187012c-aa9a-5bba-9d7f-a76a4a2ac3f4/680dfe04-edd5-4302-b16a-6f6d5405134f/d457f35a-259c-4ce4-888d-972dabfdbc67/inline-2.png)


First, create one canonical transaction set containing expected values. Use synthetic data or statement records your organization is authorized to process. Include ordinary rows and relevant edge cases, such as a debit, a credit, an ambiguous regional date, a long description, and any unusual value your downstream process must tolerate.

Encode that set twice:

- Create a CSV fixture with the intended delimiter, headings, quoting, and date representation.
- Create an XLSX fixture containing the same transactions in the intended worksheet and cells.

Submit both through `convert` mode using the same acceptance thresholds. Record expectations before execution so that returned output cannot redefine success.

| Check | Canonical expectation | CSV observed | XLSX observed | Release rule |
|---|---|---|---|---|
| Transaction count | Expected row count | Record after test | Record after test | Both equal the canonical count |
| Dates | Expected value per row | Record after test | Record after test | Every date matches the accepted interpretation |
| Descriptions | Expected text or allowed normalization | Record after test | Record after test | No material transaction identity is lost |
| Amounts | Exact expected values | Record after test | Record after test | Every amount equals its canonical value |
| Debit/credit signs | Expected sign per row | Record after test | Record after test | No sign is reversed or dropped |
| Ambiguous rows | Known review cases | Record after test | Record after test | Each case is resolved or held for review |
| Verification summary | No predetermined outcome | Record after test | Record after test | Treat as review metadata, not transaction proof |

Compare each result with the canonical set, not just with the other result. CSV and XLSX outputs containing the same error could otherwise produce a false pass.

Define what a description match means before execution. Exact equality may be necessary when source text must be preserved. A controlled rule may permit harmless whitespace or casing differences. Apply the chosen rule consistently to both fixtures.

A passing comparison supports only the tested representations under the recorded conditions. It does not prove universal CSV or XLSX layout support. Add or rerun fixtures when a bank, export tool, worksheet pattern, or material layout changes.

## Gate 2: Review normalized transactions before handoff

A completed API job has passed the processing lifecycle, not the release gate. Assign every reviewed result one of three dispositions: **pass**, **fail**, or **unresolved**.

![Reviewed transactions branch to pass, fail, or unresolved; only pass continues to approved storage.](https://files.trafficwins.com/generated-images/0371334e-670e-4ffe-a66a-c61eca5d47f4/b187012c-aa9a-5bba-9d7f-a76a4a2ac3f4/680dfe04-edd5-4302-b16a-6f6d5405134f/d457f35a-259c-4ce4-888d-972dabfdbc67/inline-3.png)


Check:

- Returned transaction count against the canonical or independently expected count.
- Missing and duplicate rows.
- Debit and credit sign preservation.
- Dates and their calendar interpretation.
- Description preservation under the predefined comparison rule.
- Amount equality at the required precision.
- Rows that cannot be matched or interpreted without human judgment.
- Conversion-level verification issues that warrant closer inspection.

A plausible-looking row can still be wrong. A reversed sign changes its financial meaning, a shifted date can place activity in the wrong period, and a materially altered description can make the transaction difficult to identify. Route material discrepancies to review rather than silently repairing them with undocumented assumptions.

Use the verification summary as a review aid, not proof. Release the result only when transaction-level checks satisfy the thresholds defined before processing.

## Choose JSON or a CSV/XLSX export

Choose the result form according to the next controlled step:

- Use **normalized JSON** when application code must enforce gates, associate transactions with internal records, or retain structured data.
- Use a **CSV export** for simple tabular interchange or a lightweight spreadsheet handoff.
- Use an **XLSX export** when an authorized reviewer or workbook-oriented process needs that artifact.

The exact public JSON schema, property names, issue codes, and per-row ambiguity representation were not supplied, so implement against the current documented response rather than assuming field names from this article.

Choosing an export does not remove the need for validation. Producing a spreadsheet also does not establish a direct integration with QuickBooks, Xero, or another accounting system; it creates an artifact for an approved downstream process.

## Store approved results before they expire

Structured results, exports, and associated job metadata expire after seven days. The service also does not provide a browsable statement history, according to its [data-retention policy](https://bankstatement.ai/data-retention).

After a result passes review:

1. Download every required result and export before the deadline.
2. Copy records the organization is authorized and required to retain into its approved durable store.
3. Record the relationship between the source file, job, result, and review disposition.
4. Confirm that the stored artifact can be retrieved.

The appropriate retention period, storage system, access controls, and legal obligations are organization-specific. Do not infer a zero-retention or immediate-deletion guarantee. The narrow implementation rule is to avoid treating a temporary API result as your system of record.

## FAQ

### Can the same API process CSV and XLSX bank statements?

Yes. The documented offering accepts CSV and XLSX bank statements, as well as PDF, up to 25 MB per file. Use `convert` mode for transaction rows, then poll the asynchronous job and retrieve its result after completion.

### Does support mean every spreadsheet layout will work identically?

No. Format support does not establish universal compatibility, extraction accuracy, or identical behavior across different layouts. Validate representative fixtures from the banks and export paths you expect to support.

### Can the verification summary replace transaction-level review?

No. It is conversion-level metadata rather than proof that each transaction is correct. Compare counts, dates, descriptions, amounts, signs, duplicates, missing rows, and ambiguous cases with expected records before release.

### Should normalized JSON or an export be stored?

Store JSON when your application needs structured records or automated controls. Store CSV or XLSX when an authorized person or spreadsheet workflow needs a file artifact. Retain both only when each has a defined purpose and your organization is authorized to keep them.

### What happens after seven days?

Results, exports, and associated job metadata expire. Retrieve required artifacts and place approved records in your authorized storage before that deadline.

### Where should the API token be kept?

Keep it on your server. Do not expose the bearer token in browser or mobile code; send client requests through your controlled backend.

When your gates and matched fixtures are ready, review the API docs, create an account, obtain a server-side token, and run the CSV/XLSX pair through the same acceptance test.