How to integrate with Twinfield: Five percent of the rate limit until certification
Twinfield publishes its limits precisely, and the precise version is stranger than the summary. The rate limit is four buckets rather than one number, a footnote drops two of them to five percent until your connection is certified, and certification is not optional. Before any of that applies you have to ask Twinfield twice where your customer's books actually live.
Who runs Twinfield, and in how many companies at once
Twinfield is Wolters Kluwer’s cloud accounting platform, and who sits in front of it shapes everything you build against it. It is built for accountancy practices that keep the books of many client companies, which is why almost every concept in the interface is scoped to a company rather than to a tenant.
Our own directory records it as serving the Netherlands, Belgium, Luxembourg and the United Kingdom, and Wolters Kluwer describes a partner community of more than 400 connected products.
That shape has a consequence you will meet on the first day. A customer who says “we use Twinfield” is frequently telling you about an organisation with dozens or hundreds of companies inside it, and a user whose access covers some of them.
Twinfield is on the list of target systems that use our interactive authentication flow rather than a plain redirect, so the company is chosen once at connect time and stored for the requests that follow. That is the default rather than the boundary: a connection can send the company parameter explicitly and overwrite what was stored, and the request that lists companies carries no company code at all. A logged-in user reaches every company their access covers.
What follows is the part of that arrangement a directory listing cannot show you: how the address is resolved, what a request costs, and what the object list means once you look at what the objects actually are. If you want the field-level view of what a connection reaches, that lives in our integrations directory alongside every other system.
Markets and partner count from Wolters Kluwer’s Twinfield partner page, checked 13 August 2026. The interactive authentication list is published in our own authentication documentation, where twinfield is one of fourteen entries.
A token, a cluster and a company code
Twinfield runs OpenID Connect over OAuth 2.0, and the authorisation half holds no surprises: you register a client on the developer portal, you send the user to login.twinfield.com, and you exchange the code for tokens. The surprise is that a token does not tell you where to send anything.
Twinfield is distributed across clusters, and your customer’s organisation lives on exactly one of them. To find out which, you call the accesstokenvalidation endpoint with the access token as a query parameter and read the twf.clusterUrl claim, which resolves to a host of the form https://api.<cluster>.twinfield.com. The same claim is available through the twf.organisation scope during authentication.
Every business call goes to that host. The login host is not the API host, and a request sent to the wrong one is not a routing detail you discover late, because nothing about it looks like an address problem.
Then there is the second lookup. The company code is mandatory in the SOAP header alongside the access token, and Twinfield states the circular problem this creates rather than leaving you to hit it: “Problem is that the company id or company code is not always known. It is possible to retrieve a list of companies by webservices but again company id or company code is mandatory.”
There is one documented way out. The request that lists companies is the one request you send with no company code in the header at all.
<!-- 1. Discover the companies. No CompanyCode here. --><soap:Header><Header xmlns="http://www.twinfield.com/"><AccessToken>2b128baa05dd3cabc61e5344</AccessToken></Header></soap:Header><!-- body: <list><type>offices</type></list> --><!-- 2. Everything else. CompanyCode is mandatory. --><soap:Header><Header xmlns="http://www.twinfield.com/"><AccessToken>2b128baa05dd3cabc61e5344</AccessToken><CompanyCode>001</CompanyCode></Header></soap:Header>
Header shape from the XML web services page and the authentication reference, checked 13 August 2026. Twinfield also recommends the Finder with type OFF for offices once the token is in hand.
The token lifetimes only make sense as a set. The authorisation code lasts five minutes, the access token an hour in the authorization code flow and twelve hours in the implicit flow, and the refresh token is documented at 788.940.000 seconds, which is twenty-five years.
You only receive a refresh token if the original request asked for the offline_access scope, and twf.organisationUser is mandatory just to sign in. A connection that is supposed to run unattended for years therefore depends on two scope strings being right once, at the beginning.
Which objects a connection reaches, and what each field is called on the way through, is on the Twinfield API page. The rest of this piece is about the things a coverage table cannot show: what a call costs, what the objects are underneath, and what happens when nobody tells you something changed.
Cluster resolution, scopes and the token lifetime table from Twinfield’s OpenID Connect documentation; the session and cluster sequence from the schematic flow. Both checked 13 August 2026.
Four credit buckets, and five percent of them before certification
Twinfield prices calls in a currency instead of capping them per second. Every call spends API credits, a query costs one and everything else costs three, and the credits are counted in four separate buckets at the same time. Exceed any of them and you get 429 Too Many Requests with the request unprocessed.
The definition of “query” is not the HTTP verb. In the web services every call is a POST. What decides the price is the SOAP action prefix, where Get, Query, Search and Load cost one credit, and for ProcessXml it is the root element, where list, read, columns, accountcode and accountcodes cost one. A write costs three.
So the cheap read and the expensive write travel over the same verb, and a limiter written around methods will mis-price both.
| Bucket | Certified | Not yet certified |
|---|---|---|
| Per IP address | 1.000 | 1.000 |
| Per client id | 1.000 | 50 |
| Per organisation id | 1.000 | 1.000 |
| Per client and organisation | 500 | 25 |
Values and the footnote from Twinfield’s fair use policy, checked 13 August 2026. Twinfield marks two of the four numbers with an asterisk and writes: “These credits are for certified integrations. For new and not yet certified ClientId credits are set to 5% of mentioned number.” The two unmarked buckets are unchanged, so the 50 and the 25 are ours to calculate and not figures Twinfield prints.
The effective limit is the lowest bucket that applies, so for a new client id the binding figure is 25 credits a minute for a single customer. At three credits a write that is around eight writes a minute per customer, and at one credit a read it is twenty-five reads.
An import that assumed a thousand-credit budget will not run slowly on an uncertified connection, it will spend most of its time in backoff.
The 50 and the 25 are five per cent of the value above them. Twinfield prints the full numbers and the footnote; the reduced pair is arithmetic on those, not a figure Twinfield states.
Two of the response headers do real work, and one of them is easy to misread. X-RateLimit-Remaining reports the lowest of all four buckets, while X-RateLimit-ClientId-Remaining reports only yours.
Twinfield says outright that the second can be higher than the first, and what to conclude: “If X-RateLimit-Remaining is 0, but X-RateLimit-ClientId-Remaining is more than 0, requests can still be fulfilled for other Organisations.”
Zero there means stop for this customer and carry on with the next one, which is a scheduling instruction and not a pause.
X-RateLimit-Credited gives the cost of the request you just made, and Twinfield presents it as the way to see whether a call was counted as a query, which is how you confirm the pricing rule above against your own traffic instead of assuming it.
Concurrency is counted separately from credits: twenty concurrent requests per client id and ten per client and organisation pair, breached with the same status code and a Concurrency limit exceeded. message.
Twinfield adds a sentence that closes the usual escape route: “Please be aware we do not support higher API limits.” Ordering the traffic is the whole of the answer, which is the argument behind how we queue and pace requests rather than passing them straight through.
What the audit checks, and what happens if you skip it
The credit footnote turns certification into a technical setting, so its terms belong in the architecture rather than in a procurement folder.
Wolters Kluwer made certification of new and existing links mandatory, it runs as a paid subscription, and the stated purpose is stability rather than marketing: “we ask you to comply with our API Best Practices and we verify the API link through certification. Every two years, we will perform an audit to inspect your API usage.”
Declining has a defined mechanism rather than a vague consequence. The client id is set to inactive, and there is a notice and a window before that happens: “We will notify you in advance. You can then still subscribe within two weeks. If we do not receive a response, we will set the ClientID to inactive and the link will no longer be usable.”
That is a fortnight between a letter and every customer connection stopping at once.
The ordering is the part our own earlier writing had backwards. Wolters Kluwer’s four steps are sign up, build, certify, publish. Step two says you can get going on the connection straight away with the documentation and the best practices, and the listing on Wolters Kluwer’s own website is step four, performed by them after a successful certification.
You do not need a certificate to start building, and you do not apply for the listing. Signing the order form is what produces the test environment and the support access.
Obligation, audit interval and the two-week window from the Wolters Kluwer support article on the certification process (updated 17 November 2025); the four steps and the subscription form from the partner page. Both checked 13 August 2026. The fee is not published. Wolters Kluwer states a subscription with a monthly charge and no amount, so no figure appears here.
One practical note on the sandbox, in two layers because both are true. Twinfield offers no free trial of its own, so before any agreement exists there is no self-serve environment to write code against. We provide a sandbox for Twinfield as we do for the other systems without a trial, and it is requested through us rather than created from a signup form.
Five of the nine readable objects are one record
Our coverage table marks nine objects readable on Twinfield: accounts, customers, dimensions, expenses, journals, journal entries, projects, suppliers and tax rates. Read that list next to Twinfield’s own model and it gets shorter, because five of those nine are the same kind of record.
Twinfield calls it a dimension, and the definition is unusually direct: “it’s possible to register financial transactions on ledgers and subanalyse them to for example, accounts receivable, accounts payable, cost centers, projects or assets. In Twinfield we call these Dimensions. The level of the dimension determines what data you can capture.”
Level one holds the balance sheet and profit and loss accounts, level two holds relations and cost centres, and level three holds projects and assets. In Twinfield a general ledger account and a customer are the same object type at two different heights.
The mapping is not one line per level. Level two carries three codes and they do not answer in the same place: DEB and CRD are the relations, which reach you as customers and suppliers, while KPL is cost centres and answers on our dimensions endpoint. Twinfield draws the same line itself, in the Finder option that returns “only the relations (dimension type: DEB and/or CRD)”. On level three only projects are resolved here; AST is published and unused.
Balance sheet and profit and loss accounts
- Accounts
The dimtype filter reaches every type; BAS and PNL are the default return.
Relations, meaning accounts payable and accounts receivable, and cost centres
- Customers
- Suppliers
- Dimensions
KPL is cost centres, and it answers on our dimensions endpoint rather than with the relations.
Projects and assets
- Projects
AST exists in Twinfield's enumeration and is not used here.
That is five of our nine readable objects on three levels of one record type. Seven of the eight codes are placed above; the eighth, ACT for activities, sits outside the three levels, because the Finder separates it through the section option rather than through a level.
Level definitions verbatim from Twinfield’s dimensions page, the eight dimtype values from the Finder options table, both checked 13 August 2026. Object names counted in our generated coverage data.
In practice that means one search endpoint does most of your master data reading. The Finder takes a type of DIM and a dimtype option, and swapping DEB for CRD is the difference between reading customers and reading suppliers.
It also means the fields you get back are the fields a dimension has, which is why the same call returns a code, a name, bank account details and address fields rather than a shape tailored per object. Mapping this onto a common data model is exactly the work of deciding which Twinfield level answers a question your product asks in its own vocabulary.
Set three options on that call deliberately, because each default hides something. company accepts an asterisk, which returns dimensions for every company the user can reach in one request instead of one request per company, and it replaces the deprecated office option, which still works but must not be sent alongside it.
includehidden defaults to excluding hidden dimensions, so an account your customer archives simply stops appearing, with no deletion and no signal. And paging is positional through firstRow and maxRows, with the total in the response, which matters once you put it next to the credit budget.
For scale, two figures from our own coverage rather than an impression. Reading dimensions is marked supported on 3 of the 30+ connected systems, and reading projects on 3 as well.
They are not the same three: only Exact Online and Twinfield do both. That is a property of two systems and not a ranking, and it is the reason a product built around cost centres or project codes runs into a very short list of systems that can feed it.
Thirty-eight browse definitions, and the regime that counts twice
Master data comes out of the Finder. Financial data comes out of something else entirely, and it is the part of Twinfield that least resembles a REST API.
In Twinfield’s words: “In order to get financial data out of Twinfield like general ledger transactions, sales invoices, and so on, use the browse data functionality. This functionality is based on so called browse codes. These browse codes are predefined definitions of financial data.”
So you do not request transactions. You pick one of 38 predefined report definitions, read that definition to find out which fields it exposes, then compose a query against those fields.
The definition read takes a company, because which fields exist depends on the company you are asking about. Twinfield notes that the first two steps only happen once, which is true in development and is also the reason a definition that differs between two of your customers will surprise you in production rather than during the build.
The code list has a structure, and it decides which code you want. General ledger transactions are 000, customer transactions 100, supplier transactions 200, projects 300, cost centres 900.
Several codes exist in numbered versions that sit beside each other rather than replacing one another, such as 030_1, 030_2 and 030_3 for general ledger details.
New behaviour arrives as a new code, so nothing you already query changes shape, and nothing tells you a better definition now exists. That per-company, per-version variety is the same problem as handling customisation across systems, arriving in the read path instead of in a custom field.
Transactions can be posted in one of four regimes: generic, fiscal, economic and commercial. If a company does not use them everything lands in generic and nothing changes for you. If it does, browsing without selecting a regime returns all lines, and selecting fiscal, commercial or economic returns those lines plus every generic line.
There is no selection that returns one regime alone. A total summed from an unfiltered browse on a company that uses regimes is wrong, and it is wrong quietly.
| Codes | No regime selected | Regime selected |
|---|---|---|
000010020030_3031_2 | All transaction lines, not grouped or summed | That regime plus all generic lines |
040_1050_1060 | Not available, a regime is mandatory | That regime plus all generic lines, grouped and summed |
Browse concept, the code list and the regime behaviour from Twinfield’s browse data page, checked 13 August 2026. The 38 is a count of the codes in that table. Twinfield’s own advice for large sets is to retrieve by period and to request only the columns you need, which is also the cheapest thing you can do to a credit budget.
No events, and a change feed that only reports deletions
Twinfield sends nothing. Across all 37 objects in our coverage table, none is marked as delivering a webhook, and there is no event subscription in the endpoint catalogue to configure. Staying current is a pull, and the question is only what you are allowed to pull on.
There is one dedicated change feed, and it reports the direction most integrations remember last. GetDeletedTransactions takes a company code, optionally a daybook and a date range, and returns each removed transaction with its daybook, number, transaction date, deletion date, the user who did it and a reason for the deletion.
It is a remarkably complete audit trail for disappearance. There is no counterpart for records that were created or changed: no endpoint in the catalogue reports those, so appearances and edits are found by browsing the period again.
<!-- Deletions: the one thing Twinfield reports back --><Query i:type="a:GetDeletedTransactions"><b:CompanyCode>001</b:CompanyCode><b:DateFrom>2026-08-01</b:DateFrom><b:DateTo>2026-08-13</b:DateTo></Query><!-- returns Daybook, TransactionNumber, TransactionDate,DeletionDate, User, ReasonForDeletion --><!-- Master data: filter on a modified timestamp instead --><options><string>dimtype</string><string>DEB</string><string>modifiedsince</string><string>20260813060000</string></options>
Query shape and fields from the deleted transactions service, the Finder option from the Finder reference, both checked 13 August 2026. The service sits in the query list of the fair use policy, so it costs one credit.
For master data there is a real delta filter. The Finder accepts modifiedsince as yyyyMMddHHmmss or yyyyMMdd in UTC, and in that form the response carries modified and revision columns alongside the code and name.
So customers, suppliers, accounts and projects can all be kept current with a high-water mark, which is the sevdesk-shaped answer to a system with no events: not a push, but a filter narrow enough that the pull stays cheap.
One detail in that filter costs nothing to encode and an afternoon to debug. Twinfield documents it as returning records modified after or at the given moment, so the boundary is inclusive and the last record of every pass comes back on the next one.
Storing the high-water mark and deduplicating on arrival costs nothing; discovering it through duplicate writes costs more. If you want the general version of that argument, what we do where a system has no events is written up separately, and the filtering and paging behaviour sits with how pagination is normalised.
What the customer's plan decides and what stays on your side
Two limits on a Twinfield integration are not yours to engineer around, and both belong in a sales conversation rather than in a retry policy.
The first is the customer’s subscription. Twinfield publishes which web services are available on which user level, and it is not a uniform surface. Creating sales invoices works on the top two levels and not on the bottom two. Projects, cost centres and journal entries fall away entirely on the lowest.
That last one has teeth, because journal entries are the single object our coverage marks writable on Twinfield alongside customers, suppliers and expenses, and the level that cannot post them is also described as only available in collaboration with a Twinfield accountant.
| Function | Available | Not available |
|---|---|---|
| Create sales invoices | Complete, SME | Bookkeeping Plus, Basic |
| Journal entries, projects, cost centres | Complete, SME, Bookkeeping Plus | Basic |
| Customers, suppliers, bank and cash transactions | All four levels | None |
Rows from Twinfield’s function overview, checked 13 August 2026, which labels the four levels Complete Accounting, SME Accounting, Bookkeeping Plus and Basic Bookkeeping, and notes that Basic Bookkeeping is only available in collaboration with a Twinfield accountant. Functions available everywhere are gathered in the last row.
The second is volume, and it lands on your customer’s invoice rather than on your error rate. Twinfield names transaction lines, invoice lines and dimensions as the entities that cost it the most, then states the remedy in commercial terms: “Twinfield will ask the subscriber to reduce the use. If the subscriber does not reduce the use, Twinfield is entitled to increase the fee.”
The subscriber is the accountancy practice, not you. An integration that writes one transaction line per event where it could write one per day is a bill somebody else receives.
Alongside that sit hard structural limits: at most 25 children inside a parent element as advice, 500 lines within a transaction or sales invoice as a recommendation, and 1.000 lines per transaction as a hard ceiling that returns 400.
Combining different request types into one call is no longer available either, since the general root element reached end of life on 1 July 2025 and a request holding a transaction and a customer has to be split into two, each paying its own three credits.
What we do not take off your hands:
- The certification subscription and the audit. The agreement is between you and Wolters Kluwer, the client id it applies to is yours, and so are the credits it unlocks. We can tell you what the audit looks at. We cannot hold the certificate for you.
- Which browse definition answers your question. The 38 codes describe reports, and which report is the right one depends on what your product claims to show. Selecting a regime is the same kind of decision.
- Write volume and the customer’s fee. How often you post and how granular each posting is are product decisions with a commercial consequence for the practice on the other end.
- What the customer’s plan permits. No interface makes a sales invoice postable on a level that does not offer it. It is a qualifying question, and it is cheaper asked early.
One narrower note on expenses, because Twinfield differs from its neighbours in a way that is easy to miss when a feature is built generically. On Twinfield an expense carries a journal code and identifies the account as accountNumber, it uses the net amount, the counterparty is not part of the request, and a file cannot travel with it.
Seven of the connected systems accept an expense at all, six of them take the file in the same request, and Twinfield is the seventh: the receipt has to arrive by another route. That is the sort of per-system difference syncing expenses across systems has to absorb.
Fair use wording and the line limits from the fair use policy, the general end-of-life date from the breaking changes page, the service catalogue from the web services overview, all checked 13 August 2026. The expense field contract comes from our own endpoint reference.
Frequently asked questions
Why does a Twinfield call fail before I have a company code?
What is the Twinfield cluster URL?
What are the Twinfield rate limits?
Does my Twinfield connection have to be certified?
Does Twinfield send webhooks?
How long does a Twinfield access token last?
Why can this customer not create a sales invoice?
QuickBooks Online Webhooks: Events, Retries and Recovery
QuickBooks Online webhooks cover 29 entity types and expect HTTP 200 in three seconds. Why Intuit still asks you to poll change data capture.
Lennart Svensson · 25 Aug 2026
Lexware Office Pagination: The 406 and One Page Size
Lexware Office validates the page size and rejects a bad one with 406, the same code it uses for an unsupported media type. What that means for your read loop.
Lennart Svensson · 20 Aug 2026
How to Integrate with DATEV Rechnungswesen: One Connection
One connection carries reading and writing in DATEV Rechnungswesen, on a two-year token. Which objects travel in which direction is the real decision.
Lennart Svensson · 17 Aug 2026Build once on the Unified API.
Twinfield prices requests in credits, hides the address behind a cluster and calls five different objects a dimension. The next system will make five different choices. Build against one interface and each of those differences becomes a field you read rather than a quarter you plan.