Codice Fiscale API - FreeAPIService docs

Base path: /codice-fiscale

The routes below validate an Italian Codice Fiscale and resolve Belfiore (catastral) codes against the geo_city table.

Unless stated otherwise, all responses are JSON and errors return a 4xx status with an error field.

GET /codice-fiscale/check

Validates a Codice Fiscale and optionally cross-checks it against the date of birth, gender, name and surname.

Query parameters

Parameter	Required	Description
`codice_fiscale`	yes	The 16-character tax code (case-insensitive).
`dob`	no	Date of birth, ISO 8601 (`YYYY-MM-DD`).
`gender_id`	no	`F` (female) or `M` (male).
`real_name`	no	First name, used to check characters 4–6.
`real_surname`	no	Last name, used to check characters 1–3.

Any parameter outside this list makes the request fail with 400 (banned parameters).

Checks performed

Regex format (config.regex.valid_codice_fiscale).
The 16th character is a valid control character.
If dob is provided: year, month and day consistency.
If dob + gender_id are provided: the day field (41–71 for female) matches the gender.
If real_name + real_surname are provided: the first six letters match the name/surname encoding.
The Belfiore code (characters 12–15) is valid:
- born abroad (Z###): must be between Z100 and Z906;
- born in Italy: must exist in geo_city.catastral_code.

Responses

Status	Body
`200`	`{ "valid": true, "codice_fiscale": "<code>" }`
`400`	`{ "error": "banned parameters", "banned": ["foo"] }`
`400`	`{ "error": "codice_fiscale is mandatory" }`
`400`	`{ "error": "invalid cf", "cause": { "error": "<reason>" } }`

Possible cause.error values: invalid (regex), invalid 16th char, invalid date of birth format, invalid year in DOB, invalid month in DOB, invalid day in DOB, invalid gender (female), invalid gender (male), invalid surname letters, invalid name letters, invalid catastral code for foreign country, invalid catastral code.

Examples

Valid code (born abroad):

curl "$BASE_URL/codice-fiscale/check?codice_fiscale=BCCMNL89M13Z600P"

{
    "codice_fiscale": "BCCMNL89M13Z600P",
    "valid": true
}

Valid code plus date of birth, gender, name and surname:

curl "$BASE_URL/codice-fiscale/check?codice_fiscale=BCCMNL89M13Z600P&dob=1989-08-13&gender_id=M&real_name=Manuel&real_surname=Bicchi"

Missing required parameter:

curl -i "$BASE_URL/codice-fiscale/check"

{
    "error": "codice_fiscale is mandatory"
}

Banned parameter:

curl -i "$BASE_URL/codice-fiscale/check?codice_fiscale=BCCMNL89M13Z600P&foo=bar"

{
    "banned": ["foo"],
    "error": "banned parameters"
}

Invalid control character:

curl -i "$BASE_URL/codice-fiscale/check?codice_fiscale=BCCMNL89M13Z600X"

{
    "cause": {
        "error": "invalid 16th char"
    },
    "error": "invalid cf"
}

GET /codice-fiscale/belfiore/:id

Returns the geo_city rows whose catastral_code matches the supplied Belfiore code.

Path parameters

Parameter	Required	Description
`id`	yes	The Belfiore/catastral code (case-insensitive, e.g. `A001`).

Responses

Status	Body
`200`	Array of matching `geo_city` rows
`400`	`{ "error": "id is mandatory" }`
`404`	`{ "error": "catastral code not found" }`

Note: a catastral code is not guaranteed to be unique — some cities have several rows (for example, multiple ZIP codes). All matching rows are returned.

Examples

curl "$BASE_URL/codice-fiscale/belfiore/A001"

[
    {
        "catastral_code": "A001",
        "city": "Abano Terme",
        "country_code": "IT",
        "province": "Padova",
        "province_code": "PD",
        "region": "Veneto",
        "region_code": 5,
        "zip": "35031"
    }
]

Lowercase input is accepted:

curl "$BASE_URL/codice-fiscale/belfiore/a001"

Unknown code:

curl -i "$BASE_URL/codice-fiscale/belfiore/XXXX"

{
    "error": "catastral code not found"
}