{"openapi":"3.1.0","info":{"title":"VerifNow API","description":"API for validating business data (Email, IBAN, VAT, Phone)","license":{"name":"Private","url":"https://www.verifnow.io"},"version":"v1.0.6"},"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":"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.","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/ValidationRequest"},"examples":{"VAT example":{"summary":"VAT number to validate","description":"VAT example","value":{"value":"FR 123 456 789 01"}}}}},"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 the format and validity of a US Social Security Number","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":"123-45-6789"}}}}},"required":true},"responses":{"200":{"description":"Validation performed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResult"},"examples":{"Valid SSN":{"summary":"Successful SSN validation","description":"Valid SSN","value":{"valid":true,"message":"Valid SSN","normalizedValue":"123456789","originalValue":"123-45-6789"}}}}}},"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":"Accepts a phone number and returns whether it is valid. Normalization strips spaces, dashes, parentheses and keeps an optional leading '+'. Valid numbers contain 10 to 15 digits.","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":"+1 (415) 555-2671"}}}}},"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":"+14155552671","originalValue":"+1 (415) 555-2671"}}}}}},"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 the format and check letter of a Spanish Tax Identification Number","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":"12345678Z","originalValue":"12345678Z"}}}}}},"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 check digit of a Canadian Social Insurance Number","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 NAS/SIN","normalizedValue":"046454286","originalValue":"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 IBAN format and checksum (mod-97). Normalization uppercases letters and removes spaces.","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"}}}}}},"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"}}}}}}}},"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.","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"}}},"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"}}},"ValidationRequest":{"type":"object","description":"Payload containing the value to validate.","properties":{"value":{"type":"string","description":"The value to validate"}},"required":["value"]}},"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"}}}}