{
  "openapi": "3.1.0",
  "info": {
    "title": "Codice fiscale API (codicefiscalesubito.it)",
    "version": "1.0.0",
    "description": "Free API and MCP server for the Italian codice fiscale: compute it from personal data, decode it (inverso), verify it, and look up the codice catastale of any comune or foreign state valid on a given date (ANPR history, suppressed comuni included). No key, CORS open, messages in Italian.",
    "contact": {
      "email": "contatto@codicefiscalesubito.it",
      "url": "https://codicefiscalesubito.it/api-codice-fiscale/"
    }
  },
  "servers": [
    {
      "url": "https://codicefiscalesubito.it"
    }
  ],
  "externalDocs": {
    "url": "https://codicefiscalesubito.it/api-codice-fiscale/"
  },
  "paths": {
    "/api/v1/calcola": {
      "get": {
        "operationId": "compute_codice_fiscale",
        "summary": "Compute a codice fiscale",
        "description": "Compute the Italian codice fiscale (tax code) of a person from surname, name, sex, birth date and birth place, with the D.M. 23/12/1976 rules. The place can be a comune ('Roma', 'Castro (LE)'), a foreign state ('Francia') or a codice catastale ('H501'); the code valid on the birth date is used. Returns the 16 characters and why each group has its value. The Agenzia delle Entrate may assign an omocodic variant: only it confirms a code.",
        "parameters": [
          {
            "name": "surname",
            "in": "query",
            "required": true,
            "description": "Surname (cognome), as on the document.",
            "schema": {
              "type": "string",
              "description": "Surname (cognome), as on the document.",
              "example": "Rossi"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "Given name(s) (nome), all of them.",
            "schema": {
              "type": "string",
              "description": "Given name(s) (nome), all of them.",
              "example": "Mario"
            }
          },
          {
            "name": "sex",
            "in": "query",
            "required": true,
            "description": "M or F.",
            "schema": {
              "type": "string",
              "description": "M or F.",
              "enum": [
                "M",
                "F"
              ],
              "example": "M"
            }
          },
          {
            "name": "birth_date",
            "in": "query",
            "required": true,
            "description": "Birth date, YYYY-MM-DD (DD/MM/YYYY accepted).",
            "schema": {
              "type": "string",
              "description": "Birth date, YYYY-MM-DD (DD/MM/YYYY accepted).",
              "example": "1985-12-10"
            }
          },
          {
            "name": "birth_place",
            "in": "query",
            "required": true,
            "description": "Comune (with province if ambiguous), foreign state, or codice catastale / Z-code.",
            "schema": {
              "type": "string",
              "description": "Comune (with province if ambiguous), foreign state, or codice catastale / Z-code.",
              "example": "Roma"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "compute_codice_fiscale_post",
        "summary": "Compute a codice fiscale (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "surname": {
                    "type": "string",
                    "description": "Surname (cognome), as on the document.",
                    "example": "Rossi"
                  },
                  "name": {
                    "type": "string",
                    "description": "Given name(s) (nome), all of them.",
                    "example": "Mario"
                  },
                  "sex": {
                    "type": "string",
                    "description": "M or F.",
                    "enum": [
                      "M",
                      "F"
                    ],
                    "example": "M"
                  },
                  "birth_date": {
                    "type": "string",
                    "description": "Birth date, YYYY-MM-DD (DD/MM/YYYY accepted).",
                    "example": "1985-12-10"
                  },
                  "birth_place": {
                    "type": "string",
                    "description": "Comune (with province if ambiguous), foreign state, or codice catastale / Z-code.",
                    "example": "Roma"
                  }
                },
                "required": [
                  "surname",
                  "name",
                  "sex",
                  "birth_date",
                  "birth_place"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/decodifica": {
      "get": {
        "operationId": "decode_codice_fiscale",
        "summary": "Decode a codice fiscale (inverso)",
        "description": "Read back a codice fiscale: sex, birth date (one or two possible centuries), birth comune or foreign state valid on that date, the consonant codes of surname and name, and omocodia. The full name cannot be recovered from a code. Fails with the reason when the format or the check character is wrong.",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "description": "Codice fiscale, 16 characters (spaces and lowercase accepted).",
            "schema": {
              "type": "string",
              "description": "Codice fiscale, 16 characters (spaces and lowercase accepted).",
              "example": "RSSMRA85T10H501O"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "decode_codice_fiscale_post",
        "summary": "Decode a codice fiscale (inverso) (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Codice fiscale, 16 characters (spaces and lowercase accepted).",
                    "example": "RSSMRA85T10H501O"
                  }
                },
                "required": [
                  "code"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verifica": {
      "get": {
        "operationId": "verify_codice_fiscale",
        "summary": "Verify a codice fiscale",
        "description": "Check that a codice fiscale is well formed, layer by layer: format, check character, a real birth date, a place code valid on that date, and optionally the surname and name letters. It says whether the code is written correctly, not whether the Agenzia delle Entrate has assigned it (only its own service does).",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "description": "Codice fiscale, 16 characters (spaces and lowercase accepted).",
            "schema": {
              "type": "string",
              "description": "Codice fiscale, 16 characters (spaces and lowercase accepted).",
              "example": "RSSMRA85T10H501O"
            }
          },
          {
            "name": "surname",
            "in": "query",
            "required": false,
            "description": "Optional surname to match against characters 1-3.",
            "schema": {
              "type": "string",
              "description": "Optional surname to match against characters 1-3.",
              "example": "Rossi"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Optional name to match against characters 4-6.",
            "schema": {
              "type": "string",
              "description": "Optional name to match against characters 4-6.",
              "example": "Mario"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "verify_codice_fiscale_post",
        "summary": "Verify a codice fiscale (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Codice fiscale, 16 characters (spaces and lowercase accepted).",
                    "example": "RSSMRA85T10H501O"
                  },
                  "surname": {
                    "type": "string",
                    "description": "Optional surname to match against characters 1-3.",
                    "example": "Rossi"
                  },
                  "name": {
                    "type": "string",
                    "description": "Optional name to match against characters 4-6.",
                    "example": "Mario"
                  }
                },
                "required": [
                  "code"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/luoghi": {
      "get": {
        "operationId": "lookup_place",
        "summary": "Find the codice catastale of a place",
        "description": "Search the 15,000 comuni of every era and the foreign states of the ANPR archive by name or by code (codice catastale like H501, Z-code like Z110). Returns up to 20 places with their province and the dates their code was valid. Give a date to keep only the places valid on it.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Name ('Roma', 'Sant Angelo') or code ('H501', 'Z110').",
            "schema": {
              "type": "string",
              "description": "Name ('Roma', 'Sant Angelo') or code ('H501', 'Z110').",
              "example": "Pola"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "Optional date YYYY-MM-DD: only places valid on that day.",
            "schema": {
              "type": "string",
              "description": "Optional date YYYY-MM-DD: only places valid on that day.",
              "example": "1940-06-02"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 60 requests per minute per IP"
          }
        }
      },
      "post": {
        "operationId": "lookup_place_post",
        "summary": "Find the codice catastale of a place (JSON body)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "type": "string",
                    "description": "Name ('Roma', 'Sant Angelo') or code ('H501', 'Z110').",
                    "example": "Pola"
                  },
                  "date": {
                    "type": "string",
                    "description": "Optional date YYYY-MM-DD: only places valid on that day.",
                    "example": "1940-06-02"
                  }
                },
                "required": [
                  "q"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result"
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "docs": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "message"
        ]
      }
    }
  }
}