Financial mutations

cURL Ruby

`/financial_mutations`	`GET`	List all financial mutations
`/financial_mutations/synchronization`	`GET`	List all ids and versions
`/financial_mutations/synchronization`	`POST`	Fetch financial mutations with given ids
`/financial_mutations/:id`	`GET`	Get a financial mutation by id
`/financial_mutations/:id/link_booking`	`PATCH`	Links a financial mutation to a booking
`/financial_mutations/:id/unlink_booking`	`DELETE`	Unlinks a booking from a financial mutation

List all financial mutations

GET /financial_mutations(.:format)

Returns a list of financial mutations in the administration. Limited to 100 financial mutations. If you need more financial mutations, use the synchronize API.

The filter argument allows you to filter on the list of financial mutations. Filters are a combination of keys and values, separated by a comma: key:value,key2:value2. The most common filter method will be period: period:this_month. Filtering works the same as in the web application, for more advanced examples, change the filtering in the web application and learn from the resulting URI.

Parameters

Parameter	Type	Description
`filter`	`String`

Example: returns all financial mutations of an administration

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations.json?
    
    

Response

        
          
          Status: 200 OK

[
  {
    "id": "426664168833156800",
    "administration_id": 123,
    "amount": "100.0",
    "code": null,
    "date": "2024-07-16",
    "message": "Factuur",
    "contra_account_name": null,
    "contra_account_number": "",
    "state": "unprocessed",
    "amount_open": "100.0",
    "sepa_fields": null,
    "batch_reference": null,
    "financial_account_id": "426664168815331004",
    "currency": "EUR",
    "original_amount": null,
    "created_at": "2024-07-16T08:31:21.268Z",
    "updated_at": "2024-07-16T08:31:21.268Z",
    "version": 1721118681,
    "financial_statement_id": "426664168832108223",
    "processed_at": null,
    "account_servicer_transaction_id": null,
    "payments": [
      {
        "id": "426664168978908887",
        "administration_id": 123,
        "invoice_type": "SalesInvoice",
        "invoice_id": "426664168955840211",
        "financial_account_id": "426664168815331004",
        "user_id": 2,
        "payment_transaction_id": null,
        "transaction_identifier": null,
        "price": "80.0",
        "price_base": "80.0",
        "payment_date": "2024-07-16",
        "credit_invoice_id": null,
        "financial_mutation_id": "426664168833156800",
        "ledger_account_id": "426664168975763158",
        "linked_payment_id": null,
        "manual_payment_action": null,
        "created_at": "2024-07-16T08:31:21.406Z",
        "updated_at": "2024-07-16T08:31:21.406Z"
      }
    ],
    "ledger_account_bookings": [
      {
        "id": "426664168871954115",
        "administration_id": 123,
        "financial_mutation_id": "426664168833156800",
        "ledger_account_id": "426664168869856962",
        "project_id": null,
        "description": "Ledger account booking",
        "price": "20.0",
        "created_at": "2024-07-16T08:31:21.304Z",
        "updated_at": "2024-07-16T08:31:21.304Z"
      }
    ]
  }
]

Example: returns all mutations filtered on period

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations.json?filter=period%3Athis_month
    
    

Response

        
          
          Status: 200 OK

[
  {
    "id": "426664169079572188",
    "administration_id": 123,
    "amount": "100.0",
    "code": null,
    "date": "2024-07-16",
    "message": "Factuur",
    "contra_account_name": null,
    "contra_account_number": "",
    "state": "unprocessed",
    "amount_open": "100.0",
    "sepa_fields": null,
    "batch_reference": null,
    "financial_account_id": "426664169061746392",
    "currency": "EUR",
    "original_amount": null,
    "created_at": "2024-07-16T08:31:21.503Z",
    "updated_at": "2024-07-16T08:31:21.503Z",
    "version": 1721118681,
    "financial_statement_id": "426664169078523611",
    "processed_at": null,
    "account_servicer_transaction_id": null,
    "payments": [
      {
        "id": "426664169215887091",
        "administration_id": 123,
        "invoice_type": "SalesInvoice",
        "invoice_id": "426664169192818415",
        "financial_account_id": "426664169061746392",
        "user_id": 2,
        "payment_transaction_id": null,
        "transaction_identifier": null,
        "price": "80.0",
        "price_base": "80.0",
        "payment_date": "2024-07-16",
        "credit_invoice_id": null,
        "financial_mutation_id": "426664169079572188",
        "ledger_account_id": "426664169212741362",
        "linked_payment_id": null,
        "manual_payment_action": null,
        "created_at": "2024-07-16T08:31:21.632Z",
        "updated_at": "2024-07-16T08:31:21.632Z"
      }
    ],
    "ledger_account_bookings": [
      {
        "id": "426664169113126623",
        "administration_id": 123,
        "financial_mutation_id": "426664169079572188",
        "ledger_account_id": "426664169111029470",
        "project_id": null,
        "description": "Ledger account booking",
        "price": "20.0",
        "created_at": "2024-07-16T08:31:21.534Z",
        "updated_at": "2024-07-16T08:31:21.534Z"
      }
    ]
  }
]

Example: raises an error when there are too many mutations to return

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations.json?
    
    

Response

        
          
          Status: 400 Bad Request

{
  "error": "Too many financial mutations to return, please use sync API"
}

List all ids and versions

GET /financial_mutations/synchronization(.:format)

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. The filter argument allows you to filter the list of financial mutations. Filters are a combination of keys and values, separated by a comma: period:this_year,state:all. The available options for filtering are:

Filter	Type	Default	Description
period	`String`	`this_year`	This can either be the description of a period (`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`

Parameters

Parameter	Type	Description
`filter`	`String`

Example: retrieves the id's for synchronization

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations/synchronization.json?
    
    

Response

        
          
          Status: 200 OK

[
  {
    "id": "426664169978201932",
    "version": 1721118682
  },
  {
    "id": "426664169990784847",
    "version": 1721118682
  },
  {
    "id": "426664170001270610",
    "version": 1721118682
  }
]

Example: retrieves the id's for synchronization with a filter

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations/synchronization.json?filter=period%3Athis_month
    
    

Response

        
          
          Status: 200 OK

[
  {
    "id": "426664170087253848",
    "version": 1721118682
  },
  {
    "id": "426664170100885339",
    "version": 1721118682
  },
  {
    "id": "426664170113468254",
    "version": 1721118682
  }
]

Example: retrieves only unique ids

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations/synchronization.json?
    
    

Response

        
          
          Status: 200 OK

[
  {
    "id": "426664170201548644",
    "version": 1721118682
  },
  {
    "id": "426664170214131559",
    "version": 1721118682
  },
  {
    "id": "426664170227763050",
    "version": 1721118682
  }
]

Fetch financial mutations with given ids

POST /financial_mutations/synchronization(.:format)

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.

Parameters

Parameter	Type	Description
`ids`	`Array[integer]`	Required

Example: it retrieves financial mutations given by ids

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPOST \
  -d '{"ids":[426664170391340921,426664170403923836]}' \
  https://moneybird.com/api/v2/123/financial_mutations/synchronization.json
    
    

Response

        
          
          Status: 200 OK

[
  {
    "id": "426664170403923836",
    "administration_id": 123,
    "amount": "100.0",
    "code": null,
    "date": "2024-07-16",
    "message": "Factuur",
    "contra_account_name": null,
    "contra_account_number": "",
    "state": "unprocessed",
    "amount_open": "100.0",
    "sepa_fields": null,
    "batch_reference": null,
    "financial_account_id": "426664170352543602",
    "currency": "EUR",
    "original_amount": null,
    "created_at": "2024-07-16T08:31:22.766Z",
    "updated_at": "2024-07-16T08:31:22.766Z",
    "version": 1721118682,
    "financial_statement_id": "426664170402875259",
    "processed_at": null,
    "account_servicer_transaction_id": null,
    "payments": [

    ],
    "ledger_account_bookings": [

    ]
  },
  {
    "id": "426664170391340921",
    "administration_id": 123,
    "amount": "100.0",
    "code": null,
    "date": "2024-07-16",
    "message": "Factuur",
    "contra_account_name": null,
    "contra_account_number": "",
    "state": "unprocessed",
    "amount_open": "100.0",
    "sepa_fields": null,
    "batch_reference": null,
    "financial_account_id": "426664170352543602",
    "currency": "EUR",
    "original_amount": null,
    "created_at": "2024-07-16T08:31:22.754Z",
    "updated_at": "2024-07-16T08:31:22.754Z",
    "version": 1721118682,
    "financial_statement_id": "426664170390292344",
    "processed_at": null,
    "account_servicer_transaction_id": null,
    "payments": [

    ],
    "ledger_account_bookings": [

    ]
  }
]

Get a financial mutation by id

GET /financial_mutations/:id(.:format)

Returns a single financial mutation in the administration.

Example: returns financial mutation by the given id

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations/426664169546188564.json?
    
    

Response

        
          
          Status: 200 OK

{
  "id": "426664169546188564",
  "administration_id": 123,
  "amount": "100.0",
  "code": null,
  "date": "2024-07-16",
  "message": "Factuur",
  "contra_account_name": null,
  "contra_account_number": "",
  "state": "unprocessed",
  "amount_open": "100.0",
  "sepa_fields": null,
  "batch_reference": null,
  "financial_account_id": "426664169528362768",
  "currency": "EUR",
  "original_amount": null,
  "created_at": "2024-07-16T08:31:21.947Z",
  "updated_at": "2024-07-16T08:31:21.947Z",
  "version": 1721118681,
  "financial_statement_id": "426664169544091411",
  "processed_at": null,
  "account_servicer_transaction_id": null,
  "payments": [
    {
      "id": "426664169687746347",
      "administration_id": 123,
      "invoice_type": "SalesInvoice",
      "invoice_id": "426664169665726247",
      "financial_account_id": "426664169528362768",
      "user_id": 2,
      "payment_transaction_id": null,
      "transaction_identifier": null,
      "price": "80.0",
      "price_base": "80.0",
      "payment_date": "2024-07-16",
      "credit_invoice_id": null,
      "financial_mutation_id": "426664169546188564",
      "ledger_account_id": "426664169685649194",
      "linked_payment_id": null,
      "manual_payment_action": null,
      "created_at": "2024-07-16T08:31:22.082Z",
      "updated_at": "2024-07-16T08:31:22.082Z"
    }
  ],
  "ledger_account_bookings": [
    {
      "id": "426664169580791575",
      "administration_id": 123,
      "financial_mutation_id": "426664169546188564",
      "ledger_account_id": "426664169578694422",
      "project_id": null,
      "description": "Ledger account booking",
      "price": "20.0",
      "created_at": "2024-07-16T08:31:21.980Z",
      "updated_at": "2024-07-16T08:31:21.980Z"
    }
  ]
}

Example: returns 404 when the financial mutation does not exist

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XGET \
  https://moneybird.com/api/v2/123/financial_mutations/34123123.json?
    
    

Response

        
          
          Status: 404 Not Found

{
  "error": "record not found",
  "symbolic": {
    "id": "not_found"
  }
}

Links a financial mutation to a booking

PATCH /financial_mutations/:id/link_booking(.:format)

Linking a booking to a financial mutations allows you to process financial mutations. Financial mutations can be linked to invoices, documents, ledger accounts and payment batches.

Parameters

Parameter	Type	Description
`booking_type`	`String`	Required Can be `SalesInvoice`, `Document`, `LedgerAccount`, `PaymentTransactionBatch`, `PurchaseTransaction`, `NewPurchaseInvoice`, `NewReceipt`, `PaymentTransaction`, `PurchaseTransactionBatch`, `ExternalSalesInvoice`, `Payment` or `VatDocument`.
`booking_id`	`Integer`
`price_base`	`Decimal`	Both a decimal and a string ‘10,95’ are accepted.
`price`	`Decimal`	Both a decimal and a string ‘10,95’ are accepted.
`description`	`String`
`payment_batch_identifier`	`String`
`project_id`	`Integer`	Should be a valid project id.
`mark_open_sepa_transaction_as_paid`	`Boolean`

Example: links a sales invoice to the financial mutation

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"SalesInvoice","booking_id":426664170575890313,"price_base":"363.0"}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664170521364354/link_booking.json
    
    

Response

        
          
          Status: 200 OK

Example: links a purchase invoice to the financial mutation

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"Document","booking_id":426664170895706014,"price_base":-100}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664170853762967/link_booking.json
    
    

Response

        
          
          Status: 200 OK

Example: creates a new purchase invoice

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"NewPurchaseInvoice","price_base":-100}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664171016292263/link_booking.json
    
    

Response

        
          
          Status: 200 OK

Example: creates a new receipt

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"NewReceipt","price_base":-100}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664171143169970/link_booking.json
    
    

Response

        
          
          Status: 200 OK

Example: creates a ledger account booking for a positive amount

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"LedgerAccount","booking_id":426664171321427903,"price_base":100}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664171306747837/link_booking.json
    
    

Response

        
          
          Status: 200 OK

Example: creates a ledger account booking for a negative amount

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"LedgerAccount","booking_id":426664171470325708,"price_base":100}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664171457742794/link_booking.json
    
    

Response

        
          
          Status: 200 OK

Example: creates a booking for a foreign invoice with an exchange rate difference

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XPATCH \
  -d '{"booking_type":"LedgerAccount","booking_id":426664171833133032,"price_base":1.48}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664171606640599/link_booking
    
    

Response

        
          
          Status: 200 OK

Unlinks a booking from a financial mutation

DELETE /financial_mutations/:id/unlink_booking(.:format)

Parameters

Parameter Type Description

Parameter	Type	Description
`booking_type`	`Camelcasestring`	Required Can be `Payment` or `LedgerAccountBooking`.
`booking_id`	`Integer`	Required

booking_type

Camelcasestring

Required

Can be Payment or LedgerAccountBooking.

booking_id

Integer

Required

Example: unlinks a payment booking

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XDELETE \
  -d '{"booking_type":"Payment","booking_id":426664172141414398}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664171947427824/unlink_booking.json
    
    

Response

        
          
          Status: 200 OK

{
  "id": "426664171947427824",
  "administration_id": 123,
  "amount": "100.0",
  "code": null,
  "date": "2024-07-16",
  "message": "Factuur",
  "contra_account_name": null,
  "contra_account_number": "",
  "state": "unprocessed",
  "amount_open": "100.0",
  "sepa_fields": null,
  "batch_reference": null,
  "financial_account_id": "426664171928553452",
  "currency": "EUR",
  "original_amount": null,
  "created_at": "2024-07-16T08:31:24.237Z",
  "updated_at": "2024-07-16T08:31:24.544Z",
  "version": 1721118684,
  "financial_statement_id": "426664171946379247",
  "processed_at": null,
  "account_servicer_transaction_id": null,
  "payments": [

  ],
  "ledger_account_bookings": [

  ]
}

Example: returns an error if booking type is invalid

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XDELETE \
  -d '{"booking_type":"foobar","booking_id":426664172555600915}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664172329108485/unlink_booking.json
    
    

Response

        
          
          Status: 400 Bad Request

{
  "error": "Booking Type isn't an option",
  "symbolic": {
    "booking_type": "in"
  }
}

Example: returns an error if booking id is not found

Request

    curl -s -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" \
  -XDELETE \
  -d '{"booking_type":"Payment","booking_id":123}' \
  https://moneybird.com/api/v2/123/financial_mutations/426664172707644441/unlink_booking.json
    
    

Response

        
          
          Status: 404 Not Found

{
  "error": "record not found",
  "symbolic": {
    "booking_id": "not_found"
  }
}