Bank transactions
List, get, and delete bank transactions for a bank account, and upload statements as JSON lines or a file.
| SDK service | client.BankTransactions (BankTransactionsService) |
| FreeAgent docs | dev.freeagent.com/docs/bank_transactions |
| Sample app | /bank-transactions (list), /bank-transactions/detail (get, delete, uploads) |
Pagination patterns: see Pagination. Bank account links: see Linked resources. Cluster context: see Banking entity map.
Nested bank_transaction_explanations on GET use the fields documented on the bank transactions page. Create, update, and delete for explanations are handled by client.BankTransactionExplanations, not this service.
A successful statement upload means FreeAgent accepted the payload. It does not confirm that every line was imported. List the account, or pass lastUploaded: true, to see the result.
Methods
ListAsync
Task<PaginatedResponse<BankTransaction>> ListAsync(
int page = 1,
int perPage = 25,
BankAccountReference? bankAccount = null,
long? bankAccountId = null,
BankTransactionView? view = null,
DateOnly? fromDate = null,
DateOnly? toDate = null,
DateTimeOffset? updatedSince = null,
bool? lastUploaded = null,
CancellationToken cancellationToken = default)
| Parameter | Type | Required | Default | Wire |
|---|---|---|---|---|
page |
int |
No | 1 |
page |
perPage |
int |
No | 25 |
per_page (max 100) |
bankAccount |
BankAccountReference? |
Yes* | null |
bank_account (URI) |
bankAccountId |
long? |
Yes* | null |
bank_account (URI built from id) |
view |
BankTransactionView? |
No | null |
view |
fromDate |
DateOnly? |
No | null |
from_date |
toDate |
DateOnly? |
No | null |
to_date |
updatedSince |
DateTimeOffset? |
No | null |
updated_since (ISO 8601) |
lastUploaded |
bool? |
No | null |
last_uploaded |
cancellationToken |
CancellationToken |
No | default |
- |
* Supply bankAccount or bankAccountId, not both.
HTTP: GET /v2/bank_transactions
Returns: One page of bank transactions for the bank account.
Client validation: page ≥ 1; perPage between 1 and 100; a bank account is required.
Sample:
var page = await client.BankTransactions.ListAsync(
bankAccountId: bankAccountId,
view: BankTransactionView.Unexplained);
ListAutoPagingAsync
IAsyncEnumerable<BankTransaction> ListAutoPagingAsync(
int perPage = 25,
BankAccountReference? bankAccount = null,
long? bankAccountId = null,
BankTransactionView? view = null,
DateOnly? fromDate = null,
DateOnly? toDate = null,
DateTimeOffset? updatedSince = null,
bool? lastUploaded = null,
CancellationToken cancellationToken = default)
Accepts the same filters as ListAsync (except page). Loops until all pages are yielded.
Sample:
await foreach (var transaction in client.BankTransactions.ListAutoPagingAsync(bankAccountId: bankAccountId))
{
Console.WriteLine($"{transaction.DatedOn} {transaction.Amount} {transaction.Description}");
}
GetBankTransactionAsync
Task<BankTransaction> GetBankTransactionAsync(
long bankTransactionId,
CancellationToken cancellationToken = default)
| Parameter | Type | Required | Default | Wire |
|---|---|---|---|---|
bankTransactionId |
long |
Yes | - | path :id |
cancellationToken |
CancellationToken |
No | default |
- |
HTTP: GET /v2/bank_transactions/:id
Returns the transaction and any nested bank_transaction_explanations.
DeleteBankTransactionAsync
Task DeleteBankTransactionAsync(
long bankTransactionId,
CancellationToken cancellationToken = default)
| Parameter | Type | Required | Default | Wire |
|---|---|---|---|---|
bankTransactionId |
long |
Yes | - | path :id |
cancellationToken |
CancellationToken |
No | default |
- |
HTTP: DELETE /v2/bank_transactions/:id
FreeAgent deletes a transaction only when it is fully unexplained or has no explanations.
The official docs page currently titles this operation “Delete a bank transaction explanation” and shows DELETE /v2/bank_transaction/:id (singular). The SDK calls the plural path used by the rest of the resource.
UploadBankStatementAsync
Task UploadBankStatementAsync(
UploadBankStatementRequest request,
BankAccountReference? bankAccount = null,
long? bankAccountId = null,
CancellationToken cancellationToken = default)
| Parameter | Type | Required | Default | Wire |
|---|---|---|---|---|
request |
UploadBankStatementRequest |
Yes | - | statement array |
bankAccount |
BankAccountReference? |
Yes* | null |
query bank_account |
bankAccountId |
long? |
Yes* | null |
query bank_account |
cancellationToken |
CancellationToken |
No | default |
- |
* Supply bankAccount or bankAccountId, not both.
HTTP: POST /v2/bank_transactions/statement?bank_account=
Each line requires dated_on. description, amount, fitid, and transaction_type are optional on the wire. The SDK omits unset optional fields. FreeAgent defaults an omitted type to OTHER.
Client validation: request must contain at least one statement line.
A successful response means the upload was accepted, not that every line was imported.
Sample:
await client.BankTransactions.UploadBankStatementAsync(
new UploadBankStatementRequest(
[
new BankStatementTransaction
{
DatedOn = new DateOnly(2019, 7, 1),
Amount = -100m,
Description = "Local Council",
FitId = "049b807d-83ea-4d98-854c-e84b18775d31"
}
]),
bankAccountId: bankAccountId);
UploadBankStatementFileAsync
Task UploadBankStatementFileAsync(
UploadBankStatementFileRequest request,
BankAccountReference? bankAccount = null,
long? bankAccountId = null,
CancellationToken cancellationToken = default)
| Parameter | Type | Required | Default | Wire |
|---|---|---|---|---|
request |
UploadBankStatementFileRequest |
Yes | - | multipart statement file part |
bankAccount |
BankAccountReference? |
Yes* | null |
query bank_account |
bankAccountId |
long? |
Yes* | null |
query bank_account |
cancellationToken |
CancellationToken |
No | default |
- |
* Supply bankAccount or bankAccountId, not both.
HTTP: POST /v2/bank_transactions/statement?bank_account= as multipart/form-data
FreeAgent recommends OFX and also accepts QIF and some CSV formats.
Client validation: the statement stream must contain data.
Models
| Model | Role |
|---|---|
BankTransaction |
Transaction returned by list and get |
BankTransactionExplanation |
Nested explanation on a transaction |
BankTransactionView |
List view filter |
BankStatementTransaction |
One JSON statement line |
BankStatementTransactionType |
Statement transaction_type wire values |
UploadBankStatementRequest |
JSON statement upload |
UploadBankStatementFileRequest |
File statement upload |