Reduce KVK API Costs: Pick the Cheapest Call per Job

Most teams start by calling the enriched lookup everywhere, because it returns the most data and it is one line of code. Then the first monthly invoice or quota warning arrives and nobody can say which feature used the tokens. The calls were all correct. They were just not all necessary.

This article walks through what each KVKBase call costs and which one fits which job, so you can cut your token use without losing any data you actually need.

What each call costs

KVKBase counts usage in tokens. A basic lookup by KVK number (name, address, status) costs 1 token. Adding ?enrich=true gives you trade names, legal form, SBI codes and branches for 2 tokens. The full profile from the KVK Basisprofiel (?enrich=true&vat=true) adds employee counts, registration date, official SBI descriptions and the VAT number for legal persons, and costs 12 tokens. A search request costs 1 token, and listing all branches of a company costs 5.

The one free call is GET /v1/verify/{kvkNumber}. It answers whether a number exists and whether the registration is active, and nothing more. The current prices and token allowances per plan are on the pricing page, and the full list is in the API reference.

The spread matters. The full profile costs twelve times a basic lookup. If you use it for a job that only needs a name and a city, you are paying for eleven tokens of data you throw away.

Match the call to the question

Think of each feature in your product as a question, and pick the cheapest call that can answer it.

“Is this a real, active company?” is a verify call, which is free. A signup form that rejects typos and dead numbers can run on it all day. One detail to handle: verify does not always know the name. Depending on where the answer comes from, name can be null and active can be unknown, so treat an unknown status as “ask again with a lookup”, not as “inactive”.

“Whose number is this, and where do they live?” is the basic lookup at 1 token. That covers invoice details, a checkout prefill and most customer records. Our guide to KVK number lookup shows the response fields.

“What do they trade as, and what do they do?” needs the enriched lookup at 2 tokens. Use it when you match on trade names or segment by SBI code.

“How big is this company, and what is the VAT number?” is the only reason to pay 12 tokens. Use it at the moment a decision depends on it, such as credit limits or a KYC file, and not on every row of an import.

Do not run the expensive call first

A cheap pattern is to escalate. Verify first, because it is free and filters out every typo and every dissolved company. Run the basic lookup only for numbers that pass. Run the full profile only for the small group that reaches a stage where you really need it, for example a customer who asks for a quote above a certain amount.

async function onboard(kvkNumber, apiKey) {
  const headers = { Authorization: `Bearer ${apiKey}` };
  const base = "https://api.kvkbase.nl/v1";

  const check = await fetch(`${base}/verify/${kvkNumber}`, { headers })
    .then((r) => r.json());
  if (!check.exists) return { ok: false, reason: "unknown number" };
  if (check.active === false) return { ok: false, reason: "not active" };

  // 1 token: name and address are enough for the account
  const company = await fetch(`${base}/lookup/${kvkNumber}`, { headers })
    .then((r) => r.json());
  return { ok: true, company };
}

In a typical signup funnel, a good share of attempts never get past the form: typos, test entries, abandoned flows. Every one of those used to cost a token and now costs nothing. You can also catch the worst typos before any call at all, using the checksum and format rules.

Batch saves round trips, not tokens

POST /v1/lookup/batch takes up to 25 KVK numbers in one request and is the right tool for imports. It does not make lookups cheaper, though: each number in the batch is charged at the price of the variant you ask for, so 25 enriched lookups cost 50 tokens whether you send them one by one or together. The batch call checks that you have enough tokens left for the whole list before it starts and refuses it otherwise, which is handy because you never end up with a half-finished import.

What a batch does save is time and rate limit. The free plan allows 10 requests per minute and the Pro plan 300, so 25 numbers per request goes much further than 25 separate calls. For the bigger picture of cleaning a customer base, see batch enrichment of CRM data.

Before you send a batch, remove duplicates from the list and numbers you already looked up recently. Company data changes slowly, and active companies are cached for 24 hours on our side, so asking again within that window gains you nothing.

Stop asking questions the data already answered

The biggest saving is often not a cheaper call but no call at all. If you check the same 2,000 suppliers every night to see whether anything changed, you pay for 2,000 lookups to learn that almost nothing did. A monitoring watch tells you when a company actually changes, and you only look up the ones that did. We describe both options in keeping company data up to date with webhooks and polling.

Also store what you get. Keep the KVK number as the key, save the fields you use together with the date you fetched them, and refetch only when the record is older than your own limit or when a business event, like a new invoice above a threshold, calls for a fresh check.

A quick audit you can do today

Open your logs and count calls per endpoint and per variant for the last 30 days. Look for three things: enriched or full-profile calls on features that only display a name, lookups that follow a failed form validation, and the same number requested more than once a day. Each of these is a place where a cheaper call or a stored result does the same job.

Want to see what your own usage looks like? Create a free KVKBase account, run your flow with the verify endpoint first and compare the token count after a week.