Skip to content
AccountCloud Docs

Company data and VAT numbers

Three operations to look up a business partner:

Operation Endpoint What it does
company.profile GET /v1/companies/{country}/{number} The profile of a company from its trade register, by its registration number.
company.search GET /v1/companies?country=&q= Finds companies in a trade register by name, trade name or number.
vat.validate GET /v1/vat-numbers/{vat_number} Checks an EU VAT number at VIES, the system of the European Commission.

A key needs the scope company or vat, or the operation itself (see scopes).

Availability. All three are in preview. company.profile has a price for Dutch companies. company.search, vat.validate and company.profile for Belgian companies have no price yet: a live key gets 503 operation_unavailable until they have one. Test keys already get answers from all three, for free; see test mode for the test companies and VAT numbers. Current prices are in GET /v1/pricing.

The registers

Section titled “The registers”
Country Register Number Where the data comes from
NL KvK Handelsregister The KvK number: 8 digits. Asked at the KvK, with our own copy as a cache.
BE KBO Open Data (Crossroads Bank for Enterprises) The enterprise number: 10 digits, starting with 0 or 1. 0403.170.701 and BE0403170701 are accepted too. Our copy of the KBO Open Data, updated every day. The KBO is never asked live.

Spaces, dots and dashes in a number are ignored. Another country gets 404 country_not_supported, with supported_countries.

Who may see Dutch data. Dutch company data comes from the KvK, whose terms do not allow passing it on to third parties. It is only available to accounts we have given access. Other accounts get 403 register_restricted, with test keys too, so a test behaves as live will. Belgian data is available to every account.

Get a company

Section titled “Get a company”
Terminal window
curl https://api.accountcloud.io/v1/companies/BE/0123456749 \
  -H "Authorization: Bearer ac_test_…"
{
  "object": "company",
  "country": "BE",
  "number": "0123456749",
  "name": "Testbedrijf NV",
  "legal_form": "Naamloze vennootschap",
  "legal_form_code": "014",
  "trade_names": ["Testbedrijf NV", "Entreprise Test SA"],
  "vat_number": "BE0123456749",
  "rsin": null,
  "establishment_number": null,
  "address": { "street": "Wetstraat", "house_number": "16", "house_number_suffix": null, "postal_code": "1000", "city": "Brussel", "country": "BE" },
  "postal_address": null,
  "registration_date": "2001-03-15",
  "end_date": null,
  "website": "www.testbedrijf.example",
  "activities": [],
  "source": {
    "register": "kbo",
    "name": "KBO Open Data (Crossroads Bank for Enterprises)",
    "freshness": "cached",
    "retrieved_at": "2026-11-03T00:00:00Z",
    "data_age_days": 1,
    "notice": "Source: KBO Open Data, FPS Economy (Belgium), data of 2026-11-03."
  }
}
Field What it is
number The registration number, digits only.
name, trade_names The name, and the names the company trades under, the name itself included. For BE every name in the KBO, in every language.
legal_form The legal form as the register writes it, in Dutch. legal_form_code: for BE the code of the legal form in the KBO; null for NL.
vat_number For BE: BE and the enterprise number. null for NL, because the KvK does not hold the VAT number. Check a VAT number with GET /v1/vat-numbers/{vat_number} before you rely on it.
rsin, establishment_number NL only: the RSIN of the legal entity when the KvK gives it, and the number of the main establishment.
address The visiting address (NL) or the registered office (BE), with street, house_number, house_number_suffix, postal_code, city and country. The postcode is as the register writes it.
postal_address NL only: the correspondence address, when it differs. A PO box has the street Postbus.
registration_date, end_date When the company was registered (NL) or started (BE), and for NL when the registration ended. Ended BE companies are not in the KBO data.
website When the register has one.
activities NL only: the SBI activities, with code, description and main: true for the main one. Empty for BE.
source Where the data comes from and how old it is; see below.

source

Section titled “source”
Field What it is
register kvk or kbo, and name its full name.
freshness cached: from our copy. live: from the register, just now.
retrieved_at When the register gave us this data. For BE the date of the KBO export it is current with.
data_age_days Whole days since retrieved_at.
notice The attribution the register requires with its data, verbatim. For the KvK: “Voor actuele informatie met juridische derdenwerking dient u altijd het Handelsregister te raadplegen.”

The registers require it: show notice and retrieved_at wherever you show their data.

Fresh or from our copy

Section titled “Fresh or from our copy”

For NL you choose where the profile may come from, with freshness:

freshness Where the profile comes from
auto (default) Our copy when it is younger than max_age_days; otherwise the KvK now, which also refreshes our copy.
cached Only our copy, whatever its age. When we hold no copy: 404 company_not_cached.
live Always the KvK now.

max_age_days (0 to 3650) says how old our copy may be with auto. 0 always asks the KvK. Without it, our own refresh period applies, now 30 days.

Terminal window
curl "https://api.accountcloud.io/v1/companies/NL/68750110?freshness=auto&max_age_days=7" \
  -H "Authorization: Bearer ac_test_…"

BE always comes from our daily copy: freshness=live gets 422 validation_failed, and max_age_days is ignored.

When the KvK does not answer, the answer is 503 provider_unavailable, also with auto when we hold an older copy. Nothing is charged.

Not found

Section titled “Not found”

A number the register does not know gets 404 company_not_found, with country and number. A number that cannot be one, such as a KvK number without 8 digits, gets 422 validation_failed on number.

Search companies

Section titled “Search companies”
Terminal window
curl "https://api.accountcloud.io/v1/companies?country=BE&q=testbedrijf" \
  -H "Authorization: Bearer ac_test_…"
{
  "object": "list",
  "data": [
    { "object": "company_summary", "country": "BE", "number": "0123456749", "name": "Testbedrijf NV", "city": "Brussel", "href": "/v1/companies/BE/0123456749" }
  ],
  "source": {
    "register": "kbo",
    "name": "KBO Open Data (Crossroads Bank for Enterprises)",
    "freshness": "cached",
    "retrieved_at": "2026-11-03T00:00:00Z",
    "notice": "Source: KBO Open Data, FPS Economy (Belgium), data of 2026-11-03."
  }
}
Parameter What it is
country Required: NL or BE.
q Required, 2 to 100 characters: (part of) a name or trade name, or a number. For NL an 8-digit KvK number, for BE the enterprise number or its start.
limit 1 to 100; 10 by default.
  • NL asks the KvK now (source.freshness: live). The KvK answers per establishment; you get one result per KvK number, with the name of the legal entity or main establishment and the place of the main establishment.
  • BE searches our copy of the KBO (source.freshness: cached), on name, trade name and the start of the enterprise number, sorted by name.

Each result has the city when it is known, and in href the path of its profile. Ask that for the full profile. Nothing found is an empty data.

Check a VAT number

Section titled “Check a VAT number”
Terminal window
curl https://api.accountcloud.io/v1/vat-numbers/NL999999990B01 \
  -H "Authorization: Bearer ac_test_…"
{
  "object": "vat_number",
  "vat_number": "NL999999990B01",
  "country": "NL",
  "valid": true,
  "format_valid": true,
  "name": "TESTBEDRIJF B.V.",
  "address": "TESTSTRAAT 00001\n1234AB AMSTERDAM",
  "consultation_number": "WAPITEST00000001",
  "source": { "register": "vies", "name": "VIES (European Commission)", "retrieved_at": "2026-11-04T09:12:41Z" }
}

Send the number with its country code, such as NL123456789B01. Spaces, dots and dashes are allowed. Every call asks VIES again, at that moment: we never reuse an earlier answer.

Field What it is
vat_number The number as VIES knows it: upper case, without separators, with its prefix (EL for Greece).
country ISO 3166-1 alpha-2, and XI for Northern Ireland.
valid Whether VIES confirms the number.
format_valid Whether the number has the format of its country. When it has not, VIES was not asked.
name, address What the member state registered, when it shares it; otherwise null. The lines of the address are separated by \n.
consultation_number The number VIES gave for this check: proof that the number was checked at source.retrieved_at. Keep it with the invoice, for example for a reverse-charge supply. null when VIES gave none.
source register vies, its name, and retrieved_at, the moment of the check. null when VIES was not asked.
  • The wrong format is a 200 with valid: false and format_valid: false, without asking VIES, and costs nothing.
  • A number VIES does not confirm is a 200 with valid: false and format_valid: true.
  • When VIES or the register of the member state does not answer, the answer is 503 provider_unavailable, also free. Try again after Retry-After.
  • No country code gets 422 validation_failed on vat_number. A country outside the EU, such as GB, gets 404 country_not_supported, with supported_countries: the EU member states and XI.

What it costs

Section titled “What it costs”
  • company.profile for NL has two prices: from our copy (source.freshness: cached), and from the KvK now (live). You pay for what you got, so with auto that depends on the age of our copy. The start prices are €0.0050 and €0.0250, excluding VAT. Before the call the higher one is reserved on your credit.
  • A Dutch number the KvK does not know costs what the KvK charges us for asking, at cost price, although the answer is a 404 company_not_found. company_not_cached and any other “not found” are free.
  • company.search, vat.validate and company.profile for BE have no price yet; see Availability above.
  • Errors and refusals are free, and test keys never cost anything.

The current prices are in GET /v1/pricing, and every answer says what it cost in AccountCloud-Charged.