Moneybird API Integration: Filtering, Pagination, OAuth, and Key Technical Limitations Explained
- Dr. Themo Voswinckel ⎪Co-Founder
- 6 days ago
- 4 min read
Updated: 5 days ago
Moneybird is a cloud-based accounting software primarily used by freelancers, small businesses, and SMEs in the Netherlands and parts of the DACH region. It focuses on simplifying invoicing, expense tracking, VAT handling, and bank reconciliation through a clean, user-friendly interface and strong local compliance coverage.
Because of its strong foothold in the Dutch SME market, having an integration to Moneybird is an important success factor for SaaS products, to automate invoice creation, contact synchronization, and financial data exchange.
However, it’s important to understand how the Moneybird API is structured, where it differs from more conventional accounting APIs, and how Maesn abstracts these particularities through its Unified API to enable scalable integrations with Moneybird and 27+ additional systems.
Key Takeaways
The Moneybird API requires the response format (.json / .xml) to be defined in the URL, which differs from standard content negotiation via headers.
Filtering in the Moneybird API is implemented via dedicated /filter endpoints and key:value syntax, not through conventional query parameters.
The Moneybird API does not return total record counts in paginated responses, requiring iterative page traversal to determine dataset size.
Documentation inconsistencies (e.g. deprecated but still documented fields) can require additional validation and testing effort.
When integrating via Maesn, responses are always normalized to JSON and mapped to a common data model and unifies filtering and pagination across all systems, including background calls to determine total pages where necessary.
Maesn enables scalable integrations with Moneybird and 27+ additional accounting systems without multiplying system-specific logic.
The Moneybird API response format differs between json and XML and is part of the URL itself
The Moneybird API follows a mostly REST-style design, but with several structural decisions that differ from what many teams expect from modern APIs.
One of the first things developers notice is that the response format is part of the URL itself. Instead of relying on headers, every endpoint explicitly defines the format, for example:
/contacts.json
/invoices.xmlThis means the format choice is hard-coded into the endpoint, not negotiated via Accept headers. While this is technically simple, it requires extra attention when building generic API clients or SDKs that assume content negotiation.
With Maesn all Moneybird responses are always normalized to JSON and mapped onto a common data model. This removes format handling and system-specific response shapes entirely.
Filtering in the Moneybird API Uses Dedicated Filter Endpoints
In the Moneybird API, filtering is not implemented through standard query parameters alone. Instead, it requires calling dedicated /filter endpoints (e.g. /contacts/filter.json) combined with a filter query parameter using a key:value syntax.
When integrating via Maesn, filtering is unified across all systems. Moneybird’s endpoint structure is handled internally, and all responses are normalized to JSON and mapped onto our common data model. As a result, product teams work against one stable schema and one consistent filtering contract - independent of how Moneybird structures its native API.
The Moneybird API Does Not Return the Total Number of Pages in Pagination
The Moneybird API uses page and per_page parameters for pagination, with a default page size of up to 25 records. However, it does not return the total number of records or pages in the response. Instead, it relies on the HTTP Link header to indicate whether a rel="next" or rel="previous" page exists. This means that if your integration needs to know how many total records or pages are available - for example to show progress, calculate workload size, or confirm that a full sync is complete - you must iterate through all pages until no rel="next" header is returned. In practice, this requires additional requests to determine the full dataset size.
When integrating via Maesn, pagination works consistently across all systems: Maesn performs an additional call in the background to determine the maximum number of pages and always returns that information, so your product can rely on a stable and predictable pagination structure independent of Moneybird’s native behavior.
Inconsistencies in the Moneybird API Documentation You Should Be Aware Of
One thing product teams regularly run into when integrating with the Moneybird API is documentation drift.
A concrete example is the handling of certain contact fields. Some fields are marked as deprecated in change logs or behaviour, yet still appear in parts of the official API documentation. This can lead to situations where:
Fields are documented but rejected or ignored by the API
PATCH and POST behaviour differs from what the docs suggest
Trial-and-error is required to determine the actual supported payload
This does not make the API unusable, but it does mean teams should budget time for validation and testing beyond the documentation.
With Maesn: Field-level differences and system-specific quirks are abstracted behind a stable common data model, reducing the need to track vendor-specific deprecations or undocumented behaviour in product code.
Typical Integration Pitfalls When Building Directly Against the Moneybird API
Teams building a native Moneybird integration often underestimate the combined effect of:
OAuth token lifecycle management
Non-standard filtering paths
Missing pagination totals
Documentation inconsistencies
None of these issues are blockers on their own. But together, they increase the maintenance cost of a direct integration over time - especially if Moneybird is only one of several accounting systems you plan to support.
With Maesn all these integration-specific differences are handled once, allowing product teams to focus on product behaviour rather than system-specific plumbing.
