{ "openapi": "3.1.0", "info": { "title": "Egon API - Validation Services", "version": "1.0.0", "description": "Validation and normalization of addresses, names, phones, emails, tax codes, and VAT numbers. Every result has quality flags and codes." }, "servers": [ { "url": "https://{host}:{port}/Egon", "variables": { "host": {"default": "localhost"}, "port": {"default": "8080"} }, "description": "Replace `{host}` and `{port}` with the address of your Egon instance." } ], "security": [{"tokenAuth": []}], "tags": [ { "name": "Validation Services", "description": "Validation and normalization of addresses, names, phones, emails, tax codes, and VAT numbers. Every result has quality flags and codes." } ], "paths": { "/api/norm#address": { "post": { "operationId": "address", "tags": ["Validation Services"], "summary": "Address", "description": "The Address endpoint validates and normalizes an address, returning the street, house number, postal data, Egon codes, and geographic coordinates.", "requestBody": { "description": "Country context, processing options, and address fields to validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationAddressRequest" }, "example": { "par": {"iso3": "ITA", "geo": "S"}, "data": { "address": {"city": "Verona", "street": "Via pacinotti 4b"} } } } } }, "responses": { "200": { "description": "Normalized address, geocoding coordinates, postal format, quality indicators, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationAddressResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "The address was processed successfully. Returns normalized address levels, geocoding coordinates, and quality flags.", "value": { "data": { "address": { "standard": { "iso2": "IT", "iso3": "ITA", "country": "Italia", "country_lng": "380", "region": "Veneto", "region_lng": "380", "province": "Verona", "province_code": "VR", "province_lng": "380", "city": "Verona", "city_lng": "380", "zipcode": "37135", "street_type": "Via", "street_name": "Antonio Pacinotti", "street": "Via Antonio Pacinotti", "street_lng": "380", "address": "Via Antonio Pacinotti,4/B", "full_address": "Via Antonio Pacinotti,4/B, Verona, VR, Veneto, 37135, Italia", "hn": "4/B", "postal_town1": "VERONA", "match_code": "3800000473038000073526000000004000000000", "adm_code": [ {"iso3": "ITA", "type": "50137", "value": "VR"}, {"iso3": "ITA", "type": "30000", "value": "L781"}, { "iso3": "ITA", "type": "30021", "value": "023091" }, {"iso3": "ITA", "type": "30022", "value": "005"}, { "iso3": "ITA", "type": "30030", "value": "11700" }, { "iso3": "ITA", "type": "30050", "value": "0777000" }, {"iso3": "ITA", "type": "30060", "value": "086"}, { "iso3": "ITA", "type": "30061", "value": "660999" }, {"iso3": "ITA", "type": "30070", "value": "ITA"}, {"iso3": "ITA", "type": "30071", "value": "IT"}, {"iso3": "ITA", "type": "30072", "value": "380"}, { "iso3": "ITA", "type": "30114", "value": "ITALIA" } ], "egon_code": { "city": 38000004730, "street": 38000073526, "hn": 380100008326045 } }, "smart": { "country": "Italia", "administrative_level": "Verona", "city": "Verona", "address": "Via Antonio Pacinotti,4/B", "zipcode": "37135" } }, "geo": { "lat_long": "45.40616800, 10.97379600", "geo_level": "A41-111", "census_code": "0230910000922", "census_lat_long": "45.40753707, 10.97251045" }, "postal": { "row4": "VIA ANTONIO PACINOTTI 4/B", "row5": "37135 VERONA VR" } }, "quality": { "address": { "locality": { "flag": "0", "code": 0, "description": "Ok" }, "street": { "flag": "1", "code": 801, "description": "Candidato strada con parole in meno" }, "hn": {"flag": "0", "code": 0, "description": "Ok"} } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#email": { "post": { "operationId": "email", "tags": ["Validation Services"], "summary": "Email", "description": "Validate one or more email addresses and return normalized values together with syntax and domain quality indicators.", "requestBody": { "description": "Country context and collection of email addresses to validate.", "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ValidationEmailRequest"}, "example": { "par": {"iso3": "ITA"}, "data": { "emails": [ {"email": "info@egon.com"}, {"email": "info@example.com"} ] } } } } }, "responses": { "200": { "description": "Normalized email addresses, validation quality indicators, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationEmailResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Email addresses verified for correct syntax and domain structure.", "value": { "data": { "emails": [ {"email": "info@egon.com"}, {"email": "info@example.com"} ] }, "quality": { "emails": [ {"flag": "0", "code": 0, "description": "Ok"}, {"flag": "0", "code": 0, "description": "Ok"} ] }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#name": { "post": { "operationId": "name", "tags": ["Validation Services"], "summary": "Name", "description": "Validate personal names, sole proprietorships, company names, co-holder names, and family surnames, and return normalized and structured output.", "requestBody": { "description": "Country context and person or company name string to validate.", "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ValidationNameRequest"}, "example": { "par": {"iso3": "ITA"}, "data": {"name": {"full_name": "Dottor Mario Rossi"}} } } } }, "responses": { "200": { "description": "Structured name components, recognized gender, separated title/surname/name, and quality indicators.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationNameResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Name successfully recognized, titles separated, and structured into first name and surname.", "value": { "data": { "name": { "type_ana": "1", "gender": "1", "full_name": "ROSSI,MARIO", "last_name": "ROSSI", "first_name": "MARIO", "title": "DOTTORE" } }, "quality": { "name": { "person": { "flag": "0", "code": 0, "description": "Ok" } } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#phone": { "post": { "operationId": "phone", "tags": ["Validation Services"], "summary": "Phone", "description": "Validate and normalize telephone numbers provided either as individual international and national prefix components or as a single full number.", "requestBody": { "description": "Country context and telephone numbers to normalize and validate.", "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/ValidationPhoneRequest"}, "example": { "par": {"iso3": "ITA"}, "data": { "phones": [ {"pre_int": "39", "pre_nat": "045", "number": "8200794"}, {"number": "390458201847"} ] } } } } }, "responses": { "200": { "description": "Normalized phone numbers with country prefixes, line type codes, quality indicators, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationPhoneResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Phone numbers validated, separated into international and national prefixes, and standardized.", "value": { "data": { "phones": [ { "iso3": "ITA", "type": "00001", "pre_int": "+39", "pre_nat": "045", "number": "8200794" }, { "iso3": "ITA", "type": "00001", "pre_int": "+39", "pre_nat": "045", "number": "8201847" } ] }, "quality": { "phones": [ {"flag": "0", "code": 0, "description": "Ok"}, {"flag": "0", "code": 0, "description": "Ok"} ] }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-calc": { "post": { "operationId": "tax-code-calc", "tags": ["Validation Services"], "summary": "Tax Code Calculation", "description": "Calculate an Italian tax code (Codice Fiscale) from surname, name, gender, date of birth, and city of birth, with a quality flag for the result.", "requestBody": { "description": "Country context, `taxfnx` function `3`, and personal identity data.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCalcRequest" }, "example": { "par": {"iso3": "ITA", "taxfnx": "3"}, "data": { "name": { "full_name": "Rossi", "first_name": "Mario", "gender": "1", "birth_date": "19930219", "birth_place": "Verona" } } } } } }, "responses": { "200": { "description": "Calculated tax code, quality indicators for personal identity fields, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCalcResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Tax code calculated successfully from personal information.", "value": { "data": { "tax_code": {"cod_description": "RSSMRA93B19L781K"} }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" }, "name": { "person": { "flag": "0", "code": 0, "description": "Ok" }, "birth_date": { "flag": "0", "code": 0, "description": "Ok" }, "birth_place": { "flag": "0", "code": 0, "description": "Ok" } } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-check": { "post": { "operationId": "tax-code-check", "tags": ["Validation Services"], "summary": "Tax Code Validation", "description": "Check the formal validity and structure of an Italian tax code (Codice Fiscale) and get a quality flag and code that describe the result.", "requestBody": { "description": "Country context, `taxfnx` function `2`, and tax code to check.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCheckRequest" }, "example": { "par": {"iso3": "ITA", "taxfnx": "2"}, "data": { "tax_code": { "cod_iso3": "ITA", "cod_type": "01110", "cod_description": "RSSMRA93B19L781K" } } } } } }, "responses": { "200": { "description": "Validated tax code, extraction verification quality indicator, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeCheckResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Tax code verified and found formally valid.", "value": { "data": { "tax_code": {"cod_description": "RSSMRA93B19L781K"} }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-extract": { "post": { "operationId": "tax-code-extract", "tags": ["Validation Services"], "summary": "Tax Code Extraction", "description": "Extract gender, date of birth, and place of birth (city and province) from an Italian tax code (Codice Fiscale), with a quality flag.", "requestBody": { "description": "Country context, `taxfnx` function `5`, and tax code to decode.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeExtractRequest" }, "example": { "par": {"iso3": "ITA", "taxfnx": "5"}, "data": { "tax_code": { "cod_iso3": "ITA", "cod_type": "01110", "cod_description": "RSSMRA93B19L781K" } } } } } }, "responses": { "200": { "description": "Extracted birth date, birth province, birth city, quality indicator, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeExtractResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Birth details and province extracted successfully from the tax code.", "value": { "data": { "name": { "birth_date": "19930219", "birth_province": "VR", "birth_place": "VERONA" } }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#tax-code-match": { "post": { "operationId": "tax-code-match", "tags": ["Validation Services"], "summary": "Tax Code Verification", "description": "Compare a tax code against a person's identifying data, including name, gender, date of birth, and birthplace.", "requestBody": { "description": "Country context, `taxfnx` function `1`, personal identity data, and tax code to compare.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeMatchRequest" }, "example": { "par": {"iso3": "ITA", "taxfnx": "1"}, "data": { "name": { "full_name": "Rossi", "first_name": "Mario", "gender": "1", "birth_date": "19930219", "birth_place": "Verona" }, "tax_code": { "cod_iso3": "ITA", "cod_type": "01110", "cod_description": "RSSMRA93B19L781K" } } } } } }, "responses": { "200": { "description": "Normalized personal data, tax code, comparison quality results for identity, birth date, birthplace, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationTaxCodeMatchResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Tax code matches personal information completely.", "value": { "data": { "name": { "type_ana": "1", "gender": "1", "full_name": "ROSSI,MARIO", "last_name": "ROSSI", "first_name": "MARIO", "birth_date": "19930219", "birth_province": "VR", "birth_place": "VERONA" }, "tax_code": {"cod_description": "RSSMRA93B19L781K"} }, "quality": { "tax_code": { "flag": "0", "code": 0, "description": "Ok" }, "name": { "person": { "flag": "0", "code": 0, "description": "Ok" }, "birth_date": { "flag": "0", "code": 0, "description": "Ok" }, "birth_place": { "flag": "0", "code": 0, "description": "Ok" } } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#vat-check": { "post": { "operationId": "vat-check", "tags": ["Validation Services"], "summary": "VAT Validation", "description": "Check the structure and formal validity of a VAT number (Partita IVA) and get a quality flag and code that describe the result of the check.", "requestBody": { "description": "Country context and VAT number to validate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatCheckRequest" }, "example": { "par": {"iso3": "ITA"}, "data": { "vat_number": { "cod_iso3": "ITA", "cod_type": "01111", "cod_description": "10851310960" } } } } } }, "responses": { "200": { "description": "Validated VAT number, verification quality indicator, and system status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatCheckResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "VAT number validated and found formally correct.", "value": { "data": { "vat_number": {"cod_description": "10851310960"} }, "quality": { "vat_number": { "flag": "0", "code": 0, "description": "Ok" } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } }, "/api/norm#vat-ext": { "post": { "operationId": "vat-ext", "tags": ["Validation Services"], "summary": "VAT Extraction", "description": "Validate and enrich company data from a VAT number: official business name, legal address, phone numbers, PEC email, and ATECO codes.", "requestBody": { "description": "Country context, `vatfnx` function `E`, and VAT number to enrich.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatExtRequest" }, "example": { "par": {"iso3": "ITA", "vatfnx": "E"}, "data": {"vat_number": {"cod_description": "01032450072"}} } } } }, "responses": { "200": { "description": "Enriched company profile including business name, tax code, address, phones, emails, activity codes, and quality indicator.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationVatExtResponse" }, "examples": { "valid": { "summary": "Valid response", "description": "Company information enriched from VAT number.", "value": { "data": { "name": { "firm_name": "CVA ENERGIE SRL", "title": "Societa' A Responsabilita' Limitata", "status": "Attiva" }, "tax_code": {"cod_description": "01032450072"}, "vat_number": {"cod_description": "01032450072"}, "address": { "standard": { "country": "Italia", "province": "Valle D'Aosta/Valle D'Aoste", "province_code": "AO", "city": "CHATILLON", "zipcode": "11024", "street_type": "VIA", "street_name": "STAZIONE", "full_address": "VIA STAZIONE 31, CHATILLON 11024 AO Valle D'Aosta/Valle D'Aoste Italia", "hn": "31" } }, "phones": [ {"type": "00001", "number": "0166822925"}, {"type": "00003", "number": "0166821032"} ], "emails": [ {"type": "01601", "email": "azienda@pec.example.com"}, {"type": "01115", "email": "info@example.com"} ], "codes": [ {"type": "01600", "cod_description": "3514"}, {"type": "01116", "cod_description": "cvatrading.it"}, { "type": "CBILL", "cod_description": "CVA ENERGIE S.R.L.#CPVVN#01032450072#002" }, { "type": "CBILL", "cod_description": "CVA ENERGIE SRL BUSIN. E SMALL BUS. M.L.#93Z76#01032450072#001" }, { "type": "CBILL", "cod_description": "CVA ENERGIE SRL CLIENTI MERCATO MAGGIOR TUTELA#7G770#01032450072#001" }, { "type": "CBILL", "cod_description": "CVA ENERGIE SRL CLIENTI RETAIL MERCATO LIBERO#AZKH5#01032450072#001" } ] }, "quality": { "vat_number": { "flag": "1", "code": 911, "description": "CODICE TROVATO: ARRICCHITI DATI DA LIVELLO 2" } }, "system": {"ret_code": 0, "des_ret_code": "Ok"} } }, "missingPar": { "summary": "Missing par", "description": "The request is missing the required par object.", "value": { "system": {"ret_code": 1, "des_ret_code": "par not found"} } }, "missingIso2AndIso3": { "summary": "Missing iso2 and iso3", "description": "Iso2 or Iso3 field is missing.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 or iso3 parameter not found" } } }, "invalidIso2": { "summary": "Invalid iso2", "description": "The iso2 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso2 not found" } } }, "invalidIso3": { "summary": "Invalid iso3", "description": "The iso3 value is not valid.", "value": { "system": { "ret_code": 1, "des_ret_code": "iso3 not found" } } }, "missingData": { "summary": "Missing data", "description": "The request is missing the required data object.", "value": { "system": { "ret_code": 1, "des_ret_code": "data not found" } } }, "missingToken": { "summary": "Missing token", "description": "Provide the required authentication token in the token request header.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not found" } } }, "invalidToken": { "summary": "Invalid token", "description": "The supplied token is invalid, expired, or not authorized for this service.", "value": { "system": { "ret_code": 1, "des_ret_code": "token not valid" } } } } } } } } } } }, "components": { "securitySchemes": { "tokenAuth": { "type": "apiKey", "in": "header", "name": "token", "description": "Authentication token sent in the `token` request header." } }, "schemas": { "ValidationPhone": { "type": "object", "properties": { "pre_int": { "type": "string", "description": "International telephone prefix" }, "pre_nat": { "type": "string", "description": "National telephone prefix" }, "number": {"type": "string", "description": "Telephone number"} }, "required": ["number"] }, "ValidationEmail": { "type": "object", "properties": { "email": {"type": "string", "description": "Email address"} }, "required": ["email"] }, "ValidationName": { "type": "object", "properties": { "type_ana": {"type": "string", "description": "Name analysis type"}, "gender": {"type": "string", "description": "Gender"}, "full_name": {"type": "string", "description": "Full name"}, "mid_name": {"type": "string", "description": "Middle name"}, "first_name": {"type": "string", "description": "First name"}, "title": {"type": "string", "description": "Title"}, "name_des": {"type": "string", "description": "Name description"}, "birth_date": {"type": "string", "description": "Date of birth"}, "birth_province": { "type": "string", "description": "Province of birth" }, "birth_place": {"type": "string", "description": "Place of birth"} } }, "ValidationAddress": { "type": "object", "properties": { "egoncode_place": { "format": "int64", "type": "number", "description": "Egon place code." }, "egoncode_hn": { "format": "int64", "type": "number", "description": "Egon house-number code." }, "country": {"type": "string", "description": "Country description."}, "state": {"type": "string", "description": "State description."}, "region": {"type": "string", "description": "Region description."}, "province": { "type": "string", "description": "Province description." }, "city": { "type": "string", "description": "City or municipality description." }, "district1": { "type": "string", "description": "First district or locality description." }, "district2": { "type": "string", "description": "Second district or locality description." }, "district3": { "type": "string", "description": "Third district or locality description." }, "zipcode": {"type": "string", "description": "Postal code."}, "street_type": { "type": "string", "description": "Street type, for example Via, Viale, Piazza, or Corso." }, "street": { "type": "string", "description": "Street description or street name." }, "address": { "type": "string", "description": "Full unstructured address." }, "hn": {"type": "string", "description": "House number."}, "care_of": {"type": "string", "description": "Care-of information."}, "building": { "type": "string", "description": "Building information." }, "sub_building": { "type": "string", "description": "Sub-building information." }, "organization": { "type": "string", "description": "Organization name." }, "street_type_str2": { "type": "string", "description": "Second street type." }, "street_2": { "type": "string", "description": "Second street description." }, "hn_2": {"type": "string", "description": "Second house number."} }, "description": "Address information to validate. All individual address fields are optional." }, "ValidationDataOutput": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/ValidationNameData", "description": "Parsed and validated personal or corporate name details" }, "tax_code": { "$ref": "#/components/schemas/ValidationTaxCodeData", "description": "Tax code details" }, "vat_number": { "$ref": "#/components/schemas/ValidationVatNumberData", "description": "VAT number details" }, "address": { "$ref": "#/components/schemas/ValidationAddressData", "description": "Normalized address details" }, "geo": { "$ref": "#/components/schemas/ValidationGeoData", "description": "Geocoding coordinates and source quality level" }, "postal": { "$ref": "#/components/schemas/ValidationPostalData", "description": "Standardized postal output rows" }, "phones": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationPhoneData"}, "description": "Phone numbers to validate" }, "emails": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationEmailData"}, "description": "Email addresses to validate" }, "codes": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationCodeData"}, "description": "Administrative and cadastral domain codes" } }, "description": "Normalized address data and optional output." }, "ValidationPhoneData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "type": {"type": "string", "description": "Administrative-code type"}, "pre_int": { "type": "string", "description": "International telephone prefix" }, "pre_nat": { "type": "string", "description": "National telephone prefix" }, "number": {"type": "string", "description": "Telephone number"} } }, "ValidationEmailData": { "type": "object", "properties": { "email": {"type": "string", "description": "Email address"} } }, "ValidationTaxCodeData": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationCodeData": { "type": "object", "properties": { "type": {"type": "string", "description": "Administrative-code type"}, "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationVatNumberData": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Code description" } } }, "ValidationNameData": { "type": "object", "properties": { "type_ana": {"type": "string", "description": "Name analysis type"}, "gender": {"type": "string", "description": "Gender"}, "full_name": {"type": "string", "description": "Full name"}, "last_name": {"type": "string", "description": "Separate surname"}, "mid_name": {"type": "string", "description": "Middle name"}, "first_name": {"type": "string", "description": "First name"}, "prename": {"type": "string", "description": "Separate name"}, "title": {"type": "string", "description": "Title"}, "firm_type": {"type": "string", "description": "Company legal form"}, "birth_date": {"type": "string", "description": "Date of birth"}, "birth_country": { "type": "string", "description": "Country of birth" }, "birth_province": { "type": "string", "description": "Province of birth" }, "birth_place": {"type": "string", "description": "Place of birth"}, "name_des": {"type": "string", "description": "Name description"}, "status": {"type": "string", "description": "Validation status"} } }, "ValidationAddressData": { "type": "object", "properties": { "standard": { "$ref": "#/components/schemas/ValidationStandardData", "description": "Standard postal address formatting" }, "short": { "$ref": "#/components/schemas/ValidationShortData", "description": "Short descriptions" }, "smart": { "$ref": "#/components/schemas/ValidationSmartData", "description": "Smart formatted address components" } }, "description": "Normalized address result." }, "ValidationStandardData": { "type": "object", "properties": { "iso2": { "type": "string", "description": "Country ISO 3166-1 alpha-2 code." }, "iso3": { "type": "string", "description": "Country ISO 3166-1 alpha-3 code." }, "country": { "type": "string", "description": "Normalized country description." }, "country_lng": { "type": "string", "description": "Country language code." }, "state": { "type": "string", "description": "Normalized state description." }, "state_code": {"type": "string", "description": "State code."}, "state_lng": { "type": "string", "description": "State language code." }, "region": { "type": "string", "description": "Normalized region description." }, "region_code": {"type": "string", "description": "Region code."}, "region_lng": { "type": "string", "description": "Region language code." }, "province": { "type": "string", "description": "Normalized province description." }, "province_code": {"type": "string", "description": "Province code."}, "province_lng": { "type": "string", "description": "Province language code." }, "city": { "type": "string", "description": "Normalized city description." }, "city_lng": {"type": "string", "description": "City language code."}, "locality": { "type": "string", "description": "Normalized locality or district description." }, "locality_lng": { "type": "string", "description": "Locality language code." }, "locality2": { "type": "string", "description": "Second locality or district description." }, "locality2_lng": { "type": "string", "description": "Second locality language code." }, "locality3": { "type": "string", "description": "Third locality or district description." }, "locality3_lng": { "type": "string", "description": "Third locality language code." }, "zipcode": { "type": "string", "description": "Normalized postal code." }, "street_type": { "type": "string", "description": "Normalized street-type description." }, "street_name": { "type": "string", "description": "Normalized street name." }, "street": { "type": "string", "description": "Normalized street type and name." }, "street_lng": { "type": "string", "description": "Street language code." }, "address": { "type": "string", "description": "Formatted street address and house number." }, "full_address": { "type": "string", "description": "Complete normalized address." }, "street_type2": { "type": "string", "description": "Second street-type description." }, "street_name2": { "type": "string", "description": "Second street name." }, "street2": { "type": "string", "description": "Second normalized street." }, "street2_lng": { "type": "string", "description": "Second street language code." }, "hn": {"type": "string", "description": "Normalized house number."}, "hn_ext": { "type": "string", "description": "Additional house-number information." }, "care_of": {"type": "string", "description": "Care-of information."}, "hn_2": {"type": "string", "description": "Second house number."}, "building": { "type": "string", "description": "Building information." }, "subbuilding": { "type": "string", "description": "Sub-building information." }, "organization": {"type": "string", "description": "Organization"}, "postal_town1": { "type": "string", "description": "Primary postal town or area." }, "postal_town2": { "type": "string", "description": "Secondary postal town or locality." }, "match_code": { "type": "string", "description": "Address matching result code." }, "adm_code": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationAdmCodeData"}, "description": "Administrative code collection." }, "cnd": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationCndData"}, "description": "Candidate address values when matching is not exact." }, "egon_code": { "$ref": "#/components/schemas/ValidationEgonCodeData", "description": "Egon internal code place, street, and house number" } }, "description": "Complete structured and normalized address." }, "ValidationShortData": { "type": "object", "properties": { "country": {"type": "string", "description": "Country description."}, "state": {"type": "string", "description": "State description."}, "region": {"type": "string", "description": "Region description."}, "province": { "type": "string", "description": "Province description." }, "city": {"type": "string", "description": "City description."}, "locality": { "type": "string", "description": "Locality or district description." }, "locality2": { "type": "string", "description": "Second locality description." }, "locality3": { "type": "string", "description": "Third locality description." }, "street_type": { "type": "string", "description": "Street-type description." }, "street_name": {"type": "string", "description": "Street name."}, "street": {"type": "string", "description": "Street type and name."} }, "description": "Short descriptions, returned when par.fmtsht is enabled." }, "ValidationAdmCodeData": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country ISO alpha-3 code." }, "type": { "type": "string", "description": "Administrative-code type." }, "value": { "type": "string", "description": "Administrative code or description." } } }, "ValidationCndData": { "type": "object", "properties": { "province": {"type": "string", "description": "Candidate province."}, "city": {"type": "string", "description": "Candidate city."}, "locality": {"type": "string", "description": "Candidate locality."}, "street": {"type": "string", "description": "Candidate street."}, "zipcode": { "type": "string", "description": "Candidate postal code." }, "street_code": { "format": "int64", "type": "number", "description": "Candidate street code." } } }, "ValidationEgonCodeData": { "type": "object", "properties": { "city": { "format": "int64", "type": "number", "description": "Egon city code." }, "locality": { "format": "int64", "type": "number", "description": "Egon locality code." }, "street": { "format": "int64", "type": "number", "description": "Egon street code." }, "hn": { "format": "int64", "type": "number", "description": "Egon house-number code." } }, "description": "Egon hierarchical code collection." }, "ValidationSmartData": { "type": "object", "properties": { "country": {"type": "string", "description": "Country description"}, "administrative_level": { "type": "string", "description": "Administrative level." }, "city": {"type": "string", "description": "City."}, "address": { "type": "string", "description": "Street type + Street description + House number" }, "zipcode": {"type": "string", "description": "Postal code."} }, "description": "Simplified address representation." }, "ValidationGeoData": { "type": "object", "properties": { "lat_long": { "type": "string", "description": "Coordinates in latitude, longitude format." }, "geo_level": { "type": "string", "description": "Geocoding quality level." }, "census_code": {"type": "string", "description": "Census code."}, "census_lat_long": { "type": "string", "description": "Census coordinates." } }, "description": "Geocoding output, returned when par.geo is set to S." }, "ValidationPostalData": { "type": "object", "properties": { "row1": {"type": "string", "description": "Postal row 1."}, "row2": {"type": "string", "description": "Postal row 2."}, "row3": {"type": "string", "description": "Postal row 3."}, "row4": {"type": "string", "description": "Postal row 4."}, "row5": {"type": "string", "description": "Postal row 5."}, "row6": {"type": "string", "description": "Postal row 6."}, "row7": {"type": "string", "description": "Postal row 7."} }, "description": "Postal-format output rows." }, "ValidationQuality": { "type": "object", "properties": { "phones": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationPhoneQuality"}, "description": "Phone numbers to validate" }, "emails": { "type": "array", "items": {"$ref": "#/components/schemas/ValidationEmailQuality"}, "description": "Email addresses to validate" }, "tax_code": { "$ref": "#/components/schemas/ValidationTaxCodeQuality", "description": "Quality indicator result (see Quality indicators → Tax code section)" }, "name": { "$ref": "#/components/schemas/ValidationNameQuality", "description": "Quality indicator result (see Quality indicators → Person section)" }, "address": { "$ref": "#/components/schemas/ValidationAddressQuality", "description": "Quality indicator result (see Quality indicators → Address section)" }, "vat_number": { "$ref": "#/components/schemas/ValidationVatNumberQuality", "description": "Quality indicator result (see Quality indicators → VAT section)" } }, "description": "Address validation quality indicators." }, "ValidationPhoneQuality": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationEmailQuality": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationTaxCodeQuality": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationVatNumberQuality": { "type": "object", "x-wp-new-istance": true, "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationNameQuality": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationPersonQualityInternal", "description": "Quality indicator result - person" }, "birth_date": { "$ref": "#/components/schemas/ValidationBirthDate", "description": "Quality indicator result - birth date" }, "birth_place": { "$ref": "#/components/schemas/ValidationBirthPlace", "description": "Quality indicator result - birth place" } } }, "ValidationPersonQualityInternal": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationBirthDate": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationBirthPlace": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": { "format": "int32", "type": "number", "description": "Quality code" }, "description": { "type": "string", "description": "Human-readable quality description" } } }, "ValidationAddressQuality": { "type": "object", "properties": { "locality": { "$ref": "#/components/schemas/ValidationLocality", "description": "Quality indicator result - locality" }, "street": { "$ref": "#/components/schemas/ValidationStreet", "description": "Quality indicator result - street" }, "hn": { "$ref": "#/components/schemas/ValidationHouseNumber", "description": "Quality indicator result - house number" } }, "description": "Quality results by address component." }, "ValidationLocality": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag."}, "code": { "format": "int32", "type": "number", "description": "Quality code." }, "description": { "type": "string", "description": "Human-readable quality result." } }, "description": "Quality of locality or city matching." }, "ValidationStreet": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag."}, "code": { "format": "int32", "type": "number", "description": "Quality code." }, "description": { "type": "string", "description": "Human-readable quality result." } }, "description": "Quality of street matching." }, "ValidationHouseNumber": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag."}, "code": { "format": "int32", "type": "number", "description": "Quality code." }, "description": { "type": "string", "description": "Human-readable quality result." } }, "description": "Quality of house-number matching." }, "ValidationSystem": { "type": "object", "properties": { "ret_code": { "format": "int32", "type": "number", "description": "Processing result code. 0 means no blocking error." }, "des_ret_code": { "type": "string", "description": "Human-readable processing result." } }, "description": "Request processing status." }, "ValidationAddressRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationAddressPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["address"], "properties": { "address": {"$ref": "#/components/schemas/ValidationAddress"} }, "description": "Address information to validate" } } }, "ValidationAddressResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ValidationDataOutput", "description": "Normalized and enriched validation output data" }, "quality": { "$ref": "#/components/schemas/ValidationQuality", "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationEmailRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationEmailPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["emails"], "properties": { "emails": { "type": "array", "description": "Email addresses to validate", "items": {"$ref": "#/components/schemas/ValidationEmail"} } }, "description": "Input data to validate" } } }, "ValidationEmailResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "emails": { "type": "array", "description": "Normalized email addresses", "items": {"$ref": "#/components/schemas/ValidationEmail"} } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "emails": { "type": "array", "description": "Quality indicator results for each email", "items": {"$ref": "#/components/schemas/ValidationQualityItem"} } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationNameRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationNamePar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["name"], "properties": { "name": { "$ref": "#/components/schemas/ValidationName", "description": "Personal name components to parse and validate" } }, "description": "Input data to validate" } } }, "ValidationNameResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "type_ana": { "type": "string", "description": "Customer data type" }, "gender": {"type": "string", "description": "Gender"}, "full_name": { "type": "string", "description": "Validated full name" }, "last_name": { "type": "string", "description": "Separate surname" }, "mid_name": {"type": "string", "description": "Middle name"}, "first_name": { "type": "string", "description": "Separate name" }, "prename": { "type": "string", "description": "Name suffix (e.g. Junior/Senior)" }, "title": { "type": "string", "description": "Academic or professional title" }, "firm_type": { "type": "string", "description": "Official juridical specification (e.g. S.R.L., S.P.A.)" }, "birth_date": { "type": "string", "description": "Date of birth in YYYYMMDD format" }, "birth_country": { "type": "string", "description": "Country of birth" }, "birth_province": { "type": "string", "description": "Province of birth" }, "birth_place": { "type": "string", "description": "City of birth" }, "name_des": { "type": "string", "description": "Name designator" }, "status": {"type": "string", "description": "Status"} }, "description": "Parsed, validated, and normalized personal name details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "name": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_date": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_place": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Quality indicators for personal name parsing and demographic verification" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationPhoneRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationPhonePar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["phones"], "properties": { "phones": { "type": "array", "description": "Collection of telephone numbers to validate", "items": {"$ref": "#/components/schemas/ValidationPhone"} } }, "description": "Input data to validate" } } }, "ValidationPhoneResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "phones": { "type": "array", "description": "Normalized telephone entries", "items": { "type": "object", "properties": { "iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "type": { "type": "string", "description": "Telephone-number type code" }, "pre_int": { "type": "string", "description": "Normalized international dialing prefix" }, "pre_nat": { "type": "string", "description": "Normalized national dialing prefix" }, "number": { "type": "string", "description": "Normalized local telephone number" } } } } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "phones": { "type": "array", "description": "Quality result for each returned phone entry", "items": {"$ref": "#/components/schemas/ValidationQualityItem"} } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeCalcRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeCalcPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["name"], "properties": { "name": { "type": "object", "required": [ "full_name", "first_name", "gender", "birth_date", "birth_place" ], "properties": { "full_name": {"type": "string", "description": "Surname"}, "first_name": {"type": "string", "description": "First name"}, "gender": { "type": "string", "description": "Gender (`1` Male, `2` Female)" }, "birth_date": { "type": "string", "description": "Date of birth in `YYYYMMDD` format" }, "birth_place": { "type": "string", "description": "Birth city description" } }, "description": "Identity and demographic data used to calculate tax code" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeCalcResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Calculated Italian tax code" } }, "description": "Calculated Italian tax code details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": { "$ref": "#/components/schemas/ValidationQualityItem" }, "name": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_date": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_place": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Quality indicators for personal name parsing and demographic verification" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeCheckRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeCheckPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["tax_code"], "properties": { "tax_code": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": {"type": "string", "description": "Type of code"}, "cod_description": { "type": "string", "description": "Italian tax code to check" } }, "description": "Italian tax code to validate" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeCheckResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Italian tax code" } }, "description": "Validated tax code details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": {"$ref": "#/components/schemas/ValidationQualityItem"} }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeExtractRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeExtractPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["tax_code"], "properties": { "tax_code": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": {"type": "string", "description": "Type of code"}, "cod_description": { "type": "string", "description": "Italian tax code to extract info from" } }, "description": "Italian tax code to extract demographics from" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeExtractResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "gender": { "type": "string", "description": "Extracted gender" }, "birth_date": { "type": "string", "description": "Extracted date of birth in `YYYYMMDD` format" }, "birth_province": { "type": "string", "description": "Extracted birth province code" }, "birth_place": { "type": "string", "description": "Extracted birth city description" } }, "description": "Extracted demographic and birthplace data" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": {"$ref": "#/components/schemas/ValidationQualityItem"} }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationTaxCodeMatchRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationTaxCodeMatchPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["name", "tax_code"], "properties": { "name": { "type": "object", "required": [ "full_name", "first_name", "gender", "birth_date", "birth_place" ], "properties": { "full_name": {"type": "string", "description": "Surname"}, "first_name": {"type": "string", "description": "First name"}, "gender": { "type": "string", "description": "Gender (`1` Male, `2` Female)" }, "birth_date": { "type": "string", "description": "Date of birth in `YYYYMMDD` format" }, "birth_place": { "type": "string", "description": "Birth city description" } }, "description": "Personal identity data to compare against tax code" }, "tax_code": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": {"type": "string", "description": "Code type"}, "cod_description": { "type": "string", "description": "Italian tax code to match" } }, "description": "Italian tax code to match" } }, "description": "Input data to validate" } } }, "ValidationTaxCodeMatchResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "type_ana": { "type": "string", "description": "Person/customer type" }, "gender": { "type": "string", "description": "Normalized gender" }, "full_name": { "type": "string", "description": "Normalized full name" }, "last_name": { "type": "string", "description": "Normalized surname" }, "first_name": { "type": "string", "description": "Normalized first name" }, "birth_date": { "type": "string", "description": "Date of birth in `YYYYMMDD` format" }, "birth_province": { "type": "string", "description": "Birth province code" }, "birth_place": { "type": "string", "description": "Normalized birthplace" } }, "description": "Validated identity data and matching outcome" }, "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Italian tax code result" } }, "description": "Matched tax code details" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "tax_code": { "$ref": "#/components/schemas/ValidationQualityItem" }, "name": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_date": { "$ref": "#/components/schemas/ValidationQualityItem" }, "birth_place": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Quality indicators for personal name parsing and demographic verification" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationVatCheckRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationVatCheckPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["vat_number"], "properties": { "vat_number": { "type": "object", "required": ["cod_description"], "properties": { "cod_iso3": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "cod_type": {"type": "string", "description": "Type of code"}, "cod_description": { "type": "string", "description": "VAT number to check" } }, "description": "VAT number to formally validate" } }, "description": "Input data to validate" } } }, "ValidationVatCheckResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "vat_number": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Validated VAT number" } }, "description": "Formal validation outcome for VAT number" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "vat_number": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationVatExtRequest": { "type": "object", "required": ["par", "data"], "properties": { "par": { "$ref": "#/components/schemas/ValidationVatExtPar", "description": "Processing options and country context" }, "data": { "type": "object", "required": ["vat_number"], "properties": { "vat_number": { "type": "object", "required": ["cod_description"], "properties": { "cod_description": { "type": "string", "description": "VAT number to enrich" } }, "description": "VAT number to query extended company registry for" } }, "description": "Input data to validate" } } }, "ValidationVatExtResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "object", "properties": { "firm_name": { "type": "string", "description": "Company name" }, "title": { "type": "string", "description": "Company juridical form" }, "status": { "type": "string", "description": "Company operational status" } }, "description": "Company business name and legal form" }, "tax_code": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "Tax code description" } }, "description": "Company fiscal code details" }, "vat_number": { "type": "object", "properties": { "cod_description": { "type": "string", "description": "VAT number" } }, "description": "Extended VAT registration details" }, "address": { "type": "object", "properties": { "standard": { "type": "object", "properties": { "country": {"type": "string", "description": "Country"}, "province": { "type": "string", "description": "Province description" }, "province_code": { "type": "string", "description": "Province abbreviation" }, "city": {"type": "string", "description": "City name"}, "zipcode": { "type": "string", "description": "Postal code" }, "street_type": { "type": "string", "description": "Street type" }, "street_name": { "type": "string", "description": "Street name" }, "full_address": { "type": "string", "description": "Full normalized address" }, "hn": {"type": "string", "description": "House number"} }, "description": "Standardized company registered address details" } }, "description": "Company registered office address details" }, "phones": { "type": "object", "properties": { "type": {"type": "string", "description": "Phone type"}, "number": {"type": "string", "description": "Phone number"} }, "description": "Associated company phone numbers" }, "emails": { "type": "object", "properties": { "type": {"type": "string", "description": "Email type"}, "email": { "type": "string", "description": "Certified email address (PEC)" } }, "description": "Associated company email addresses" }, "codes": { "type": "object", "properties": { "type": {"type": "string", "description": "Code type"}, "cod_description": { "type": "string", "description": "ATECO economic activity code" } }, "description": "Economic activity (Ateco) and registry codes" } }, "description": "Normalized and enriched validation output data" }, "quality": { "type": "object", "properties": { "vat_number": { "$ref": "#/components/schemas/ValidationQualityItem" } }, "description": "Validation quality indicators and score flags" }, "system": { "$ref": "#/components/schemas/ValidationSystem", "description": "System error and execution status" } } }, "ValidationQualityItem": { "type": "object", "properties": { "flag": {"type": "string", "description": "Quality flag"}, "code": {"type": "number", "description": "Quality result code"}, "description": { "type": "string", "description": "Quality result description" } }, "description": "Quality indicator result (see https://documentation.egon.com/docs/quality-indicators)" }, "ValidationAddressPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "geo": { "type": "string", "default": "N", "description": "Activate geocoding.\n\n- `N` No\n- `S` Yes" }, "fmtout": { "type": "string", "description": "Output format.\n\n- `C` Capitalized\n- `M` Upper case\n- `T` Upper case with apostrophes instead of accents\n- `X` Upper case without accents", "default": "C" }, "fmtsht": { "type": "string", "default": "N", "description": "Activate short descriptions.\n\n- `N` No\n- `S` Yes" }, "lngout": { "type": "string", "description": "Output language.\n\n- `NAT` Native output language\n- `TRA` Transliterated output language\n- `INT` International or English output language\n- `` Keep the input language" }, "tpxout": { "type": "string", "description": "Output description format.\n\n- `LAT` Latinized output without accents" }, "hn_code": { "type": "string", "default": "S", "description": "Activate Egon house-number codes." } }, "description": "Processing options and country context for address validation." }, "ValidationEmailPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for email validation." }, "ValidationNamePar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for name analysis and validation." }, "ValidationPhonePar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for phone number normalization." }, "ValidationTaxCodeCalcPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "3", "description": "Tax-code configuration function.\n\n- `3` Calculate tax code from identity data" } }, "required": ["taxfnx"], "description": "Country context and tax-code calculation function." }, "ValidationTaxCodeCheckPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "2", "description": "Tax-code configuration function.\n\n- `2` Formal check and validation" } }, "required": ["taxfnx"], "description": "Country context and tax-code validation function." }, "ValidationTaxCodeExtractPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "5", "description": "Tax-code configuration function.\n\n- `5` Extract demographic information from tax code" } }, "required": ["taxfnx"], "description": "Country context and tax-code extraction function." }, "ValidationTaxCodeMatchPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "taxfnx": { "type": "string", "default": "1", "description": "Tax-code configuration function.\n\n- `1` Compare and match tax code against personal identity data" } }, "required": ["taxfnx"], "description": "Country context and tax-code match function." }, "ValidationVatCheckPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." } }, "description": "Country context for VAT number formal validation." }, "ValidationVatExtPar": { "type": "object", "properties": { "iso2": { "type": "string", "maxLength": 2, "minLength": 2, "description": "Country code, ISO 3166-1 alpha-2.\n\nOne of `iso2` or `iso3` is **required**." }, "iso3": { "type": "string", "maxLength": 3, "minLength": 3, "description": "Country code, ISO 3166-1 alpha-3.\n\nOne of `iso2` or `iso3` is **required**." }, "vatfnx": { "type": "string", "default": "E", "description": "VAT-number configuration function.\n\n- `E` Extended company registry details lookup" } }, "required": ["vatfnx"], "description": "Country context and extended VAT function." } } } }