{ "openapi": "3.1.0", "info": { "title": "RadarAddress API", "version": "1", "description": "Verifies postal addresses against the delivery standard of their country — Italy and every country whose national address register is in service (Germany, France, Spain, the Netherlands, Czechia; the list grows with the data), street and house number verified with postcode and coordinates; elsewhere the address is put in the country's postal form —, deduplicates records, generates/validates/extracts the Italian tax code (codice fiscale), and verifies email addresses, phone numbers, websites and personal names, all in JSON with one endpoint per service. Every call returns a keyword outcome (empty when there is nothing to report), a human-readable label and, for addresses, the two normalized forms (accented, and postal: ASCII with apostrophes). Identifiers are English: field names, endpoint names, enumerated values and outcome codes. The Italian names used by older clients are still accepted in every request (x-legacy-fields, x-legacy-endpoints, x-legacy-values); `language` selects the language of labels, reasons and messages (x-language), and with `language=it` — or on the historical host without `language` — the response comes back with the Italian keys and codes.", "contact": { "name": "RadarAddress", "email": "info@radaraddress.it", "url": "https://www.radaraddress.com/it/api.php" } }, "externalDocs": { "description": "API documentation with full examples", "url": "https://www.radaraddress.com/it/api.php" }, "servers": [ { "url": "https://www.radaraddress.com", "description": "Production. English identifiers; add \"language\" for the texts (it, en, de, fr, es, nl, pt, sv, no, fi, da, is, el)." }, { "url": "https://www.radaraddress.it", "description": "Historical host: without \"language\" it answers with the Italian field names and codes, for the clients that already use them." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "indice", "description": "Self-service description of the endpoints" }, { "name": "credito", "description": "Available operations and state of the three counters, without consuming any" }, { "name": "contatto", "description": "Contact verification: address, name and tax code of the record" }, { "name": "deduplica", "description": "Record deduplication (duplicate detection)" }, { "name": "codicefiscale", "description": "Tax code (codice fiscale): generate, validate, extract, compare" }, { "name": "arricchimento", "description": "Name enrichment: gender, subject type, title, salutations" }, { "name": "email", "description": "Email verification" }, { "name": "telefono", "description": "Phone verification" }, { "name": "sito", "description": "Website verification" }, { "name": "suggerisci", "description": "Session-based address autocomplete" }, { "name": "nazioni", "description": "ISO 3166-1 catalogue with names in Italian, English and the country's own language" }, { "name": "lavori", "description": "Reading asynchronous jobs (volumes above the per-call limit)" } ], "paths": { "/api/v1/": { "get": { "tags": [ "indice" ], "operationId": "indice", "summary": "Description of the available endpoints", "description": "Public endpoint, no authentication required: lists the API endpoints, how to work asynchronously and the HTTP status codes used.", "security": [], "responses": { "200": { "description": "Description of the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndiceResponse" } } } } } } }, "/api/v1/contact": { "post": { "tags": [ "contatto" ], "operationId": "contattoNormalizza", "summary": "Verifies a contact (address, name, tax code)", "description": "Cleans up a whole contact: the address according to the Italian delivery standard, the name and — when the request carries it — the Italian tax code (codice fiscale), cleaned, completed when only the check character is missing, and compared with last name, first name, gender and birth date. One contact per request body, or up to 500 in `items`. With `items` and `async:true` the job is queued (see GET `/api/v1/contact` and the asynchronous jobs section).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequest" }, "examples": { "singolo": { "summary": "One contact", "value": { "address": "via leopardi 4", "postcode": "20100", "city": "milano", "province": "mi", "id": "RIF-001" } }, "lotto": { "summary": "Up to 500 contacts", "value": { "items": [ { "id": "1", "address": "via leopardi 4", "city": "milano" }, { "id": "2", "address": "via roma 1", "postcode": "20121", "tax_code": "RSSMRA85M01H501Q" } ] } }, "asincrono": { "summary": "Asynchronous batch (above 500, up to 100,000)", "value": { "async": true, "items": [ { "id": "1", "address": "via leopardi 4", "city": "milano" } ] } } } } } }, "responses": { "200": { "description": "Contact processed (single, synchronous batch, or job queued with `async:true`). For a single contact, `ok:false` with the same HTTP status 200 when the outcome is `INCOMPLETE_DATA`: the request was processed, the limitation lies in the input.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ContactSingleResponse" }, { "$ref": "#/components/schemas/ContactBatchResponse" }, { "$ref": "#/components/schemas/JobQueuedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/AccountRequired" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "tags": [ "contatto", "lavori" ], "operationId": "contattoLavoro", "summary": "Reads back an asynchronous contact-verification job", "description": "Reads back the state (and, once completed, the result) of a job queued with `async:true`. Below 5,000 rows the result is also returned in `results` inside the JSON; above that, download it with `format=csv`.", "parameters": [ { "$ref": "#/components/parameters/JobCode" }, { "$ref": "#/components/parameters/JobFormat" } ], "responses": { "200": { "description": "Job state (JSON or, with `format=csv`, the CSV file streamed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateResponse" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "x-legacy-path": "/api/v1/contatto" }, "/api/v1/dedupe": { "post": { "tags": [ "deduplica" ], "operationId": "deduplica", "summary": "Deduplicates a list of records", "description": "Recognises records that refer to the same person at the same address even when they are written differently (abbreviated street or variant spellings, postcode corrected by the engine, last name and first name swapped, diminutives and equivalent first names). The record-matching engine builds on the address normalization engine. Address books (vCard): a contact can have several addresses (`addresses`), several phones (`phones`) and several emails (`emails`), each with a type, with no cap; two contacts match if any pair of their addresses matches, or if they have the same name and one contact detail in common; the merged record is the union of addresses and contact details with their types, and a contact with duplicates inside it comes out merged even on its own (`INTERNAL_DUPLICATE`). One contact is one operation, however many addresses and contact details it has. At most 500 contacts per call (`records` + `reference`); for larger lists use the asynchronous CSV batch from your account area. Instead of a deduplication, the body can carry `{job, group, processed}` to mark a group already read as reviewed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DedupeRequest" }, { "$ref": "#/components/schemas/DedupeUpdateRequest" } ] }, "examples": { "lista_singola": { "summary": "One list: finds the duplicates within it", "value": { "records": [ { "id": "C1", "last_name": "Rossi", "first_name": "Daniela", "address": "Via Leopardi 4", "postcode": "20123", "city": "Milano", "province": "MI" }, { "id": "C2", "last_name": "Rossi", "first_name": "Daniela", "address": "V. Leopardi 4", "postcode": "20100", "city": "milano", "province": "MI" } ] } }, "rubrica": { "summary": "Address book: several addresses and contact details per contact, with their type", "value": { "records": [ { "id": "C1", "last_name": "Rossi", "first_name": "Daniela", "addresses": [ { "type": "home", "address": "Via Roma 12", "postcode": "20021", "city": "Bollate", "province": "MI" }, { "type": "work", "address": "Via Leopardi 4", "postcode": "20123", "city": "Milano", "province": "MI" } ], "phones": [ { "type": "work", "value": "02 66710423" }, "340 7491386" ], "emails": [ { "type": "home", "value": "daniela@example.com" } ] }, { "id": "C2", "last_name": "Rossi", "first_name": "Daniela", "address": "V. Leopardi 4", "postcode": "20100", "city": "milano", "province": "MI", "phone": "+39 340 7491386" } ] } }, "due_liste": { "summary": "With a reference list: looks up each record in the second list", "value": { "records": [ { "id": "C1", "last_name": "Rossi", "first_name": "Daniela", "address": "Via Leopardi 4", "postcode": "20123", "city": "Milano", "province": "MI" } ], "reference": [ { "id": "R1", "last_name": "Rossi", "first_name": "Dany", "address": "V. Leopardi 4", "postcode": "20100", "city": "Milano", "province": "MI" } ] } }, "segna_lavorato": { "summary": "Marks a group as reviewed", "value": { "job": "a1b2c3d4e5f6a1b2c3d4e5f6", "group": 2, "processed": true } } } } } }, "responses": { "200": { "description": "Groups of duplicates (or matches, in two-list mode), or confirmation of the \"processed\" update.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DedupeResponse" }, { "$ref": "#/components/schemas/DedupeReferenceResponse" }, { "$ref": "#/components/schemas/DedupeUpdateResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "deduplica", "lavori" ], "operationId": "deduplicaLavoro", "summary": "Reads back a saved deduplication result", "description": "Reads back the groups of a saved deduplication job (by default every deduplication that finds duplicates is saved and can be read back for 30 days). The job code is the one returned in `job.code` by the POST call.", "parameters": [ { "$ref": "#/components/parameters/JobCode" } ], "responses": { "200": { "description": "Saved job and groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupeJobReadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "x-legacy-path": "/api/v1/deduplica" }, "/api/v1/tax-code": { "post": { "tags": [ "codicefiscale" ], "operationId": "codiceFiscale", "summary": "Generates, validates, extracts or compares a tax code", "description": "Four actions on the Italian tax code (codice fiscale) of natural persons, selected by the `action` field: `generate` from personal data, `validate` an existing code (format, check character, homocode variants), `extract` the information it contains (birth date, age, gender, municipality or foreign country of birth), `compare` a code with the declared personal data. One item in the body, or up to 2,000 in `items` (the same `action` for the whole batch). With `items` and `async:true` the job is queued. The tax code counts among the light operations: the first 500 light operations a month are free, then they draw on the light-operations counter.radaraddress.com/en/pricing).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxCodeRequest" }, "examples": { "genera": { "summary": "Generate from personal data", "value": { "action": "generate", "last_name": "Rossi", "first_name": "Mario", "gender": "M", "birth_date": "1980-01-01", "birth_place": "Roma" } }, "valida": { "summary": "Validate an existing code", "value": { "action": "validate", "tax_code": "RSSMRA80A01H501U" } }, "estrai": { "summary": "Extract the information it contains", "value": { "action": "extract", "tax_code": "RSSMRA80A01H501U" } }, "confronta": { "summary": "Compare with personal data", "value": { "action": "compare", "tax_code": "RSSMRA80A01H501U", "last_name": "Rossi", "first_name": "Mario", "gender": "M", "birth_date": "1980-01-01" } }, "lotto": { "summary": "Up to 2,000 items, same action", "value": { "action": "validate", "items": [ { "id": "1", "tax_code": "RSSMRA80A01H501U" } ] } } } } } }, "responses": { "200": { "description": "Outcome of the action (single or batch).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaxCodeSingleResponse" }, { "$ref": "#/components/schemas/TaxCodeBatchResponse" }, { "$ref": "#/components/schemas/JobQueuedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/AccountRequired" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "codicefiscale", "lavori" ], "operationId": "codiceFiscaleLavoro", "summary": "Reads back an asynchronous tax-code job", "parameters": [ { "$ref": "#/components/parameters/JobCode" }, { "$ref": "#/components/parameters/JobFormat" } ], "responses": { "200": { "description": "Job state (JSON or, with `format=csv`, the CSV file streamed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateResponse" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "x-legacy-path": "/api/v1/codicefiscale" }, "/api/v1/enrichment": { "post": { "tags": [ "arricchimento" ], "operationId": "arricchimento", "summary": "Enriches a name", "description": "Gender inferred from the first name, subject type (natural or legal person), normalized title and salutation forms ready for correspondence (formal and, where possible, informal). Also recognises the married-name form in the last name (\"Rossi in Verdi\"). One item in the body, or up to 500 in `items`. With `items` and `async:true` the job is queued.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentRequest" }, "examples": { "singolo": { "summary": "One name", "value": { "last_name": "Rossi", "first_name": "Dott.ssa Maria" } }, "lotto": { "summary": "Up to 500 items", "value": { "items": [ { "id": "1", "last_name": "Rossi", "first_name": "Dott.ssa Maria" } ] } } } } } }, "responses": { "200": { "description": "Enriched name (single or batch).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/EnrichmentResponse" }, { "$ref": "#/components/schemas/EnrichmentBatchResponse" }, { "$ref": "#/components/schemas/JobQueuedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/AccountRequired" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "arricchimento", "lavori" ], "operationId": "arricchimentoLavoro", "summary": "Reads back an asynchronous enrichment job", "parameters": [ { "$ref": "#/components/parameters/JobCode" }, { "$ref": "#/components/parameters/JobFormat" } ], "responses": { "200": { "description": "Job state (JSON or, with `format=csv`, the CSV file streamed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateResponse" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "x-legacy-path": "/api/v1/arricchimento" }, "/api/v1/email": { "post": { "tags": [ "email" ], "operationId": "verificaEmail", "summary": "Verifies an email address", "description": "Syntax, domain existence (MX/A records), typos in common domains with a suggested correction, disposable domains, role-based addresses (info@, amministrazione@). No SMTP check of the individual mailbox. One item in the body, or up to 500 in `items`. `dns:false` skips the domain lookup (faster). With `items` and `async:true` the job is queued.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" }, "examples": { "singolo": { "summary": "One address", "value": { "email": "mario.rossi@gmial.com" } }, "lotto": { "summary": "Up to 500 items", "value": { "items": [ { "id": "1", "email": "mario.rossi@gmial.com" } ] } } } } } }, "responses": { "200": { "description": "Outcome of the verification (single or batch).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/EmailResponse" }, { "$ref": "#/components/schemas/EmailBatchResponse" }, { "$ref": "#/components/schemas/JobQueuedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/AccountRequired" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "email", "lavori" ], "operationId": "verificaEmailLavoro", "summary": "Reads back an asynchronous email-verification job", "parameters": [ { "$ref": "#/components/parameters/JobCode" }, { "$ref": "#/components/parameters/JobFormat" } ], "responses": { "200": { "description": "Job state (JSON or, with `format=csv`, the CSV file streamed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateResponse" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/phone": { "post": { "tags": [ "telefono" ], "operationId": "verificaTelefono", "summary": "Verifies a phone number without placing a call", "description": "Form, class (`mobile`, `landline`, `special`, `foreign` for an international prefix) and type when recognised, length according to the numbering plan, district of a landline and the operator the number block was originally assigned to. A field can contain several numbers (\"347… - 338…\"): they are split and returned as `phone`, `phone2`, `phone3` (up to 3 per row). One item in the body, or up to 5,000 in `items`. With `items` and `async:true` the job is queued. Billing: one operation per NUMBER verified, not per call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRequest" }, "examples": { "singolo": { "summary": "One or more numbers in a single field", "value": { "phone": "3470328959 - 011 1253265" } }, "lotto": { "summary": "Up to 5,000 items", "value": { "items": [ { "id": "1", "phone": "011 1234567" } ] } } } } } }, "responses": { "200": { "description": "Outcome of the verification (single or batch).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PhoneResponse" }, { "$ref": "#/components/schemas/PhoneBatchResponse" }, { "$ref": "#/components/schemas/JobQueuedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/AccountRequired" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "telefono", "lavori" ], "operationId": "verificaTelefonoLavoro", "summary": "Reads back an asynchronous phone-verification job", "parameters": [ { "$ref": "#/components/parameters/JobCode" }, { "$ref": "#/components/parameters/JobFormat" } ], "responses": { "200": { "description": "Job state (JSON or, with `format=csv`, the CSV file streamed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateResponse" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "x-legacy-path": "/api/v1/telefono" }, "/api/v1/website": { "post": { "tags": [ "sito" ], "operationId": "verificaSito", "summary": "Verifies that a website responds", "description": "Domain existence, HTTP request with redirects followed (one at a time), final status code, certificate validity. No judgement on the content. A field can contain several URLs: they are split and returned as `website`, `website2`, `website3` (up to 3 per row). One item in the body, or up to 100 in `items` (a smaller batch than the other endpoints: every check opens a network connection). `network:false` checks the form only, without contacting the site. With `items` and `async:true` the job is queued. Billing: one operation per WEBSITE verified, not per call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteRequest" }, "examples": { "singolo": { "summary": "One URL", "value": { "website": "www.esempio.it" } }, "lotto": { "summary": "Up to 100 items", "value": { "items": [ { "id": "1", "website": "www.esempio.it" } ] } } } } } }, "responses": { "200": { "description": "Outcome of the verification (single or batch).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebsiteResponse" }, { "$ref": "#/components/schemas/WebsiteBatchResponse" }, { "$ref": "#/components/schemas/JobQueuedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/AccountRequired" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "413": { "$ref": "#/components/responses/BatchTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "tags": [ "sito", "lavori" ], "operationId": "verificaSitoLavoro", "summary": "Reads back an asynchronous website-verification job", "parameters": [ { "$ref": "#/components/parameters/JobCode" }, { "$ref": "#/components/parameters/JobFormat" } ], "responses": { "200": { "description": "Job state (JSON or, with `format=csv`, the CSV file streamed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStateResponse" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "x-legacy-path": "/api/v1/sito" }, "/api/v1/suggest": { "post": { "tags": [ "suggerisci" ], "operationId": "suggerisciIndirizzo", "summary": "Address autocomplete as the user types", "description": "Session-based model: the client generates a UUID for each address being filled in. Suggestion queries (the default action, `suggest`) are free: the server decides on its own what to propose from the text and the context (postcode/city/province already filled in). When the user picks a suggestion, the `select` action charges one contact verification and returns the normalized record; refining the house number on the same street in the same session is not charged again, another street is another charge. Suggestions carry street, municipality and province but not the postcode, which comes with the selection. The `house_numbers` phase (`street_id` plus a partial house number, with `exists`) opens only in the session that selected that street (409 `selection_required`). A session is valid for 10 minutes, up to 30 calls including selections (429 `session_quota`). Sessions without a selection are free up to 200 a day per token, plus five for every selection (429 `session_budget`, with `retry_after`). Works in every country in service (the same countries `/contact` verifies against a national register; see `/countries` and the Countries page): `country_code` selects the country's own catalogue, free text is read the way people write there (street, house number, postcode and city in one field: `kalverstraat 92 amst`, `92 rue de rivoli paris`, in the Netherlands `1012PH 92`), and every response carries `parsed` (how the server read street, house number and postcode) so the form knows where the number goes without knowing the country's rules. Suggestions never carry the postcode or house numbers: they come with the selection, which goes through the engine and returns the same record as `/contact`. `attribution` is the source notice to display next to the suggestions (the register's licence requires it); `source` on each row is `registry` or `osm` where the national register does not publish. A session belongs to one country: change country, generate a new UUID (409 `session_country`). Country not in service: still 200 with `supported:false`, no session, no charge. Default country IT.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SuggestRequest" }, { "$ref": "#/components/schemas/SuggestSelezionaRequest" } ] }, "examples": { "digitazione": { "summary": "Query while typing", "value": { "session": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "q": "via verdi", "city": "monz" } }, "selezione": { "summary": "The user picks a suggestion", "value": { "session": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "action": "select", "street_id": 1063428, "house_number": "4" } } } } } }, "responses": { "200": { "description": "Suggestions (phase `names`/`streets`/`localita`/`municipalities`/`house_numbers`), or the normalized record after the selection.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SuggestResponse" }, { "$ref": "#/components/schemas/SuggestSelezionaResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "410": { "description": "Session expired (more than 10 minutes): generate a new UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (300 calls a minute), `session_quota` (30 calls in the session) or `session_budget` (sessions without a selection over the daily allowance, with `retry_after`)." }, "500": { "$ref": "#/components/responses/InternalError" }, "409": { "description": "`selection_required`: house numbers are completed only after the street has been selected in this session. `session_country`: the session belongs to another country; generate a new UUID when the country changes." } } }, "x-legacy-path": "/api/v1/suggerisci" }, "/api/v1/credit": { "get": { "tags": [ "credito" ], "operationId": "credito", "summary": "Available operations and state of each counter, without consuming any", "description": "For each counter (`contact`, `dedupe`, `light`): `state` with a `warning` (a bare zero does not say whether the customer has run out, and needs to top up, or simply does not use the service), available operations, free operations left this month and the date they reset, subscription (left, size, renewal), active packs one by one (they do not expire) and how many were bought, auto top-up (active, size, monthly cap and amount spent this month in euro), usage (month, total, last); at the top, `needs_topup` and `endpoint`, the map of which counter each endpoint consumes. Requires the token of an account: a token without an account gets 404 `no_account`. The call consumes nothing.", "responses": { "200": { "description": "Balances of the three counters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditCountersResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The token does not belong to an account with counters (`error.code`: `no_account`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } }, "x-legacy-path": "/api/v1/credito" }, "/api/v1/countries": { "get": { "tags": [ "nazioni" ], "operationId": "nazioni", "summary": "ISO 3166-1 catalogue with names in Italian, English and the country's own language", "description": "Without parameters it returns the whole catalogue: for every country iso2, iso3, the short name in the language of the request (`name`; the Italian short name is also returned in `name_it`), the official Italian name (`long_name`), the English name (`name_en`), the name in the country's own language (`name_original`, European languages only; English for the others) and `languages`. With `q` it resolves a single country from a code or from a name written any which way: Italian, English, the country's own language, the official name or a common alias (`DE`, `Germania`, `Germany`, `Deutschland`, `Repubblica federale di Germania`; `UK` and `Olanda` resolve to GB and NL). Public endpoint: no Bearer token required.", "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "ISO 3166-1 code (alpha-2 or alpha-3), or the country name in Italian, English or the country's own language, including the official long name or a common alias (UK, Olanda, Turkey).", "schema": { "type": "string" }, "example": "Germania" }, { "name": "in_service", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "1 = only the countries where the address register is in service (Italy included)." } ], "responses": { "200": { "description": "Full catalogue, or the country resolved with `q`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CountriesListResponse" }, { "$ref": "#/components/schemas/CountryRisoltaResponse" } ] } } } }, "404": { "description": "Country not found in the ISO 3166-1 catalogue (with `q`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } }, "x-legacy-path": "/api/v1/nazioni" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ra_...", "description": "`Authorization: Bearer ` header. Tokens are generated from your account area (prefix `ra_`, historically `ra_live_`). The `X-Api-Key` header is accepted as an alternative. The token must NOT be passed as the `?api_key=` query string (rejected with 401: it would end up in logs). An optional expiry can be set when the token is created: past that date, 401 with code `token_expired`." } }, "parameters": { "JobCode": { "name": "job", "in": "query", "required": true, "description": "Code of the asynchronous job (24 hexadecimal characters), returned by a call with `async:true` (or, for deduplication, by a saved deduplication).", "schema": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "example": "369e46e9e7bb4c1a2b3c4d5e" }, "JobFormat": { "name": "format", "in": "query", "required": false, "description": "With `csv`, downloads the result file instead of the JSON (required above 5,000 rows).", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } }, "responses": { "BadRequest": { "description": "Invalid input: body is not JSON, required field missing, unknown action, invalid country, or similar. The `error.code` field tells the cases apart (`bad_request`, `missing_field`, `invalid_json`, `bad_action`, `missing_session`, `invalid_country`, …).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Token missing, invalid, expired or revoked. `error.code`: `unauthorized`, `invalid_token`, `token_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "Not enough credit for the whole requirement of the call, and auto top-up absent, at its cap or with a failed charge: the request is not processed. `error.code`: `payment_required`. For prices see https://www.radaraddress.com/en/pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "AccountRequired": { "description": "Asynchronous mode (`async:true`) requires a token tied to an account: the job goes into that account's queue. `error.code`: `account_required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MethodNotAllowed": { "description": "HTTP method not supported by this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found (job, suggestion, country…). `error.code`: `not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BatchTooLarge": { "description": "The batch (`items`, or `records`+`reference` for deduplication) exceeds the limit for a synchronous call. `error.code`: `batch_too_large`. Above the limit use `async:true` (up to 100,000 items) or the file upload from your account area.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Quota or rate limit exceeded. `error.code`: `rate_limited` (requests-per-minute limit for the token, with a `Retry-After` header), `quota_exceeded` (daily demo quota for anonymous/legacy tokens, with a `Retry-After` header until midnight Europe/Rome) or `session_quota` (too many queries in a `/suggest` session).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code, e.g. `unauthorized`, `bad_request`, `payment_required`." }, "message": { "type": "string", "description": "Human-readable message, in the language of the request (`language`)." } } } }, "required": [ "ok", "error" ] }, "OutcomeLabel": { "type": "object", "description": "Human-readable label for the outcome, derived from the keyword list in the `outcome` field.", "properties": { "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "title": { "type": "string" }, "message": { "type": "string" } } }, "Country": { "type": "object", "properties": { "iso2": { "type": "string", "description": "ISO 3166-1 alpha-2 code.", "example": "IT" }, "iso3": { "type": "string", "description": "ISO 3166-1 alpha-3 code.", "example": "ITA" }, "name": { "type": "string", "description": "Short name in the language of the request (English by default); the Italian short name is also returned in `name_it`.", "example": "Italia" }, "long_name": { "type": "string", "description": "Official name in Italian.", "example": "Repubblica Italiana" }, "name_en": { "type": "string", "description": "English name.", "example": "Italy" }, "name_original": { "type": "string", "description": "Name in the country's own language (European languages; English for the others). Several official languages separated by « / ».", "example": "Italia" }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages of the country used for the address form (ISO 639-1 codes).", "example": [ "it" ] }, "in_service": { "type": "boolean", "description": "True where the national address register is in service (autocomplete and house-number verification work there); false where only the postal form applies." } } }, "CreditCountersResponse": { "type": "object", "description": "Response of GET /api/v1/credit: the balances of the token's three counters.", "properties": { "ok": { "type": "boolean" }, "counters": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/CreditCounter" }, "dedupe": { "$ref": "#/components/schemas/CreditCounter" }, "light": { "$ref": "#/components/schemas/CreditCounter" } } }, "needs_topup": { "type": "array", "items": { "type": "string" }, "description": "Counters in state `used_up`, `free_used_up` or `awaiting_renewal`." }, "overall_cap_eur": { "type": [ "number", "null" ], "description": "Overall monthly cap of auto top-up in euro; null = no cap." }, "spent_overall_month_eur": { "type": "number", "description": "How much auto top-up has spent this month across all counters, in euro." }, "free_forever": { "type": "boolean", "description": "Account with a 100% discount: operations do not consume anything." }, "endpoint": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Which counter each endpoint consumes (`contact`, `dedupe`, `light`).", "example": { "contact": "contatto", "suggerisci": "contatto", "dedupe": "deduplica", "email": "leggere", "phone": "leggere", "website": "leggere", "arricchimento": "leggere", "codicefiscale": "leggere" } }, "states": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Legend of the states." }, "notes": { "type": "string" }, "account": { "type": "object", "description": "The account that owns the token (used by the WooCommerce plugin to show who is connected).", "properties": { "email": { "type": "string" }, "full_name": { "type": "string" } } } } }, "CreditCounter": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Verifica contatto" }, "state": { "type": "string", "enum": [ "never_used", "free", "free_used_up", "active", "awaiting_renewal", "used_up" ], "description": "A bare zero does not say whether the customer has run out or simply does not use the service: `never_used` = no operations and no packs, ever; `free` = never bought anything, working within the monthly free allowance; `free_used_up` = never bought anything and the free allowance is finished; `active` = has bought or subscription operations; `awaiting_renewal` = subscription with its allocation used up and no packs; `used_up` = bought in the past and nothing is left, needs a top-up." }, "warning": { "type": "string", "description": "What the state means and what to do; empty for `active`." }, "available": { "type": "integer", "description": "Free operations left + subscription allocation + packs." }, "used": { "type": "object", "properties": { "month": { "type": "integer" }, "total": { "type": "integer" }, "last_used": { "type": [ "string", "null" ], "format": "date-time" } } }, "free": { "type": "object", "properties": { "remaining": { "type": "integer" }, "month": { "type": "integer", "description": "Monthly free allowance of the counter." }, "reset_on": { "type": "string", "format": "date" } } }, "subscription": { "type": [ "object", "null" ], "description": "null without a subscription.", "properties": { "left": { "type": "integer" }, "size": { "type": "integer" }, "renews_on": { "type": [ "string", "null" ], "format": "date", "description": "Unused allocation is lost at renewal." }, "notes": { "type": "string" } } }, "packs": { "type": "object", "properties": { "left": { "type": "integer" }, "active_packs": { "type": "array", "description": "Packs with operations still to use, oldest first; they do not expire.", "items": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "purchase", "auto_topup", "gift" ] }, "size": { "type": "integer" }, "left": { "type": "integer" }, "activated_on": { "type": "string", "format": "date" } } } }, "bought": { "type": "object", "properties": { "n": { "type": "integer", "description": "Packs ever bought or received, including finished ones." }, "last_on": { "type": [ "string", "null" ], "format": "date-time" } } }, "notes": { "type": "string" } } }, "auto_topup": { "type": "object", "properties": { "active": { "type": "boolean" }, "size": { "type": "integer", "description": "Size of the pack bought automatically." }, "monthly_cap_eur": { "type": [ "number", "null" ] }, "spent_month_eur": { "type": "number" } } } } }, "Credit": { "type": "object", "description": "What was consumed and from where (present in every response of a paid operation, when the caller is an account). Operations are bought as packs or by subscription, per counter: see https://www.radaraddress.com/en/pricing.", "properties": { "counter": { "type": "string", "description": "Counter of the service: `contact`, `dedupe` or `light`.", "example": "contatto" }, "charged": { "type": "integer", "description": "Operations deducted from the counter (free ones excluded)." }, "free": { "type": "integer", "description": "Operations covered by the monthly free allowance (nothing deducted)." }, "subscription": { "type": "object", "description": "Part deducted from the monthly subscription allocation.", "properties": { "operations": { "type": "integer" }, "left": { "type": "integer", "description": "Monthly allocation left after the deduction." } } }, "packs": { "type": "object", "description": "Part deducted from the packs, oldest first.", "properties": { "operations": { "type": "integer" }, "left": { "type": "integer", "description": "Operations left in the packs after the deduction." } } }, "available": { "type": "integer", "description": "Operations available on the counter after the deduction (monthly free operations included)." }, "auto_topup": { "type": "integer", "description": "Packs bought automatically to cover this call." }, "notes": { "type": "string", "description": "Plain-text explanation (no markup), in the language of the request." } } }, "HouseNumber": { "type": "object", "properties": { "number": { "type": [ "string", "null" ] }, "suffix": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "colour": { "type": [ "string", "null" ], "description": "Colour of the house number (e.g. Genoa, R/N)." }, "specificity": { "type": [ "string", "null" ], "description": "House-number qualifier (colour, snc for an unnumbered building, interno for the unit)." }, "metric": { "type": [ "string", "null" ], "description": "Metric value for roads addressed by kilometre." }, "other": { "type": [ "string", "null" ] } } }, "StreetName": { "type": "object", "properties": { "street_type": { "type": [ "string", "null" ], "description": "Street type, the generic designation (Via, Corso, Piazza…)." }, "street_proper_name": { "type": [ "string", "null" ], "description": "Street proper name, the specific designation (the name of the street)." }, "house_number_label": { "type": [ "string", "null" ] } } }, "Geo": { "type": [ "object", "null" ], "description": "WGS84 coordinates of the address. `precision` says which level was reached: `house_number` (georeferenced number), `interpolated` (exact number missing, point estimated from the nearby house numbers), `street` (point on the street) or `municipality` (centre of the municipality). Null only if the municipality is not resolved.", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" }, "precision": { "type": "string", "enum": [ "house_number", "interpolated", "street", "municipality" ] }, "source": { "type": "string", "enum": [ "anncsu", "inspire", "osm" ], "description": "`anncsu` = Italian national register; `inspire` = the national address register of the country (open data, attribution in the message where the register requires it); `osm` = © OpenStreetMap contributors, ODbL licence: attribution to be reproduced if you publish the coordinates." } } }, "Territory": { "type": [ "object", "null" ], "description": "Territorial identifiers of the resolved municipality. Null if the municipality was not resolved. In Italy: ISTAT code, cadastral code, CAB, street id. Abroad: `country` and the municipality code of the national register (`municipality_code`, `municipality_code_type`); the Italian codes are null.", "properties": { "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 of the country, foreign addresses only." }, "municipality_code": { "type": [ "string", "null" ], "description": "Code of the municipality in the national address register of the country, foreign addresses only (e.g. `AdminUnitName_49021011010101` in Germany)." }, "municipality_code_type": { "type": [ "string", "null" ], "description": "Which register the code belongs to (`inspire`)." }, "istat_code": { "type": [ "string", "null" ], "description": "ISTAT code of the municipality (6 digits); null abroad." }, "cadastral_code": { "type": [ "string", "null" ], "description": "Cadastral (Belfiore) code of the municipality, e.g. F205." }, "cab": { "type": [ "string", "null" ], "description": "CAB code of the municipality." }, "street_id": { "type": [ "string", "null" ], "description": "National identifier of the street in the house-number register; null if the street was not linked." } } }, "CityType": { "type": [ "object", "null" ], "description": "Whether the address is in a provincial capital or in another municipality of the province.", "properties": { "provincial_capital": { "type": [ "boolean", "null" ], "description": "`null` when there is not enough to tell." }, "label": { "type": "string" }, "source": { "type": "string" } } }, "Change": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "before": { "type": "string" }, "after": { "type": "string" }, "kind": { "type": "string", "enum": [ "filled", "normalized", "modified" ] } } }, "Explanation": { "type": "object", "description": "The reason behind a significant difference between the input and the normalized output.", "properties": { "field": { "type": "string" }, "kind": { "type": "string" }, "tag": { "type": "string" }, "title": { "type": "string" }, "short": { "type": "string" }, "long": { "type": "string" } } }, "Suggestion": { "type": "object", "description": "An alternative proposal when the outcome is STREET_AMBIGUOUS/CITY_AMBIGUOUS or similar.", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "postcode": { "type": "string" }, "province": { "type": "string" }, "type": { "type": "string", "enum": [ "strada", "frazione", "comune" ] }, "multiple_postcodes": { "type": "boolean" }, "legacy_default": { "type": "boolean" } } }, "Dropped": { "type": "object", "description": "Field cleared in the output because it could not be resolved against the register (e.g. city not found): the original value remains in `input` anyway.", "properties": { "field": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_in_db", "ambiguous_in_db" ] } } }, "AddressFields": { "type": "object", "description": "The address/name record in one of its three views (input, normalized, normalized_postal). In the normalized view the fields follow the case rule: city and province in UPPERCASE, last_name/first_name/title/care_of/building/address in Title Case, postcode untouched.", "properties": { "id": { "type": [ "string", "null" ] }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "care_of": { "type": "string" }, "building": { "type": "string" }, "address": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "gender": { "type": "string" }, "title": { "type": "string" }, "country": { "type": "string", "description": "Country name." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 code." }, "country_original": { "type": "string", "description": "Foreign addresses only: country name in its own language (Deutschland, France)." } } }, "AddressResult": { "type": "object", "description": "Structure returned by the verification of an address. Present in `/contact` (field `result`) and in the selection of `/suggest`. On a batch item with both `address` and `care_of` empty, the result is reduced to `{error, outcome:\"INCOMPLETE_DATA\"}` without the other fields.", "properties": { "error": { "type": "string", "description": "Present only when the data is not enough to normalize that batch item." }, "found": { "type": "boolean" }, "outcome": { "type": "string", "description": "Space-separated list of keywords, empty when there is nothing to report. Schema: ` [MODIFIED ]`.", "example": "MODIFIED POSTCODE CITY_FORM PROVINCE STREET" }, "outcome_label": { "$ref": "#/components/schemas/OutcomeLabel" }, "reason": { "type": "string", "description": "The reason, in one line." }, "comments": { "type": "array", "items": { "type": "string" }, "description": "Recommended actions." }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/Suggestion" } }, "input": { "$ref": "#/components/schemas/AddressFields" }, "normalized": { "$ref": "#/components/schemas/AddressFields" }, "normalized_postal": { "allOf": [ { "$ref": "#/components/schemas/AddressFields" } ], "description": "Like `normalized`, but in postal form: ASCII with an apostrophe in place of the accent (FORLI', CITTA' DEL VATICANO)." }, "municipality": { "type": [ "string", "null" ], "description": "Main municipality resolved, useful when the city is a hamlet; abroad, the official name of the municipality (both forms where the register is bilingual, e.g. «Pamplona/Iruña»)." }, "district": { "type": [ "string", "null" ], "description": "District, borough or arrondissement of the city when its national register has them (Hamburg-Altstadt, Berlin-Mitte, Paris 4e Arrondissement); null otherwise. `city` stays the city." }, "canonical_address": { "type": [ "string", "null" ], "description": "Canonical street when the user wrote a historical alias (`preserve_original` flag)." }, "canonical_city": { "type": [ "string", "null" ], "description": "Canonical Italian municipality when the user wrote the local-language form (`preserve_original` flag)." }, "address_key": { "type": "string", "description": "Foreign addresses only (outcome FOREIGN when language=it): the form the deduplication uses to recognise the same street written in two ways («350 Fifth Avenue» and «350 5th Ave» match). Returned whether or not the street was verified in a national register." }, "city_key": { "type": "string", "description": "Foreign addresses only: ASCII key of the city in the country's language." }, "text": { "type": "string", "description": "The normalized address as a block of lines ready to paste: name (when given), care-of, building, street and house number, then the postal line in the order of the country («20123 MILANO MI», «80331 MÜNCHEN», «LONDON SW1A 2AA») and the country line for foreign addresses." }, "dropped": { "type": "array", "items": { "$ref": "#/components/schemas/Dropped" } }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "explanations": { "type": "array", "items": { "$ref": "#/components/schemas/Explanation" } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "valorizzato", "normalizzato", "modificato" ] } }, "house_number": { "$ref": "#/components/schemas/HouseNumber" }, "sub_address": { "type": "array", "description": "Floor, staircase, flat and building written in the address, read with the postal rules of its country (in Germany after «//», in France on its own line, in Portugal «3º Esq»). The address line itself stays in the country's form; this is the same information as structured data. Empty when nothing was written or it was not recognised: never guessed.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "unit", "staircase", "floor", "block", "building", "building_number", "block_number" ] }, "value": { "type": "string" } } } }, "sub_address_confirmed": { "type": [ "boolean", "null" ], "description": "true when the country's address register lists the floor, staircase or flat written at this house number; null when we do not know. Never false: registers do not list every unit, and not finding one does not mean it is wrong." }, "street_name": { "$ref": "#/components/schemas/StreetName" }, "geo": { "$ref": "#/components/schemas/Geo" }, "territory": { "$ref": "#/components/schemas/Territory" }, "confidence": { "type": [ "string", "null" ], "enum": [ "high", "medium", null ], "description": "Reliability of the normalization decision; null on error outcomes." }, "notes": { "type": [ "string", "null" ], "description": "Transparency note on the decision (when confidence is not 'high', or on other corrections worth mentioning)." }, "zoned": { "type": "boolean" }, "multiple_postcodes": { "type": "boolean" }, "city_type": { "$ref": "#/components/schemas/CityType" }, "postcode_check": { "type": [ "object", "null" ], "description": "Where the postcode comes from and how sure it is: source (osm, wikidata, manual), precision (house_number: the number itself; interpolated: the neighbouring numbers of the street; street: the majority of the street; locality; municipality; nearby: the house numbers around the point), house_numbers counted, agreement (share of the chosen postcode, 0-1), confirmed (false when the outcome carries POSTCODE_UNCONFIRMED or POSTCODE_PRESUMED) and presumed. Null when the address is not resolved.", "properties": { "source": { "type": [ "string", "null" ] }, "precision": { "type": [ "string", "null" ], "enum": [ "house_number", "interpolated", "street", "locality", "municipality", "nearby", null ] }, "house_numbers": { "type": "integer" }, "agreement": { "type": [ "number", "null" ] }, "confirmed": { "type": "boolean" }, "presumed": { "type": "boolean", "description": "true with POSTCODE_PRESUMED: we set the postcode without confirmation from the house number (street with several postcodes, or none given and taken from the nearby house numbers)." }, "nearby": { "type": [ "object", "null" ], "description": "With POSTCODE_UNCONFIRMED: what the house numbers around the point say, when it differs from the postcode given (cap, house_numbers, agreement). The given postcode is kept.", "properties": { "postcode": { "type": "string" }, "house_numbers": { "type": "integer" }, "agreement": { "type": "number" } } } } }, "meta": { "type": "object", "properties": { "city_passes": { "type": [ "integer", "null" ] }, "street_passes": { "type": [ "integer", "null" ] }, "segment_passes": { "type": [ "integer", "null" ] } } }, "country": { "$ref": "#/components/schemas/Country" }, "tax_code": { "type": "string", "description": "Only on /contact: cleaned-up form of the record's tax code, when provided." }, "tax_code_outcome": { "type": "object", "description": "Only on /contact, when `tax_code` is provided in the record.", "properties": { "outcome": { "type": "string" }, "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "reason": { "type": "string" }, "valid": { "type": "boolean" }, "match": { "type": [ "boolean", "null" ] }, "suggestion": { "type": [ "string", "null" ] } } } } }, "ContactItem": { "type": "object", "description": "A contact (address + name + optional tax code). At least one of `address` and `care_of` is required.", "properties": { "id": { "type": "string", "description": "Caller's reference, returned as is." }, "address": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 code. Italy is assumed if missing. In the countries whose national address register is in service (see GET /countries and the Countries page: Germany, France, Spain, the Netherlands, Czechia at the time of writing, the list grows with the data) street and house number are verified like in Italy, with postcode, coordinates, `district` and `territory.municipality_code`; elsewhere the address is put in the postal form of the country (with language=it the outcome carries FOREIGN, in the other languages only the changes; the message says the street is not verified)." }, "country": { "type": "string", "description": "Alternative to `country_code`: name of the country." }, "care_of": { "type": "string" }, "building": { "type": "string" }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string" }, "tax_code": { "type": "string" } } }, "ContactRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ContactItem" }, { "type": "object", "properties": { "postal_form": { "type": "boolean", "description": "Forces `normalized` into the postal form as well." }, "preserve_original": { "type": "boolean", "description": "Keeps the name as the user wrote it (historical street, municipality in the local language) and exposes the canonical one separately." }, "precision": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3, "description": "1 exact … 5 the most it can find. Above 3 the match is approximate and confidence will not be 'high'." }, "foreign": { "type": "string", "enum": [ "declared", "detect" ], "default": "dichiarati", "description": "`declared`: only a record that states its country (country/country_code, province EE) is foreign. `detect`: a record without a country that is not found in Italy is recognised as foreign from explicit signals (country name in the text, known foreign city, postal code with a non-Italian form), never by exclusion." } } } ] }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100000, "items": { "$ref": "#/components/schemas/ContactItem" } }, "postal_form": { "type": "boolean" }, "preserve_original": { "type": "boolean" }, "precision": { "type": "integer", "minimum": 1, "maximum": 5 }, "foreign": { "type": "string", "enum": [ "declared", "detect" ], "default": "dichiarati" }, "async": { "type": "boolean", "description": "Above 500 items (up to 100,000): queues the job instead of answering right away." } } } ] }, "ContactSingleResponse": { "type": "object", "description": "Unlike the batch response, the single response does not carry the `credit` field in the body (the consumption is still in the X-RA-Charged/X-RA-Available headers).", "properties": { "ok": { "type": "boolean", "description": "`false` when the outcome is INCOMPLETE_DATA: the request was processed anyway (HTTP status 200)." }, "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/AddressResult" } } }, "ContactBatchResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/AddressResult" } } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "JobQueuedResponse": { "type": "object", "description": "Response when the call carries `items` with `async:true`.", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "job": { "type": "string", "description": "Job code (24 hexadecimal characters).", "example": "369e46e9e7bb4c1a2b3c4d5e" }, "state": { "type": "string", "example": "in_coda" }, "rows": { "type": "integer" }, "check": { "type": "string", "description": "Path to call with GET for the state." }, "credit": { "type": "object", "description": "Operations consumed by the job (deducted when it is queued).", "properties": { "counter": { "type": "string" }, "charged": { "type": "integer" }, "free": { "type": "integer" }, "subscription": { "type": "object", "properties": { "operations": { "type": "integer" } } }, "packs": { "type": "object", "properties": { "operations": { "type": "integer" } } }, "auto_topup": { "type": "integer" }, "notes": { "type": "string" } } } } }, "JobStateResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "job": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "in_corso", "completed", "error" ] }, "rows": { "type": "integer" }, "done": { "type": "integer" }, "outcomes": { "type": "object", "properties": { "ok": { "type": "integer" }, "modified": { "type": "integer" }, "to_check": { "type": "integer" }, "unresolved": { "type": "integer" } } }, "error": { "type": "string", "description": "Present only with state `error`." }, "warning": { "type": "string", "description": "E.g. result no longer available (30-day retention), or referral to the CSV above 5,000 rows." }, "csv": { "type": "string", "description": "Path to download the CSV, when the JSON does not carry `results`." }, "results": { "type": [ "array", "null" ], "description": "Result rows (one object per row, CSV columns as keys); `null` when referring to the CSV.", "items": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "DedupRecord": { "type": "object", "description": "The merged contact: the best name and the UNION of addresses and contact details, each with its type as it arrived, the vCard `type_normalized` and the `provenance` (ids of the contacts it comes from). The flat fields (`address`, `postcode`, `city`, `province`, `phone`, `email`) carry the first element.", "properties": { "last_name": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string" }, "tax_code": { "type": "string", "description": "The Italian tax code of the merged records, when valid and consistent with the name; empty otherwise." }, "address": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "care_of": { "type": "string" }, "building": { "type": "string", "description": "Staircase, flat, building written with the address (e.g. «Scala A Interno 3»): kept in the merged record, never dropped." }, "country": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "type_normalized": { "type": "string" }, "address": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "care_of": { "type": "string" }, "building": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" }, "description": "All the labels the same address was filed under." }, "provenance": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "integer", "description": "How many entries (spellings) collapsed into this address." } } } }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/DedupContactDetailMerged" } }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/DedupContactDetailMerged" } } } }, "DedupContactDetail": { "oneOf": [ { "type": "string", "description": "The value alone, without a type." }, { "type": "object", "required": [ "value" ], "properties": { "type": { "type": "string", "description": "Label as it is in the address book (casa, ufficio, cellulare, home, work, cell, iPhone…): returned as it arrived, plus `type_normalized` in the vCard 4.0 vocabulary. It has no weight in the matching." }, "value": { "type": "string" } } } ] }, "DedupAddress": { "type": "object", "properties": { "type": { "type": "string", "description": "Label as it is in the address book (casa, ufficio, altro…)." }, "address": { "type": "string" }, "postcode": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "care_of": { "type": "string" }, "building": { "type": "string" } } }, "DedupSingle": { "type": "object", "description": "A contact with no duplicates among the others. With `outcome` = `INTERNAL_DUPLICATE` it has duplicates inside itself (the same address written twice, a repeated number or email): `reason` says so and `record` is the merged contact, with addresses and contact details deduplicated.", "properties": { "id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "", "INTERNAL_DUPLICATE" ] }, "reason": { "type": "string" }, "record": { "$ref": "#/components/schemas/DedupRecord" } } }, "DedupContactDetailMerged": { "type": "object", "properties": { "type": { "type": "string" }, "type_normalized": { "type": "string" }, "value": { "type": "string", "description": "As it arrived in the first occurrence." }, "normalized": { "type": "string", "description": "The comparison key: E.164 for foreign phones, digits only for Italian ones, lowercase for emails." }, "types": { "type": "array", "items": { "type": "string" } }, "provenance": { "type": "array", "items": { "type": "string" } }, "occurrences": { "type": "integer", "description": "How many times it appeared in the merged contacts." } } }, "DedupeRequest": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/DedupRecord" }, "description": "Required, max 500 records (together with `reference`)." }, "reference": { "type": "array", "items": { "$ref": "#/components/schemas/DedupRecord" }, "description": "Optional: enables two-list mode." }, "min_level": { "type": "string", "enum": [ "certain", "probable", "ambiguous" ], "default": "probabile" }, "foreign": { "type": "string", "enum": [ "declared", "detect" ], "default": "dichiarati", "description": "`detect`: recognises foreign records even without `country`, from explicit signals in the text." }, "save": { "type": "boolean", "default": true, "description": "Saves the result, readable for 30 days with GET ?job=." } } }, "DedupeUpdateRequest": { "type": "object", "required": [ "job", "group" ], "properties": { "job": { "type": "string", "pattern": "^[0-9a-f]{24}$" }, "group": { "type": "integer" }, "processed": { "type": "boolean" } } }, "DedupGroup": { "type": "object", "properties": { "group": { "type": "integer" }, "members": { "type": "array", "items": { "type": "string" }, "description": "Ids of the group members." }, "main_record": { "type": [ "string", "null" ], "description": "Id of the record to keep." }, "record": { "type": [ "object", "null" ], "description": "Consolidated record (the best data merged)." }, "outcome": { "type": "string", "enum": [ "DUPLICATE" ] }, "level": { "type": [ "string", "null" ], "enum": [ "certain", "probable", "ambiguous", null ] }, "reason": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "comments": { "type": "array", "items": { "type": "string" } } } }, "DedupeResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/DedupGroup" } }, "singles": { "type": "array", "items": { "$ref": "#/components/schemas/DedupSingle" }, "description": "Contacts with no matches with others; with `outcome` INTERNAL_DUPLICATE they have duplicates inside themselves and carry the merged record." }, "discarded": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "string" }, "error": { "type": "string" }, "id": { "type": [ "string", "null" ] } } } }, "summary": { "type": "object" }, "job": { "type": "object", "description": "Present when `save` is true and there are groups.", "properties": { "code": { "type": "string" }, "expiry": { "type": "string", "format": "date" } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "DedupeReferenceResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reference_id": { "type": "string" } } } }, "not_found": { "type": "array", "items": { "type": "string" } }, "discarded": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "object" }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "DedupeUpdateResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "job": { "type": "string" }, "group": { "type": "integer" }, "processed": { "type": "boolean" } } }, "DedupeJobReadResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "job": { "type": "object", "properties": { "code": { "type": "string" }, "created": { "type": "string" }, "n_records": { "type": "integer" } } }, "groups": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/DedupGroup" }, { "type": "object", "properties": { "processed": { "type": "boolean" }, "processed_at": { "type": [ "string", "null" ] } } } ] } } } }, "TaxCodeItemGenerate": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "enum": [ "generate" ] }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string", "enum": [ "M", "F" ] }, "birth_date": { "type": "string", "description": "YYYY-MM-DD or DD/MM/YYYY, with slashes, dashes or dots; also the eight digits run together, the month in words (Italian, e.g. 1 gennaio 1980) and a trailing time. Four-digit year." }, "birth_place": { "type": "string", "description": "Or a foreign country (e.g. \"Francia\")." }, "birth_province": { "type": "string", "description": "Optional; disambiguates municipalities with the same name." } } }, "TaxCodeRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "generate", "validate", "extract", "compare" ] }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string", "enum": [ "M", "F" ] }, "birth_date": { "type": "string" }, "birth_place": { "type": "string" }, "birth_province": { "type": "string" }, "tax_code": { "type": "string", "description": "Required for `validate`, `extract`, `compare`." }, "items": { "type": "array", "maxItems": 100000, "description": "Up to 2,000 per synchronous call (beyond that, with `async:true`, up to 100,000); the same `action` for the whole batch.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "gender": { "type": "string" }, "birth_date": { "type": "string" }, "birth_place": { "type": "string" }, "birth_province": { "type": "string" }, "tax_code": { "type": "string" } } } }, "async": { "type": "boolean" } } }, "TaxCodeSingleResponse": { "type": "object", "description": "The shape depends on the action: `generate` → tax_code/place/province/foreign_address; `validate`/`extract` → the fields below; `compare` → match/differences. Unlike the batch response, the single response does not carry the `credit` field in the body (the consumption is still in the X-RA-Charged/X-RA-Available headers).", "properties": { "ok": { "type": "boolean" }, "tax_code": { "type": "string" }, "place": { "type": [ "string", "null" ] }, "province": { "type": [ "string", "null" ] }, "foreign_address": { "type": "boolean" }, "valid": { "type": "boolean" }, "format": { "type": "boolean" }, "check_digit": { "type": "boolean" }, "homocode": { "type": "boolean" }, "error": { "type": [ "string", "null" ], "description": "Short error code: empty, length, format, check_digit, homocode, month, date, place; on generate: last_name, first_name, gender, birth_date, birth_place, ambiguous_place, last_name_non_latin, first_name_non_latin. Italian codes only with language=it." }, "suggestion": { "type": [ "string", "null" ], "description": "Suggested corrected code, when it can be rebuilt (e.g. only the check character is missing)." }, "birth_date": { "type": "string" }, "age": { "type": "integer" }, "gender": { "type": "string", "enum": [ "M", "F" ] }, "birth_place_name": { "type": "string" }, "birth_province": { "type": [ "string", "null" ] }, "born_abroad": { "type": "boolean" }, "belfiore_code": { "type": "string" }, "birth_country": { "type": [ "string", "null" ] }, "ambiguous_year": { "type": "boolean", "description": "The two digits of the year do not distinguish the century (e.g. 1926 vs 2026)." }, "match": { "type": "boolean", "description": "Only on `compare`." }, "differences": { "type": "array", "items": { "type": "string" }, "description": "Only on `compare`: fields that do not match." }, "outcome": { "type": "string", "description": "Keywords: GENERATED (generate), empty when valid (validate), MATCH / MISMATCH (compare), TAX_CODE_EMPTY, TAX_CODE_LENGTH_WRONG, TAX_CODE_CHECK_DIGIT_MISSING, TAX_CODE_FORMAT_WRONG, TAX_CODE_CHECK_DIGIT_WRONG, TAX_CODE_HOMOCODE_UNRESOLVED, TAX_CODE_MONTH_WRONG, TAX_CODE_DATE_INVALID, TAX_CODE_PLACE_UNKNOWN, TAX_CODE_INVALID. Italian codes only with language=it." }, "reason": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "comments": { "type": "array", "items": { "type": "string" } } } }, "TaxCodeBatchResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/TaxCodeSingleResponse" } } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "EnrichmentItem": { "type": "object", "properties": { "id": { "type": "string" }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "title": { "type": "string" }, "gender": { "type": "string", "description": "M or F; written forms are accepted too (maschio, donna, Sig.ra, male). X = organisation, G = family or couple." }, "profession": { "type": "string", "description": "The profession (also accepted as `professione`). When the title is missing and the profession carries one, the title is filled in from it." }, "education": { "type": "string", "description": "The educational qualification (also accepted as `titstudio`): when it carries a title, the title is filled in from it." } } }, "EnrichmentRequest": { "oneOf": [ { "$ref": "#/components/schemas/EnrichmentItem" }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100000, "items": { "$ref": "#/components/schemas/EnrichmentItem" } }, "async": { "type": "boolean" } } } ] }, "EnrichmentResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "outcome": { "type": "string", "enum": [ "ENRICHED", "LEGAL_PERSON", "PARTIAL" ], "description": "ENRICHED: gender and salutations set; LEGAL_PERSON: company or organisation; PARTIAL: first name missing or gender not inferable. Italian codes (ARRICCHITO, GIURIDICA, PARZIALE) only with language=it." }, "reason": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "comments": { "type": "array", "items": { "type": "string" } }, "subject_type": { "type": "string", "enum": [ "natural_person", "legal_person" ] }, "gender": { "type": "string", "enum": [ "M", "F", "" ] }, "gender_source": { "type": "string", "enum": [ "given", "inferred", "" ] }, "title": { "type": "string" }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "contact_person": { "type": [ "object", "null" ], "description": "When the field contained an organisation + a contact person.", "properties": { "title": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "gender": { "type": "string" }, "salutation": { "type": "string" } } }, "formal_salutation": { "type": "string" }, "informal_salutation": { "type": [ "string", "null" ] }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "EnrichmentBatchResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/EnrichmentResponse" } } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "EmailItem": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" } } }, "EmailRequest": { "oneOf": [ { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" }, "dns": { "type": "boolean", "default": true, "description": "false skips the domain lookup." } } }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100000, "items": { "$ref": "#/components/schemas/EmailItem" } }, "dns": { "type": "boolean", "default": true }, "async": { "type": "boolean" } } } ] }, "EmailResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "valid": { "type": "boolean" }, "email": { "type": "string" }, "syntax": { "type": "boolean" }, "domain_exists": { "type": [ "boolean", "null" ], "description": "MX/A lookup of the domain that was checked: the domain of `suggestion` when a typo is suspected, otherwise the domain as written." }, "domain_checked": { "type": "string", "description": "The domain the checks were run on (the correction's, when a typo is suspected)." }, "corrected_from": { "type": "string", "description": "The address as written, when a certain typo in the domain was corrected outright (outcome MODIFIED EMAIL_DOMAIN): `email` carries the corrected form." }, "suggestion": { "type": [ "string", "null" ], "description": "Suggested correction for a typo in a common domain." }, "disposable": { "type": "boolean" }, "generic": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } }, "outcome": { "type": "string" }, "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "title": { "type": "string" }, "reason": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "comments": { "type": "array", "items": { "type": "string" } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "EmailBatchResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/EmailResponse" } } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "PhoneDetail": { "type": "object", "properties": { "field": { "type": "string", "description": "phone, phone2, phone3 (according to the position in the source field)." }, "input": { "type": "string" }, "normalized": { "type": "string" }, "number": { "type": "string" }, "e164": { "type": "string" }, "national_number": { "type": "string", "description": "The number in the national form of its own country (trunk zero included where the country uses it), for numbers outside Italy." }, "class": { "type": "string", "enum": [ "landline", "mobile", "special", "foreign", "" ], "description": "mobile, landline or special. With country_code, a number of the record's own country gets its class where we know the numbering plan; 'foreign' is a number of a different country than the record's." }, "type": { "type": "string", "description": "Finer reading when the service is recognised by name (toll-free, premium rate, public utility, foreign…)." }, "district": { "type": "string" }, "town": { "type": "string" }, "operator": { "type": "string", "description": "Operator the number block was originally assigned to." }, "valid": { "type": "boolean" }, "changed": { "type": "boolean" }, "outcome": { "type": "string" }, "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "title": { "type": "string" }, "reason": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "comments": { "type": "array", "items": { "type": "string" } } } }, "PhoneItem": { "type": "object", "properties": { "id": { "type": "string" }, "phone": { "type": "string" }, "country_code": { "type": "string", "description": "Optional: country of the number. A number without a prefix is read as a national number of that country and returned in E.164; `country` with the name works too." } } }, "PhoneRequest": { "oneOf": [ { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "description": "Can contain several numbers (up to 3): they are split automatically." }, "format": { "type": "string", "enum": [ "national", "international" ], "default": "nazionale" }, "country_code": { "type": "string", "description": "Optional: country of the numbers without a prefix (default Italy)." } } }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100000, "items": { "$ref": "#/components/schemas/PhoneItem" } }, "format": { "type": "string", "enum": [ "national", "international" ], "default": "nazionale" }, "country_code": { "type": "string", "description": "Optional: country of the whole batch for the numbers without a prefix; an item can override it." }, "async": { "type": "boolean" } } } ] }, "PhoneResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "phone": { "type": "string", "description": "Always filled when there is at least one number, even if it was the second one in the text." }, "phone2": { "type": "string" }, "phone3": { "type": "string" }, "outcome": { "type": "string" }, "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "reason": { "type": "string" }, "detail": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneDetail" } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "PhoneBatchResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "numbers": { "type": "integer", "description": "Total distinct numbers found in the batch (the billing unit)." }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/PhoneResponse" } } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "WebsiteDetail": { "type": "object", "properties": { "field": { "type": "string", "description": "website, website2, website3 (according to the position in the source field)." }, "input": { "type": "string" }, "normalized": { "type": "string" }, "url": { "type": "string" }, "url_normalized": { "type": "string" }, "host": { "type": "string" }, "reachable": { "type": [ "boolean", "null" ] }, "http_status": { "type": [ "integer", "null" ] }, "final_url": { "type": "string", "description": "URL after the redirects followed." }, "redirects": { "type": "boolean" }, "https": { "type": "boolean" }, "certificate_ok": { "type": [ "boolean", "null" ] }, "time_ms": { "type": [ "integer", "null" ] }, "valid": { "type": "boolean" }, "changed": { "type": "boolean" }, "outcome": { "type": "string" }, "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "title": { "type": "string" }, "reason": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "comments": { "type": "array", "items": { "type": "string" } } } }, "WebsiteItem": { "type": "object", "properties": { "id": { "type": "string" }, "website": { "type": "string" } } }, "WebsiteRequest": { "oneOf": [ { "type": "object", "required": [ "website" ], "properties": { "website": { "type": "string", "description": "Can contain several URLs (up to 3): they are split automatically." }, "network": { "type": "boolean", "default": true, "description": "false checks the form only, without contacting the site." } } }, { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "maxItems": 100000, "items": { "$ref": "#/components/schemas/WebsiteItem" } }, "network": { "type": "boolean", "default": true }, "async": { "type": "boolean" } } } ] }, "WebsiteResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "website": { "type": "string" }, "website2": { "type": "string" }, "website3": { "type": "string" }, "outcome": { "type": "string" }, "kind": { "type": "string", "enum": [ "ok", "modified", "warning", "error" ] }, "reason": { "type": "string" }, "detail": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteDetail" } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "WebsiteBatchResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "websites": { "type": "integer", "description": "Total distinct websites found in the batch (the billing unit)." }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "result": { "$ref": "#/components/schemas/WebsiteResponse" } } } }, "credit": { "$ref": "#/components/schemas/Credit" } } }, "SuggestRequest": { "type": "object", "required": [ "session" ], "properties": { "session": { "type": "string", "description": "UUID generated by the client for the address being filled in (16-36 hexadecimal characters/dashes).", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "action": { "type": "string", "enum": [ "suggerisci" ], "default": "suggerisci" }, "q": { "type": "string", "description": "Text typed in the address field (or, after a name is chosen, the filter on the city). Outside Italy it may be free text: street, house number, postcode and city in one field; see `parsed` in the response." }, "postcode": { "type": "string", "description": "Optional context, even partial." }, "city": { "type": "string", "description": "Optional context, even partial." }, "province": { "type": "string", "description": "Optional context." }, "country_code": { "type": "string", "description": "Optional; default IT. Any country in service (ISO 3166-1 alpha-2); a country not in service answers `supported:false`." }, "name_id": { "type": "integer", "description": "Id of the name chosen in the 'nomi' phase: `q` becomes the filter on the city." }, "street_id": { "type": "integer", "description": "Id of the chosen street: enables the 'civici' phase (house-number completion/validation)." }, "house_number": { "type": "string", "description": "Partial or complete house number, used with `street_id` in the 'civici' phase." } } }, "SuggestSelezionaRequest": { "type": "object", "required": [ "session", "action", "street_id" ], "properties": { "session": { "type": "string" }, "action": { "type": "string", "enum": [ "select" ] }, "street_id": { "type": "integer", "description": "Id of the chosen suggestion." }, "house_number": { "type": "string" }, "postcode": { "type": "string", "description": "Optional: the postcode written in the form (or read from the text). Outside Italy the register confirms or corrects it." } } }, "SuggestVia": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "street" ] }, "id": { "type": "integer" }, "street_type": { "type": "string" }, "name": { "type": "string" }, "municipality": { "type": "string" }, "province": { "type": "string", "description": "Province code (Italy only)." }, "hamlet": { "type": "string" }, "zoned": { "type": "boolean" }, "area": { "type": "string", "description": "Locality inside the municipality, where the register has one (empty otherwise)." }, "source": { "type": "string", "enum": [ "registry", "osm" ], "description": "Outside Italy: the national register, or OpenStreetMap where the register does not publish." } }, "description": "A street suggested while typing. Without the postcode: it comes with the selection, from the engine." }, "SuggestNome": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "name" ] }, "id": { "type": "integer" }, "street_type": { "type": "string" }, "name": { "type": "string" }, "n_municipalities": { "type": "integer" } } }, "SuggestComune": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "municipality" ] }, "municipality": { "type": "string" }, "province": { "type": "string" } } }, "SuggestHouseNumber": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "house_number" ] }, "house_number": { "type": "string" }, "suffix": { "type": "string" }, "label": { "type": "string" } } }, "SuggestResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "phase": { "type": "string", "enum": [ "names", "streets", "cities", "municipalities", "house_numbers", "waiting", "unsupported" ] }, "truncated": { "type": "boolean", "description": "True if the results exceed the internal limit and were cut." }, "hints": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SuggestVia" }, { "$ref": "#/components/schemas/SuggestNome" }, { "$ref": "#/components/schemas/SuggestComune" }, { "$ref": "#/components/schemas/SuggestHouseNumber" } ] } }, "supported": { "type": "boolean", "description": "false when the requested country is not in service: no session, no charge, the form goes on manually." }, "country": { "$ref": "#/components/schemas/Country" }, "available": { "type": "boolean", "description": "'house_numbers' phase: false when we have no house numbers for that street (no validation possible)." }, "exists": { "type": [ "boolean", "null" ], "description": "'house_numbers' phase, with a typed house number: whether it is among the recorded house numbers (null = cannot be checked, e.g. 'snc')." }, "duration_ms": { "type": "integer" }, "parsed": { "$ref": "#/components/schemas/SuggestParsed" }, "attribution": { "type": "string", "description": "Source notice to display next to the suggestions (present outside Italy; the register's licence requires it)." } } }, "SuggestSelezionaResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "result": { "$ref": "#/components/schemas/AddressResult" }, "parsed": { "$ref": "#/components/schemas/SuggestParsed" }, "attribution": { "type": "string" } } }, "CountriesListResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "count": { "type": "integer" }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "source": { "type": "string", "example": "ISO 3166-1 / EU Vocabularies 20260318-0" } } }, "CountryRisoltaResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "country": { "$ref": "#/components/schemas/Country" }, "source": { "type": "string" } } }, "IndiceEndpoint": { "type": "object", "properties": { "path": { "type": "string" }, "method": { "type": "string" }, "description": { "type": "string" }, "auth": { "type": "string" }, "body": { "type": "string" }, "query": { "type": "string" } } }, "IndiceResponse": { "type": "object", "description": "Response of GET /api/v1/ (public endpoint, no `ok` field: this is a static index, not an outcome JSON).", "properties": { "service": { "type": "string", "example": "RadarAddress API" }, "version": { "type": "string", "example": "v1" }, "docs_url": { "type": "string", "example": "/api.php" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/IndiceEndpoint" } }, "async": { "type": "object", "properties": { "come": { "type": "string" }, "state": { "type": "string" }, "notes": { "type": "string" } } }, "status_codes": { "type": "object", "additionalProperties": { "type": "string" } } } }, "SuggestParsed": { "type": "object", "description": "How the server read the text: the form uses it to know where the house number is (before the street in France and Ireland, after it elsewhere).", "properties": { "street": { "type": "string" }, "house_number": { "type": "string" }, "postcode": { "type": "string" } } } } }, "x-language": { "parameter": "language (alias: lingua), in the body or the query string: it | en | de | fr | es | nl | pt | sv | no | fi | da | is | el", "fallback": [ "Accept-Language", "language of the account of the token", "English" ], "effect": "labels, reasons and messages come in that language (Content-Language in the response); field names, endpoint names, enumerated values and outcome codes are English identifiers in every language, except with language=it or on the historical host without language, where the Italian names come out" }, "x-legacy-endpoints": { "/api/v1/contatto": "/api/v1/contact", "/api/v1/deduplica": "/api/v1/dedupe", "/api/v1/codicefiscale": "/api/v1/tax-code", "/api/v1/arricchimento": "/api/v1/enrichment", "/api/v1/email": "/api/v1/email", "/api/v1/telefono": "/api/v1/phone", "/api/v1/sito": "/api/v1/website", "/api/v1/suggerisci": "/api/v1/suggest", "/api/v1/nazioni": "/api/v1/countries", "/api/v1/credito": "/api/v1/credit" }, "x-legacy-fields": { "account": "account", "action": "azione", "activated_on": "attivato_il", "active": "attiva", "active_packs": "attivi", "address": "indirizzo", "address_key": "indirizzo_confronto", "addresses": "indirizzi", "after": "dopo", "age": "eta", "agreement": "consenso", "ambiguous_year": "anno_ambiguo", "area": "area", "async": "asincrono", "auto_topup": "auto_ricarica", "available": "disponibile", "before": "prima", "belfiore_code": "codice_belfiore", "birth_country": "nazione_nascita", "birth_date": "data_nascita", "birth_place": "comune_nascita", "birth_place_name": "luogo_nascita", "birth_province": "provincia_nascita", "born_abroad": "nato_estero", "bought": "comprati", "building": "edificio", "cadastral_code": "catastale", "canonical_address": "indirizzo_canonico", "canonical_city": "localita_canonica", "care_of": "presso", "certificate_ok": "certificato_ok", "changed": "modificato", "changes": "modifiche", "charged": "consumate", "check": "controlla", "check_digit": "controllo", "city": "localita", "city_key": "localita_confronto", "city_passes": "cicli_localita", "city_type": "localita_tipo", "class": "classe", "code": "codice", "colour": "colore", "comments": "commenti", "conditions": "condizioni", "confidence": "confidenza", "confirmed": "confermato", "consolidate": "consolida", "contact": "contatto", "contact_person": "referente", "corrected_from": "corretta_da", "counter": "contatore", "counters": "contatori", "countries": "nazioni", "country": "nazione", "country_code": "nazione_iso2", "country_original": "nazione_originale", "country_prefix": "prefisso_paese", "created": "creato", "credit": "credito", "dedupe": "deduplica", "detail": "dettaglio", "differences": "differenze", "discarded": "scartati", "disposable": "usa_e_getta", "district": "quartiere", "domain_checked": "dominio_verificato", "domain_exists": "dominio_esiste", "done": "fatte", "duration_ms": "durata_ms", "e164": "formato_e164", "education": "titolo_studio", "entries": "schede", "error": "errore", "exists": "esiste", "expiry": "scadenza", "explanations": "spiegazioni", "extension": "estensione", "field": "campo", "final_url": "url_finale", "first_name": "nome", "foreign": "esteri", "foreign_address": "estero", "formal_salutation": "saluto_formale", "format": "formato", "found": "trovato", "free": "gratuite", "free_forever": "gratis_per_sempre", "full_name": "nominativo", "gender": "sesso", "gender_source": "fonte_sesso", "generic": "generica", "group": "gruppo", "groups": "gruppi", "hamlet": "frazione", "hints": "suggerimenti", "homocode": "omocodo", "house_number": "civico", "house_number_label": "civico_label", "house_number_verified": "civico_verificato", "house_numbers": "civici", "informal_salutation": "saluto_informale", "iso2": "codice_iso2", "iso3": "codice_iso3", "istat_code": "istat", "items": "elementi", "job": "lavoro", "language": "lingua", "languages": "lingue", "last_name": "cognome", "last_on": "ultimo_il", "last_used": "ultimo_uso", "left": "residuo", "legacy_default": "default_storico", "level": "livello", "light": "leggere", "long": "lungo", "long_name": "nome_esteso", "main_record": "principale", "match": "corrisponde", "matches": "abbinamenti", "members": "membri", "method": "metodo", "metric": "metrico", "min_level": "livello_minimo", "missing": "mancano", "modified": "modificati", "month": "mese", "monthly_cap_eur": "tetto_mese_eur", "multiple_postcodes": "multicap", "municipality": "comune", "municipality_code": "comune_codice", "municipality_code_type": "comune_codice_tipo", "n_records": "n_anagrafiche", "name_id": "nome_id", "name_original": "nome_originale", "national_number": "nazionale", "nearby": "vicino", "needed": "necessarie", "needs_topup": "da_ricaricare", "network": "rete", "normalized": "normalizzato", "normalized_postal": "normalizzato_postale", "not_found": "non_trovati", "note": "nota", "notes": "note", "number": "numero", "numbers": "numeri", "occurrences": "occorrenze", "operations": "elaborazioni", "operator": "operatore", "origin": "origine", "other": "altro", "outcome": "esito", "outcome_label": "esito_label", "outcomes": "esiti", "overall_cap_eur": "tetto_globale_eur", "packs": "pacchetti", "parsed": "letto", "phase": "fase", "phone": "telefono", "phone2": "telefono2", "phone3": "telefono3", "phones": "telefoni", "place": "luogo", "position": "posizione", "postcode": "cap", "postcode_check": "cap_verifica", "precision": "precisione", "preserve_original": "preserva_originale", "presumed": "presunto", "processed": "lavorato", "processed_at": "datalav", "profession": "qualifica", "provenance": "provenienza", "province": "provincia", "provincial_capital": "capoluogo", "reachable": "raggiungibile", "reason": "motivo", "record_outcome": "esito_record", "records": "anagrafiche", "redirects": "redirect", "reference": "riferimento", "reference_id": "riferimento_id", "remaining": "rimaste", "renews_on": "si_rinnova_il", "reset_on": "si_azzerano_il", "rows": "righe", "salutation": "saluto", "save": "salva", "segment_passes": "cicli_arcostradale", "session": "sessione", "short": "breve", "singles": "singoli", "size": "taglia", "source": "fonte", "specificity": "specificita", "spent_month_eur": "speso_mese_eur", "spent_overall_month_eur": "speso_globale_mese_eur", "state": "stato", "states": "stati", "street": "strada", "street_id": "via_id", "street_name": "toponimo", "street_passes": "cicli_toponimo", "street_proper_name": "duf", "street_type": "dug", "sub_address": "subindirizzo", "sub_address_confirmed": "subindirizzo_confermato", "subject_type": "tipo_soggetto", "subscription": "abbonamento", "suffix": "esponente", "suggestion": "suggerimento", "summary": "riepilogo", "supported": "supportato", "syntax": "sintassi", "tax_code": "codice_fiscale", "tax_code_outcome": "codice_fiscale_esito", "territory": "territorio", "text": "testo", "time_ms": "tempo_ms", "title": "titolo", "to_check": "da_controllare", "total": "totali", "town": "citta", "truncated": "troncato", "type": "tipo", "type_normalized": "tipo_norm", "types": "tipi", "unresolved": "non_risolti", "url_normalized": "url_normalizzato", "used": "usate", "valid": "valida", "value": "valore", "warning": "avviso", "warnings": "avvisi", "website": "sito", "website2": "sito2", "website3": "sito3", "websites": "siti", "zoned": "zonato" }, "x-legacy-values": { "format": { "national": "nazionale", "international": "internazionale" }, "action": { "generate": "genera", "validate": "valida", "extract": "estrai", "compare": "confronta", "select": "seleziona", "suggest": "suggerisci" }, "phase": { "names": "nomi", "streets": "vie", "cities": "localita", "municipalities": "comuni", "house_numbers": "civici", "waiting": "attesa", "unsupported": "non_supportata" }, "foreign": { "declared": "dichiarati", "detect": "rileva" }, "min_level": { "certain": "certo", "probable": "probabile", "ambiguous": "ambiguo" }, "level": { "certain": "certo", "probable": "probabile", "ambiguous": "ambiguo" }, "confidence": { "high": "alta", "medium": "media", "low": "bassa" }, "state": { "queued": "in_coda", "processing": "in_lavorazione", "completed": "completato", "error": "errore", "cancelled": "annullato", "draft": "bozza", "never_used": "mai_usato", "free": "gratuite", "free_used_up": "gratuite_esaurite", "active": "attivo", "awaiting_renewal": "in_attesa_del_rinnovo", "used_up": "esaurito" }, "kind": { "filled": "valorizzato", "normalized": "normalizzato", "modified": "modificato" }, "counter": { "contact": "contatto", "dedupe": "deduplica", "light": "leggere" }, "precision": { "house_number": "civico", "interpolated": "interpolato", "street": "via", "locality": "localita", "municipality": "comune", "nearby": "vicinanza" }, "class": { "landline": "fisso", "mobile": "mobile", "special": "speciale", "foreign": "estero" }, "type": { "landline": "fisso", "mobile": "mobile", "foreign": "estero", "service": "servizio", "special": "speciale", "toll_free": "numero_verde", "premium_rate": "a_pagamento", "home": "casa", "work": "lavoro", "cell": "cellulare", "other": "altro", "street": "via", "name": "nome", "municipality": "comune", "house_number": "civico", "unit": "interno", "staircase": "scala", "floor": "piano", "block": "palazzina", "building_number": "palazzo", "building": "edificio", "block_number": "isolato" }, "subject_type": { "natural_person": "fisica", "legal_person": "giuridica", "uncertain": "incerto" }, "gender_source": { "given": "esplicito", "inferred": "dedotto" }, "source": { "manual": "manuale", "registry": "registro" }, "error": { "empty": "vuoto", "length": "lunghezza", "format": "formato", "check_digit": "carattere_controllo", "homocode": "omocodia", "month": "mese", "date": "data", "place": "luogo", "last_name": "cognome", "first_name": "nome", "gender": "sesso", "birth_date": "data_nascita", "birth_place": "luogo_nascita", "ambiguous_place": "luogo_ambiguo", "last_name_non_latin": "cognome_non_latino", "first_name_non_latin": "nome_non_latino" }, "origin": { "purchase": "acquisto", "auto_topup": "auto_ricarica", "gift": "omaggio", "subscription": "abbonamento" } }, "x-legacy-input-synonyms": { "zip": "cap", "zip_code": "cap", "postal_code": "cap", "post_code": "cap", "town": "localita", "locality": "localita", "municipality": "localita", "county": "provincia", "state": "provincia", "region": "provincia", "surname": "cognome", "family_name": "cognome", "lastname": "cognome", "company": "cognome", "organisation": "cognome", "organization": "cognome", "name": "cognome", "firstname": "nome", "given_name": "nome", "forename": "nome", "sex": "sesso", "salutation": "titolo", "prefix": "titolo", "phone_number": "telefono", "telephone": "telefono", "mobile": "telefono", "tel": "telefono", "email_address": "email", "mail": "email", "url": "sito", "web": "sito", "homepage": "sito", "fiscal_code": "codice_fiscale", "tax_id": "codice_fiscale", "tin": "codice_fiscale", "date_of_birth": "data_nascita", "dob": "data_nascita", "birthdate": "data_nascita", "place_of_birth": "comune_nascita", "birthplace": "comune_nascita", "c_o": "presso", "co": "presso", "care_of": "presso", "country_iso2": "nazione_iso2", "iso2": "nazione_iso2", "list": "elementi", "batch": "elementi", "contacts": "anagrafiche" } }