{
  "openapi": "3.0.0",
  "info": {
    "description": "The iAML REST API provides access to AML and Compliance services: screening of persons and entities against PEP and RCA databases, over 75 sanction lists and warning lists, public register data, and risk assessment — through one consistent API.",
    "version": "1.0",
    "title": "iAML REST API",
    "contact": {
      "email": "support@iaml.com.pl"
    }
  },
  "tags": [
    {
      "name": "Public Registers",
      "description": "Access to public register data: Central Register of Beneficial Owners (CRBR) and the VAT White List."
    },
    {
      "name": "Compliance & AML Databases",
      "description": "Proprietary compliance databases: PEP, RCA, 75+ sanction lists, the KNF Warning List and EURO-BOZON."
    },
    {
      "name": "Risk Sources & Specialist Lists",
      "description": "High-risk countries and industries plus specialist registers: Virtual Currency Register, Gambling Domains Register, MiCA register."
    },
    {
      "name": "iAML Services",
      "description": "iAML platform services: Record Check and Risk Engine."
    }
  ],
  "paths": {
    "/real_beneficiary": {
      "get": {
        "tags": [
          "Public Registers"
        ],
        "summary": "find ultimate beneficiaries of a company (CRBR)",
        "description": "Returns the beneficial owners of a company registered in CRBR, identified by its NIP, REGON or KRS number.",
        "operationId": "findBeneficiary",
        "parameters": [
          {
            "in": "query",
            "name": "number",
            "description": "NIP/REGON/KRS",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Beneficiary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable – the source register (CRBR or GUS) is temporarily unreachable; the request was not charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceUnavailable"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/company_beneficiary": {
      "get": {
        "tags": [
          "Public Registers"
        ],
        "summary": "find companies of an ultimate beneficiary (CRBR)",
        "description": "Returns the companies in which the person identified by PESEL is registered in CRBR as a beneficial owner.",
        "operationId": "findCompanyBeneficiary",
        "parameters": [
          {
            "in": "query",
            "name": "number",
            "description": "PESEL",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyBeneficiary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable – the source register (CRBR or GUS) is temporarily unreachable; the request was not charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceUnavailable"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/company_beneficiary2": {
      "get": {
        "tags": [
          "Public Registers"
        ],
        "summary": "find companies of an ultimate beneficiary (CRBR)",
        "description": "Returns the companies in which the person identified by first name, surname and date of birth is registered in CRBR as a beneficial owner.",
        "operationId": "findCompanyBeneficiary2",
        "parameters": [
          {
            "in": "query",
            "name": "first_name",
            "description": "First name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "surname",
            "description": "Surname",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "birthday",
            "description": "Date of birth",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyBeneficiary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable – the source register (CRBR or GUS) is temporarily unreachable; the request was not charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceUnavailable"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/vat_white_list": {
      "get": {
        "tags": [
          "Public Registers"
        ],
        "summary": "check the VAT White List",
        "description": "Checks on the VAT White List whether the given bank account (nrb) is assigned to the taxpayer (nip) on the given date. Returns TAK (yes) or NIE (no) in result.accountAssigned.",
        "operationId": "checkWhiteVatList",
        "parameters": [
          {
            "in": "query",
            "name": "nip",
            "description": "NIP",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "nrb",
            "description": "Bank account number (NRB)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VatWhiteList"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/peps": {
      "get": {
        "tags": [
          "Compliance & AML Databases"
        ],
        "summary": "find a person in the PEP database",
        "description": "Searches the PEP database by first and last name, optionally narrowed by birth date or PESEL (the PESEL is only used to derive the birth date). Called without parameters, it redirects to the full PEP list export.",
        "operationId": "findPep",
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "description": "First and last name of the PEP",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "birth_date",
            "description": "Birth date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "pesel",
            "description": "PESEL",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "fuzziness",
            "description": "Turns on fuzzy matching (tolerant of typos and spelling variants) alongside the strict search. The value is the minimum match score, in percent.\n\n**Values**\n- An integer from `50` to `100`. A lower value returns more, but weaker, matches.\n- Omitted or empty (`fuzziness=`): only the strict search runs. The response has the same format as without this parameter: records carry no `match` key.\n- Out of range or not an integer (e.g. `49`, `101`, `70.5`, `abc`): `412 Precondition Failed`, with the error in `errors`. No search runs.\n\n**Access**\n- Requires the `api_fuzzy_search` service on the organization's licence. It applies to every API key of the organization and is not assigned to a key.\n- Without the service, any non-empty value returns `403 Forbidden`. The licence is checked before the value is validated.\n- Uses no extra quota: the request counts as a regular `/v1/peps` query.\n\n**Response**\n\nEvery record in the `peps` array has a `match` key that says how it was found:\n- `strict`: `true` if the strict search returned the record, `false` otherwise.\n- `similarity`: the fuzzy match similarity in percent, an integer from the `fuzziness` sent up to `100`. `null` if fuzzy matching did not return the record.\n\nA record both searches find appears once, with `strict: true` and its `similarity`.\n\nStrict search results come first, then the records only fuzzy matching found, sorted by `similarity`, highest first, then by name. Fuzzy matching returns at most 100 records. Strict results are not capped.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 50,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "peps"
                  ],
                  "properties": {
                    "peps": {
                      "type": "array",
                      "description": "PEP persons found.",
                      "items": {
                        "$ref": "#/components/schemas/Person"
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "summary": "Without `fuzziness`",
                    "value": {
                      "peps": [
                        {
                          "id": 104233,
                          "type": "individual",
                          "name": "JAN KOWALSKI",
                          "names": {
                            "first": "JAN",
                            "middle": null,
                            "third": null,
                            "father": null,
                            "last": "KOWALSKI",
                            "full": "JAN KOWALSKI"
                          },
                          "aliases": [
                            "JAN KOWALSKI"
                          ],
                          "gender": "m",
                          "title": null,
                          "remarks": null,
                          "nationalities": [
                            {
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "birth_places": [
                            {
                              "place": "Warszawa",
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "birth_dates": [
                            {
                              "date": "1965-03-12",
                              "year": 1965,
                              "month": 3,
                              "day": 12
                            }
                          ],
                          "addresses": [
                            {
                              "address": null,
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "passports": [],
                          "identifiers": [
                            {
                              "type": "pseudoPESEL",
                              "number": "65031200012",
                              "country_name": "",
                              "country_code": "",
                              "info": ""
                            }
                          ],
                          "sources": [
                            {
                              "organization": "Ministerstwo Obrony Narodowej",
                              "function": "Sekretarz stanu",
                              "reason": "Członek rządu",
                              "since": "2023-12-13",
                              "to": null,
                              "clause_url": "Źródło: BIP Ministerstwa Obrony Narodowej"
                            }
                          ],
                          "decease_on": null,
                          "created_on": "2024-05-10",
                          "reviewed_on": "2026-09-30",
                          "updated_on": "2026-09-30",
                          "deleted_at": null,
                          "deactivated_on": null
                        }
                      ]
                    }
                  },
                  "fuzziness": {
                    "summary": "With `fuzziness=70`",
                    "value": {
                      "peps": [
                        {
                          "id": 104233,
                          "type": "individual",
                          "name": "JAN KOWALSKI",
                          "names": {
                            "first": "JAN",
                            "middle": null,
                            "third": null,
                            "father": null,
                            "last": "KOWALSKI",
                            "full": "JAN KOWALSKI"
                          },
                          "aliases": [
                            "JAN KOWALSKI"
                          ],
                          "gender": "m",
                          "title": null,
                          "remarks": null,
                          "nationalities": [],
                          "birth_places": [],
                          "birth_dates": [
                            {
                              "date": "1965-03-12",
                              "year": 1965,
                              "month": 3,
                              "day": 12
                            }
                          ],
                          "addresses": [],
                          "passports": [],
                          "identifiers": [
                            {
                              "type": "pseudoPESEL",
                              "number": "65031200012",
                              "country_name": "",
                              "country_code": "",
                              "info": ""
                            }
                          ],
                          "sources": [
                            {
                              "organization": "Ministerstwo Obrony Narodowej",
                              "function": "Sekretarz stanu",
                              "reason": "Członek rządu",
                              "since": "2023-12-13",
                              "to": null,
                              "clause_url": "Źródło: BIP Ministerstwa Obrony Narodowej"
                            }
                          ],
                          "decease_on": null,
                          "created_on": "2024-05-10",
                          "reviewed_on": "2026-09-30",
                          "updated_on": "2026-09-30",
                          "deleted_at": null,
                          "deactivated_on": null,
                          "match": {
                            "strict": true,
                            "similarity": 100
                          }
                        },
                        {
                          "id": 98712,
                          "type": "individual",
                          "name": "JAN KOWALSKY",
                          "names": {
                            "first": "JAN",
                            "middle": "PIOTR",
                            "third": null,
                            "father": null,
                            "last": "KOWALSKY",
                            "full": "JAN KOWALSKY"
                          },
                          "aliases": [
                            "JAN KOWALSKY",
                            "JAN PIOTR KOWALSKY"
                          ],
                          "gender": "m",
                          "title": null,
                          "remarks": null,
                          "nationalities": [
                            {
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "birth_places": [
                            {
                              "place": "Gdańsk",
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "birth_dates": [],
                          "addresses": [
                            {
                              "address": "ul. Długa 5, Gdańsk",
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "passports": [],
                          "identifiers": [],
                          "sources": [
                            {
                              "organization": "Rada Miasta Gdańska",
                              "function": "Radny",
                              "reason": "Członek organu samorządu",
                              "since": "2018-11-21",
                              "to": "2024-05-06",
                              "clause_url": "Źródło: BIP Miasta Gdańska"
                            }
                          ],
                          "decease_on": null,
                          "created_on": "2024-05-10",
                          "reviewed_on": "2026-09-30",
                          "updated_on": "2026-09-30",
                          "deleted_at": null,
                          "deactivated_on": "2025-05-06",
                          "match": {
                            "strict": false,
                            "similarity": 82
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/rcas": {
      "get": {
        "tags": [
          "Compliance & AML Databases"
        ],
        "summary": "find a person in the RCA database",
        "description": "Searches the RCA database by first and last name, optionally narrowed by birth date or PESEL (the PESEL is only used to derive the birth date). Called without parameters, it redirects to the full RCA list export.",
        "operationId": "findRca",
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "description": "First and last name of the RCA",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "birth_date",
            "description": "Birth date",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "pesel",
            "description": "PESEL",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "fuzziness",
            "description": "Turns on fuzzy matching (tolerant of typos and spelling variants) alongside the strict search. The value is the minimum match score, in percent.\n\n**Values**\n- An integer from `50` to `100`. A lower value returns more, but weaker, matches.\n- Omitted or empty (`fuzziness=`): only the strict search runs. The response has the same format as without this parameter: records carry no `match` key.\n- Out of range or not an integer (e.g. `49`, `101`, `70.5`, `abc`): `412 Precondition Failed`, with the error in `errors`. No search runs.\n\n**Access**\n- Requires the `api_fuzzy_search` service on the organization's licence. It applies to every API key of the organization and is not assigned to a key.\n- Without the service, any non-empty value returns `403 Forbidden`. The licence is checked before the value is validated.\n- Uses no extra quota: the request counts as a regular `/v1/rcas` query.\n\n**Response**\n\nEvery record in the `rcas` array has a `match` key that says how it was found:\n- `strict`: `true` if the strict search returned the record, `false` otherwise.\n- `similarity`: the fuzzy match similarity in percent, an integer from the `fuzziness` sent up to `100`. `null` if fuzzy matching did not return the record.\n\nA record both searches find appears once, with `strict: true` and its `similarity`.\n\nStrict search results come first, then the records only fuzzy matching found, sorted by `similarity`, highest first, then by name. Fuzzy matching returns at most 100 records. Strict results are not capped.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 50,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "rcas"
                  ],
                  "properties": {
                    "rcas": {
                      "type": "array",
                      "description": "RCA persons found.",
                      "items": {
                        "$ref": "#/components/schemas/Rca"
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "summary": "Without `fuzziness`",
                    "value": {
                      "rcas": [
                        {
                          "id": 55120,
                          "type": "individual",
                          "name": "ANNA NOWAK",
                          "names": {
                            "first": "ANNA",
                            "middle": null,
                            "third": null,
                            "father": null,
                            "last": "NOWAK",
                            "full": "ANNA NOWAK"
                          },
                          "aliases": [
                            "ANNA NOWAK"
                          ],
                          "gender": "f",
                          "title": null,
                          "remarks": null,
                          "nationalities": [
                            {
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "birth_places": [],
                          "birth_dates": [
                            {
                              "date": "1972-08-04",
                              "year": 1972,
                              "month": 8,
                              "day": 4
                            }
                          ],
                          "addresses": [
                            {
                              "address": null,
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "passports": [],
                          "identifiers": [
                            {
                              "type": "pseudoPESEL",
                              "number": "72080400003",
                              "country_name": "",
                              "country_code": "",
                              "info": ""
                            }
                          ],
                          "sources": [
                            {
                              "pep": "JAN KOWALSKI",
                              "company": "ACME SP. Z O.O.",
                              "type": "associate",
                              "ex": false,
                              "since": "2019-06-01",
                              "to": null,
                              "clause": "Źródło: Krajowy Rejestr Sądowy"
                            }
                          ],
                          "decease_on": null,
                          "created_on": "2024-06-21",
                          "reviewed_on": "2026-09-30",
                          "updated_on": "2026-09-30",
                          "deleted_at": null,
                          "deactivated_on": null
                        }
                      ]
                    }
                  },
                  "fuzziness": {
                    "summary": "With `fuzziness=70`",
                    "value": {
                      "rcas": [
                        {
                          "id": 55120,
                          "type": "individual",
                          "name": "ANNA NOWAK",
                          "names": {
                            "first": "ANNA",
                            "middle": null,
                            "third": null,
                            "father": null,
                            "last": "NOWAK",
                            "full": "ANNA NOWAK"
                          },
                          "aliases": [
                            "ANNA NOWAK"
                          ],
                          "gender": "f",
                          "title": null,
                          "remarks": null,
                          "nationalities": [
                            {
                              "country_name": "Poland",
                              "country_code": "PL"
                            }
                          ],
                          "birth_places": [],
                          "birth_dates": [],
                          "addresses": [],
                          "passports": [],
                          "identifiers": [],
                          "sources": [
                            {
                              "pep": "JAN KOWALSKI",
                              "company": "ACME SP. Z O.O.",
                              "type": "associate",
                              "ex": false,
                              "since": "2019-06-01",
                              "to": null,
                              "clause": "Źródło: Krajowy Rejestr Sądowy"
                            }
                          ],
                          "decease_on": null,
                          "created_on": "2024-05-10",
                          "reviewed_on": "2026-09-30",
                          "updated_on": "2026-09-30",
                          "deleted_at": null,
                          "deactivated_on": null,
                          "match": {
                            "strict": true,
                            "similarity": 100
                          }
                        },
                        {
                          "id": 61877,
                          "type": "individual",
                          "name": "ANNA NOWACK",
                          "names": {
                            "first": "ANNA",
                            "middle": null,
                            "third": null,
                            "father": null,
                            "last": "NOWACK",
                            "full": "ANNA NOWACK"
                          },
                          "aliases": [
                            "ANNA NOWACK"
                          ],
                          "gender": "f",
                          "title": null,
                          "remarks": null,
                          "nationalities": [],
                          "birth_places": [],
                          "birth_dates": [
                            {
                              "date": "1972-08-04",
                              "year": 1972,
                              "month": 8,
                              "day": 4
                            }
                          ],
                          "addresses": [],
                          "passports": [],
                          "identifiers": [
                            {
                              "type": "pseudoPESEL",
                              "number": "72080400003",
                              "country_name": "",
                              "country_code": "",
                              "info": ""
                            }
                          ],
                          "sources": [
                            {
                              "pep": "JAN KOWALSKY",
                              "company": "",
                              "type": "associate",
                              "ex": true,
                              "since": "2010-01-01",
                              "to": "2022-12-31",
                              "clause": "Źródło: Krajowy Rejestr Sądowy"
                            }
                          ],
                          "decease_on": null,
                          "created_on": "2024-05-10",
                          "reviewed_on": "2026-09-30",
                          "updated_on": "2026-09-30",
                          "deleted_at": null,
                          "deactivated_on": null,
                          "match": {
                            "strict": false,
                            "similarity": 76
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/sanctions": {
      "get": {
        "tags": [
          "Compliance & AML Databases"
        ],
        "summary": "find a person or entity on sanction lists",
        "description": "Searches the sanction lists enabled for the organization by person or entity name. Called without the name parameter, it redirects to the full sanctions export.",
        "operationId": "findSanction",
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "description": "Person or entity name",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "fuzziness",
            "description": "Turns on fuzzy matching (tolerant of typos and spelling variants) alongside the strict search. The value is the minimum match score, in percent.\n\n**Values**\n- An integer from `50` to `100`. A lower value returns more, but weaker, matches.\n- Omitted or empty (`fuzziness=`): only the strict search runs. The response has the same format as without this parameter: records carry no `match` key.\n- Out of range or not an integer (e.g. `49`, `101`, `70.5`, `abc`): `412 Precondition Failed`, with the error in `errors`. No search runs.\n\n**Access**\n- Requires the `api_fuzzy_search` service on the organization's licence. It applies to every API key of the organization and is not assigned to a key.\n- Without the service, any non-empty value returns `403 Forbidden`. The licence is checked before the value is validated.\n- Uses no extra quota: the request counts as a regular `/v1/sanctions` query.\n\n**Response**\n\nEvery record in the `sanctions` array has a `match` key that says how it was found:\n- `strict`: `true` if the strict search returned the record, `false` otherwise.\n- `similarity`: the fuzzy match similarity in percent, an integer from the `fuzziness` sent up to `100`. `null` if fuzzy matching did not return the record.\n\nA record both searches find appears once, with `strict: true` and its `similarity`.\n\nStrict search results come first, then the records only fuzzy matching found, sorted by `similarity`, highest first, then by `id`. Fuzzy matching returns at most 100 records. Strict results are not capped.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 50,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "sanctions"
                  ],
                  "properties": {
                    "sanctions": {
                      "type": "array",
                      "description": "Sanction list records found.",
                      "items": {
                        "$ref": "#/components/schemas/Sanction"
                      }
                    }
                  }
                },
                "examples": {
                  "response": {
                    "summary": "Without `fuzziness`",
                    "value": {
                      "sanctions": [
                        {
                          "id": "a1b2c3d4e5f60718",
                          "name": "IVAN PETROV",
                          "type": "individual",
                          "names": {
                            "full": "IVAN PETROV",
                            "last": "PETROV",
                            "first": "IVAN",
                            "third": "",
                            "father": "",
                            "middle": ""
                          },
                          "title": "",
                          "gender": null,
                          "aliases": [
                            "IWAN PIETROW",
                            "Ivan Petrov"
                          ],
                          "remarks": null,
                          "sources": [
                            {
                              "reason": "UKR",
                              "function": "Członek kierownictwa przedsiębiorstwa sektora obronnego.",
                              "organization": "Rada Unii Europejskiej"
                            }
                          ],
                          "addresses": [],
                          "passports": [
                            {
                              "info": "",
                              "type": "passport",
                              "number": "7512345678",
                              "country_code": "RU",
                              "country_name": ""
                            }
                          ],
                          "created_on": "2025-01-15T10:22:31.000+01:00",
                          "deleted_at": null,
                          "updated_on": "2026-09-30T08:05:12.000+02:00",
                          "birth_dates": [
                            {
                              "day": 21,
                              "date": "1970-05-21",
                              "year": 1970,
                              "month": 5
                            }
                          ],
                          "identifiers": [],
                          "reviewed_on": "2026-09-30T08:05:12.000+02:00",
                          "birth_places": [
                            {
                              "country_name": null,
                              "country_code": null,
                              "place": "Moskwa"
                            }
                          ],
                          "nationalities": [],
                          "deactivated_on": null
                        }
                      ]
                    }
                  },
                  "fuzziness": {
                    "summary": "With `fuzziness=70`",
                    "value": {
                      "sanctions": [
                        {
                          "id": "a1b2c3d4e5f60718",
                          "name": "IVAN PETROV",
                          "type": "individual",
                          "names": {
                            "full": "IVAN PETROV",
                            "last": "PETROV",
                            "first": "IVAN",
                            "third": "",
                            "father": "",
                            "middle": ""
                          },
                          "title": "",
                          "gender": null,
                          "aliases": [],
                          "remarks": null,
                          "sources": [
                            {
                              "reason": "UKR",
                              "function": "Członek kierownictwa przedsiębiorstwa sektora obronnego.",
                              "organization": "Rada Unii Europejskiej"
                            }
                          ],
                          "addresses": [],
                          "passports": [
                            {
                              "info": "",
                              "type": "passport",
                              "number": "7512345678",
                              "country_code": "RU",
                              "country_name": ""
                            }
                          ],
                          "created_on": "2025-01-15T10:22:31.000+01:00",
                          "deleted_at": null,
                          "updated_on": "2026-09-30T08:05:12.000+02:00",
                          "birth_dates": [],
                          "identifiers": [],
                          "reviewed_on": "2026-09-30T08:05:12.000+02:00",
                          "birth_places": [],
                          "nationalities": [],
                          "deactivated_on": null,
                          "match": {
                            "strict": true,
                            "similarity": 100
                          }
                        },
                        {
                          "id": "f9e8d7c6b5a40312",
                          "name": "IWAN PETROW",
                          "type": "individual",
                          "names": {
                            "full": "IWAN PETROW",
                            "last": "PETROW",
                            "first": "IWAN",
                            "third": "",
                            "father": "",
                            "middle": ""
                          },
                          "title": "",
                          "gender": null,
                          "aliases": [
                            "IVAN PETROFF"
                          ],
                          "remarks": null,
                          "sources": [
                            {
                              "reason": "BLR",
                              "function": "Funkcjonariusz aparatu państwowego.",
                              "organization": "Rada Unii Europejskiej"
                            }
                          ],
                          "addresses": [],
                          "passports": [],
                          "created_on": "2025-01-15T10:22:31.000+01:00",
                          "deleted_at": null,
                          "updated_on": "2026-09-30T08:05:12.000+02:00",
                          "birth_dates": [
                            {
                              "day": 2,
                              "date": "1968-11-02",
                              "year": 1968,
                              "month": 11
                            }
                          ],
                          "identifiers": [],
                          "reviewed_on": "2026-09-30T08:05:12.000+02:00",
                          "birth_places": [
                            {
                              "country_name": null,
                              "country_code": null,
                              "place": "Mińsk"
                            }
                          ],
                          "nationalities": [],
                          "deactivated_on": null,
                          "match": {
                            "strict": false,
                            "similarity": 71
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/sanction_lists": {
      "get": {
        "tags": [
          "Compliance & AML Databases"
        ],
        "summary": "retrieve available sanction lists",
        "description": "Returns the sanction lists available in the caller organization's group, each with an enabled flag indicating whether it is switched on in the organization's settings (and therefore searched by POST /scan). The source values match the codes returned in meta.sanction_sources of the POST /scan response. The endpoint is read-only and does not consume the request quota.",
        "operationId": "getSanctionLists",
        "parameters": [
          {
            "in": "header",
            "name": "Accept-Language",
            "description": "Language of the name field translations (pl, en). Defaults to pl.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sanction lists available to the organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SanctionListItem"
                  }
                },
                "examples": {
                  "response": {
                    "value": [
                      {
                        "source": "eu_fsf",
                        "name": "European Union Consolidated Financial Sanctions List (EU)",
                        "enabled": true
                      },
                      {
                        "source": "un_sc_sanctions",
                        "name": "Consolidated United Nations Security Council Sanctions List (ONZ)",
                        "enabled": false
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/knfs": {
      "get": {
        "tags": [
          "Compliance & AML Databases"
        ],
        "summary": "find a warning on the KNF Warning List",
        "description": "Searches the KNF public warnings list by person or entity name. Called without the name parameter, it returns all warnings.",
        "operationId": "findKnf",
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "description": "Person or entity name",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnfWarrning"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/eurobozon": {
      "get": {
        "tags": [
          "Compliance & AML Databases"
        ],
        "summary": "find a warning in the EURO-BOZON database",
        "description": "Searches the EURO-BOZON database (warnings published by foreign supervisory authorities) by entity name and returns matching records in the records array.",
        "operationId": "findEurobozon",
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "description": "Entity name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Eurobozon"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/countries": {
      "get": {
        "tags": [
          "Risk Sources & Specialist Lists"
        ],
        "summary": "list high-risk countries",
        "description": "Returns the full list of countries flagged with at least one AML risk category (FATF, tax risk, European Commission, corruption, Basel AML Index, terrorism sponsoring, etc.).",
        "operationId": "listCountries",
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "countries"
                  ],
                  "properties": {
                    "countries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Country"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/pkds": {
      "get": {
        "tags": [
          "Risk Sources & Specialist Lists"
        ],
        "summary": "list high-risk industries (PKD codes)",
        "description": "Returns the full list of PKD activity codes flagged as elevated AML risk.",
        "operationId": "listPkds",
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "pkds"
                  ],
                  "properties": {
                    "pkds": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Pkd"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/crypto_service_registry": {
      "get": {
        "tags": [
          "Risk Sources & Specialist Lists"
        ],
        "summary": "find an entity in the Virtual Currency Register",
        "description": "Searches the Virtual Currency Register by registry entry number, entity name, NIP or KRS and returns matching records in the records array.",
        "operationId": "findCryptoServiceRegistry",
        "parameters": [
          {
            "in": "query",
            "name": "registry_number",
            "description": "Registry entry number",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "description": "Entity name (partial match)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "nip",
            "description": "Tax ID (NIP)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "krs",
            "description": "Court registry number (KRS)",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CryptoServiceRegistry"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/hazard_domains": {
      "get": {
        "tags": [
          "Risk Sources & Specialist Lists"
        ],
        "summary": "find a domain in the Gambling Domains Register",
        "description": "Searches the Gambling Domains Register by domain name and returns matching records in the records array.",
        "operationId": "findHazardDomain",
        "parameters": [
          {
            "in": "query",
            "name": "domain",
            "description": "Domain name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HazardDomain"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/mica": {
      "get": {
        "tags": [
          "Risk Sources & Specialist Lists"
        ],
        "summary": "search the MiCA register",
        "description": "Searches the MiCA Interim Register using the same full-text search mechanism as the scanner. The q parameter is required. Results are grouped by register (emtwp, artzz, casps, other, ncasp) — the field set of each record depends on the register it belongs to. The endpoint consumes the request quota.",
        "operationId": "getMica",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "description": "Search term (e.g. entity name).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Accept-Language",
            "description": "Language of the name field translations (pl, en). Defaults to pl.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MiCA register records grouped by register",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MicaResponse"
                },
                "examples": {
                  "response": {
                    "value": {
                      "meta": {
                        "count": 1,
                        "term": "acme"
                      },
                      "records": {
                        "emtwp": [],
                        "artzz": [],
                        "casps": [
                          {
                            "register": "casps",
                            "ac_entityLegalName": "Acme sp. z o.o.",
                            "ac_serviceCode": [
                              "custody"
                            ]
                          }
                        ],
                        "other": [],
                        "ncasp": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MicaBadRequest"
                },
                "examples": {
                  "response": {
                    "value": {
                      "message": "The 'q' query parameter is required.",
                      "errors": [
                        "q is required"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation or limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/scan": {
      "post": {
        "tags": [
          "iAML Services"
        ],
        "summary": "Record Check – scan a person or entity",
        "description": "Scans a single company or a single person against all supported lists and registries — using only the data supplied in the request (the service does not look up data in external registries; in particular it does not fetch beneficial owners). The endpoint accepts two optional keys — companies, people:\n\n- companies → the company to scan, as a single-element array.\n- people → the person to scan, as a single-element array.\n\nProvide exactly one of them — either companies or people, but not both; each accepts at most one entry. Omitting both, providing both, or sending more than one entry returns 400. The response always has the ScanResponse shape with companies[]/persons[]/company_scans[]/person_scans[]/relationships[] arrays. The relationships[] array is currently always empty and will be populated from KRS data in the future.",
        "operationId": "scan",
        "parameters": [
          {
            "in": "header",
            "name": "Accept-Language",
            "description": "Language used to translate the message field (pl, en). Defaults to pl.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/scan/{scan_id}/pdf": {
      "post": {
        "tags": [
          "iAML Services"
        ],
        "summary": "Record Check – print the PDF report of a scan",
        "description": "Renders the PDF report of the scan identified by scan_id (meta.scan_id of the POST /scan response) and returns the PDF file itself. The request carries the scan's meta.scan_secret: the scan's results are stored encrypted with it, and iAML keeps no copy of the secret, so nobody without it (iAML included) can read them. Keep the secret with the scan_id for as long as you may need the report. The results stay stored for 30 minutes after the scan; after that the report can no longer be printed and the scan has to be run again. Every call renders the report anew; no PDF is stored. It is the report the iAML Scanner prints for a scan run there. The report language is inherited from the original POST /scan call (based on the Accept-Language header used at scan time) — it cannot be overridden here. Status code semantics:\n\n- 200: the PDF file.\n- 404: no scan with this scan_id and scan_secret — the scan_id is unknown, the secret does not match it, or the scan's results have expired.",
        "operationId": "printScanPdf",
        "parameters": [
          {
            "in": "path",
            "name": "scan_id",
            "description": "Scan identifier returned in meta.scan_id of the POST /scan response.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScanPdfRequest"
              },
              "examples": {
                "request": {
                  "value": {
                    "scan_secret": "q3W8vZ1x0kNfR2s9cD4hT6yB7mJ5pL1aE0uG3iK8oQw"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The PDF report",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                },
                "examples": {
                  "response": {
                    "value": {
                      "message": "Missing or invalid API key."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                },
                "examples": {
                  "response": {
                    "value": {
                      "message": "Your API key does not have access to this scan."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No scan with this scan_id and scan_secret, or its results have expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotFound"
                },
                "examples": {
                  "response": {
                    "value": {
                      "message": "No scan found for the provided scan_id and scan_secret, or its results have expired."
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/complex": {
      "post": {
        "tags": [
          "iAML Services"
        ],
        "summary": "Record Check – comprehensive database search",
        "description": "Checks the posted entity (person or company) against the PEP, RCA, sanction and KNF warning databases in a single request and returns per-list results in the entity object.",
        "operationId": "complex",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ComplexRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComplexResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/risk": {
      "get": {
        "tags": [
          "iAML Services"
        ],
        "summary": "Risk Engine – assess risk level",
        "description": "Assesses the risk level for a person or company name: a sanctions hit returns level 3 (unacceptable), a KNF warning level 2 (high), a PEP or RCA hit level 1 (significant), and no hits level 0 (low). The result is returned in the risk object with a Polish label.",
        "operationId": "assessRisk",
        "parameters": [
          {
            "in": "query",
            "name": "name",
            "description": "Person or company name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Risk"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          },
          "412": {
            "description": "Precondition Failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreconditionFailed"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    },
    "/risk2": {
      "get": {
        "tags": [
          "iAML Services"
        ],
        "summary": "Risk Engine – assess business risk level",
        "description": "Calculates a weighted business risk score from the country code, legal form, PKD code and product categories, and returns it in the sc field.",
        "operationId": "assessRisk2",
        "parameters": [
          {
            "in": "query",
            "name": "cc",
            "description": "Two-character country code",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "ec",
            "description": "Two-character legal form code",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "pc",
            "description": "PKD code",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "pc_version",
            "description": "PKD classification version for the pc parameter: 2007 or 2025 (default 2007)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "2007",
                "2025"
              ],
              "default": "2007"
            }
          },
          {
            "in": "query",
            "name": "rp",
            "description": "Product category",
            "required": true,
            "style": "form",
            "explode": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Risk2"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequest"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Unauthorized"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                }
              }
            }
          }
        },
        "security": [
          {
            "api_key": []
          }
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.aml.pl/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "X-Api-Key",
        "in": "header"
      }
    },
    "schemas": {
      "BadRequest": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "PreconditionFailed": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Unauthorized": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "Forbidden": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "ComplexRequest": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "origin_country": {
                "type": "string"
              },
              "operation_country": {
                "type": "string"
              },
              "pkds": {
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "string",
                      "description": "PKD code (e.g. \"62.01.Z\" or \"6201Z\")."
                    },
                    {
                      "type": "object",
                      "description": "A PKD code with its classification version.",
                      "required": [
                        "number"
                      ],
                      "properties": {
                        "number": {
                          "type": "string",
                          "description": "PKD code (e.g. \"62.01.Z\" or \"6201Z\")."
                        },
                        "version": {
                          "type": "string",
                          "enum": [
                            "2007",
                            "2025"
                          ],
                          "default": "2007",
                          "description": "PKD classification version: \"2007\" or \"2025\". Optional — when absent the code is treated as PKD 2007."
                        }
                      }
                    }
                  ]
                },
                "description": "The entity's PKD codes. An element is either a string (a PKD 2007 code, as before) or an object with number and version."
              },
              "id_number": {
                "type": "string"
              }
            }
          }
        }
      },
      "ComplexResponse": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "object",
            "properties": {
              "sanctions": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "boolean"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              },
              "pep": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "boolean"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              },
              "geo": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "boolean"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              },
              "pkd": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "boolean"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              },
              "knf": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "boolean"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              },
              "rca": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "boolean"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "VatWhiteList": {
        "type": "object",
        "properties": {
          "accountAssigned": {
            "type": "string"
          }
        }
      },
      "Risk": {
        "type": "object",
        "properties": {
          "risk": {
            "type": "object",
            "properties": {
              "pl": {
                "type": "string"
              },
              "lvl": {
                "type": "integer",
                "format": "int64"
              }
            }
          }
        }
      },
      "Risk2": {
        "type": "object",
        "properties": {
          "sc": {
            "type": "string"
          }
        }
      },
      "Beneficiary": {
        "type": "object",
        "properties": {
          "beneficiaries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "first_name": {
                  "type": "string"
                },
                "middle_names": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "last_name": {
                  "type": "string"
                },
                "pesel": {
                  "type": "string"
                },
                "birthday": {
                  "type": "string"
                },
                "citizenship": {
                  "type": "string"
                },
                "shares": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string"
                      },
                      "info": {
                        "type": "string"
                      },
                      "unit": {
                        "type": "string"
                      },
                      "amount": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "representatives": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "pesel": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "CompanyBeneficiary": {
        "type": "object",
        "properties": {
          "companies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "nip": {
                  "type": "string"
                },
                "krs": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "KnfWarrning": {
        "type": "object",
        "properties": {
          "info": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "number": {
            "type": "string"
          },
          "judgment": {
            "type": "string"
          },
          "prosecutor": {
            "type": "string"
          },
          "notification_type": {
            "type": "string"
          }
        }
      },
      "HazardDomain": {
        "type": "object",
        "properties": {
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "registry_number": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Registry entry number"
                },
                "domain": {
                  "type": "string",
                  "description": "Domain name"
                },
                "registered_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Registry entry date"
                }
              }
            }
          }
        }
      },
      "Eurobozon": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Entry identifier"
          },
          "company": {
            "type": "string",
            "description": "Entity name"
          },
          "otherCompanyNames": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Other entity names"
          },
          "country": {
            "type": "string",
            "description": "Country"
          },
          "warningTitle": {
            "type": "string",
            "description": "Warning title"
          },
          "regulatorName": {
            "type": "string",
            "description": "Regulator name"
          },
          "announcementDate": {
            "type": "string",
            "format": "date",
            "description": "Announcement date"
          }
        }
      },
      "CryptoServiceRegistry": {
        "type": "object",
        "properties": {
          "registry_number": {
            "type": "string",
            "description": "Registry entry number"
          },
          "name": {
            "type": "string",
            "description": "Entity name"
          },
          "krs": {
            "type": "string",
            "description": "Court registry number (KRS). The /scan response returns it in the canonical zero-padded 10-digit form (e.g. \"0000968535\"); GET /crypto_service_registry strips leading zeros (e.g. \"968535\")."
          },
          "nip": {
            "type": "string",
            "description": "Tax ID (NIP)"
          },
          "registration_date": {
            "type": "string",
            "format": "date",
            "description": "Registration date"
          },
          "services": {
            "type": "string",
            "description": "Services offered"
          }
        }
      },
      "Rca": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "names": {
            "type": "object",
            "properties": {
              "first": {
                "type": "string"
              },
              "last": {
                "type": "string"
              },
              "middle": {
                "type": "string"
              },
              "full": {
                "type": "string"
              },
              "third": {
                "type": "string"
              },
              "father": {
                "type": "string"
              }
            }
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "gender": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "remarks": {
            "type": "string"
          },
          "nationalities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "birth_places": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "place": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "birth_dates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "integer"
                },
                "date": {
                  "type": "string"
                },
                "year": {
                  "type": "integer"
                },
                "month": {
                  "type": "integer"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "address": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "passports": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "identifiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "pep": {
                  "type": "string"
                },
                "company": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "ex": {
                  "type": "boolean"
                },
                "since": {
                  "type": "string"
                },
                "to": {
                  "type": "string"
                },
                "clause": {
                  "type": "string"
                }
              }
            }
          },
          "decease_on": {
            "type": "string"
          },
          "created_on": {
            "type": "string"
          },
          "reviewed_on": {
            "type": "string"
          },
          "updated_on": {
            "type": "string"
          },
          "deleted_at": {
            "type": "string"
          },
          "deactivated_on": {
            "type": "string"
          },
          "match": {
            "type": "object",
            "description": "How the search found the record. Present only when `fuzziness` is sent.",
            "properties": {
              "strict": {
                "type": "boolean",
                "description": "Whether the strict search returned the record."
              },
              "similarity": {
                "type": "integer",
                "minimum": 50,
                "maximum": 100,
                "nullable": true,
                "description": "Fuzzy match similarity in percent, from the `fuzziness` sent up to `100`. `null` if fuzzy matching did not return the record."
              }
            }
          }
        }
      },
      "Person": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "names": {
            "type": "object",
            "properties": {
              "first": {
                "type": "string"
              },
              "last": {
                "type": "string"
              },
              "middle": {
                "type": "string"
              },
              "full": {
                "type": "string"
              },
              "third": {
                "type": "string"
              },
              "father": {
                "type": "string"
              }
            }
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "gender": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "remarks": {
            "type": "string"
          },
          "nationalities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "birth_places": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "place": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "birth_dates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "integer"
                },
                "date": {
                  "type": "string"
                },
                "year": {
                  "type": "integer"
                },
                "month": {
                  "type": "integer"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "address": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "passports": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "identifiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "organization": {
                  "type": "string"
                },
                "function": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "since": {
                  "type": "string"
                },
                "to": {
                  "type": "string"
                },
                "clause_url": {
                  "type": "string"
                }
              }
            }
          },
          "decease_on": {
            "type": "string"
          },
          "created_on": {
            "type": "string"
          },
          "reviewed_on": {
            "type": "string"
          },
          "updated_on": {
            "type": "string"
          },
          "deleted_at": {
            "type": "string"
          },
          "deactivated_on": {
            "type": "string"
          },
          "match": {
            "type": "object",
            "description": "How the search found the record. Present only when `fuzziness` is sent.",
            "properties": {
              "strict": {
                "type": "boolean",
                "description": "Whether the strict search returned the record."
              },
              "similarity": {
                "type": "integer",
                "minimum": 50,
                "maximum": 100,
                "nullable": true,
                "description": "Fuzzy match similarity in percent, from the `fuzziness` sent up to `100`. `null` if fuzzy matching did not return the record."
              }
            }
          }
        }
      },
      "Sanction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "names": {
            "type": "object",
            "properties": {
              "full": {
                "type": "string"
              },
              "last": {
                "type": "string"
              },
              "first": {
                "type": "string"
              },
              "third": {
                "type": "string"
              },
              "father": {
                "type": "string"
              },
              "middle": {
                "type": "string"
              }
            }
          },
          "title": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "remarks": {
            "type": "string"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "reason": {
                  "type": "string"
                },
                "function": {
                  "type": "string"
                },
                "organization": {
                  "type": "string"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "address": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "passports": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "created_on": {
            "type": "string"
          },
          "deleted_at": {
            "type": "string"
          },
          "updated_on": {
            "type": "string"
          },
          "birth_dates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "day": {
                  "type": "integer"
                },
                "date": {
                  "type": "string"
                },
                "year": {
                  "type": "integer"
                },
                "month": {
                  "type": "integer"
                }
              }
            }
          },
          "identifiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "info": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "reviewed_on": {
            "type": "string"
          },
          "birth_places": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "place": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "nationalities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": {
                  "type": "string"
                },
                "country_name": {
                  "type": "string"
                }
              }
            }
          },
          "deactivated_on": {
            "type": "string"
          },
          "match": {
            "type": "object",
            "description": "How the search found the record. Present only when `fuzziness` is sent.",
            "properties": {
              "strict": {
                "type": "boolean",
                "description": "Whether the strict search returned the record."
              },
              "similarity": {
                "type": "integer",
                "minimum": 50,
                "maximum": 100,
                "nullable": true,
                "description": "Fuzzy match similarity in percent, from the `fuzziness` sent up to `100`. `null` if fuzzy matching did not return the record."
              }
            }
          }
        }
      },
      "PersonInput": {
        "type": "object",
        "description": "Person data provided directly in the request — used as the scan subject (kind=person).",
        "required": [
          "full_name"
        ],
        "properties": {
          "full_name": {
            "type": "string",
            "description": "Full name (given name and surname)."
          },
          "identifiers": {
            "type": "array",
            "description": "Identifiers of the person.",
            "items": {
              "$ref": "#/components/schemas/PersonIdentifier"
            }
          },
          "birth_dates": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$"
            },
            "description": "Birth dates in ISO 8601 format. Partial dates are allowed: YYYY, YYYY-MM, YYYY-MM-DD. Multiple variants may be provided if the exact date is unknown."
          },
          "residence": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "description": "Countries of residence (ISO 3166-1 alpha-2)."
          },
          "citizenship": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "description": "Citizenships (ISO 3166-1 alpha-2)."
          }
        }
      },
      "PersonIdentifier": {
        "type": "object",
        "required": [
          "type",
          "value"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "PESEL"
            ],
            "description": "Type of person identifier. Currently supported: PESEL (PL — country may be omitted). Values such as SSN, passport or tax id may be added in the future."
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Country issuing the identifier (ISO 3166-1 alpha-2). Optional for type=PESEL (PL is assumed)."
          },
          "value": {
            "type": "string",
            "description": "Identifier value."
          }
        }
      },
      "CompanyIdentifier": {
        "type": "object",
        "required": [
          "type",
          "value"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Identifier type. Supported values: NIP (PL — country may be omitted), REGON (PL — country may be omitted), KRS (PL — country may be omitted), VAT_UE (EU VAT number — country is required). The field is open to new values in the future."
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Country issuing the identifier (ISO 3166-1 alpha-2). Required for type=VAT_UE, optional for type=NIP/REGON/KRS (PL is assumed)."
          },
          "value": {
            "type": "string",
            "description": "Identifier value."
          }
        }
      },
      "IndustryCode": {
        "type": "object",
        "required": [
          "type",
          "value"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "PKD"
            ],
            "description": "Industry classification. Currently supported: PKD (Polish Classification of Activities). Values such as NACE, NAICS, WZ may be added in the future."
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Classification country (ISO 3166-1 alpha-2). Optional for type=PKD (PL is assumed)."
          },
          "value": {
            "type": "string",
            "description": "Code in the chosen classification (e.g. 62.01.Z for PKD)."
          }
        }
      },
      "BankAccount": {
        "type": "object",
        "required": [
          "type",
          "value"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "IBAN"
            ],
            "description": "Account identifier format. Currently supported: IBAN. Values such as US_ACH, SWIFT/BIC may be added in the future."
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Account country (ISO 3166-1 alpha-2). Currently supported: PL."
          },
          "value": {
            "type": "string",
            "description": "Account number in the format specified by type (e.g. for IBAN: PL61109010140000071219812874)."
          }
        }
      },
      "CompanyInput": {
        "type": "object",
        "description": "Company data provided directly in the request — used as the scan subject (kind=company). The scan uses only this data; the service does not look up data in external registries.",
        "required": [
          "names"
        ],
        "properties": {
          "names": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "description": "Company names from the current one to the oldest. The first element is the current name, subsequent ones are historical names."
          },
          "identifiers": {
            "type": "array",
            "description": "Company identifiers (NIP, REGON, KRS, VAT_UE).",
            "items": {
              "$ref": "#/components/schemas/CompanyIdentifier"
            }
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "description": "Countries of registration / operation (ISO 3166-1 alpha-2)."
          },
          "address": {
            "type": "string",
            "description": "Address."
          },
          "industry_codes": {
            "type": "array",
            "description": "Company industry classification codes (e.g. PKD).",
            "items": {
              "$ref": "#/components/schemas/IndustryCode"
            }
          },
          "bank_accounts": {
            "type": "array",
            "description": "Company bank accounts (e.g. for VAT white list check).",
            "items": {
              "$ref": "#/components/schemas/BankAccount"
            }
          }
        }
      },
      "Country": {
        "type": "object",
        "description": "Country from the AML risk list — flags indicate categories under which the country was flagged. Each entry has at least one flag set to true.",
        "required": [
          "iso2"
        ],
        "properties": {
          "iso2": {
            "type": "string",
            "pattern": "^[a-z]{2}$",
            "description": "ISO 3166-1 alpha-2 country code (lowercase)."
          },
          "fatf": {
            "type": "boolean",
            "description": "Country is on the FATF (Financial Action Task Force) jurisdictions list."
          },
          "tax_risk": {
            "type": "boolean",
            "description": "Country classified as a tax risk jurisdiction."
          },
          "other_risks": {
            "type": "boolean",
            "description": "Country flagged with other, unspecified AML risk."
          },
          "european_commission": {
            "type": "boolean",
            "description": "Country on the European Commission high-risk third countries list."
          },
          "corruption": {
            "type": "boolean",
            "description": "Country flagged for corruption risk."
          },
          "basel_index": {
            "type": "boolean",
            "description": "Country flagged by the Basel AML Index."
          },
          "sponsoring_terrorism": {
            "type": "boolean",
            "description": "Country classified as a state sponsoring terrorism."
          },
          "unclassified": {
            "type": "boolean",
            "description": "Country has a risk not covered by the above categories."
          }
        }
      },
      "Pkd": {
        "type": "object",
        "description": "PKD code (Polish Classification of Activities) flagged as elevated AML risk.",
        "required": [
          "number",
          "version",
          "description"
        ],
        "properties": {
          "number": {
            "type": "string",
            "description": "PKD code (e.g. \"62.01.Z\")."
          },
          "version": {
            "type": "string",
            "enum": [
              "2007",
              "2025"
            ],
            "description": "PKD classification version the code belongs to: \"2007\" or \"2025\". The same symbol (e.g. 6020Z) may exist in both versions under a different name."
          },
          "description": {
            "type": "string",
            "description": "Activity description."
          }
        }
      },
      "ScanRequest": {
        "type": "object",
        "description": "Request body for POST /scan. Two optional keys: companies, people. Provide exactly one of them — either a single company or a single person, but not both (enforced by the API; OpenAPI 2.0 cannot express the either/or rule in the schema). Each key is an array of at most one entry; the array shape is kept for forward compatibility. The scan uses only the provided data, with no lookup in external registries (in particular it does not fetch beneficial owners). Omitting both, providing both, or sending more than one entry returns 400.",
        "properties": {
          "companies": {
            "type": "array",
            "maxItems": 1,
            "description": "The company to scan, as a single-element array. Mutually exclusive with people.",
            "items": {
              "$ref": "#/components/schemas/CompanyInput"
            }
          },
          "people": {
            "type": "array",
            "maxItems": 1,
            "description": "The person to scan, as a single-element array. Mutually exclusive with companies.",
            "items": {
              "$ref": "#/components/schemas/PersonInput"
            }
          }
        }
      },
      "ScanBucketBase": {
        "type": "object",
        "description": "Common fields shared by every bucket in a /scan response. Concrete buckets (SanctionBucket, PepBucket, …) extend this schema with a records field typed to the bucket's specific record. A bucket is always present in the response — records may be empty.",
        "required": [
          "terms",
          "status",
          "outcome",
          "match_count",
          "message"
        ],
        "properties": {
          "terms": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Values used to search this particular list (different lists may be searched with different expressions — e.g. names, NIP numbers, PKD codes)."
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "not_checked",
              "not_applicable",
              "error"
            ],
            "description": "Machine-readable status of the check execution (whether it happened at all): ok (checked), not_checked (service unavailable in the plan), not_applicable (no input data for this list), error (source error)."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "clear",
              "match",
              "skipped",
              "error"
            ],
            "description": "Machine-readable outcome (whether there are any matches): clear (checked, no matches), match (checked, has matches), skipped (not checked — status=not_checked|not_applicable), error (status=error)."
          },
          "match_count": {
            "type": "integer",
            "description": "Number of matches (equal to records.length). Useful for summaries and webhooks without parsing records."
          },
          "message": {
            "type": "string",
            "description": "User-facing message — translated according to the Accept-Language header."
          }
        }
      },
      "SanctionCryptoWallet": {
        "type": "object",
        "description": "A crypto wallet linked to a sanction record.",
        "properties": {
          "currency": {
            "type": "string",
            "description": "Currency code (e.g. BTC, ETH)."
          },
          "public_key": {
            "type": "string",
            "description": "Public key / wallet address."
          },
          "topics": {
            "type": "string",
            "description": "Wallet topics / tags."
          }
        }
      },
      "SanctionIdentification": {
        "type": "object",
        "description": "An identification document (passport, ID card, etc.) linked to a sanction record.",
        "properties": {
          "country": {
            "type": "string",
            "description": "Issuing country."
          },
          "identification_type": {
            "type": "string",
            "description": "Document type."
          },
          "number": {
            "type": "string",
            "description": "Document number."
          },
          "start_date": {
            "type": "string",
            "description": "Issue date."
          },
          "end_date": {
            "type": "string",
            "description": "Expiry date."
          },
          "authority": {
            "type": "string",
            "description": "Issuing authority."
          },
          "summary": {
            "type": "string",
            "description": "Summary."
          }
        }
      },
      "SanctionFlatConnection": {
        "type": "object",
        "description": "Flat link to another element from the full-sanction schema: a descriptive role label and the linked element's source_id.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Connection description (e.g. \"director of organization\")."
          },
          "source_id": {
            "type": "string",
            "description": "Source identifier of the linked element."
          }
        }
      },
      "FullSanctionRecord": {
        "type": "object",
        "description": "Sanction record in the /scan response, in the flat \"full sanction\" schema (matching the bulk data dump from iaml-pep-manager). Array fields group every value variant for the record (e.g. names, aliases). Internal database identifiers (integer id, old_id) are not exposed — source_id identifies the record. Array fields are null when no value is present.",
        "required": [
          "source_id",
          "sanction_type",
          "db_created",
          "db_updated"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Source (sanctions list) name."
          },
          "source_id": {
            "type": "string",
            "description": "Record identifier within the source."
          },
          "sanction_type": {
            "type": "string",
            "description": "Entity/sanction type (e.g. Person, Organization, Company, Vessel)."
          },
          "reason": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Reasons for the sanction (null when none)."
          },
          "sanction_source_url": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sanction source URLs (null when none)."
          },
          "provisions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sanction provisions (null when none)."
          },
          "authority_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Reference number(s) assigned by the issuing authority: either the entry number on the sanctions list (e.g. OFAC ent_num \"23845\", EU FSF \"EU.13592.53\") or a reference to the legal act behind the listing (e.g. \"88 FR 13675\"). Format is source-specific and not normalized; may contain several values. Present only for some sources (null when none)."
          },
          "name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Entity names (null when none)."
          },
          "alias": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Aliases (null when none)."
          },
          "weak_alias": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Weak aliases (null when none)."
          },
          "father_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Father's name (null when none)."
          },
          "gender": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Gender (null when none)."
          },
          "birth_date": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Birth dates (null when none)."
          },
          "birth_place": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Birth places (null when none)."
          },
          "birth_country": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Birth countries (null when none)."
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional notes (null when none)."
          },
          "website": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Websites (null when none)."
          },
          "tax_number": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tax numbers (null when none)."
          },
          "registration_number": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Registration numbers (null when none)."
          },
          "country": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Countries (null when none)."
          },
          "source_url": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Record source URLs (null when none)."
          },
          "inn_code": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "INN codes (null when none)."
          },
          "kpp_code": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "KPP codes (null when none)."
          },
          "legal_form": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legal form (null when none)."
          },
          "jurisdiction": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Jurisdiction (null when none)."
          },
          "type": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Entity type (null when none)."
          },
          "call_sign": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Call sign (null when none)."
          },
          "gross_registered_tonnage": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Gross registered tonnage (null when none)."
          },
          "model": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Model (null when none)."
          },
          "build_date": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Build date (null when none)."
          },
          "serial_number": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Serial number (null when none)."
          },
          "address": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Addresses."
          },
          "crypto_wallet": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SanctionCryptoWallet"
            },
            "description": "Crypto wallets."
          },
          "identification": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SanctionIdentification"
            },
            "description": "Identification documents."
          },
          "additional_info": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional information (null when none)."
          },
          "connection": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SanctionFlatConnection"
            },
            "description": "Links to other entities (descriptive label + the linked element's source_id)."
          },
          "end_date": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Sanction end date (null when none)."
          },
          "db_created": {
            "type": "string",
            "description": "Timestamp when the record was created in the database (UTC, format YYYY-MM-DD HH:MM:SS)."
          },
          "db_updated": {
            "type": "string",
            "description": "Timestamp of the last database update (UTC, format YYYY-MM-DD HH:MM:SS)."
          },
          "db_deleted": {
            "type": "string",
            "description": "Timestamp when the record was deleted in the database (null when the record is active)."
          }
        }
      },
      "SanctionConnection": {
        "type": "object",
        "description": "A link between a sanction record and another entity (connection-graph edge). Specific to /scan — not present in GET /sanctions.",
        "required": [
          "relation",
          "role",
          "id",
          "sanctioned"
        ],
        "properties": {
          "relation": {
            "type": "string",
            "enum": [
              "directorship",
              "ownership",
              "membership",
              "representation",
              "unknownlink",
              "family",
              "security"
            ],
            "description": "Kind of link."
          },
          "role": {
            "type": "string",
            "description": "Role of the linked entity within the relation (e.g. director, organization, owner, member, agent, client, person, relative, issuer, isin)."
          },
          "id": {
            "type": "string",
            "description": "Identifier of the linked entity."
          },
          "sanctioned": {
            "type": "boolean",
            "description": "Whether the linked entity is itself on a sanctions list."
          },
          "record": {
            "$ref": "#/components/schemas/FullSanctionRecord"
          },
          "name": {
            "type": "string",
            "description": "Name of the linked entity (present when sanctioned=false)."
          }
        }
      },
      "ScanSanction": {
        "description": "Sanction record in the /scan response — the flat full-sanction record (FullSanctionRecord) extended with connections (the connection graph, with embedded sanction records). GET /sanctions returns the older Sanction format instead.",
        "allOf": [
          {
            "$ref": "#/components/schemas/FullSanctionRecord"
          },
          {
            "type": "object",
            "required": [
              "connections"
            ],
            "properties": {
              "connections": {
                "type": "array",
                "description": "Connection graph of this record to other entities (empty array when there are none). Enriches the flat connection field with role, sanctioned flag and the embedded linked record.",
                "items": {
                  "$ref": "#/components/schemas/SanctionConnection"
                }
              }
            }
          }
        ]
      },
      "SanctionBucket": {
        "description": "Sanctions bucket — records are entries from sanctions lists (EU/US/UN/PL).",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ScanSanction"
                }
              }
            }
          }
        ]
      },
      "PepRcaPerson": {
        "type": "object",
        "description": "Shared PEP/RCA record fields in the /scan response, matching the peps[]/rcas[] item shape of the iaml-pep-manager daily full-list dump. Internal-only fields (type, title, remarks, addresses, passports, match_score) are not exposed. GET /peps and /rcas return the older Person/Rca format instead.",
        "required": [
          "id",
          "names",
          "db_created",
          "db_updated"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Record identifier in the PEP/RCA database."
          },
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Known names for the person (primary name and aliases)."
          },
          "gender": {
            "type": "string",
            "description": "Gender of the person (omitted when unknown)."
          },
          "identifiers": {
            "type": "array",
            "description": "Identification documents.",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                }
              }
            }
          },
          "nationality": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Nationalities as ISO 3166-1 alpha-2 country codes (null when none)."
          },
          "birth_place": {
            "type": "object",
            "description": "Place of birth (null when unknown).",
            "properties": {
              "place": {
                "type": "string"
              },
              "country_code": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 country code."
              }
            }
          },
          "birth_date": {
            "type": "object",
            "description": "Date of birth; each part is null when unknown.",
            "properties": {
              "year": {
                "type": "integer"
              },
              "month": {
                "type": "integer"
              },
              "day": {
                "type": "integer"
              }
            }
          },
          "decease_on": {
            "type": "string",
            "description": "Date of decease, YYYY-MM-DD (null when not deceased)."
          },
          "deactivated_on": {
            "type": "string",
            "description": "Date of deactivation, YYYY-MM-DD (null when active)."
          },
          "old_id": {
            "type": "integer",
            "description": "Legacy record id from the record_ids table (null when none)."
          },
          "db_created": {
            "type": "string",
            "description": "Timestamp when the record was created in the database."
          },
          "db_updated": {
            "type": "string",
            "description": "Timestamp of the last database update."
          },
          "db_deleted": {
            "type": "string",
            "description": "Timestamp when the record was deleted in the database (null when the record is active)."
          }
        }
      },
      "ScanPep": {
        "description": "PEP record in the /scan response — the shared person fields (PepRcaPerson) extended with the sources confirming PEP status. GET /peps returns the older Person format instead.",
        "allOf": [
          {
            "$ref": "#/components/schemas/PepRcaPerson"
          },
          {
            "type": "object",
            "required": [
              "sources"
            ],
            "properties": {
              "sources": {
                "type": "array",
                "description": "Sources confirming PEP status.",
                "items": {
                  "type": "object",
                  "required": [
                    "organization",
                    "function",
                    "reason"
                  ],
                  "properties": {
                    "organization": {
                      "type": "string"
                    },
                    "function": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "since": {
                      "type": "string",
                      "description": "Start date, YYYY-MM-DD (null when none)."
                    },
                    "to": {
                      "type": "string",
                      "description": "End date, YYYY-MM-DD (null when none)."
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "ScanRca": {
        "description": "RCA record in the /scan response — the shared person fields (PepRcaPerson) extended with the related PEPs. GET /rcas returns the older Rca format instead.",
        "allOf": [
          {
            "$ref": "#/components/schemas/PepRcaPerson"
          },
          {
            "type": "object",
            "required": [
              "related_peps"
            ],
            "properties": {
              "related_peps": {
                "type": "array",
                "description": "Related politically exposed persons.",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "name",
                    "type",
                    "company"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "Identifier of the related PEP."
                    },
                    "name": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "description": "Type of relationship."
                    },
                    "company": {
                      "type": "string"
                    },
                    "since": {
                      "type": "string",
                      "description": "Relationship start date, YYYY-MM-DD (null when none)."
                    },
                    "to": {
                      "type": "string",
                      "description": "Relationship end date, YYYY-MM-DD (null when none)."
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "PepBucket": {
        "description": "PEP bucket — records are entries from the politically exposed persons list.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ScanPep"
                }
              }
            }
          }
        ]
      },
      "RcaBucket": {
        "description": "Bucket of PEP associates (RCA) — records are entries from the RCA list.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ScanRca"
                }
              }
            }
          }
        ]
      },
      "KnfBucket": {
        "description": "KNF bucket — records are entries from the Polish Financial Supervision Authority public warning list.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/KnfWarrning"
                }
              }
            }
          }
        ]
      },
      "BozonBucket": {
        "description": "Euro-bozon bucket — records are entries from the Euro-bozon warning list.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Eurobozon"
                }
              }
            }
          }
        ]
      },
      "CountryBucket": {
        "description": "Risk countries bucket — records are entries from the list of countries flagged with at least one AML risk category (matched against a person's citizenship/residence or a company's countries).",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Country"
                }
              }
            }
          }
        ]
      },
      "IndustryCodeMatch": {
        "type": "object",
        "description": "A single match in the industry_code bucket. Carries the classification context (type + country) so the consumer can tell e.g. Polish PKD from future classifications (NACE/NAICS) — even though concrete code values may look similar.",
        "required": [
          "type",
          "country",
          "value",
          "description"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "PKD"
            ],
            "description": "Classification the code belongs to. Currently supported: PKD. Values such as NACE, NAICS, WZ may be added in the future — matches IndustryCode.type."
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Classification country (ISO 3166-1 alpha-2). Lets the consumer disambiguate the same number across different national classifications."
          },
          "value": {
            "type": "string",
            "description": "The matched code value (e.g. \"62.01.Z\")."
          },
          "description": {
            "type": "string",
            "description": "Human-readable activity description for the code — in the language indicated by Accept-Language when a translation is available."
          }
        }
      },
      "IndustryCodeBucket": {
        "description": "Risk industry codes bucket — records are the specific codes (e.g. PKD) that were matched. Each record carries classification context (type + country), since different countries may use their own classifications.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/IndustryCodeMatch"
                }
              }
            }
          }
        ]
      },
      "VatWhiteListBucket": {
        "description": "VAT white list bucket — records are entries from the VAT taxpayers white list.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/VatWhiteList"
                }
              }
            }
          }
        ]
      },
      "CryptoServiceRegistryBucket": {
        "description": "Virtual Currency Activity Registry bucket — records are entries from the registry.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ScanBucketBase"
          },
          {
            "type": "object",
            "required": [
              "records"
            ],
            "properties": {
              "records": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CryptoServiceRegistry"
                }
              }
            }
          }
        ]
      },
      "ScanMeta": {
        "type": "object",
        "description": "Summary of the whole response — one place where the client can read whether it is worth looking further into results / person_scans. Counters aggregate results across all scan subjects (the company + all persons).",
        "required": [
          "scan_id",
          "scan_secret",
          "checked_at",
          "report_date",
          "subject",
          "outcome",
          "buckets",
          "matches",
          "matched_subjects",
          "sanction_sources"
        ],
        "properties": {
          "scan_id": {
            "type": "string",
            "description": "Stable identifier for this scan. Lets the caller refer back to this response in later API calls — e.g. to print its PDF report (POST /scan/{scan_id}/pdf), together with scan_secret."
          },
          "scan_secret": {
            "type": "string",
            "description": "Secret the scan's results are stored encrypted with, required to print its PDF report (POST /scan/{scan_id}/pdf). iAML keeps no copy of it: a lost secret cannot be recovered, and the report can then no longer be printed. Treat it like a password."
          },
          "checked_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the scan execution (ISO 8601 / RFC 3339)."
          },
          "report_date": {
            "type": "string",
            "format": "date",
            "description": "Date the report data reflects (\"data as of\"). Currently the day before the scan was executed (ISO 8601, YYYY-MM-DD)."
          },
          "subject": {
            "type": "object",
            "required": [
              "kind",
              "id"
            ],
            "description": "The subject the caller asked about. Other entities in the response (companies/persons) are context (relationships, depth=1).",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "company",
                  "person"
                ],
                "description": "Kind of the queried subject — derived from which key was provided in the request (company → company, person → person)."
              },
              "id": {
                "type": "string",
                "description": "Identifier of the subject within this response — points to an entry in companies[] or persons[]."
              }
            }
          },
          "outcome": {
            "type": "string",
            "enum": [
              "clear",
              "match",
              "partial",
              "error"
            ],
            "description": "Overall machine-readable verdict: clear (all checked lists with no matches), match (at least one list returned a match), partial (no matches, but some lists were not checked — e.g. plan, missing data), error (at least one list ended with an error)."
          },
          "buckets": {
            "type": "object",
            "required": [
              "checked",
              "matched",
              "skipped",
              "failed"
            ],
            "description": "Bucket counters by status/outcome — summed across all scan subjects.",
            "properties": {
              "checked": {
                "type": "integer",
                "description": "Number of buckets with status=ok (regardless of outcome)."
              },
              "matched": {
                "type": "integer",
                "description": "Number of buckets with outcome=match."
              },
              "skipped": {
                "type": "integer",
                "description": "Number of buckets with status=not_checked|not_applicable."
              },
              "failed": {
                "type": "integer",
                "description": "Number of buckets with status=error."
              }
            }
          },
          "matches": {
            "type": "object",
            "description": "Total match counts per bucket (key = bucket name, value = match_count summed across all subjects). Contains only buckets with matches. Lets the client quickly judge the weight of the alert — a hit in sanction weighs differently than one in industry_code — without iterating over results.",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "matched_subjects": {
            "type": "array",
            "description": "List of subjects (companies and/or persons) that contributed matches. Lets the client point at a specific person/company without iterating over company_scans/person_scans. Empty when outcome=clear.",
            "items": {
              "type": "object",
              "required": [
                "kind",
                "id",
                "matches"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "company",
                    "person"
                  ],
                  "description": "Kind of the subject the matches refer to."
                },
                "id": {
                  "type": "string",
                  "description": "Identifier of the subject (matches companies[].id or persons[].id)."
                },
                "matches": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "integer"
                  },
                  "description": "Map bucket → match_count for this specific subject."
                }
              }
            }
          },
          "sanction_sources": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Source codes of the sanction lists actually searched in this scan. Empty array when the sanction scan did not run."
          }
        }
      },
      "ScanPdfRequest": {
        "type": "object",
        "description": "Body of POST /scan/{scan_id}/pdf.",
        "required": [
          "scan_secret"
        ],
        "properties": {
          "scan_secret": {
            "type": "string",
            "description": "The secret returned in meta.scan_secret of the POST /scan response."
          }
        }
      },
      "PersonScanResults": {
        "type": "object",
        "description": "Result of person checks — each bucket is a different list/registry. Links to other companies (e.g. those where the person is a beneficial owner) are not here — they are represented by relationships and entries in companies[] / company_scans[] at the ScanResponse level.",
        "required": [
          "sanction",
          "pep",
          "rca",
          "knf",
          "bozon",
          "country"
        ],
        "properties": {
          "sanction": {
            "$ref": "#/components/schemas/SanctionBucket"
          },
          "pep": {
            "$ref": "#/components/schemas/PepBucket"
          },
          "rca": {
            "$ref": "#/components/schemas/RcaBucket"
          },
          "knf": {
            "$ref": "#/components/schemas/KnfBucket"
          },
          "bozon": {
            "$ref": "#/components/schemas/BozonBucket"
          },
          "country": {
            "$ref": "#/components/schemas/CountryBucket"
          }
        }
      },
      "CompanyScanResults": {
        "type": "object",
        "description": "Result of company checks — each bucket is a different list/registry. The company's beneficial owners are not a bucket — they are represented by relationships and entries in persons[] / person_scans[] at the ScanResponse level.",
        "required": [
          "sanction",
          "knf",
          "bozon",
          "country",
          "industry_code",
          "vat_white_list",
          "crypto_service_registry"
        ],
        "properties": {
          "sanction": {
            "$ref": "#/components/schemas/SanctionBucket"
          },
          "knf": {
            "$ref": "#/components/schemas/KnfBucket"
          },
          "bozon": {
            "$ref": "#/components/schemas/BozonBucket"
          },
          "country": {
            "$ref": "#/components/schemas/CountryBucket"
          },
          "industry_code": {
            "$ref": "#/components/schemas/IndustryCodeBucket"
          },
          "vat_white_list": {
            "$ref": "#/components/schemas/VatWhiteListBucket"
          },
          "crypto_service_registry": {
            "$ref": "#/components/schemas/CryptoServiceRegistryBucket"
          }
        }
      },
      "ScanPerson": {
        "type": "object",
        "description": "Person — entity appearing in a /scan response (either the queried subject or a related entity, e.g. a beneficial owner). The person scan result itself is not here, but in person_scans (key: id). Separate schema from Person (the PEP list entry).",
        "required": [
          "id",
          "full_name",
          "identifiers",
          "birth_dates",
          "citizenship",
          "residence"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Person identifier unique within this response. Used for correlation with person_scans, relationships and meta.matched_subjects."
          },
          "full_name": {
            "type": "string",
            "description": "Given name and surname (same form as full_name in the request)."
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PersonIdentifier"
            }
          },
          "birth_dates": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$"
            },
            "description": "Birth dates (ISO 8601, partial dates allowed: YYYY, YYYY-MM, YYYY-MM-DD)."
          },
          "citizenship": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            }
          },
          "residence": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            }
          }
        }
      },
      "ScanCompany": {
        "type": "object",
        "description": "Company — entity appearing in a /scan response (either the queried subject or a related entity, e.g. a company where the scanned person is a beneficial owner). The company scan result itself is not here, but in company_scans (key: id).",
        "required": [
          "id",
          "names",
          "identifiers",
          "countries",
          "industry_codes",
          "bank_accounts"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Company identifier unique within this response. Used for correlation with company_scans, relationships and meta.matched_subjects."
          },
          "names": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "description": "Company names from the current one to the oldest. The first element is the current name, subsequent ones are historical names."
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyIdentifier"
            }
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string",
              "pattern": "^[A-Z]{2}$"
            },
            "description": "Countries of registration / operation (ISO 3166-1 alpha-2)."
          },
          "address": {
            "type": "string",
            "description": "Company address (optional — may not be available)."
          },
          "industry_codes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IndustryCode"
            }
          },
          "bank_accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BankAccount"
            }
          }
        }
      },
      "PersonScanEntry": {
        "type": "object",
        "description": "Scan result of a single person in the context of the shared response. meta for this person is aggregated at the root ScanResponse.meta — only buckets in results live here.",
        "required": [
          "person_id",
          "results"
        ],
        "properties": {
          "person_id": {
            "type": "string",
            "description": "Correlation key with persons[].id."
          },
          "results": {
            "$ref": "#/components/schemas/PersonScanResults"
          }
        }
      },
      "CompanyScanEntry": {
        "type": "object",
        "description": "Scan result of a single company in the context of the shared response. meta for this company is aggregated at the root ScanResponse.meta — only buckets in results live here.",
        "required": [
          "company_id",
          "results"
        ],
        "properties": {
          "company_id": {
            "type": "string",
            "description": "Correlation key with companies[].id."
          },
          "results": {
            "$ref": "#/components/schemas/CompanyScanResults"
          }
        }
      },
      "Relationship": {
        "type": "object",
        "description": "Relationship between a person and a company. Currently supported: beneficiary_of (the person is a beneficial owner of the company). In the future, e.g. representative_of may be added.",
        "required": [
          "kind",
          "person_id",
          "company_id"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "beneficiary_of"
            ],
            "description": "Kind of relationship."
          },
          "person_id": {
            "type": "string",
            "description": "Correlation key with persons[].id."
          },
          "company_id": {
            "type": "string",
            "description": "Correlation key with companies[].id."
          },
          "role": {
            "type": "string",
            "description": "Role in the company (e.g. shareholder, board member) — specific to kind=beneficiary_of."
          },
          "share": {
            "type": "string",
            "description": "Share or number of shares (string, as per CRBR format, e.g. \"55%\") — specific to kind=beneficiary_of."
          }
        }
      },
      "ScanResponse": {
        "type": "object",
        "description": "Response of POST /scan. Contains a graph of entities (companies and persons), scan results and the relationships between them. meta.subject indicates the entity the caller asked about. Current depth: 1 (we scan the subject + its direct relationships). A request parameter controlling depth may be added in the future.",
        "required": [
          "meta",
          "companies",
          "persons",
          "company_scans",
          "person_scans",
          "relationships"
        ],
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/ScanMeta"
          },
          "companies": {
            "type": "array",
            "description": "All companies in the response (the queried one + related ones). Each has a unique id within this response.",
            "items": {
              "$ref": "#/components/schemas/ScanCompany"
            }
          },
          "persons": {
            "type": "array",
            "description": "All persons in the response (the queried one or related, e.g. beneficial owners of the queried company). Each has a unique id within this response.",
            "items": {
              "$ref": "#/components/schemas/ScanPerson"
            }
          },
          "company_scans": {
            "type": "array",
            "description": "Scan results for companies for which a check was performed (usually only the queried subject at the current depth). Correlation key: company_id.",
            "items": {
              "$ref": "#/components/schemas/CompanyScanEntry"
            }
          },
          "person_scans": {
            "type": "array",
            "description": "Scan results for persons for which a check was performed. Correlation key: person_id.",
            "items": {
              "$ref": "#/components/schemas/PersonScanEntry"
            }
          },
          "relationships": {
            "type": "array",
            "description": "Relationships between companies and persons (graph edges). Always present — empty array if no relationships were found.",
            "items": {
              "$ref": "#/components/schemas/Relationship"
            }
          }
        }
      },
      "SanctionListItem": {
        "type": "object",
        "description": "A single sanction list available in the organization's group, together with whether the organization has it enabled.",
        "required": [
          "source",
          "name",
          "enabled"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "Source code of the sanction list. The same code appears in meta.sanction_sources of the POST /scan response."
          },
          "name": {
            "type": "string",
            "description": "Translated name of the sanction list (language per the Accept-Language header)."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the list is enabled in the organization's settings and therefore included in scans."
          }
        }
      },
      "NotFound": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      },
      "MicaBadRequest": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "MicaEmtRecord": {
        "type": "object",
        "properties": {
          "register": {
            "type": "string",
            "enum": [
              "emtwp"
            ],
            "description": "EMT — e-money token issuer."
          },
          "competent_authority": {
            "type": "string",
            "description": "Competent Authority."
          },
          "home_member_state": {
            "type": "string",
            "description": "Home Member State."
          },
          "name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legal name of the issuer/entity."
          },
          "lei": {
            "type": "string",
            "description": "LEI."
          },
          "national_code": {
            "type": "string",
            "description": "National code."
          },
          "commercial_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Commercial or trading names."
          },
          "address": {
            "type": "string",
            "description": "Address."
          },
          "website": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Website."
          },
          "authorisation_date": {
            "type": "string",
            "description": "Authorisation date (dd/mm/yyyy)."
          },
          "withdrawal_date": {
            "type": "string",
            "description": "Withdrawal date (dd/mm/yyyy)."
          },
          "exemption_48_4": {
            "type": "string",
            "description": "Exemption under Article 48(4)."
          },
          "exemption_48_5": {
            "type": "string",
            "description": "Exemption under Article 48(5)."
          },
          "authorisation_type": {
            "type": "string",
            "description": "Authorised as."
          },
          "dti_ffg": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DTI FFG codes (ISO 24165)."
          },
          "dti": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DTI codes (ISO 24165)."
          },
          "white_paper_url": {
            "type": "string",
            "description": "White paper."
          },
          "offer_start_date": {
            "type": "string",
            "description": "Start date of the offer to the public or admission to trading (dd/mm/yyyy)."
          },
          "comments": {
            "type": "string",
            "description": "Comments."
          },
          "last_update": {
            "type": "string",
            "description": "Last update (dd/mm/yyyy)."
          }
        }
      },
      "MicaArtRecord": {
        "type": "object",
        "properties": {
          "register": {
            "type": "string",
            "enum": [
              "artzz"
            ],
            "description": "ART — asset-referenced token issuer."
          },
          "competent_authority": {
            "type": "string",
            "description": "Competent Authority."
          },
          "home_member_state": {
            "type": "string",
            "description": "Home Member State."
          },
          "name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legal name of the issuer/entity."
          },
          "lei": {
            "type": "string",
            "description": "LEI."
          },
          "national_code": {
            "type": "string",
            "description": "National code."
          },
          "commercial_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Commercial or trading names."
          },
          "address": {
            "type": "string",
            "description": "Address."
          },
          "website": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Website."
          },
          "authorisation_date": {
            "type": "string",
            "description": "Authorisation date (dd/mm/yyyy)."
          },
          "withdrawal_date": {
            "type": "string",
            "description": "Withdrawal date (dd/mm/yyyy)."
          },
          "credit_institution": {
            "type": "string",
            "description": "Credit institution."
          },
          "dti_ffg": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DTI FFG codes (ISO 24165)."
          },
          "dti": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DTI codes (ISO 24165)."
          },
          "white_paper_url": {
            "type": "string",
            "description": "White paper."
          },
          "offer_start_date": {
            "type": "string",
            "description": "Start date of the offer to the public or admission to trading (dd/mm/yyyy)."
          },
          "offer_countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Offer countries."
          },
          "comments": {
            "type": "string",
            "description": "Comments."
          },
          "last_update": {
            "type": "string",
            "description": "Last update (dd/mm/yyyy)."
          }
        }
      },
      "MicaCaspRecord": {
        "type": "object",
        "properties": {
          "register": {
            "type": "string",
            "enum": [
              "casps"
            ],
            "description": "CASP — crypto-asset service provider."
          },
          "competent_authority": {
            "type": "string",
            "description": "Competent Authority."
          },
          "home_member_state": {
            "type": "string",
            "description": "Home Member State."
          },
          "name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legal name of the issuer/entity."
          },
          "lei": {
            "type": "string",
            "description": "LEI."
          },
          "national_code": {
            "type": "string",
            "description": "National code."
          },
          "commercial_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Commercial or trading names."
          },
          "address": {
            "type": "string",
            "description": "Address."
          },
          "website": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Website."
          },
          "trading_platform_website": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Trading platform."
          },
          "authorisation_date": {
            "type": "string",
            "description": "Authorisation date (dd/mm/yyyy)."
          },
          "withdrawal_date": {
            "type": "string",
            "description": "Withdrawal date (dd/mm/yyyy)."
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "custody",
                "trading_platform",
                "crypto_to_funds",
                "crypto_to_crypto",
                "order_execution",
                "placement",
                "order_routing",
                "advisory",
                "portfolio_management",
                "transfer"
              ]
            },
            "description": "Services."
          },
          "service_countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Service countries."
          },
          "comments": {
            "type": "string",
            "description": "Comments."
          },
          "last_update": {
            "type": "string",
            "description": "Last update (dd/mm/yyyy)."
          }
        }
      },
      "MicaOtherRecord": {
        "type": "object",
        "properties": {
          "register": {
            "type": "string",
            "enum": [
              "other"
            ],
            "description": "Other crypto-asset (white paper)."
          },
          "competent_authority": {
            "type": "string",
            "description": "Competent Authority."
          },
          "home_member_state": {
            "type": "string",
            "description": "Home Member State."
          },
          "name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legal name of the issuer/entity."
          },
          "lei": {
            "type": "string",
            "description": "LEI."
          },
          "national_code": {
            "type": "string",
            "description": "National code."
          },
          "casp_name": {
            "type": "string",
            "description": "CASP name."
          },
          "casp_lei": {
            "type": "string",
            "description": "CASP LEI."
          },
          "offer_countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Offer countries."
          },
          "dti_ffg": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DTI FFG codes (ISO 24165)."
          },
          "dti": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "DTI codes (ISO 24165)."
          },
          "white_paper_url": {
            "type": "string",
            "description": "White paper."
          },
          "comments": {
            "type": "string",
            "description": "Comments."
          },
          "last_update": {
            "type": "string",
            "description": "Last update (dd/mm/yyyy)."
          }
        }
      },
      "MicaNcaspRecord": {
        "type": "object",
        "properties": {
          "register": {
            "type": "string",
            "enum": [
              "ncasp"
            ],
            "description": "Non-compliant entity."
          },
          "competent_authority": {
            "type": "string",
            "description": "Competent Authority."
          },
          "home_member_state": {
            "type": "string",
            "description": "Home Member State."
          },
          "name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legal name of the issuer/entity."
          },
          "lei": {
            "type": "string",
            "description": "LEI."
          },
          "national_code": {
            "type": "string",
            "description": "National code."
          },
          "commercial_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Commercial or trading names."
          },
          "website": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Website."
          },
          "infringement": {
            "type": "string",
            "description": "Infringement (Art. 17)."
          },
          "reason": {
            "type": "string",
            "description": "Reason."
          },
          "decision_date": {
            "type": "string",
            "description": "Decision date (dd/mm/yyyy)."
          },
          "comments": {
            "type": "string",
            "description": "Comments."
          },
          "last_update": {
            "type": "string",
            "description": "Last update (dd/mm/yyyy)."
          }
        }
      },
      "MicaResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Total number of records returned."
              },
              "term": {
                "type": "string",
                "description": "The search term (q parameter)."
              }
            }
          },
          "records": {
            "type": "object",
            "description": "Records grouped by register. The field set of each record depends on the register it belongs to.",
            "properties": {
              "emtwp": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MicaEmtRecord"
                },
                "description": "EMT — e-money token issuers."
              },
              "artzz": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MicaArtRecord"
                },
                "description": "ART — asset-referenced token issuers."
              },
              "casps": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MicaCaspRecord"
                },
                "description": "CASP — crypto-asset service providers."
              },
              "other": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MicaOtherRecord"
                },
                "description": "Other crypto-assets (white paper)."
              },
              "ncasp": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/MicaNcaspRecord"
                },
                "description": "Non-compliant entities."
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
