Bank Transaction

• Allowed query parameters
• Upload and import bank transactions
  • Monitoring import progress
• Create a bank transaction
• Retrieve a bank transaction
• Delete a bank transaction
• List bank transactions

Bank transactions represent financial movements in your bank accounts, typically imported from bank statement files (CAMT.053, etc.). They can be reconciled with invoices, expenses, journal transactions, and other business records for comprehensive financial tracking.

Allowed query parameters

Filters

Filter	Type	Description
search	String	Full-text search across transaction details
bank_account	Id	Filter by Bank Account Id
date_range	DateRange	Filter by booking date <start-date>,<end-date>
amount_range	Range	Filter by transaction amount range
reconciled	Boolean	Filter by reconciliation status
is_processing	Boolean	Show only transactions currently being processed

Sorting

booking_date, value_date, document_date, amount, name, created_at

Includes

bankAccount, matches.matchable

Upload and import bank transactions

post

/bank_account/{bankAccountId}/import-transactions

This endpoint allows you to upload and import bank transactions from various file formats. The system supports multiple import methods with automatic data processing and matching capabilities.

Supported file formats

Format	Extensions	Description
CAMT XML	.xml	Standard bank statement format (CAMT.053) with complete transaction details
CSV/Excel	.csv, .txt, .xls, .xlsx	Tabular data with AI-powered column mapping

Request parameters

Attribute (* required)	Type	Description
files.* *	File	Array of files to import (max 5MB each)

Example request

POST /bank_account/AG52olvLXP/import-transactions
Content-Type: multipart/form-data
files[0]=bank_statement.xml
files[1]=transactions.csv

Example response

// HTTP 200 OK
[
    {
        "id": "9c3b5e4d-8f2a-4b6c-9d1e-2f3a4b5c6d7e",
        "name": "bank_statement.xml",
        "totalJobs": 25,
        "pendingJobs": 25,
        "processedJobs": 0,
        "progress": 0,
        "finished": false,
        "cancelled": false,
        "created_at": "2024-01-15T10:30:00.000000Z"
    },
    {
        "id": "8b2a4c3d-7e1f-5a8b-8c2d-1e4f5a8b9c2d",
        "name": "transactions.csv",
        "totalJobs": 150,
        "pendingJobs": 150,
        "processedJobs": 0,
        "progress": 0,
        "finished": false,
        "cancelled": false,
        "created_at": "2024-01-15T10:30:00.000000Z"
    }
]

Error handling

Common error scenarios:

• 422 Unprocessable Entity: Could not match CSV columns automatically
• 413 Payload Too Large: File exceeds 5MB limit
• 415 Unsupported Media Type: Invalid file format
• 403 Forbidden: Insufficient permissions (requires create bank_transaction or supervise invoices permission)

Monitoring import progress

The import process runs asynchronously in the background. Use the returned batch IDs to monitor processing status and provide real-time feedback to users.

For detailed information on monitoring batch progress, polling recommendations, and handling batch status updates, see the Background Jobs guide.

Create a bank transaction

post

/bank_transaction

Create a bank transaction manually. The transaction will be automatically processed for AI optimization (if name is missing but text is provided) or matching against existing records.

Attribute (* required)	Type	Description
bank_account_id *	String	Bank Account Id
acc_serv_ref *	String	Unique identifier for this transaction
amount *	Numeric	Transaction amount (positive for credits, negative for debits)
entry_acc_serv_ref	String?	Entry account servicer reference
document_date	Date?	Document date from the transaction
booking_date	Date?	Booking date when transaction was processed
value_date	Date?	Value date when funds become available
currency	String?	Currency code (max 3 characters, defaults to bank account currency)
reference	String?	Payment reference or structured reference
name	String?	Transaction counterparty name
text	String?	Additional transaction description
end_to_end_id	String?	End-to-end identification

Example response

// HTTP 201 Created
{
    "id": "v7rnRjBn9o",
    "bank_account_id": "AG52olvLXP",
    "bank_account": null,
    "matches": [],
    "acc_serv_ref": "202401150001",
    "entry_acc_serv_ref": "202401150001-1",
    "end_to_end_id": "NOTPROVIDED",
    "document_date": "2024-01-15",
    "booking_date": "2024-01-15",
    "value_date": "2024-01-15",
    "amount": -125.5,
    "currency": "CHF",
    "reference": "RF18 5390 0754 7034 2",
    "name": "ACME Corporation AG",
    "text": "Invoice payment 2024-001",
    "is_processing": true,
    "is_reconciled": false
}

Important notes

• Processing: New transactions are automatically set to is_processing: true and will be processed asynchronously
• AI Optimization: If name is not provided but text is provided, the transaction will be optimized using AI to extract better details
• Auto-matching: After creation (or AI optimization), the system automatically attempts to match the transaction with existing records (invoices, expenses, etc.)
• Uniqueness: The acc_serv_ref must be unique across all bank transactions

Retrieve a bank transaction

get

/bank_transaction/{id}

Example response

// HTTP 200 OK
{
    "id": "v7rnRjBn9o",
    "bank_account_id": "AG52olvLXP",
    "acc_serv_ref": "202401150001",
    "entry_acc_serv_ref": "202401150001-1",
    "end_to_end_id": "NOTPROVIDED",
    "document_date": "2024-01-15",
    "booking_date": "2024-01-15",
    "value_date": "2024-01-15",
    "amount": -125.5,
    "currency": "CHF",
    "reference": "RF18 5390 0754 7034 2",
    "name": "ACME Corporation AG",
    "text": "Invoice payment 2024-001",
    "is_processing": false,
    "is_reconciled": false,
    "bank_account": {
        "id": "AG52olvLXP",
        "name": "Business Account CHF",
        "iban": "CH93 0076 2011 6238 5295 7",
        "currency": "CHF"
    },
    "matches": []
}

Delete a bank transaction

delete

/bank_transaction/{id}

Deleting a bank transaction will also remove all associated matches and reconciliations.

Example response

// HTTP 204 No Content

List bank transactions

get

/bank_transaction

Returns a paginated list of bank transactions. The list endpoint accepts the same query parameters as described above and returns an array of bank transaction objects in the data property.

Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.

Example response

// HTTP 200 OK
{
    "data": [
        {
            "id": "v7rnRjBn9o",
            "bank_account_id": "AG52olvLXP",
            "acc_serv_ref": "202401150001",
            "entry_acc_serv_ref": "202401150001-1",
            "end_to_end_id": "NOTPROVIDED",
            "document_date": "2024-01-15",
            "booking_date": "2024-01-15",
            "value_date": "2024-01-15",
            "amount": -125.5,
            "currency": "CHF",
            "reference": "RF18 5390 0754 7034 2",
            "name": "ACME Corporation AG",
            "text": "Invoice payment 2024-001",
            "is_processing": false,
            "is_reconciled": false,
            "bank_account": null,
            "matches": []
        }
        // ... more transactions
    ],
    "links": {
        "first": "https://api.strawblond.com/bank_transaction?page=1",
        "last": "https://api.strawblond.com/bank_transaction?page=10",
        "prev": null,
        "next": "https://api.strawblond.com/bank_transaction?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "path": "https://api.strawblond.com/bank_transaction",
        "per_page": 50,
        "to": 50,
        "total": 487
    }
}