QueryTaxpayer — adószám validation

QueryTaxpayer is the NAV service for real-time validation of Hungarian tax numbers (adószám). Essential for B2B flow integrity and avoiding RTIR rejections for unknown TaxNumber.

Structure of an adószám

The Hungarian adószám (tax number of a taxable person) follows a rigid 11-digit structure, divided into three blocks:

• Standard format. 12345678-2-42 or without hyphens 12345678242.
• EU prefix. For intra-EU operations, the HU prefix is added on the tax base number: HU12345678. Separate validation via VIES.
• Individuals. Individuals have an adóazonosító jel (personal identification number, 10 digits, different from adószám). Not validatable via queryTaxpayer.

Endpoint and request

• Prod URL: https://api.onlineszamla.nav.gov.hu/invoiceService/v3/queryTaxpayer
• Test URL: https://api-test.onlineszamla.nav.gov.hu/invoiceService/v3/queryTaxpayer
• Method: POST + signed XML (same common:header / common:user / software headers as other endpoints)
• Auth: requires a prior TokenExchange token

POST /invoiceService/v3/queryTaxpayer HTTP/1.1
Host: api.onlineszamla.nav.gov.hu
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<QueryTaxpayerRequest xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
  <common:header>...</common:header>
  <common:user>...</common:user>
  <software>...</software>
  <taxNumber>12345678</taxNumber>
</QueryTaxpayerRequest>

<?xml version="1.0" encoding="UTF-8"?>
<QueryTaxpayerResponse xmlns="http://schemas.nav.gov.hu/OSA/3.0/api">
  <common:header>...</common:header>
  <common:result><common:funcCode>OK</common:funcCode></common:result>
  <software>...</software>
  <taxpayerValidity>true</taxpayerValidity>
  <taxpayerData>
    <taxpayerName>Sample Nagykereskedelmi Kft.</taxpayerName>
    <taxpayerShortName>Sample Kft.</taxpayerShortName>
    <taxNumberDetail>
      <base:taxpayerId>12345678</base:taxpayerId>
      <base:vatCode>2</base:vatCode>
      <base:countyCode>42</base:countyCode>
    </taxNumberDetail>
    <incorporation>SELF_EMPLOYED_OR_OTHER</incorporation>
    <taxpayerAddressList>
      <taxpayerAddressItem>
        <taxpayerAddressType>HQ</taxpayerAddressType>
        <taxpayerAddress>
          <base:countryCode>HU</base:countryCode>
          <base:postalCode>1051</base:postalCode>
          <base:city>Budapest</base:city>
          <base:streetName>Sample</base:streetName>
          <base:publicPlaceCategory>utca</base:publicPlaceCategory>
          <base:number>12</base:number>
        </taxpayerAddress>
      </taxpayerAddressItem>
    </taxpayerAddressList>
  </taxpayerData>
  <infoDate>2026-05-19T08:00:00.000Z</infoDate>
</QueryTaxpayerResponse>

Returned statuses

The taxpayerValidity field is a synthetic boolean, but other fields detail the situation:

• taxpayerValidity = true. Active number. Normal invoice issuance / receipt.
• taxpayerValidity = false. Inactive or non-existent number. Several possible causes, detailed in incorporation and taxpayerStatus elements.
• incorporation = SELF_EMPLOYED_OR_OTHER. Self-employed individual or other legal form.
• incorporation = INDIVIDUAL. Individual (rare in B2B).
• incorporation = ORGANIZATION. Company or organization (SME, JSC, BV, GmbH, etc.).
• taxpayerStatus = ACTIVE. Active. No restriction.
• taxpayerStatus = SUSPENDED. Suspended (felfüggesztett). Do not issue to this recipient — input VAT deduction is blocked on the buyer side.
• taxpayerStatus = DELETED. Struck off. The adoszám no longer exists and will never be reactivated.

VAT groups (csoportos áfa)

The Hungarian VAT group regime (csoportos áfa, art. 8 ÁFA tv.) allows several related companies to group fiscally, with a single group adoszám issuing invoices:

• Identification. A group member has vatCode = 5 (csoport tag) in its individual adószám. The group itself has vatCode = 3 (group).
• groupMemberTaxNumber field. On invoices issued by a group, the groupMemberTaxNumber field must identify the responsible operational member.
• Validation. queryTaxpayer returns the taxpayerGroupMembership block indicating membership and the parent group's adózszám (parentTaxNumber).
• RTIR effect. The tax number of the recipient used in the invoice is the group's (vatCode=3), not the member's. An error triggers a REF-INVALID_RECIPIENT rejection.

ERP integration and caching

Good practice for ERP integrations handling significant volumes:

• 24h cache. NAV data is refreshed at most J+1. A local 24h cache is enough for 99% of cases (status change rare).
• Invalidation. On any RTIR rejection for REF-TAXPAYER_NOT_FOUND or SUSPENDED status, invalidate the cache entry and re-query.
• Pre-flight check. On new partner entry in the ERP, validate in real-time. On partner data modification, re-validate.
• Batch validation. No official batch mode for queryTaxpayer. To validate 10,000 partners, serialize calls and respect the rate limit (~100 req/s).
• VIES cross-reference. For intra-EU operations, queryTaxpayer does not replace VIES validation (which tests HU prefix + base number in EU mode). Do both for cross-border flows.

Common pitfalls

• Passing the full adószám to queryTaxpayer. NAV only accepts the 8-digit root (tax base number), not the vatCode/countyCode. Passing 12345678242 instead of 12345678 triggers a format error.
• Not distinguishing SUSPENDED from DELETED. A SUSPENDED partner can become active again after NAV regularization. A DELETED one is final. Different commercial policies.
• Trusting cache infinitely. Once a year, a major player goes into adjustment and its status flips to SUSPENDED for 30 days. A non-invalidated cache propagates the error throughout that period.
• Confusing adószám and adóazonosító jel. The adóazonosító is an individual's personal identification number (10 digits) without country prefix. Not validatable via queryTaxpayer (B2C does not need NAV validation).
• Mishandling VAT groups. An invoice addressed to a group member must carry the group's tax number (vatCode=3), not the member's (vatCode=5). Frequent confusion during BeNeLux imports operating Hungarian subsidiaries as a group.

Cross-links

• Hungary hub — full RTIR
• NAV Online Számla — platform
• NAV API — specifications
• Hungarian VAT regimes
• RTIR — architecture
• NAV — adoszám web check
• VIES — EU VAT validation
• NAV documentation — API