> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reconlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Imports

> Upload files, inspect mapping outcomes, and troubleshoot failed rows.

The **Import center** is where operators turn batch files — bank statements, PSP reports, on-chain exports, and internal ledgers — into data the reconciliation engine can use. The page header reads "Import center" with the description "Track uploads, validate mappings, inspect failed rows, and explain how file data enters reconciliation."

<Note>
  Every import on this page is an `ImportBatch` created through `POST /v1/import-batches`. The dashboard is a convenience layer over the same ingestion pipeline available to your own systems.
</Note>

## KPI strip

At the top of the page, four cards summarize the import surface:

| Card        | Value                                                                          |
| ----------- | ------------------------------------------------------------------------------ |
| Formats     | The accepted file extensions: `.csv`, `.json`, `.xlsx`, `.tsv`                 |
| Profiles    | The number of active [import profiles](/dashboard/configuration#file-mappings) |
| Failed rows | The number of current row-level validation issues                              |
| Flow        | A reminder of the pipeline: `RawRecords -> Cases`                              |

<Warning>
  The live ingestion path currently parses **CSV and TSV files only**. `.json` and `.xlsx` are listed as accepted formats but uploading them through the live upload flow will be rejected with an error until that part of the pipeline is completed.
</Warning>

## Tabs

The page has three tabs, gated by permission:

* **Import history** (`imports_view`) — every `ImportBatch` for the organization
* **Failed rows** (`imports_review`) — row-level validation failures across batches
* **File templates** — reference column layouts for each source type

### Import history

Each row in the history table represents one `ImportBatch`, loaded from [List import batches](/api-reference/imports/list-import-batches) (`GET /v1/import-batches?limit=100`):

| Column         | Source                                                                    |
| -------------- | ------------------------------------------------------------------------- |
| File name      | `originalFileName`                                                        |
| Source type    | `sourceType`                                                              |
| Provider       | `provider`                                                                |
| Profile        | the linked import profile's name                                          |
| Mapping status | whether the batch resolved to a mapped profile                            |
| Status         | `status`, mapped to one of `pending`, `processing`, `completed`, `failed` |
| Rows           | `validRows` / `warningRows` / `failedRows` out of `totalRows`             |
| Output         | payment intents created / flow legs created                               |
| Linked cases   | number of cases linked from this batch                                    |
| Created        | `createdAt`                                                               |
| Actions        | "View" link to the batch summary                                          |

The underlying `status` values from the API (`uploaded`, `mapping_required`, `parsing`, `validating`, `processing`, `completed`, `failed`) are collapsed into four UI states:

| API status                            | UI status  |
| ------------------------------------- | ---------- |
| `uploaded`, `mapping_required`        | Pending    |
| `parsing`, `validating`, `processing` | Processing |
| `completed`                           | Completed  |
| `failed`                              | Failed     |

### Failed rows

Each entry shows:

* A badge — `failed` or `matched_with_exception` depending on `validationStatus`
* The row number and `sourceRef`
* The list of `validationErrors` for that row
* The raw payload as pretty-printed JSON
* A "RawRecord validation" badge

This is the row-level detail behind the `failedRows` and `warningRows` counts on the history table and on the [Overview](/dashboard/overview) page's Recent Import Failures widget. Each failing row corresponds to a `RawRecord` with `validationStatus = failed`, which can be retrieved via [List import batch raw records](/api-reference/imports/list-import-batch-raw-records).

### File templates

Reference cards showing the expected columns for each source type, used as a starting point when preparing a file:

| Template            | Columns                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| Client ledger       | `ref_id`, `send_amount`, `send_currency`, `receive_amount`, `receive_currency`, `payment_date` |
| PSP report (Bridge) | `transfer_id`, `amount`, `currency`, `status`, `created_at`                                    |
| Bank statement      | `statement_ref`, `credit_amount`, `currency`, `posted_at`, `beneficiary_account`               |
| On-chain report     | `tx_hash`, `chain_id`, `token_address`, `amount`, `occurred_at`                                |

These map onto the canonical fields configured for each [import profile](/dashboard/configuration#file-mappings).

## Uploading a file

Selecting **Upload file** (requires `imports_upload`) opens a four-step modal:

<Steps>
  <Step title="Choose a source type">
    Pick the `ImportSourceType` for the file. This determines whether the import is expectation-first (creates `PaymentIntent` records) or evidence-first (creates `FlowLeg` records):

    | Source type              | Output                                         |
    | ------------------------ | ---------------------------------------------- |
    | `client_internal_ledger` | Creates `PaymentIntent` + `ReconciliationCase` |
    | `bank_statement`         | Creates `FlowLeg` evidence                     |
    | `psp_report`             | Creates `FlowLeg` evidence                     |
    | `onchain_report`         | Creates `FlowLeg` evidence                     |
    | `client_transfer_report` | Creates `FlowLeg` evidence                     |
    | `manual`                 | Creates `FlowLeg` or `PaymentIntent`           |
  </Step>

  <Step title="Choose an import profile">
    Select the [import profile](/dashboard/configuration#file-mappings) that maps this file's columns to canonical fields. Profiles are filtered to ones matching the chosen source type.
  </Step>

  <Step title="Upload the file">
    Files up to 50 MB are accepted. For live processing, only CSV and TSV are currently supported.
  </Step>

  <Step title="Preview and confirm">
    Review a preview of the parsed rows before submitting. Confirming calls [Create an import batch](/api-reference/imports/create-an-import-batch):

    ```
    POST /v1/import-batches
    ```

    with the import profile ID, original file name, file contents, and content type.
  </Step>
</Steps>

<Note>
  Live uploads are archived to Cloudflare R2 and hashed for deduplication. If you upload the same file content twice for the same organization, the API recognizes the existing `ImportBatch` by its file hash rather than creating a duplicate.
</Note>

## Batch summary

Selecting "View" on a batch opens its summary, which presents the batch's row metrics — total, valid, warning, and failed row counts — alongside the batch's mapping status and file name, with a button to copy the batch ID. The same data is available directly from [Get import batch detail](/api-reference/imports/get-import-batch-detail) (`GET /v1/import-batches/{batchId}`) and the underlying rows from [List import batch raw records](/api-reference/imports/list-import-batch-raw-records) (`GET /v1/import-batches/{batchId}/raw-records`).

## From here

<CardGroup cols={2}>
  <Card title="List import batches" icon="code" href="/api-reference/imports/list-import-batches">
    Query batch history directly, including status and row counts.
  </Card>

  <Card title="Create an import batch" icon="upload" href="/api-reference/imports/create-an-import-batch">
    Submit a file programmatically instead of through the dashboard.
  </Card>

  <Card title="Configuration" icon="gear" href="/dashboard/configuration">
    Manage the import profiles and canonical fields that govern how files are mapped.
  </Card>

  <Card title="Cases" icon="briefcase" href="/dashboard/cases">
    See the `PaymentIntent` and `ReconciliationCase` records produced by a successful import.
  </Card>
</CardGroup>