Uploading files

This guide covers how to import transaction data from external sources into Matcher for reconciliation.

Supported formats

Matcher accepts transaction files in three general-purpose formats:

CSV: Comma-separated values with headers. Most common for bank exports.
JSON: Array of transaction objects. Best for API integrations.
XML: Structured elements. Common for enterprise systems.

Beyond these, the upload endpoint also accepts specialized banking formats such as camt053 and the namespaced descriptor keys from the format catalog (CNAB, acquirer layouts). See Import formats for the full catalog.

File structure requirements

Each file must contain transaction records with fields you can map to Matcher’s internal schema.

Required fields

Every transaction must have these fields (or mappable equivalents):

Field	Type	Description
`external_id`	String	Unique identifier within the source
`amount`	Decimal	Transaction amount (positive or negative)
`currency`	String	ISO 4217 currency code
`date`	Date/DateTime	Transaction date

Optional fields

Field	Type	Description
`description`	String	Free-text description
`fee_amount`	Decimal	Fee charged on the transaction
`fee_currency`	String	Currency of the fee
`direction`	Object	Column that marks each row as debit or credit. See Debit and credit column.

Matcher keeps unmapped columns as transaction metadata.

Debit and credit column

Some files mark each row as debit or credit in a separate column. To read the sign from that column, map the optional direction key to an object {column, debit, credit}:

"direction": { "column": "type", "debit": "debit", "credit": "credit" }

A debit row imports with a negative amount, and a credit row imports with a positive amount. With direction mapped, the amount column must be unsigned. A signed amount, an empty direction cell, or an unknown direction value rejects the row. Matcher reads direction in CSV, JSON, and XML files only.

Format examples

CSV

CSV Requirements:

First row must be column headers
UTF-8 encoding and comma delimiter by default (configurable)
Quote fields containing commas or newlines

Code example

 transaction_id,amount,currency,date,reference,type
 BANK-2024-001,1500.00,USD,2024-01-15,Invoice #1234,credit
 BANK-2024-002,250.00,USD,2024-01-15,Service fee,debit
 BANK-2024-003,3200.50,USD,2024-01-16,Customer payment,credit
 BANK-2024-004,89.99,USD,2024-01-16,Subscription,debit

JSON

JSON Requirements:

An array of objects, or a single object
Consistent field names across objects
UTF-8 encoding by default (configurable)

Code example

[
  {
    "transaction_id": "BANK-2024-001",
    "amount": 1500.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice #1234",
    "type": "credit"
  },
  {
    "transaction_id": "BANK-2024-002",
    "amount": 250.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Service fee",
    "type": "debit"
  }
]

XML

XML Requirements:

Well-formed XML
Record elements named transaction, row, record, item, or entry
UTF-8 encoding by default (configurable)

Code example

  <?xml version="1.0" encoding="UTF-8"?>
  <transactions>
    <transaction>
      <transaction_id>BANK-2024-001</transaction_id>
      <amount>1500.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
     <reference>Invoice #1234</reference>
      <type>credit</type>
    </transaction>
    <transaction>
      <transaction_id>BANK-2024-002</transaction_id>
      <amount>250.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
      <reference>Service fee</reference>
      <type>debit</type>
      </transaction>
  </transactions>

Upload via API

Use the import endpoint to upload transaction files.

Preview before uploading

Before committing a file for ingestion, you can preview it to verify column detection and sample data. This helps catch field mapping issues early.

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/preview" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_statement_january.csv" \
 -F "max_rows=5"

Response

{
  "columns": ["transaction_id", "amount", "currency", "date", "reference"],
  "sampleRows": [
    ["BANK-2024-001", "1500.00", "USD", "2024-01-15", "Invoice #1234"],
    ["BANK-2024-002", "-250.00", "USD", "2024-01-15", "Service fee"]
  ],
  "rowCount": 2,
  "format": "csv"
}

API Reference: Preview file

Single file upload

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_statement_january.csv"

Send the format field before the file part. If file arrives first, Matcher infers the format from the filename extension for .csv and .json only. Matcher never infers .xml, because it is a format family that covers plain XML and camt.053. Send the explicit format field for XML. Matcher rejects the upload without it.

Matcher parses and stores the whole file inside the upload request. Upload returns 202 Accepted with the finished job. When the import fails, Matcher answers with an error instead of the job. Matcher reads an idempotency key only from the X-Idempotency header, and only when you send one. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. A replayed answer carries the X-Idempotency-Replayed header.

The upload limit is 1 GiB. It counts the whole request body of the upload, including every part, part header, and boundary, not only the file.

Matcher refuses an upload larger than the upload limit with 413 (MTCH-0010). It refuses an upload that stops sending data for too long with 408 (MTCH-0311).

API Reference: Upload file

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1250,
  "droppedDuplicateRows": 0,
  "flaggedDuplicateRows": 0,
  "reviewRows": 0,
  "failureRatePercent": 0,
  "completedWithErrors": false,
  "startedAt": "2024-01-20T10:30:00Z",
  "completedAt": "2024-01-20T10:30:45Z",
  "createdAt": "2024-01-20T10:30:00Z"
}

Check import status

cURL

curl -X GET https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId} \
 -H "Authorization: Bearer $TOKEN"

API Reference: Get import status

Response (Processing)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PROCESSING",
  "fileName": "bank_statement_january.csv",
  "startedAt": "2024-01-20T10:30:05Z"
}

Response (Completed)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "completedWithErrors": true,
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1233,
  "droppedDuplicateRows": 12,
  "failedRows": 5,
  "failureRatePercent": 1,
  "reviewRows": 0,
  "diagnosis": "",
  "startedAt": "2024-01-20T10:30:05Z",
  "completedAt": "2024-01-20T10:30:45Z"
}

Per-row parse/normalization errors are not embedded in the job. When completedWithErrors is true (or the job FAILED), fetch the details from GET /v1/imports/contexts/{contextId}/jobs/{jobId}/errors (capped at 100 stored rows, with totalErrors/truncated accounting). For a wholesale FAILED job, diagnosis carries a safe one-line reason.

reviewRows counts rows with a blank external_id that Matcher imports with status PENDING_REVIEW. This happens when the source sets blank_external_id to NEEDS_REVIEW in its config. With the default, REJECT, a blank external_id fails the row.

Import job status values

Status	Description
`PROCESSING`	File is being parsed and normalized
`COMPLETED`	Import finished (check `completedWithErrors` for partial failures)
`FAILED`	Import aborted wholesale (see `diagnosis`)

Validation and error handling

Matcher validates uploaded files at multiple stages.

Validation stages

Format Validation

Verifies the file is valid CSV, JSON, or XML with correct structure.

Schema Validation

Checks that required fields are present and match the configured field map.

Data Type Validation

Validates amounts are valid decimals, dates are parseable, currencies are valid ISO codes.

Common validation errors

Each row error carries the row number, the field when one applies, and a message. Common messages:

Message	Cause	Solution
`missing required field`	A required field is blank in the row	Fill the field in the source file
`invalid decimal amount`	Amount not a valid number	Check for currency symbols or thousands separators
`invalid date format`	Date cannot be parsed	Use ISO 8601 format (YYYY-MM-DD)
`invalid ISO 4217 currency code`	Currency code not recognized	Use ISO 4217 codes (USD, EUR, BRL)

Handling errors

By default, Matcher imports valid rows even if some rows have errors. To fail the job when failed rows exceed a percentage, set fail_on_error_rate_percent (1 to 99) in the source config.

Duplicate detection

Matcher automatically detects and handles duplicate transactions to prevent double-counting.

How duplicates are detected

By default, a row is a duplicate when it repeats the external_id of a row from the same source, within the same upload or against already-persisted data. To detect duplicates on other fields, set duplicate_key in the source config. Its value is an ordered list of field-map names, such as ["external_id", "amount"].

Duplicate handling options

Set the duplicate_policy key in the source config to control handling:

Policy	Behavior
`FLAG_AS_EXCEPTION` (default)	Drops the repeat and raises a `DUPLICATE_TRANSACTION` exception on the surviving transaction (subset of `droppedDuplicateRows` reported as `flaggedDuplicateRows`)
`KEEP_FIRST`	Keeps the first occurrence and silently drops repeats, counted in `droppedDuplicateRows`
`REJECT`	Turns each repeated row into an ingestion row error, counted in `failedRows`

When duplicate_policy is absent, FLAG_AS_EXCEPTION applies.

Viewing duplicate details

The import summary shows the number of duplicates:

{
  "totalRows": 1000,
  "persistedRows": 950,
  "droppedDuplicateRows": 50,
  "failedRows": 0,
  "failureRatePercent": 0
}

Batch uploads

For large reconciliation jobs, you can upload multiple files in sequence.

Upload multiple files

# Upload bank statement
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_january.csv"

# Upload ledger export
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_january.csv"

Wait for all imports

Before running matching, make sure all imports are complete.

# List imports for context
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"

Search uploaded transactions

After importing files, you can search across all transactions in a context to verify data quality or investigate specific records.

cURL

curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/search?q=Invoice&amount_min=1000&status=UNMATCHED" \
 -H "Authorization: Bearer $TOKEN"

Response

{
  "items": [
    {
      "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "1500.00",
      "currency": "USD",
      "date": "2024-01-15T00:00:00Z",
      "description": "Invoice #1234",
      "status": "UNMATCHED"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

API Reference: Search transactions

Supported filters include amount_min, amount_max, date_from, date_to, currency, source_id, status, exact external_id match via the reference parameter, and free-text search via the q parameter.

Best practices

Validate files before upload

Check file format and encoding locally before uploading. This catches obvious errors faster.

# Check CSV is valid
head -5 transactions.csv

# Check encoding
file transactions.csv

Use consistent date formats

Standardize on ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ) across all sources to avoid parsing issues.

Include transaction IDs

Always include unique transaction IDs from the source system. This enables proper duplicate detection and audit trails.

Handle negative amounts consistently

Decide on a convention (negative for debits, positive for credits) and apply it consistently. When a file marks debits and credits in a separate column, map that column with the direction key instead.

Upload incrementally for large files

For files larger than 50 MB, consider splitting them into smaller chunks by date range. This is a reliability recommendation, not the upload limit, and allows partial retries.

Set up automated uploads

For recurring reconciliation, automate file uploads using scheduled jobs.

# Example: Daily upload via cron
0 6 * * * /scripts/upload_bank_statement.sh

​Supported formats

​File structure requirements

​Required fields

​Optional fields

​Debit and credit column

​Format examples

​CSV

​JSON

​XML

​Upload via API

​Preview before uploading

​Response

​Single file upload

​Response

​Check import status

​Response (Processing)

​Response (Completed)

​Import job status values

​Validation and error handling

​Validation stages

​Common validation errors

​Handling errors

​Duplicate detection

​How duplicates are detected

​Duplicate handling options

​Viewing duplicate details

​Batch uploads

​Upload multiple files

​Wait for all imports

​Search uploaded transactions

​Response

​Best practices

​Next steps

Reviewing Matches

Field Mapping

Supported formats

File structure requirements

Required fields

Optional fields

Debit and credit column

Format examples

CSV

JSON

XML

Upload via API

Preview before uploading

Response

Single file upload

Response

Check import status

Response (Processing)

Response (Completed)

Import job status values

Validation and error handling

Validation stages

Common validation errors

Handling errors

Duplicate detection

How duplicates are detected

Duplicate handling options

Viewing duplicate details

Batch uploads

Upload multiple files

Wait for all imports

Search uploaded transactions

Response

Best practices

Next steps