How to integrate with Exact Online: 5.000 calls a day, and every event you act on spends one

Exact Online is where a large share of Dutch and Belgian businesses keep their books, which is usually the reason a product ends up integrating with it. What makes it demanding is not the protocol. It is REST, it borrows OData’s query options and type names, and fetching a single record is unremarkable.

The difficulty is that there is no single Exact Online. The platform runs as separate regional environments, and an app belongs to exactly one of them. Inside an environment, data belongs to a division rather than to an account, and almost every resource URI carries it.

Three regional target systems are documented, each with its own callback, and only one of them supports the interactive flow that settles the division for you at connect time.

Two calls are worth knowing before anything else. /api/v1/current/Me?$select=CurrentDivision tells you which division you are in, and /api/v1/{division}/system/Divisions tells you which ones the granting user actually opened up to your app. Those are not the same set as the ones they can open themselves, which is the next paragraph.

On the consent screen the user chooses which divisions your app may read, and Exact documents the consequence with a worked example. A user with rights to divisions A, B and C grants your app A and B.

Asking for C then returns User division is not within division scope. Asking for D returns Wrong division. Two errors, two causes: the first is your app’s grant, the second is the user’s own access.

If you want the object coverage, the authentication options and the App Store listing in one place, that is the Exact Online API page. What follows is how to build against the platform without spending a customer’s daily allowance on your first sync.

Exact publishes two rate limits and they are the frame for everything else on this page. An app may make 60 API calls per company per minute and 5.000 per company per day. Exceeding either returns 429.

Read the scope carefully, because it cuts both ways. Exact’s restrictions page states that both limits are per app and per division, and company and division are the same thing in this documentation. So a customer running four divisions gives you four separate budgets, and you cannot borrow from one to finish a sync in another.

The minute limit is also not a bandwidth figure, because you are not allowed to use it in parallel. Exact, verbatim: parallel API calls are not allowed, all integrations must use sequential API calls. Multi-threaded requests and pipelining are named as things not to do. Sixty a minute therefore describes a queue, not a burst.

The second budget is the one nobody plans for. Exact allows no more than ten errors per API key, per user, per company, per endpoint and per hour. Past that the key is blocked from making further requests, the block lifts automatically after an hour, and it grows longer if the errors keep coming.

Which responses count is the part that changes how you write code: 400, 401, 403 and 404. A missing record is an error in this accounting. So the pattern of asking whether something exists and creating it if not is not merely wasteful here, it is a way to lock yourself out of one endpoint for an hour.

The same applies to retries. Exact asks you not to retry failing messages indefinitely and to separate transient errors from functional ones, because retrying a functional error is a loop that ends in a block rather than in a success.

Backoff, classification and the difference between a rejected call and a blocked client are the same problem on every system, which is why they sit in unified error handling rather than in each integration.

Exact’s reference documentation puts it in one line: most of the REST API have a page size of 60, the bulk and sync endpoints have a pagesize of 1000, and it is recommended to use the sync endpoints where possible.

Behind it are five API types, and most objects offer several of them. Picking the right one is not an optimisation, it is the difference between fitting inside a customer’s daily allowance and asking them to buy a Premium licence.

Two details will bite eventually. The Timestamp is a row version and has no relation to a date, so it cannot be compared with one or converted into one.

And Exact resets those values when it moves a division to another database, after which everything has to be synchronised again. The date of the last move is readable as DivisionMoveDate on the divisions endpoint, which makes the reset detectable rather than mysterious.

Paging is sequential by construction. A response longer than the page size carries a __next property with a $skiptoken, and the next request cannot be built until the previous response arrives. Since parallel calls are forbidden anyway, that is consistent rather than restrictive. How the same paging and filtering question looks across systems is unified pagination and filtering.

One more rule closes the loop: Exact applies mandatory filtering on single and bulk endpoints where a sync API exists. Leave the $filter out and you get a 400 naming the fields it expects. The platform is steering you onto the cheap path, and it is worth going.

Exact Online authenticates with OAuth, and the token lifecycle has one number in it that surprises almost everyone. An access token is valid for 600 seconds. A new one may not be requested before 570 seconds have passed since the last successful token call. Both numbers are Exact’s, and they are on two separate pages of its documentation.

Subtract them and the legal refresh window is 30 seconds wide, once every ten minutes. Ask too early and you get Rate limit exceeded: access_token not expired. Ask too late and the token is already gone.

The refresh token has rules of its own, and each one ends the same way. It is single use: reusing one returns 401, and only the most recently issued one is valid. Running several authorisation requests in parallel invalidates the earlier chain, which Exact reports as token is not allowed, because of invalid or empty chainId. And since July 2021 a refresh token expires after 30 days.

That last one is an operational fact rather than a technical one. A connection nobody touches for a month does not degrade, it stops, and the only way back is asking your customer to authorise again.

Maesn holds the tokens, refreshes them inside the window and keeps the connection alive, so what your code carries is an account key that does not expire on a schedule. The general shape of that is unified authentication.

Exact Online has webhooks, and they are the reason you do not have to poll for changes. What they will not tell you is which kind of change happened.

Exact’s own tutorial is explicit twice over: creating, updating or deleting a record all produce a notification, and the action is either UPDATE or DELETE, and when the complete account is deleted the action is DELETE, in all other cases the action will be UPDATE.

The second thing to know is what the notification contains, because it decides what an event costs you. Exact sends a Content object with the topic, the action, the division, the record’s Key and an ExactOnlineEndpoint to fetch it from, plus a HashCode for verification. It does not send the record.

So every event you act on is a call against the budget from earlier on this page. The notification itself is free, because the limits count the calls your app makes and Exact names webhooks as a way to stay under them. What costs is the fetch that follows, and an integration that fetches on every notification for a busy customer can spend a working day’s allowance on follow-up reads.

There is also a constraint that quietly decides where the subscription lives. Exact requires the callback URL to share the URL and domain of the redirect URI the app was registered with, over HTTPS, and validates it with an empty POST that has to answer 200 or 201.

Your app’s redirect URI points at Maesn, so the subscription is registered here and the normalised event is what continues to your service.

Three details in that payload matter. The subscription is created per customer, so every connected account is its own registration. You subscribe to CONTACT and receive CUSTOMER or SUPPLIER, because Exact splits the two on the way out. And filterDate and userId arrive empty, because Exact does not send them.

Those two empty fields are the honest part of unification. The same envelope carries a Xero event with userId filled and a Lexware Office event with both of them empty, exactly like this one.

A unified payload does not invent data the source never sent, which is the point of a common data model and the reason to read a null as a fact rather than as a gap. The subscription mechanics are the same call on every system, which is unified webhooks.

Finally, plan for delivery failures. Exact retries a notification ten times with a delay of two to the power of the attempt number, in minutes. The gap between the ninth attempt and the tenth is 1.024 minutes, and the whole ladder spans 34 hours.

That is generous, and it has a second effect worth designing for: a callback that was down all morning hands you a burst afterwards, and the burst still has to fit inside 60 calls a minute.

This is the failure mode to build for first, because it does not look like one. Exact’s response code table says it plainly: when a client performs a GET but has no rights to retrieve that information, status 200 is returned with an empty list of records.

Nothing in that response separates it from a customer who genuinely has no invoices. A sync that quietly returns nothing looks healthy on every dashboard you have, and the first person to notice is the customer, weeks later, asking why their data never arrived.

The defence is cheap and it is worth wiring in on day one. When a read comes back empty for an object you expect to be populated, check what the user actually granted with /api/v1/{division}/system/Divisions before you conclude the company is empty, and surface the difference to the customer rather than to your log.

Its louder sibling is 403, which is not one condition but eight. Reading them as one status is how a permissions problem gets classified as an outage.

Not every endpoint is available to every Exact Online customer. Availability follows the package they bought, and the failure is a 403 reading incompatible EOL functionality, which tells you nothing about which module is missing.

It is documented, though, and per endpoint rather than in a single list. Every entity page in the reference carries a line saying this endpoint is available for the following packages.

PurchaseOrders, for instance, is available for Manufacturing in all versions, for Professional Services in Plus, Professional and Premium only and for Wholesale and Distribution in all versions. Check it while choosing endpoints rather than while debugging a customer.

The same principle catches a case that is easy to blame on the platform: multi-currency. A journal in Exact Online has one currency unless variable currency is switched on for it, and a foreign-currency entry posted into a single-currency journal is rejected or misread.

That part is real. What is not is the idea that it can only be arranged by hand: the journal exposes both properties over the API, and the exchange rate endpoint accepts writes too.

We absorb the shape of the integration, not the rules of the platform. Five things stay with you, and it is cheaper to know that now than after the first customer call.

• The rate limit still reaches you. Only Maesn’s asynchronous endpoints absorb bursts. Everything synchronous passes the target system’s 429 through, so backoff for Exact Online is yours to implement. What the asynchronous path does and does not cover is asynchronous processing.
• Tax is not calculated by Maesn. We deliver the rates and structures as the system publishes them. What is owed, and on which basis, stays your model.
• Currency conversion is yours. We can read you the journal’s currency and whether it accepts others. Choosing a rate and standing behind it is a decision on your side.
• The App Store review is Exact’s decision. It runs in three stages, data and security, marketing and functional, and until it clears only the account that registered the app can authenticate. We prepare it and go through it with you as an official Exact partner, and we do not grant it.
• The maintenance window belongs in your scheduler. Exact documents that Exact Online and its APIs are unavailable between 4:00 and 4:30 in your local time, every day. A nightly job that starts at four will look like an outage once a day for as long as nobody moves it.