{"openapi":"3.1.0","info":{"title":"VerifNow API","description":"One API key for every field a billing or onboarding form has to check: EU VAT numbers verified against VIES, IBANs, national identifiers (NIF, SIN, SSN), email addresses and phone numbers.\n\nVAT lookups degrade rather than fail. VIES publishes no SLA and drops member states several times a month, so every VAT response carries a `source` (LIVE, CACHE, STALE, UNVERIFIED), and `registered` is null — never false — when the registry could not be reached. Reporting an outage as \"not registered\" would refuse legitimate customers.\n\nFree tier: 250 validations per month at the same depth as the paid Starter plan, no credit card. Per-country VIES availability is published without an API key at `/api/v1/status/vies`, and the VAT rates of every member state, from the Commission's TEDB, at `/api/v1/vat/rates`.","termsOfService":"https://www.verifnow.io/en/company/terms","contact":{"name":"VerifNow","url":"https://www.verifnow.io/en/contact"},"license":{"name":"Commercial — see terms of service","url":"https://www.verifnow.io/en/company/terms"},"version":"v1.0.25"},"servers":[{"url":"https://api.verifnow.io","description":"Production server (HTTPS)"}],"security":[{"X-API-Key":[]}],"tags":[{"name":"Email Validation","description":"Validate email addresses and get normalization and diagnostics."},{"name":"Phone Validation","description":"Validate international phone numbers and return normalization and diagnostics."},{"name":"IBAN Validation","description":"Validate IBAN numbers (format and checksum), and return normalization and diagnostics."},{"name":"NAS Validation","description":"Validate Canadian Social Insurance Numbers (NAS/SIN)"},{"name":"NIF Validation","description":"Validate Spanish Tax Identification Numbers (NIF)"},{"name":"SSN Validation","description":"Validate US Social Security Numbers"},{"name":"Status","description":"Public availability reporting."},{"name":"VAT rates","description":"EU VAT rates by member state, from the Commission's TEDB."},{"name":"VAT Validation","description":"Validate VAT numbers and verify them against VIES for EU VAT numbers."}],"paths":{"/api/v1/validate/vat":{"post":{"tags":["VAT Validation"],"summary":"Validate a VAT number","description":"Accepts a VAT number and validates its format. For EU VAT numbers, also verifies against VIES API. Returns validation status and normalized form.\n\nSend `traderName` as well to ask whether the number belongs to that company. `vatDetails.trader_name_match` answers MATCH, MISMATCH or NOT_AVAILABLE, and `trader_name_match_source` says who compared: VerifNow, against the name VIES publishes (most member states), or VIES itself where it withholds the name but checks one (Spain). Germany neither publishes nor checks: NOT_AVAILABLE.","operationId":"validateVat","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the VAT number to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatValidationRequest"},"examples":{"VAT example":{"summary":"VAT number to validate","description":"VAT example","value":{"value":"FR 123 456 789 01"}},"VAT and company name":{"summary":"VAT number, checked against the expected holder","description":"VAT and company name","value":{"value":"IE6388047V","traderName":"Google Ireland Ltd"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid VAT":{"summary":"Successful VAT validation","description":"Valid VAT","value":{"valid":true,"message":"Valid VAT number","normalizedValue":"FR12345678901","originalValue":"FR 123 456 789 01"}}}}}},"400":{"description":"Invalid request (missing or malformed VAT number)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Unauthorized (missing or invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too Many Requests (rate limit exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/validate/ssn":{"post":{"tags":["SSN Validation"],"summary":"Validate a US Social Security Number","description":"Validates a US Social Security Number against the numbers the SSA never issues: area 000, 666 or 900-999, group 00, serial 0000, and well-known advertising samples. An SSN has no check digit, so a typo that lands on another possible number cannot be caught, and only the SSA can confirm a number was issued. ssnDetails.itin flags an IRS ITIN, which is a taxpayer number but not an SSN. Spaces and dashes are accepted.","operationId":"validateSsn","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the SSN to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"},"examples":{"SSN example":{"summary":"US SSN to validate","description":"SSN example","value":{"value":"078-05-1120"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Sample number rejected":{"summary":"A published sample number, not a real SSN — no example here is a possible real SSN","description":"Sample number rejected","value":{"valid":false,"message":"That is a well-known sample number, not a real SSN","originalValue":"078-05-1120","ssnDetails":{"itin":false}}}}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/validate/phone":{"post":{"tags":["Phone Validation"],"summary":"Validate a phone number","description":"Validates a phone number against its country's numbering plan: length and allocated prefix. The number must include its country code, written with '+' or the '00' international prefix. Valid numbers are normalized to E.164, and phoneDetails reports the country, the line type (MOBILE, FIXED_LINE, VOIP, PREMIUM_RATE...) and formatted forms. A valid number is one that exists in the plan, not a line known to be live.","operationId":"validatePhoneNumber","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the phone number to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"},"examples":{"Phone example":{"summary":"Phone number to validate","description":"Phone example","value":{"value":"+33 6 12 34 56 78"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid phone":{"summary":"Successful phone validation","description":"Valid phone","value":{"valid":true,"message":"Valid phone number","normalizedValue":"+33612345678","originalValue":"+33 6 12 34 56 78","phoneDetails":{"country_code":"FR","calling_code":33,"line_type":"MOBILE","international_format":"+33 6 12 34 56 78","national_format":"06 12 34 56 78"}}}}}}},"400":{"description":"Invalid request (missing or malformed phone number)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Unauthorized (missing or invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too Many Requests (rate limit exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/validate/nif":{"post":{"tags":["NIF Validation"],"summary":"Validate a Spanish NIF","description":"Validates a Spanish tax identification number: a DNI (8 digits and a letter), a NIE for foreign nationals (X, Y or Z, 7 digits and a letter), the K, L and M series, or the NIF of a company or other entity (a letter for the legal form, 7 digits, a control character). nifDetails reports the type, whether it belongs to a person, and for an entity its legal form. Spaces, dots, dashes and a leading ES are accepted. A valid NIF is not automatically a valid EU VAT number: use /validate/vat for that.","operationId":"validateNif","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the NIF to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"},"examples":{"NIF example":{"summary":"Spanish NIF to validate","description":"NIF example","value":{"value":"12345678Z"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid NIF":{"summary":"Successful NIF validation","description":"Valid NIF","value":{"valid":true,"message":"Valid NIF","normalizedValue":"B12345674","originalValue":"B-12345674","nifDetails":{"type":"ENTITY","natural_person":false,"checksum_valid":true,"entity_letter":"B","entity_type":"Private limited company (Sociedad de responsabilidad limitada)"}}}}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/validate/nas":{"post":{"tags":["NAS Validation"],"summary":"Validate a Canadian Social Insurance Number (NAS/SIN)","description":"Validates the format and Luhn check digit of a Canadian Social Insurance Number. nasDetails reports the series: temporary_resident for a 9-series number, which expires with the holder's permit (the number does not carry the date), and individual_series false for numbers starting with 0 or 8, which are not issued to individuals. Spaces and dashes are accepted. Only collect a SIN where the law requires it — in the private sector, essentially employment and income reporting.","operationId":"validateNas","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the NAS/SIN to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"},"examples":{"NAS example":{"summary":"Canadian SIN to validate","description":"NAS example","value":{"value":"046 454 286"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid NAS":{"summary":"Successful NAS/SIN validation","description":"Valid NAS","value":{"valid":true,"message":"Valid SIN format, but numbers starting with 0 are not issued to individuals","normalizedValue":"046454286","originalValue":"046 454 286","nasDetails":{"checksum_valid":true,"temporary_resident":false,"individual_series":false,"formatted":"046 454 286"}}}}}}},"400":{"description":"Invalid request payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/validate/iban":{"post":{"tags":["IBAN Validation"],"summary":"Validate an IBAN","description":"Validates an IBAN against the SWIFT registry entry for its country — length and character layout — and then the mod-97 check digits. Both answers are reported separately in ibanDetails, so a form can tell \"that is not how accounts are numbered there\" from \"check what you typed\". ibanDetails.sepa says whether the IBAN's country is inside the SEPA schemes' geographical scope, which is what decides whether a direct debit is possible at all — a perfectly valid Egyptian IBAN is not collectable under a SEPA mandate. Normalization uppercases letters and removes spaces and dashes.","operationId":"validateIBAN","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the IBAN to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"},"examples":{"IBAN example":{"summary":"IBAN to validate","description":"IBAN example","value":{"value":"FR14 2004 1010 0505 0001 3M02 606"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid IBAN":{"summary":"Successful IBAN validation","description":"Valid IBAN","value":{"valid":true,"message":"Valid IBAN","normalizedValue":"FR1420041010050500013M02606","originalValue":"FR14 2004 1010 0505 0001 3M02 606","ibanDetails":{"country_code":"FR","sepa":true,"structure_valid":true,"checksum_valid":true,"length":27,"expected_length":27,"formatted":"FR14 2004 1010 0505 0001 3M02 606"}}}}}}},"400":{"description":"Invalid request (missing or malformed IBAN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Unauthorized (missing or invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too Many Requests (rate limit exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/validate/email":{"post":{"tags":["Email Validation"],"summary":"Validate an email address","description":"Validates a single email address with deep diagnostics. The checks currently include: syntax validation, MX presence, typo detection with domain suggestion, disposable domain detection, role-based mailbox detection, free provider detection, domain age estimation, and MX provider quality assessment. The response contains a generic validation result plus email-specific details, including a risk score and deliverability assessment.","operationId":"validateEmail","parameters":[{"$ref":"#/components/parameters/X-VerifNow-SDK"}],"requestBody":{"description":"JSON payload containing the email to validate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationRequest"},"examples":{"Email example":{"summary":"Email address to validate","description":"Email example","value":{"value":"USER@Example.Com"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid email":{"summary":"Successful email validation","description":"Valid email","value":{"valid":true,"message":"Valid email","normalizedValue":"user@example.com","originalValue":"USER@Example.Com","validationLevel":"ADVANCED"}}}}}},"400":{"description":"Invalid request (missing or malformed body value)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"401":{"description":"Unauthorized (missing or invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"429":{"description":"Too Many Requests (rate limit exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"}}}}}}},"/api/v1/vat/rates":{"get":{"tags":["VAT rates"],"summary":"VAT rates of every EU member state","description":"Standard, reduced and regional VAT rates of the 27 member states, retrieved daily from the European Commission's Taxes in Europe Database. Requires no API key and is not counted against any quota.\n\nThese are the rates a member state has, not the rate a sale is charged. In B2B trade between member states the invoice is usually zero-rated under the reverse charge, whatever the buyer's country rate is.","operationId":"all","responses":{"200":{"description":"Rates of every member state retrieved so far","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatRates"}}}},"503":{"description":"No rates retrieved from TEDB yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VatRates"}}}}},"security":[]}},"/api/v1/vat/rates/{countryCode}":{"get":{"tags":["VAT rates"],"summary":"VAT rates of one EU member state","description":"One member state's standard, reduced and regional VAT rates. Accepts GR for Greece as well as EL. Requires no API key.","operationId":"one","parameters":[{"name":"countryCode","in":"path","description":"Member state code, e.g. FR, DE, EL (or GR).","required":true,"schema":{"type":"string"},"example":"FR"}],"responses":{"200":{"description":"The member state's rates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryVatRates"}}}},"404":{"description":"Not an EU member state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryVatRates"}}}},"503":{"description":"No rates retrieved for it yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryVatRates"}}}}},"security":[]}},"/api/v1/status/vies":{"get":{"tags":["Status"],"summary":"VIES availability by member state","description":"Current availability of each EU member state's VAT registry as reported by VIES, together with the share of our own observations in which it was reachable over the reporting window. Requires no API key.","operationId":"vies","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ViesStatusResponse"}}}}},"security":[]}}},"components":{"schemas":{"EmailSignals":{"type":"object","description":"Signal-level diagnostics used to compute deliverability and risk scoring.","properties":{"syntax_valid":{"type":"boolean","description":"True when the address passes RFC syntax checks","example":true},"mx_valid":{"type":"boolean","description":"True when MX records are present and resolvable","example":true},"typo_detected":{"type":"boolean","description":"True when a common domain typo is detected","example":false},"suggested_domain":{"type":"string","description":"Suggested corrected domain when a typo is detected","example":"gmail.com"},"disposable":{"type":"boolean","description":"True when the domain is a known disposable provider","example":false},"role_based":{"type":"boolean","description":"True when the local part is a role-based mailbox","example":false},"free_provider":{"type":"boolean","description":"True when the domain is a known free email provider","example":true},"domain_age_days":{"type":"integer","format":"int64","description":"Estimated domain age in days when available","example":3650},"mx_provider":{"type":"string","description":"Detected MX provider name when resolvable","example":"Google Workspace"},"mx_quality_score":{"type":"number","format":"double","description":"MX provider quality score on a 0.0 to 1.0 scale","example":0.92}}},"EmailValidationDetails":{"type":"object","description":"Email-specific diagnostics returned when advanced validation is applied.","properties":{"signals":{"$ref":"#/components/schemas/EmailSignals","description":"Signal breakdown used to compute deliverability and risk."},"risk_score":{"type":"integer","format":"int32","description":"Aggregated risk score on a 0 to 100 scale (0 = low risk, 100 = high risk)","example":18},"risk_level":{"type":"string","description":"Overall risk assessment derived from the risk score (LOW, MEDIUM, HIGH). Only available for GROWTH and PRO plans (ADVANCED depth or higher).","enum":["LOW","MEDIUM","HIGH"],"example":"LOW"},"deliverability":{"type":"string","description":"Overall deliverability assessment derived from signals","enum":["DELIVERABLE","RISKY","UNDELIVERABLE","UNKNOWN"],"example":"DELIVERABLE"},"applied_level":{"type":"string","description":"Validation level effectively applied for this response","enum":["BASIC","STANDARD","ADVANCED","PREMIUM"],"example":"ADVANCED"}}},"IbanValidationDetails":{"type":"object","description":"Structure and checksum diagnostics for an IBAN.","properties":{"country_code":{"type":"string","description":"The IBAN's country, as its first two characters. Present even when the country is unknown to the registry.","example":"FR"},"sepa":{"type":"boolean","description":"The IBAN's country is inside the geographical scope of the SEPA schemes, so a bank there may collect a SEPA direct debit. Whether this particular bank does is published per bank, not per country, and is not knowable from the IBAN.","example":true},"structure_valid":{"type":"boolean","description":"The length and character layout match the registry entry for that country.","example":true},"checksum_valid":{"type":"boolean","description":"The mod-97 check digits are correct.","example":true},"length":{"type":"integer","format":"int32","description":"Length of the value as submitted, spaces removed.","example":27},"expected_length":{"type":"integer","format":"int32","description":"Length the registry requires for that country. Null when the country is not in the registry.","example":27},"formatted":{"type":"string","description":"Print format, in groups of four. Present only for a valid IBAN.","example":"FR14 2004 1010 0505 0001 3M02 606"}}},"NasValidationDetails":{"type":"object","description":"Check digit and series of a Canadian Social Insurance Number.","properties":{"checksum_valid":{"type":"boolean","description":"The Luhn check digit is correct.","example":true},"temporary_resident":{"type":"boolean","description":"A 9-series number, issued to temporary residents. It expires with the holder's work permit, study permit or visitor record, and the number itself does not say when: check the document.","example":false},"individual_series":{"type":"boolean","description":"The first digit belongs to a series issued to individuals (1 to 7, or 9). Numbers starting with 0 or 8 are not issued to individuals as SINs — 0 is used for tax numbers assigned by the Canada Revenue Agency, 8 for business numbers — and the government's own sample number, 046 454 286, starts with 0 for that reason.","example":true},"formatted":{"type":"string","description":"Printed form, in three groups of three.","example":"046 454 286"}}},"NifValidationDetails":{"type":"object","description":"Type, control character and, for an entity, legal form of a Spanish NIF.","properties":{"type":{"type":"string","description":"DNI, NIE, NIF_K, NIF_L, NIF_M, or ENTITY.","enum":["DNI","NIE","NIF_K","NIF_L","NIF_M","ENTITY"],"example":"ENTITY"},"natural_person":{"type":"boolean","description":"The number belongs to a person rather than a company or other entity.","example":false},"checksum_valid":{"type":"boolean","description":"The control character is correct.","example":true},"entity_letter":{"type":"string","description":"For an entity, the letter that encodes its legal form.","example":"B"},"entity_type":{"type":"string","description":"For an entity, its legal form, from Orden EHA/451/2008.","example":"Private limited company (Sociedad de responsabilidad limitada)"}}},"PhoneValidationDetails":{"type":"object","description":"Country, line type and formatting of a phone number.","properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the number belongs to. Absent when the calling code is shared and the number does not identify a single country.","example":"FR"},"calling_code":{"type":"integer","format":"int32","description":"International calling code, without the plus sign.","example":33},"line_type":{"type":"string","description":"Kind of line according to the country's numbering plan. A premium-rate or VOIP number is still valid; this field is how a caller decides to exclude it.","enum":["MOBILE","FIXED_LINE","FIXED_LINE_OR_MOBILE","TOLL_FREE","PREMIUM_RATE","SHARED_COST","VOIP","PERSONAL_NUMBER","PAGER","UAN","VOICEMAIL","UNKNOWN"],"example":"MOBILE"},"international_format":{"type":"string","description":"Human-readable international format.","example":"+33 6 12 34 56 78"},"national_format":{"type":"string","description":"Format as dialled from inside the country.","example":"06 12 34 56 78"}}},"SsnValidationDetails":{"type":"object","description":"What a US SSN's structure reveals.","properties":{"itin":{"type":"boolean","description":"The number is an IRS Individual Taxpayer Identification Number, not an SSN: it starts with 9 and its fourth and fifth digits fall in 50-65, 70-88, 90-92 or 94-99. Valid as a taxpayer number where one is accepted; never an SSN.","example":false}}},"ValidationResult":{"type":"object","description":"Outcome of a validation request for a specific input value.","properties":{"valid":{"type":"boolean","description":"Whether the input value is syntactically valid and passes configured checks","example":true},"message":{"type":"string","description":"Human-readable description of the validation result","example":"Valid value"},"normalizedValue":{"type":"string","description":"Normalized or canonical representation of the input when available"},"originalValue":{"type":"string","description":"The exact value received as input"},"validationLevel":{"type":"string","description":"Applied validation strictness level","enum":["BASIC","STANDARD","ADVANCED","PREMIUM"],"example":"ADVANCED"},"emailDetails":{"$ref":"#/components/schemas/EmailValidationDetails","description":"Optional email-specific diagnostics for advanced checks"},"vatDetails":{"$ref":"#/components/schemas/VatValidationDetails","description":"Optional VAT-specific diagnostics, including registry lookup state"},"phoneDetails":{"$ref":"#/components/schemas/PhoneValidationDetails","description":"Optional phone-specific diagnostics: country, line type and formats"},"ibanDetails":{"$ref":"#/components/schemas/IbanValidationDetails","description":"Optional IBAN-specific diagnostics: structure and checksum"},"nasDetails":{"$ref":"#/components/schemas/NasValidationDetails","description":"Optional Canadian SIN diagnostics: check digit and series"},"nifDetails":{"$ref":"#/components/schemas/NifValidationDetails","description":"Optional Spanish NIF diagnostics: type, control character, legal form"},"ssnDetails":{"$ref":"#/components/schemas/SsnValidationDetails","description":"Optional US SSN diagnostics: whether the number is an ITIN"}}},"VatValidationDetails":{"type":"object","description":"Structural and registry diagnostics for a VAT number.","properties":{"format_valid":{"type":"boolean","description":"The number matches its member state's structure.","example":true},"registered":{"type":"boolean","description":"Present in the member state's registry. Null when VIES could not be consulted — null means unknown, not unregistered.","example":true},"country_code":{"type":"string","description":"Member state the number belongs to.","example":"FR"},"source":{"type":"string","description":"Where the registration verdict came from.","enum":["LIVE","CACHE","STALE","UNVERIFIED","NOT_APPLICABLE"]},"checked_at":{"type":"string","format":"date-time","description":"When the registration was last confirmed against VIES."},"trader_name":{"type":"string","description":"Registered trading name, when the member state discloses it."},"trader_address":{"type":"string","description":"Registered address, when the member state discloses it."},"vies_available":{"type":"boolean","description":"Whether VIES could answer for this country during the request."},"consultation_number":{"type":"string","description":"The consultation number VIES issued for this lookup — the receipt a tax authority accepts as evidence of the check. Present only when the account has a VAT number configured, since VIES issues one only to an identified requester.","example":"WAPIAAAAX8k1abcd"},"trader_name_match":{"type":"string","description":"Present when a traderName was sent with the request: whether it belongs to the registered holder.","enum":["MATCH","MISMATCH","NOT_AVAILABLE"]},"trader_name_match_source":{"type":"string","description":"Who compared the names: VIES itself (Spain), or VerifNow against the name VIES published. Absent when no comparison was possible.","enum":["VIES","VERIFNOW"]}}},"VatValidationRequest":{"type":"object","description":"A VAT number to validate, and optionally the company name to check it against.","properties":{"value":{"type":"string","description":"The VAT number, with its country prefix.","example":"IE6388047V"},"traderName":{"type":"string","description":"Optional. The company you expect to hold this VAT number. The response then says whether it matches the registered holder, in vatDetails.trader_name_match.","example":"Google Ireland Ltd","maxLength":200}},"required":["value"]},"ValidationRequest":{"type":"object","description":"Payload containing the value to validate.","properties":{"value":{"type":"string","description":"The value to validate"}},"required":["value"]},"CountryVatRates":{"type":"object","description":"One member state's VAT rates.","properties":{"countryCode":{"type":"string","description":"Member state, as TEDB and VIES name it: Greece is EL.","example":"FR"},"standardRate":{"type":"number","example":20},"reducedRates":{"type":"array","description":"Every reduced, super-reduced and parking rate on the mainland territory, ascending. Which one applies depends on the product.","example":[2.1,5.5,10],"items":{"type":"number"}},"regionalRates":{"type":"array","description":"Rates for part of the territory only — overseas departments, autonomous regions, islands.","items":{"$ref":"#/components/schemas/RegionalVatRate"}},"situationOn":{"type":"string","format":"date","description":"The date TEDB says these rates apply from.","example":"2026-07-01"},"fetchedAt":{"type":"string","format":"date-time","description":"When we last retrieved them from TEDB."}}},"RegionalVatRate":{"type":"object","description":"A rate applying to part of a member state only.","properties":{"rate":{"type":"number","example":8.5},"note":{"type":"string","description":"Where it applies, in TEDB's words.","example":"The standard VAT rate in Martinique, Guadeloupe and Réunion is 8.5%."},"euVatArea":{"type":"boolean","description":"False for the Canary Islands and the French overseas territories, which the VAT Directive excludes (Article 6(1)): goods shipped there from another member state are an export, not a distance sale at this rate.","example":false}}},"VatRates":{"type":"object","description":"VAT rates of every EU member state.","properties":{"source":{"type":"string","example":"TEDB"},"sourceUrl":{"type":"string","example":"https://ec.europa.eu/taxation_customs/tedb/"},"countries":{"type":"integer","format":"int32","description":"Member states in this response. 27 unless TEDB has never returned one cleanly.","example":27},"rates":{"type":"array","items":{"$ref":"#/components/schemas/CountryVatRates"}}}},"CountryStatusResponse":{"type":"object","properties":{"countryCode":{"type":"string"},"availableNow":{"type":"boolean"},"availabilityPercent":{"type":"number","format":"double"},"sampleCount":{"type":"integer","format":"int64"}}},"ViesStatusResponse":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"windowDays":{"type":"integer","format":"int32"},"viesReachable":{"type":"boolean"},"lastCheckedAt":{"type":"string","format":"date-time"},"countriesTracked":{"type":"integer","format":"int32"},"countriesUnavailableNow":{"type":"integer","format":"int64"},"countries":{"type":"array","items":{"$ref":"#/components/schemas/CountryStatusResponse"}}}}},"parameters":{"X-VerifNow-SDK":{"name":"X-VerifNow-SDK","in":"header","description":"Identifies the calling SDK. Format: <lang>/<version>. Version must follow SemVer (MAJOR.MINOR.PATCH). Regex: ^[a-zA-Z0-9_-]+/\\d+\\.\\d+\\.\\d+$. Example: java/1.2.3. If missing or invalid → custom.","required":false,"schema":{"type":"string","example":"java/1.2.3"}}},"securitySchemes":{"X-API-Key":{"type":"apiKey","description":"API Key for authentication","name":"X-API-Key","in":"header"}}}}