How to integrate with Moneybird: Versions decide what changed

Connecting to Moneybird is the ordinary half. You register an application, your customer authorises it, and you hold a bearer token. Moneybird offers a personal token as the shortcut and describes its blast radius plainly: it “is similar to a password and gives access to your entire company account”. For anything with customers in it, the OAuth route is the one.

Two details of that flow shape what you build afterwards. The first is who may agree: Moneybird states that the user should be owner of the administration, so consent is not something an arbitrary colleague can give. The second is who gets the credit for what follows.

On authorisation Moneybird “creates a special API user”, and “all actions performed by your application, will be named based on the application you registered”. Your writes appear in the customer’s history under your product’s name rather than under the person who connected it, which is usually what you want and always worth knowing before a support conversation about it.

One more thing sits between the token and the first useful call: an administration id. It is part of every path, and a customer can have more than one. Through us that selection is part of the connect flow rather than a field you collect, because moneybird is one of the systems where the interactive flow stores the choice and replays it on later requests.

You are not obliged to use it. The selection step exists so your customer settles the administration once, but you can skip it and name the company on each call instead, which is the route to take when your own product already knows which administration it means. Both paths end at the same account key, and the choice is yours rather than the system’s.

Which objects a connection reaches, field by field, is on the Moneybird API page rather than repeated here. What the rest of this piece is about is the part that is not a list: how you find out that something changed.

Moneybird publishes six scopes. Five of them name a working area and one names a data type, and the object most integrations are built around is not in the list at all.

The documentation is explicit about the consequence: “either the sales_invoices, documents, estimates, bank or settings scope is required to access contacts … Having access to only time_entries will not allow you to access contacts.” So contacts arrive as a side effect of asking for something else.

This matters at the consent screen rather than in your code. A customer who is asked for the bank scope so that your product can read a contact record will read that request as a request about their bank. There is no narrower ask available, so the honest move is to explain the one you make instead of looking for a smaller one.

It also removes a design option. Some systems let you separate a read-only integration from a writing one at the scope level. Here the same five scopes carry both, so the boundary between reading and writing is one you enforce on your side.

In our coverage data moneybird has no readable Customers object and no readable Suppliers object. Both sit on not supported in all five columns. That is not a gap in the data, it is the shape of the system: Moneybird keeps one party record and distinguishes roles on the documents that reference it.

It is a property moneybird shares with three other connected systems rather than a peculiarity of its own. What makes it worth a section is the second half: Contacts is also the only object here that we support for reading, creating and updating at once.

Read the two halves together and the integration writes itself in outline. Your partner data round-trips: you read contacts, you create them and you update them. Everything else is a read at best, so a product that plans to push documents into this system is planning against the on-demand column rather than against what is enabled.

The mapping question that follows is where a unified model earns its keep. If your product holds customers and suppliers as separate types, something has to fold them onto one record on the way in and unfold them on the way out. The shared data model is where that lives, and it is the same code whether the system underneath keeps one party record or three.

Moneybird has a webhook system, and it is a thorough one. The premise is stated the way you would hope: “Instead of querying the API at a certain interval, Moneybird will notify you about changes to information in the bookkeeping.”

The catalogue behind that sentence is large. The events page lists 343 event types for the enabled_events field, spread across 49 top-level groups, and you may subscribe to a whole group by naming its prefix rather than enumerating its members.

The delivery mechanics are equally complete. Your endpoint is checked for a 200 at registration. A failure is retried ten times at widening intervals. Every push carries an Idempotency-Key that is unique per delivery, which is what makes those retries safe to accept twice.

One property separates this from most event systems worth comparing it to. The payload is not a pointer. It carries entity_type, entity_id, action and then the whole entity, and in Moneybird’s own example an invoice arrives with its contact object nested inside it, addresses and mandate fields included.

That is convenient and it is a decision you inherit. A full entity in a webhook body means customer data lands in your logs unless you keep it out of them, which is a retention question rather than an integration one.

What state each delivery ended in is recorded on the webhook itself, because Moneybird keeps the last status code and body for debugging. That is the same information the logging model exposes for calls that run through us.

Everything above describes what the vendor publishes. What a connection through us uses today is the version index in the next section, and events on this system are switched on by request rather than by default.

Our own documentation sits between those two facts and is worth reading in full before you plan around either. It describes the subscription for this system concretely, naming four resources and three event types, and it specifies the call that creates one per customer.

Both facts belong in the same paragraph because a plan built on either alone goes wrong. A system with a documented catalogue is not a system without events, and an interface that does not carry them today is not one that never will. The event model is where that distinction lives, and on this system the pull half is currently the whole of it.

So the useful question is what the pull stands on. On most systems the answer is a modified-since timestamp. Here it is something better, and Moneybird documents it for exactly this purpose rather than leaving you to assemble it.

The synchronisation endpoints answer the freshness question with versions instead of clocks. A GET returns every record in the administration as an id and a version number. You compare those against what you hold. Then a POST to the same path returns the records you name.

Counted in Moneybird’s published OpenAPI description, 11 of its 211 documented paths carry this pattern, contacts and sales invoices among them, along with estimates, financial mutations and the document types. So it covers the objects a bookkeeping integration moves, and it does not cover everything.

Two properties make it worth building on. A version comparison does not care about clock skew or time zones, which on a system that resolves timestamps through a header, then an administration setting, then UTC is a category of bug you simply do not open.

And it catches up. A worker that was down for a day asks the same question on the next run and gets a complete answer, with no cursor to have preserved.

Moneybird’s throttling is generous in its framing and specific in its unit. Usage is unlimited within the subscription and permissions of the account you connect, and then one sentence sets the unit: “To prevent fraud and abuse, requests to the API are throttled on a per ip-address basis.”

The number is 150 requests per five minutes, and 50 per five minutes for everything under the reporting endpoints. Read the unit again, because it is the part that decides an architecture. The budget belongs to the address, not to the token, the customer or the administration.

For a single-tenant script that is roomy. For a direct integration serving many customers from one egress address it is a single pool, and adding customers does not add capacity: 150 per five minutes is 30 a minute, whether one administration is behind it or four hundred.

Through Maesn that arithmetic stops being yours. The calls to Moneybird are made from our infrastructure, so the address the limit counts is ours and the scheduling against it happens on our side of the interface. What reaches you when the ceiling is hit is the standardised error below, not a budget you have to size your own egress for.

There is a documented way out, and it is a conversation rather than a parameter: “Partners with popular Oauth Applications can request a per-administration limit instead of ip-address limits.” Worth knowing early, because the request is easier to make before the limit is the reason you are making it.

One more sentence from the same page changes how you verify work. Moneybird caches reads: “we strongly advise against using GET methods for verification purposes as this may result in an incomplete result. To verify API requests, developers can check the response status codes.”

So a read-back after a write is not a confirmation, and the status code is. Where a write is queued rather than immediate, the asynchronous path reports the outcome instead of asking you to poll for it.

Filtering happens on a dedicated path rather than through query parameters on the list call. You ask /contacts/filter.json and pass a filter string of comma-separated key:value terms. That much the previous version of this article had right, and the sentence next to it in the reference is the one that costs time.

Moneybird states it plainly: “Any filter you pass replaces the defaults below entirely, so include every key you need.” A filter is not a narrowing of the default set, it is a replacement of it. Passing one key drops every condition you assumed was implied, and the response looks plausible while being wrong.

Pagination is conventional and one expectation about it is not. You get page and per_page, the default page size is 50 and the maximum is 100. What you do not get is a total. Moneybird returns a Link header with rel="next" and rel="prev", so the size of a result set is something you discover by reaching the end of it.

That is a progress-bar problem more than a correctness one, and it has an obvious interaction with the section above: walking every page to learn how many there were spends the same address budget as the sync itself. Both numbers describe a direct integration. Through Maesn you send one limit and one page against one pagination contract, and Moneybird’s page size, its ceiling and its missing total stop being yours to remember.

What we take off the list:

• The administration selection. Choosing which administration a token applies to is part of the connect flow and is stored for later calls, so it is not a field you collect, validate and thread through every request.
• The party mapping. One contact record arrives as the same shape your other systems produce, so a product holding customers and suppliers separately does not grow a moneybird-shaped branch.
• The response shape. Format in the path, ids that must survive as strings and a filter contract of its own stop at our boundary rather than reaching your models.

What stays with you, and two of these are decisions rather than tasks:

• The cadence, and the arithmetic behind it. Nothing turns this connection into an event source today. How fresh your product needs to be, against a budget that belongs to an address rather than to a customer, is yours to choose.
• What you tell a customer the consent covers. There is no contacts scope to ask for, so the explanation on your side does work the permission screen cannot.
• Retention of what an event would carry. If subscriptions become part of your design later, the payload is a full entity. Where that lands and how long it stays is a decision no interface makes for you.