Financial mutations
Financial mutations are the transactions on your financial accounts.
List all ids and versions
Returns all financial mutations in the administration. The list contains the id and the version of the financial mutation.
Check if the version of the financial mutation is newer than the version you have stored locally, use the POST
variant for fetching financial mutations with the given ids.
Required scope(s)
bank
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
filterFilters are key:value terms separated by commas (e.g. period:this_year,state:all). Any filter you pass replaces the defaults below entirely, so include every key you need — in particular pass an explicit period (a named period or a YYYYMMDD..YYYYMMDD range) to look beyond the default financial year. Available filters:
| Filter | Type | Default | Description |
|---|---|---|---|
| period | String | this_year | This can either be the description of a period (this_week, prev_week, next_week, this_month, prev_month, next_month, this_quarter, prev_quarter, next_quarter, this_year, prev_year, next_year) or a custom period (201301..201302, 20130101..20130131) |
| state | String | Can be all, unprocessed or processed | |
| mutation_type | String | Can be all, debit or credit | |
| financial_account_id | String |
List all ids and versions › Responses
IDs and versions of records
idversionFetch financial mutations with given ids
Given a list of financial mutation ids, returns the financial mutation information belonging to the financial mutation. Returns a maximum of 100 financial mutations, even if more ids are provided.
Required scope(s)
bank
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Fetch financial mutations with given ids › Responses
A financial mutation
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
amountcodedatemessagecontra_account_namecontra_account_numberstatesettlement_stateamount_opensepa_fieldsbatch_referencefinancial_account_id^\d+$A unique record identifier
currencyISO 4217 currency code
original_amountcreated_atupdated_atversionfinancial_statement_id^\d+$A unique record identifier
processed_ataccount_servicer_transaction_idLinks a financial mutation to a booking
Linking a booking to a financial mutation allows you to process financial mutations. Financial mutations can be linked to invoices, documents, ledger accounts and payment batches.
Required scope(s)
bank
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Links a financial mutation to a booking › Request Body
booking_typeThe type of record to link the mutation to.
booking_id^\d+$The id of the record to link, of the type set in booking_type (e.g. the ledger account id when booking_type is LedgerAccount).
The booking amount, in the administration's base currency. This is
the field that carries the amount for most booking types; when
linking a payment to an invoice it is the base-currency counterpart
of price. For booking_type LedgerAccount send the amount
here — price is ignored. Both a decimal and a string '10,95' are
accepted.
Whether to send a positive or a negative amount depends on
booking_type:
booking_type | Amount |
|---|---|
SalesInvoice, ExternalSalesInvoice, Document | Always positive. The payment direction is taken from the financial mutation, so refunds and credit notes also take a positive amount, whichever way the money moved |
LedgerAccount | Positive books in the same direction as the mutation, negative against it. Splitting a mutation over several bookings takes one request per part: an outgoing mutation of -95 consisting of 100 in costs and 5 received back takes one request with 100 and one with -5. One exception: once an incoming mutation has more booked than its own amount (its open amount went negative), positive and negative swap — a positive amount then books against the mutation |
VatDocument | The amount as it appears on the VAT return: positive when VAT is payable, negative for a refund |
NewPurchaseInvoice, NewReceipt | Positive when the mutation is outgoing (a purchase you paid), negative when it is incoming (money received back) |
Payment, PaymentTransaction, PaymentTransactionBatch, PurchaseTransactionBatch, PurchaseTransaction | Ignored — the amount comes from the record being linked |
Amount in the booking's own currency, used when linking a payment to
an invoice. The same positive/negative rules apply as for
price_base (see the table there). For a foreign-currency invoice both price and price_base
are required; otherwise price_base alone is enough. Only used when
booking_type is SalesInvoice, ExternalSalesInvoice, Document
or VatDocument; every other booking type takes its amount from
price_base or ignores it. Both a decimal and a string '10,95' are
accepted.
descriptionpayment_batch_identifierproject_id^\d+$Should be a valid project id.
mark_open_sepa_transaction_as_paidLinks a financial mutation to a booking › Responses
Status code
Unlinks a booking from a financial mutation
Unlinks a booking from a financial mutation.
Required scope(s)
bank
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Unlinks a booking from a financial mutation › Request Body
booking_typeCan be Payment or LedgerAccountBooking.
booking_id^\d+$ · requiredA unique record identifier
Unlinks a booking from a financial mutation › Responses
A financial mutation
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
amountcodedatemessagecontra_account_namecontra_account_numberstatesettlement_stateamount_opensepa_fieldsbatch_referencefinancial_account_id^\d+$A unique record identifier
currencyISO 4217 currency code
original_amountcreated_atupdated_atversionfinancial_statement_id^\d+$A unique record identifier
processed_ataccount_servicer_transaction_idGet a financial mutation by id
Returns a single financial mutation in the administration.
Required scope(s)
bank
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
id^\d+$ · requiredA unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
Get a financial mutation by id › Responses
A financial mutation
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
amountcodedatemessagecontra_account_namecontra_account_numberstatesettlement_stateamount_opensepa_fieldsbatch_referencefinancial_account_id^\d+$A unique record identifier
currencyISO 4217 currency code
original_amountcreated_atupdated_atversionfinancial_statement_id^\d+$A unique record identifier
processed_ataccount_servicer_transaction_idList all financial mutations
Returns a list of financial mutations in the administration. Limited to 100 financial mutations. If you need more financial mutations, use the synchronize API.
Required scope(s)
bank
path Parameters
administration_id^\d+$ · requiredThe unique identifier of the administration
A unique record identifier
format^(.(json|xml))?$ · requiredThe format in which the response is given, can be empty to use the default format
query Parameters
filterFilters are key:value terms separated by commas (e.g. period:this_year,state:unprocessed). Any filter you pass replaces the defaults below entirely, so include every key you need — in particular pass an explicit period (a named period or a YYYYMMDD..YYYYMMDD range) to look beyond the default financial year. Available filters:
| Filter | Type | Default | Description |
|---|---|---|---|
| period | String | this_year | A named period (this_week, prev_week, next_week, this_month, prev_month, next_month, this_quarter, prev_quarter, next_quarter, this_year, prev_year, next_year) or a custom range (201301..201302, 20130101..20130131) |
| state | String | all | all, unprocessed, processed or auto_booked |
| mutation_type | String | all | all, debit or credit |
| financial_account_id | Integer | Restrict to a single financial account | |
| amount_from | String | Lower bound on the absolute mutation amount (negative input is treated as positive) | |
| amount_to | String | Upper bound on the absolute mutation amount |
Multiple values for state and mutation_type can be combined with a pipe, e.g. state:unprocessed|processed.
List all financial mutations › Responses
A list of financial mutations
id^\d+$A unique record identifier
administration_id^\d+$A unique record identifier
amountcodedatemessagecontra_account_namecontra_account_numberstatesettlement_stateamount_opensepa_fieldsbatch_referencefinancial_account_id^\d+$A unique record identifier
currencyISO 4217 currency code
original_amountcreated_atupdated_atversionfinancial_statement_id^\d+$A unique record identifier
processed_ataccount_servicer_transaction_id