{
  "openapi": "3.1.0",
  "info": {
    "title": "Umbrella API",
    "version": "1.0.0",
    "description": "API documentation for Umbrella services including KYB, KYC, AML, payments, phone intelligence, onboarding, and address verification."
  },
  "servers": [
    {
      "url": "/mock/api/services",
      "description": "Mock"
    },
    {
      "url": "https://api-umbrella.io/api/services",
      "description": "Production"
    },
    {
      "url": "https://sandbox-umbrella-api.api-umbrella.io/api/services",
      "description": "Sandbox"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Bearer token obtained from POST /auth. Valid for 60 minutes."
      }
    },
    "schemas": {
      "Error400": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Invalid request payload"
          }
        }
      },
      "Error401": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Unauthorized request"
          }
        }
      },
      "Error403": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Forbidden"
          }
        }
      },
      "Error500": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Internal Server Error"
          }
        }
      },
      "Error404": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Journey not found"
          }
        }
      },
      "Error422": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Missing required images"
          }
        }
      },
      "Error429": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Too Many Requests"
          },
          "message": {
            "type": "string",
            "example": "Rate limit exceeded."
          },
          "code": {
            "type": "string",
            "example": "429"
          }
        }
      },
      "Error501": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Not Implemented"
          },
          "message": {
            "type": "string",
            "example": "The operation was not implemented."
          },
          "code": {
            "type": "string",
            "example": "501"
          }
        }
      },
      "Error503": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Service Unavailable"
          },
          "message": {
            "type": "string",
            "example": "Service is unavailable."
          },
          "code": {
            "type": "string",
            "example": "503"
          }
        }
      },
      "Error504": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Gateway Timeout"
          },
          "message": {
            "type": "string",
            "example": "Gateway has timed out."
          },
          "code": {
            "type": "string",
            "example": "504"
          }
        }
      },
      "Error409": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Webhook configuration already exists"
          },
          "message": {
            "type": "string",
            "example": "Webhook configuration already exists for this product and customer."
          }
        }
      },
      "AddressVerificationRequest": {
        "type": "object",
        "required": [
          "country",
          "address",
          "identity"
        ],
        "properties": {
          "country": {
            "type": "string",
            "description": "ISO 3166-1 Alpha-2/Alpha-3 country code (e.g., DE, AT, ES).",
            "minLength": 2,
            "maxLength": 3
          },
          "address": {
            "type": "object",
            "required": [
              "street",
              "number",
              "zip",
              "city"
            ],
            "properties": {
              "street": {
                "type": "string",
                "description": "Street name."
              },
              "number": {
                "type": "string",
                "description": "House or building number."
              },
              "zip": {
                "type": "string",
                "description": "Zip or post code."
              },
              "city": {
                "type": "string",
                "description": "Town or city name."
              },
              "province": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Accepted and ignored by the service."
              }
            }
          },
          "identity": {
            "type": "object",
            "required": [
              "firstname",
              "lastname",
              "dob"
            ],
            "properties": {
              "firstname": {
                "type": "string",
                "description": "First name of the person."
              },
              "lastname": {
                "type": "string",
                "description": "Last name of the person."
              },
              "dob": {
                "type": "string",
                "description": "Date of birth in the format YYYY-MM-DD.",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "example": "1970-12-01"
              }
            }
          }
        }
      },
      "AddressVerificationResponse": {
        "type": "object",
        "required": [
          "finalAddress",
          "addressStatus",
          "matchQuality",
          "score",
          "globalResult"
        ],
        "properties": {
          "inputAddress": {
            "type": "string",
            "description": "Raw address provided."
          },
          "correctedAddress": {
            "type": "string",
            "description": "Corrected version of the address."
          },
          "finalAddress": {
            "type": "string",
            "description": "Final confirmed address."
          },
          "addressStatus": {
            "type": "string",
            "description": "Status after verification.",
            "enum": [
              "corrected",
              "unchanged"
            ]
          },
          "addressComponents": {
            "type": "object",
            "description": "Detailed components of the final address.",
            "properties": {
              "street": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "number": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "zip": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "province": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "additionalProperties": false
          },
          "matchQuality": {
            "type": "string",
            "description": "Match level.",
            "enum": [
              "EXACT",
              "HOUSEHOLD_MATCH",
              "PARTIAL_MATCH",
              "HOUSENUMBER_MATCH",
              "STREET_MATCH",
              "CITY_MATCH",
              "IDENTITY_MISMATCH",
              "NO_MATCH"
            ]
          },
          "score": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "maximum": 100,
            "description": "Confidence score (0-100)."
          },
          "globalResult": {
            "type": "object",
            "required": [
              "overall"
            ],
            "properties": {
              "overall": {
                "type": "string",
                "enum": [
                  "OK",
                  "NOK",
                  "REVIEW",
                  "ERROR"
                ],
                "description": "Decision: OK, REVIEW or NOK. ERROR is reserved; the service reports failures as HTTP errors."
              },
              "totalScore": {
                "type": "integer",
                "format": "int32",
                "minimum": 0,
                "maximum": 100,
                "description": "Optional repetition of score for compatibility."
              }
            }
          },
          "identity": {
            "type": "object",
            "description": "Details of the identity as found in the search.",
            "properties": {
              "fullName": {
                "type": "string",
                "description": "First name and last name as submitted, joined by a space."
              },
              "dob": {
                "type": "string",
                "description": "Date of birth as submitted in the request."
              }
            },
            "additionalProperties": true
          },
          "extendedMessage": {
            "type": "string",
            "description": "Detail for the result. Free-form: an empty string is normal. Common values include addressCorrected, cityMatch, postcodeMatch, districtMatch, localityMatch, NoCity, NoPostCode, NoStreet, previousAddress, incorrectAddress, identityNotFound, deceased, addressFakeSuspicion, noMatch, dobPartial, dobFailedFull, lastNameOnly and firstNameOnly. Do not branch on this field; use globalResult.overall."
          }
        }
      },
      "AMLIndividualCheckRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Search string checked against name fields.",
            "example": "Boris Johnson"
          },
          "dob": {
            "type": "string",
            "description": "Date of birth in the format yyyy/mm/dd.",
            "example": "1964/06/19"
          }
        }
      },
      "AMLIndividualCheckResponse": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "description": "The timestamp of the response (ISO 8601 date time).",
            "example": "2024/09/24T19:16:00Z"
          },
          "totalHits": {
            "type": "number",
            "description": "The total number of hits for the searched parameters.",
            "example": 1
          },
          "foundRecords": {
            "type": "array",
            "description": "Array with attributes of type Individual.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique identifier for the record.",
                  "example": "c438b18a93cd3c13"
                },
                "sourceType": {
                  "type": "string",
                  "description": "Possible values: SANCTION, PEP, CRIMINAL.",
                  "enum": [
                    "SANCTION",
                    "PEP",
                    "CRIMINAL"
                  ],
                  "example": "PEP"
                },
                "pepType": {
                  "type": "string",
                  "description": "Type of PEP (e.g., POLITICIAN, JUDGE, BOARD_MEMBER_OF_CENTRAL_BANK).",
                  "example": "POLITICIAN"
                },
                "sourceId": {
                  "type": "string",
                  "description": "The source ID of the list.",
                  "example": "example-provider_pep"
                },
                "entityType": {
                  "type": "string",
                  "description": "Enumeration: INDIVIDUAL, UNKNOWN.",
                  "enum": [
                    "INDIVIDUAL",
                    "UNKNOWN"
                  ],
                  "example": "INDIVIDUAL"
                },
                "gender": {
                  "type": "string",
                  "description": "Enumeration: FEMALE, MALE, UNKNOWN.",
                  "enum": [
                    "FEMALE",
                    "MALE",
                    "UNKNOWN"
                  ],
                  "example": "MALE"
                },
                "name": {
                  "type": "string",
                  "description": "Name of the individual.",
                  "example": "Boris Johnson"
                },
                "lastNames": {
                  "type": "array",
                  "description": "A list of last names of this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "Johnson",
                    "Pfeffel"
                  ]
                },
                "aliasNames": {
                  "type": "array",
                  "description": "A list of alias names of this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "Alexander Boris de Pfeffel Johnson",
                    "Boris",
                    "BoJo"
                  ]
                },
                "givenNames": {
                  "type": "array",
                  "description": "A list of given names of this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "Alexander",
                    "Boris"
                  ]
                },
                "dateOfBirth": {
                  "type": "array",
                  "description": "A list of dates of birth for this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "1964/06/19"
                  ]
                },
                "placeOfBirth": {
                  "type": "array",
                  "description": "A list of places of birth for this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "New York City"
                  ]
                },
                "citizenship": {
                  "type": "array",
                  "description": "A list of citizenships for this individual in ISO 3166-1 alpha-2 format.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "GB",
                    "US"
                  ]
                },
                "occupations": {
                  "type": "array",
                  "description": "A list of occupations for this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "journalist",
                    "politician"
                  ]
                },
                "positions": {
                  "type": "array",
                  "description": "A list of positions for this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "2001/06/07 - 2005/04/11 Member of the 53rd Parliament of the United Kingdom",
                    "Since 2019/07/24 Prime Minister of the United Kingdom"
                  ]
                },
                "politicalParties": {
                  "type": "array",
                  "description": "A list of political parties for this individual.",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "Conservative Party"
                  ]
                },
                "links": {
                  "type": "array",
                  "description": "A list of links for this individual (e.g., websites, email addresses).",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "https://www.gov.uk/government/people/boris-johnson",
                    "Facebook: borisjohnson"
                  ]
                }
              }
            }
          }
        }
      },
      "AMLRegisterIndividualRequest": {
        "type": "object",
        "required": [
          "profileId",
          "names"
        ],
        "properties": {
          "profileId": {
            "type": "string",
            "description": "Unique identifier for the individual profile in the system.",
            "example": "8dac-b5393ce5ef3a"
          },
          "names": {
            "type": "string",
            "description": "Full name of the individual (e.g., \"Elon Musk\").",
            "example": "Elon Musk"
          },
          "gender": {
            "type": "string",
            "description": "Gender of the individual (optional, e.g., \"male\").",
            "example": "male"
          },
          "searchAll": {
            "type": "string",
            "description": "This field cannot be combined with the names parameter."
          },
          "dob": {
            "type": "string",
            "description": "Date of birth of the individual (optional).",
            "example": "1971/06/28"
          },
          "fuzzySearch": {
            "type": "string",
            "description": "Enables fuzzy search for the name (optional)."
          }
        }
      },
      "AmlRegisterIndividualResponse": {
        "type": "object",
        "required": [
          "error",
          "message",
          "profileId"
        ],
        "properties": {
          "error": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "profileId": {
            "type": "string",
            "description": "The registered profile ID for reference."
          }
        }
      },
      "AMLRegisterEntityRequest": {
        "type": "object",
        "required": [
          "profileId",
          "names"
        ],
        "properties": {
          "profileId": {
            "type": "string",
            "description": "Unique identifier for the entity profile in the system.",
            "example": "8dac-b5393ce5ef3a"
          },
          "names": {
            "type": "string",
            "description": "Full name of the entity (e.g., \"Tesla\").",
            "example": "Tesla"
          },
          "searchAll": {
            "type": "string",
            "description": "This field cannot be combined with the names parameter."
          },
          "fuzzySearch": {
            "type": "string",
            "description": "Enables fuzzy search for the name (optional)."
          }
        }
      },
      "AmlRegisterEntityResponse": {
        "type": "object",
        "required": [
          "error",
          "message",
          "profileId"
        ],
        "properties": {
          "error": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "profileId": {
            "type": "string",
            "description": "The registered profile ID for reference."
          }
        }
      },
      "AMLRemoveProfileRequest": {
        "type": "object",
        "required": [
          "profileId"
        ],
        "properties": {
          "profileId": {
            "type": "string",
            "description": "Unique identifier for the entity profile in the system.",
            "example": "8dac-b5393ce5ef3a"
          }
        }
      },
      "OpenJourneyRequest": {
        "type": "object",
        "description": "Optional metadata to be carried through the journey.",
        "properties": {
          "passThroughData": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "OpenJourneyResponse": {
        "type": "object",
        "required": [
          "journeyId"
        ],
        "properties": {
          "journeyId": {
            "type": "string",
            "description": "Unique identifier for the verification journey."
          },
          "passThroughData": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "AddImagePayload": {
        "description": "Either a single image object or an array of image objects.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/AddImageItem"
          },
          {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AddImageItem"
            },
            "minItems": 1
          }
        ]
      },
      "AddImageItem": {
        "type": "object",
        "required": [
          "imageName",
          "imageSide",
          "imageData"
        ],
        "properties": {
          "journeyId": {
            "type": "string",
            "description": "Unique identifier for the verification journey."
          },
          "imageName": {
            "type": "string",
            "description": "Name of the uploaded image file."
          },
          "imageSide": {
            "type": "string",
            "description": "Specifies which side of the document.",
            "enum": [
              "front",
              "back",
              "selfie"
            ]
          },
          "storeOnly": {
            "type": "boolean",
            "description": "If true, stores the image without classification."
          },
          "imageData": {
            "type": "string",
            "description": "Base64-encoded image data."
          },
          "passThroughData": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": false
      },
      "AddImageMultipart": {
        "type": "object",
        "required": [
          "journeyId",
          "imageName",
          "imageSide",
          "file"
        ],
        "properties": {
          "journeyId": {
            "type": "string"
          },
          "imageName": {
            "type": "string"
          },
          "imageSide": {
            "type": "string",
            "enum": [
              "front",
              "back",
              "selfie"
            ]
          },
          "storeOnly": {
            "type": "boolean"
          },
          "file": {
            "type": "string",
            "format": "binary"
          },
          "passThroughData": {
            "type": "string",
            "description": "JSON string for metadata if needed."
          }
        }
      },
      "AddImageResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "boolean",
            "default": false
          },
          "message": {
            "type": "string"
          },
          "journeyId": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "imageName": {
                  "type": "string"
                },
                "imageSide": {
                  "type": "string",
                  "enum": [
                    "front",
                    "back",
                    "selfie"
                  ]
                },
                "imageId": {
                  "type": "string"
                },
                "stored": {
                  "type": "boolean"
                },
                "classified": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": [
          "journeyId"
        ],
        "properties": {
          "journeyId": {
            "type": "string",
            "description": "Unique identifier for the verification journey."
          }
        }
      },
      "VerifyResponse": {
        "type": "object",
        "required": [
          "journeyId",
          "status"
        ],
        "properties": {
          "journeyId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "e.g., 'verificationComplete'."
          },
          "identitySubject": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "example": "person"
              },
              "fullName": {
                "type": "string"
              },
              "nameStructure": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string"
                  },
                  "lastName": {
                    "type": "string"
                  },
                  "nativeFullName": {
                    "type": "string"
                  }
                }
              },
              "gender": {
                "type": "string",
                "enum": [
                  "M",
                  "F",
                  "X"
                ]
              },
              "nationality": {
                "type": "string",
                "description": "ISO 3166 code (e.g., 'DE')."
              },
              "dob": {
                "type": "string",
                "description": "YYYY/MM/DD"
              },
              "addressSingleLine": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "mobileNumber": {
                "type": "string"
              }
            }
          },
          "authoritativeData": {
            "type": "object",
            "properties": {
              "identityDocument": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "example": "passport"
                  },
                  "idNumber": {
                    "type": "string"
                  },
                  "issuingCountry": {
                    "type": "string"
                  },
                  "expeditor": {
                    "type": "string"
                  },
                  "expirationDate": {
                    "type": "string",
                    "description": "YYYY/MM/DD"
                  },
                  "verificationChannel": {
                    "type": "string",
                    "example": "optical"
                  }
                }
              }
            }
          },
          "proofOfWork": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "example": "image"
              },
              "titleOfProof": {
                "type": "string"
              },
              "timestampOfProof": {
                "type": "string",
                "description": "YYYY/MM/DDTHH:MM:SSZ"
              }
            }
          },
          "auditTrail": {
            "type": "object",
            "properties": {
              "workId": {
                "type": "string"
              },
              "workStatus": {
                "type": "string",
                "enum": [
                  "PASS",
                  "FAIL"
                ]
              },
              "workStartTst": {
                "type": "string"
              },
              "workEndTst": {
                "type": "string"
              },
              "workResult": {
                "type": "string"
              }
            }
          },
          "fraudAlerts": {
            "type": "object",
            "properties": {
              "fraudAlertDetail": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "aggregateFraudAlertScore": {
                "type": "number"
              }
            }
          },
          "croppedImages": {
            "type": "object",
            "properties": {
              "front": {
                "type": "string",
                "description": "base64-encoded"
              },
              "portrait": {
                "type": "string",
                "description": "base64-encoded"
              },
              "signature": {
                "type": "string",
                "description": "base64-encoded"
              },
              "back": {
                "type": "string",
                "description": "base64-encoded"
              },
              "selfie": {
                "type": "string",
                "description": "base64-encoded"
              }
            }
          }
        }
      },
      "AgeVerifyRequest": {
        "type": "object",
        "required": [
          "journeyId"
        ],
        "properties": {
          "journeyId": {
            "type": "string"
          },
          "ageFrom": {
            "type": "number",
            "description": "Minimum age for eligibility (mutually exclusive with ageTo)."
          },
          "ageTo": {
            "type": "number",
            "description": "Maximum age for eligibility (mutually exclusive with ageFrom)."
          },
          "minDisabilityPercentage": {
            "type": "number"
          }
        }
      },
      "AgeVerifyResponse": {
        "type": "object",
        "required": [
          "journeyId",
          "status",
          "ageResult",
          "disabilityResult"
        ],
        "properties": {
          "journeyId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "example": "ageAndDisabilityVerificationComplete"
          },
          "ageResult": {
            "type": "string",
            "enum": [
              "yes",
              "no"
            ]
          },
          "disabilityResult": {
            "type": "string",
            "enum": [
              "eligible",
              "not eligible"
            ]
          }
        }
      },
      "VerifySingleRequest": {
        "type": "object",
        "required": [
          "images"
        ],
        "properties": {
          "images": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/VerifyImageItem"
            },
            "description": "List of image objects for verification."
          }
        }
      },
      "VerifyImageItem": {
        "type": "object",
        "required": [
          "imageName",
          "imageSide",
          "imageData"
        ],
        "properties": {
          "imageName": {
            "type": "string",
            "description": "Name of the uploaded image."
          },
          "imageSide": {
            "type": "string",
            "description": "Specifies document side.",
            "enum": [
              "front",
              "back",
              "selfie"
            ]
          },
          "imageData": {
            "type": "string",
            "description": "Base64-encoded image data."
          }
        },
        "additionalProperties": false
      },
      "VerifySingleMultipart": {
        "type": "object",
        "required": [
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "description": "Upload multiple images as files; each part represents one image.",
            "items": {
              "type": "string",
              "format": "binary"
            }
          }
        }
      },
      "IdentityVerificationRequest": {
        "type": "object",
        "required": [
          "identity",
          "address"
        ],
        "properties": {
          "identity": {
            "type": "object",
            "required": [
              "firstName",
              "lastName",
              "birthDate"
            ],
            "properties": {
              "firstName": {
                "type": "string"
              },
              "lastName": {
                "type": "string"
              },
              "nationalId": {
                "type": "string"
              },
              "birthDate": {
                "type": "string",
                "description": "Birthdate of the individual in the format YYYY/MM/DD.",
                "pattern": "^\\d{4}\\/\\d{2}\\/\\d{2}$"
              }
            }
          },
          "address": {
            "type": "object",
            "required": [
              "street",
              "postalCode",
              "city",
              "countryCode"
            ],
            "properties": {
              "street": {
                "type": "string"
              },
              "houseNumber": {
                "type": "string"
              },
              "building": {
                "type": "string"
              },
              "postalCode": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "district": {
                "type": "string"
              },
              "province": {
                "type": "string"
              },
              "countryCode": {
                "type": "string"
              }
            }
          },
          "phone": {
            "type": "object",
            "properties": {
              "phoneNumber": {
                "type": "string"
              }
            }
          }
        }
      },
      "IdentityVerificationResponse": {
        "type": "object",
        "required": [
          "globalResult",
          "resultDetails"
        ],
        "properties": {
          "globalResult": {
            "type": "object",
            "properties": {
              "totalScore": {
                "type": "integer",
                "enum": [
                  0,
                  50,
                  75,
                  100
                ],
                "description": "Aggregate verification score."
              }
            }
          },
          "resultDetails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "datasource": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "matches": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "record": {
                        "type": "string"
                      },
                      "match": {
                        "type": "string",
                        "enum": [
                          "full",
                          "partial",
                          "not-present"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "InitiatePaymentRequest": {
        "type": "object",
        "required": [
          "referenceId",
          "transactionDescription",
          "returnUrl",
          "IBAN",
          "currency",
          "amount"
        ],
        "properties": {
          "referenceId": {
            "type": "string",
            "description": "Unique identifier for the transaction generated by your system.",
            "example": "uniqueRefId123"
          },
          "transactionDescription": {
            "type": "string",
            "description": "Description of the transaction.",
            "example": "Payment for Order #12345"
          },
          "returnUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to redirect after payment completion – back to the calling app or website.",
            "example": "https://example.com/callback"
          },
          "IBAN": {
            "type": "string",
            "description": "Recipient's IBAN for direct payment.",
            "example": "DE89370400440532013000"
          },
          "storedBIC": {
            "type": "string",
            "description": "Pre-stored BIC code.",
            "example": "BOFIIE2D"
          },
          "language": {
            "type": "string",
            "description": "Language code.",
            "example": "DE"
          },
          "currency": {
            "type": "string",
            "description": "Currency code.",
            "example": "EUR"
          },
          "amount": {
            "type": "string",
            "description": "Payment amount formatted as a decimal string.",
            "example": "12.50"
          },
          "country": {
            "type": "string",
            "description": "Country code.",
            "example": "DE"
          }
        }
      },
      "InitiatePaymentResponse": {
        "type": "object",
        "required": [
          "requestId",
          "redirectUrl"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Unique identifier for the request. Will be used to query the transfer status in the Retrieve Transaction Status API call.",
            "example": "req123456789"
          },
          "redirectUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to redirect the user to the hosted payment page.",
            "example": "https://example.com/app/req_123456789"
          }
        }
      },
      "RetrieveStatusRequest": {
        "type": "object",
        "required": [
          "referenceId"
        ],
        "properties": {
          "referenceId": {
            "type": "string",
            "description": "Unique identifier for the transaction generated from the Initiate Payment API call.",
            "example": "uniqueRefId123"
          }
        }
      },
      "RetrieveStatusResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "description": "Transaction status.",
            "enum": [
              "PROCESSING",
              "SUCCESS",
              "INITIATED",
              "PENDING",
              "PENDING_EXTERNAL_AUTHORIZATION",
              "FAILURE_GENERIC",
              "FAILURE_PERMISSION_DENIED",
              "FAILURE_CANCELED",
              "FAILURE_EXPIRED",
              "FAILURE_INSUFFICIENT_FUNDS",
              "FAILURE_DECLINED",
              "SETTLEMENT_IN_PROGRESS",
              "SETTLEMENT_COMPLETED",
              "SETTLEMENT_INCOMPLETE",
              "COMPLETED",
              "FAILED"
            ],
            "example": "PENDING",
            "x-enumDescriptions": {
              "PROCESSING": "The transaction is in process; the final status has not yet been received from the bank.",
              "SUCCESS": "Successful payment initiation has been received from the bank. Settlement might not be complete.",
              "INITIATED": "The transaction was initiated but the result is unknown. This status will not be updated further.",
              "PENDING": "Authorization at the bank is complete; transfer is pending redemption (2-step flows).",
              "PENDING_EXTERNAL_AUTHORIZATION": "User is at the bank to complete authorization; may transition to FAILURE_EXPIRED.",
              "FAILURE_GENERIC": "Technical failure with no additional details from the bank.",
              "FAILURE_PERMISSION_DENIED": "User denied authorization at the bank (2-step flows).",
              "FAILURE_CANCELED": "Payment initiation was canceled before execution.",
              "FAILURE_EXPIRED": "Authorization not completed in time; payment expired.",
              "FAILURE_INSUFFICIENT_FUNDS": "Rejected due to insufficient funds.",
              "FAILURE_DECLINED": "Rejected by the bank.",
              "SETTLEMENT_IN_PROGRESS": "Waiting for funds to reach the payee bank.",
              "SETTLEMENT_COMPLETED": "Funds reached the payee bank; reconciliation complete.",
              "SETTLEMENT_INCOMPLETE": "Reconciliation failed; corresponding transaction not found.",
              "COMPLETED": "High-level: transaction completed successfully.",
              "FAILED": "High-level: transaction failed."
            }
          },
          "statusReasonInformation": {
            "type": "string",
            "description": "Additional details about the status.",
            "example": "User redirected to bank."
          }
        }
      },
      "ChallengeDepositRequest": {
        "type": "object",
        "required": [
          "amount",
          "currency",
          "description",
          "firstName",
          "lastName",
          "piiToggle",
          "nameMatchLogic"
        ],
        "properties": {
          "amount": {
            "type": "string",
            "description": "Small amount sent for verification.",
            "example": "0.10",
            "pattern": "^[0-9]+(\\.[0-9]{1,2})?$"
          },
          "currency": {
            "type": "string",
            "description": "Currency code.",
            "example": "EUR",
            "minLength": 3,
            "maxLength": 3
          },
          "description": {
            "type": "string",
            "description": "Mandatory, non-blank. Alphanumeric only; hyphens (-) allowed as separators. No spaces or other special characters.",
            "example": "merchantId19887-65",
            "pattern": "^[A-Za-z0-9-]+$"
          },
          "firstName": {
            "type": "string",
            "description": "First name for identity verification.",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Last name for identity verification.",
            "example": "Doe"
          },
          "piiToggle": {
            "type": "integer",
            "description": "Determines if PII details should be returned.",
            "enum": [
              0,
              1
            ],
            "example": 1
          },
          "nameMatchLogic": {
            "type": "string",
            "description": "Name matching logic type.",
            "enum": [
              "exact",
              "fuzzy"
            ],
            "example": "fuzzy"
          }
        }
      },
      "ChallengeDepositResponse": {
        "type": "object",
        "required": [
          "description",
          "status",
          "globalResult",
          "nameMatchScore"
        ],
        "properties": {
          "transactionId": {
            "type": "string",
            "description": "Unique identifier for the challenge deposit transaction.",
            "example": "e5c81c78-272b-4307-9197-3ace19109fd3"
          },
          "description": {
            "type": "string",
            "description": "The description sent in the request.",
            "example": "merchantId19887-65"
          },
          "status": {
            "type": "string",
            "description": "Status of the challenge deposit.",
            "enum": [
              "OK",
              "FAIL"
            ],
            "example": "OK"
          },
          "globalResult": {
            "type": "object",
            "description": "Contains verification score and assessment result.",
            "required": [
              "overall",
              "totalScore"
            ],
            "properties": {
              "overall": {
                "type": "string",
                "description": "Overall assessment.",
                "enum": [
                  "review",
                  "pass",
                  "fail"
                ],
                "example": "review"
              },
              "totalScore": {
                "type": "integer",
                "description": "Score (0-100) indicating verification quality.",
                "minimum": 0,
                "maximum": 100,
                "example": 100
              }
            }
          },
          "nameMatchScore": {
            "type": "integer",
            "description": "Score (0-100) indicating how well names matched.",
            "minimum": 0,
            "maximum": 100,
            "example": 85
          },
          "iban": {
            "type": "string",
            "description": "Verified IBAN.",
            "example": "DE44500105175407324931"
          },
          "returnedFirstName": {
            "type": "string",
            "description": "First name returned from verification if available and `piiToggle = 1`.",
            "example": "John"
          },
          "returnedLastName": {
            "type": "string",
            "description": "Last name returned from verification if available and `piiToggle = 1`.",
            "example": "Doe"
          }
        }
      },
      "PhoneStatusRequest": {
        "type": "object",
        "required": [
          "phoneNumber"
        ],
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "The phone number to check, including country code (E.164).",
            "example": "+4915123456789"
          }
        }
      },
      "PhoneStatusResponse": {
        "type": "object",
        "properties": {
          "referenceId": {
            "type": "string",
            "description": "Unique reference ID for the transaction.",
            "example": "ABC123XYZ789"
          },
          "subResource": {
            "type": "string",
            "description": "Sub-resource type (e.g., 'live').",
            "example": "live"
          },
          "status": {
            "type": "object",
            "properties": {
              "code": {
                "type": "number",
                "description": "Status code (e.g., 300 for success).",
                "example": 300
              },
              "description": {
                "type": "string",
                "description": "Status description.",
                "example": "Transaction successfully completed"
              },
              "updatedOn": {
                "type": "string",
                "description": "Timestamp of the last update (ISO 8601 format).",
                "example": "2025-08-01T14:32:10Z"
              }
            }
          },
          "errors": {
            "type": "array",
            "description": "List of errors, if any.",
            "items": {
              "type": "string"
            }
          },
          "phoneType": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Phone type code (e.g., '2' for mobile).",
                "example": "2"
              },
              "description": {
                "type": "string",
                "description": "Phone type description.",
                "example": "MOBILE"
              }
            }
          },
          "blocklisting": {
            "type": "object",
            "properties": {
              "blocked": {
                "type": "boolean",
                "description": "Whether the number is blocked.",
                "example": false
              },
              "blockCode": {
                "type": "number",
                "description": "Block code (0 = not blocked).",
                "example": 0
              },
              "blockDescription": {
                "type": "string",
                "description": "Block description.",
                "example": "Not blocked"
              }
            }
          },
          "numbering": {
            "type": "object",
            "properties": {
              "cleansing": {
                "type": "object",
                "properties": {
                  "call": {
                    "type": "object",
                    "properties": {
                      "countryCode": {
                        "type": "string",
                        "example": "49"
                      },
                      "phoneNumber": {
                        "type": "string",
                        "example": "15123456789"
                      },
                      "cleansedCode": {
                        "type": "number",
                        "example": 100
                      },
                      "minLength": {
                        "type": "number",
                        "example": 7
                      },
                      "maxLength": {
                        "type": "number",
                        "example": 13
                      }
                    }
                  },
                  "sms": {
                    "type": "object",
                    "properties": {
                      "countryCode": {
                        "type": "string",
                        "example": "49"
                      },
                      "phoneNumber": {
                        "type": "string",
                        "example": "15123456789"
                      },
                      "cleansedCode": {
                        "type": "number",
                        "example": 100
                      },
                      "minLength": {
                        "type": "number",
                        "example": 7
                      },
                      "maxLength": {
                        "type": "number",
                        "example": 13
                      }
                    }
                  }
                }
              },
              "original": {
                "type": "object",
                "properties": {
                  "completePhoneNumber": {
                    "type": "string",
                    "example": "+4915123456789"
                  },
                  "countryCode": {
                    "type": "string",
                    "example": "49"
                  },
                  "phoneNumber": {
                    "type": "string",
                    "example": "15123456789"
                  }
                }
              }
            }
          },
          "location": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "example": "Berlin"
              },
              "state": {
                "type": "string",
                "nullable": true,
                "example": "Berlin"
              },
              "zip": {
                "type": "string",
                "nullable": true,
                "example": "10115"
              },
              "metroCode": {
                "type": "string",
                "nullable": true
              },
              "county": {
                "type": "string",
                "nullable": true,
                "example": "Berlin County"
              },
              "country": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Germany"
                  },
                  "iso2": {
                    "type": "string",
                    "example": "DE"
                  },
                  "iso3": {
                    "type": "string",
                    "example": "DEU"
                  }
                }
              },
              "coordinates": {
                "type": "object",
                "properties": {
                  "latitude": {
                    "type": "string",
                    "nullable": true,
                    "example": "52.5200"
                  },
                  "longitude": {
                    "type": "string",
                    "nullable": true,
                    "example": "13.4050"
                  }
                }
              },
              "timeZone": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "nullable": true,
                    "example": "Europe/Berlin"
                  },
                  "utcOffsetMax": {
                    "type": "string",
                    "example": "+2"
                  },
                  "utcOffsetMin": {
                    "type": "string",
                    "example": "+1"
                  }
                }
              }
            }
          },
          "carrier": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the carrier.",
                "example": "Generic Mobile GmbH"
              }
            }
          },
          "live": {
            "type": "object",
            "properties": {
              "subscriberStatus": {
                "type": "string",
                "example": "ACTIVE"
              },
              "deviceStatus": {
                "type": "string",
                "example": "REACHABLE"
              },
              "roaming": {
                "type": "string",
                "example": "UNAVAILABLE"
              },
              "roamingCountry": {
                "type": "string",
                "nullable": true
              },
              "roamingCountryIso2": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "PhoneIDRequest": {
        "type": "object",
        "required": [
          "phoneNumber"
        ],
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Phone number to query, including country code (no spaces or symbols).",
            "example": "15555550100"
          },
          "accountLifecycleEvent": {
            "type": "string",
            "description": "Stage of the user journey.",
            "enum": [
              "create",
              "sign-in",
              "transact",
              "update",
              "delete"
            ],
            "example": "create"
          },
          "externalId": {
            "type": "string",
            "description": "Customer-defined ID echoed in the response.",
            "example": "CustomExternalID7349"
          },
          "originatingIp": {
            "type": "string",
            "description": "End user's IP address (IPv4 or IPv6).",
            "example": "203.0.113.45"
          },
          "addons": {
            "type": "object",
            "description": "Add-on services to enrich the phone lookup.",
            "properties": {
              "ageVerify": {
                "type": "object",
                "properties": {
                  "ageThreshold": {
                    "type": "integer",
                    "description": "Age threshold to verify against.",
                    "example": 21
                  }
                }
              },
              "breachedData": {
                "type": "object",
                "description": "Checks whether the phone number has appeared in known data breaches."
              },
              "callForwardDetection": {
                "type": "object",
                "description": "Detects whether call forwarding is active and under what conditions."
              },
              "contact": {
                "type": "object",
                "description": "Returns known contact details such as name, address, and email.",
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "test@example.com"
                  }
                }
              },
              "contactMatch": {
                "type": "object",
                "description": "Compares submitted contact data against the carrier’s data and returns a match score.",
                "properties": {
                  "firstName": {
                    "type": "string"
                  },
                  "lastName": {
                    "type": "string"
                  },
                  "address": {
                    "type": "string"
                  },
                  "city": {
                    "type": "string"
                  },
                  "postalCode": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "inputUsed": {
                    "type": "string",
                    "description": "e.g., 'phoneNumber and email' or 'email'."
                  }
                }
              },
              "contactPlus": {
                "type": "object",
                "description": "Enhanced contact information module.",
                "properties": {
                  "billingPostalCode": {
                    "type": "string",
                    "example": "95110"
                  }
                }
              },
              "numberDeactivation": {
                "type": "object",
                "description": "Indicates if/when the number was deactivated.",
                "properties": {
                  "carrierName": {
                    "type": "string",
                    "example": "Verizon"
                  },
                  "lastDeactivated": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2016-04-05T00:00:00Z"
                  },
                  "trackingSince": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2014-10-06T00:00:00Z"
                  },
                  "status": {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "integer",
                        "example": 2800
                      },
                      "description": {
                        "type": "string",
                        "example": "Request successfully completed"
                      }
                    }
                  },
                  "recycledSinceLastVerification": {
                    "type": "string",
                    "example": "notRecycled"
                  }
                }
              },
              "subscriberStatus": {
                "type": "object",
                "description": "Provides subscriber account details like type, tenure, and activation."
              },
              "portingHistory": {
                "type": "object",
                "description": "Shows porting history of the number across carriers.",
                "properties": {
                  "pastXDays": {
                    "type": "integer",
                    "example": 10
                  }
                }
              },
              "portingStatus": {
                "type": "object",
                "description": "Displays current carrier and whether the number was recently ported."
              },
              "simSwap": {
                "type": "object",
                "description": "Detects recent SIM changes and evaluates risk."
              }
            }
          },
          "consent": {
            "type": "object",
            "description": "Consent record for querying the number, required for certain add-ons.",
            "properties": {
              "method": {
                "type": "integer",
                "description": "Numeric code for how consent was collected.",
                "enum": [
                  1,
                  2,
                  3,
                  4
                ],
                "example": 1
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp of when consent was collected.",
                "example": "2018-05-05T00:00:00Z"
              }
            }
          }
        }
      },
      "PhoneIDResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates if the API request itself was successful."
          },
          "data": {
            "type": "object",
            "properties": {
              "referenceId": {
                "type": "string",
                "description": "Unique 32-character hex ID for the transaction."
              },
              "externalId": {
                "type": "string",
                "nullable": true,
                "description": "Echoed custom ID if provided."
              },
              "status": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "integer",
                    "description": "Processing status code (e.g., 300 for success)."
                  },
                  "description": {
                    "type": "string",
                    "description": "Human-readable description of the transaction status."
                  },
                  "updatedOn": {
                    "type": "string",
                    "description": "ISO 8601/RFC 3339 timestamp of last update."
                  }
                }
              },
              "phoneType": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              },
              "blocklisting": {
                "type": "object",
                "properties": {
                  "blocked": {
                    "type": "boolean"
                  },
                  "blockCode": {
                    "type": "integer"
                  },
                  "blockDescription": {
                    "type": "string"
                  }
                }
              },
              "carrier": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              },
              "numbering": {
                "type": "object",
                "properties": {
                  "original": {
                    "type": "object",
                    "properties": {
                      "completePhoneNumber": {
                        "type": "string"
                      },
                      "countryCode": {
                        "type": "string"
                      },
                      "phoneNumber": {
                        "type": "string"
                      }
                    }
                  },
                  "cleansing": {
                    "type": "object",
                    "properties": {
                      "call": {
                        "type": "object",
                        "properties": {
                          "countryCode": {
                            "type": "string"
                          },
                          "phoneNumber": {
                            "type": "string"
                          },
                          "cleansedCode": {
                            "type": "integer"
                          },
                          "minLength": {
                            "type": "integer"
                          },
                          "maxLength": {
                            "type": "integer"
                          }
                        }
                      },
                      "sms": {
                        "type": "object",
                        "properties": {
                          "countryCode": {
                            "type": "string"
                          },
                          "phoneNumber": {
                            "type": "string"
                          },
                          "cleansedCode": {
                            "type": "integer"
                          },
                          "minLength": {
                            "type": "integer"
                          },
                          "maxLength": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "location": {
                "type": "object",
                "properties": {
                  "city": {
                    "type": "string",
                    "nullable": true
                  },
                  "state": {
                    "type": "string",
                    "nullable": true
                  },
                  "zip": {
                    "type": "string",
                    "nullable": true
                  },
                  "metroCode": {
                    "type": "string",
                    "nullable": true
                  },
                  "county": {
                    "type": "string",
                    "nullable": true
                  },
                  "country": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "iso2": {
                        "type": "string",
                        "nullable": true
                      },
                      "iso3": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  },
                  "coordinates": {
                    "type": "object",
                    "properties": {
                      "latitude": {
                        "type": "number",
                        "nullable": true
                      },
                      "longitude": {
                        "type": "number",
                        "nullable": true
                      }
                    }
                  },
                  "timeZone": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "utcOffsetMax": {
                        "type": "string",
                        "nullable": true
                      },
                      "utcOffsetMin": {
                        "type": "string",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "PhoneRiskScoreRequest": {
        "type": "object",
        "required": [
          "phoneNumber",
          "accountLifecycleEvent"
        ],
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "The phone number to check, including country code (E.164).",
            "example": "+436501234567"
          },
          "accountLifecycleEvent": {
            "type": "string",
            "description": "The action being evaluated.",
            "enum": [
              "create",
              "sign-in",
              "transact",
              "update",
              "delete"
            ],
            "example": "create"
          },
          "externalId": {
            "type": "string",
            "description": "Customer-generated ID echoed in the response.",
            "example": "1234567890"
          },
          "originatingIp": {
            "type": "string",
            "description": "End user's IP address (IPv4 or IPv6). Do not send your server IP.",
            "example": "192.168.1.1"
          },
          "deviceId": {
            "type": "string",
            "description": "Case-sensitive device ID.",
            "example": "1234567890"
          },
          "accountId": {
            "type": "string",
            "description": "Case-sensitive account ID.",
            "example": "1234567890"
          },
          "emailAddress": {
            "type": "string",
            "description": "Case-sensitive email address.",
            "example": "test@example.com"
          }
        }
      },
      "PhoneRiskScoreResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates if the API request was successful."
          },
          "data": {
            "type": "object",
            "properties": {
              "referenceId": {
                "type": "string",
                "description": "Unique reference ID for the transaction."
              },
              "externalId": {
                "type": "string",
                "nullable": true,
                "description": "External reference ID (nullable)."
              },
              "status": {
                "type": "object",
                "properties": {
                  "updatedOn": {
                    "type": "string",
                    "description": "Timestamp of the last update (ISO 8601 format)."
                  },
                  "code": {
                    "type": "number",
                    "description": "Status code (e.g., 300 for success)."
                  },
                  "description": {
                    "type": "string",
                    "description": "Status description message."
                  }
                }
              },
              "numbering": {
                "type": "object",
                "properties": {
                  "original": {
                    "type": "object",
                    "properties": {
                      "completePhoneNumber": {
                        "type": "string"
                      },
                      "countryCode": {
                        "type": "string"
                      },
                      "phoneNumber": {
                        "type": "string"
                      }
                    }
                  },
                  "cleansing": {
                    "type": "object",
                    "properties": {
                      "call": {
                        "type": "object",
                        "properties": {
                          "countryCode": {
                            "type": "string"
                          },
                          "phoneNumber": {
                            "type": "string"
                          },
                          "cleansedCode": {
                            "type": "number"
                          },
                          "minLength": {
                            "type": "number"
                          },
                          "maxLength": {
                            "type": "number"
                          }
                        }
                      },
                      "sms": {
                        "type": "object",
                        "properties": {
                          "countryCode": {
                            "type": "string"
                          },
                          "phoneNumber": {
                            "type": "string"
                          },
                          "cleansedCode": {
                            "type": "number"
                          },
                          "minLength": {
                            "type": "number"
                          },
                          "maxLength": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "riskInsights": {
                "type": "object",
                "description": "Risk assessment details.",
                "properties": {
                  "status": {
                    "type": "number"
                  },
                  "category": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "a2P": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "p2P": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "numberType": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "ip": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "email": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  }
                }
              },
              "phoneType": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              },
              "location": {
                "type": "object",
                "properties": {
                  "city": {
                    "type": "string",
                    "nullable": true
                  },
                  "state": {
                    "type": "string",
                    "nullable": true
                  },
                  "zip": {
                    "type": "string",
                    "nullable": true
                  },
                  "metroCode": {
                    "type": "string",
                    "nullable": true
                  },
                  "county": {
                    "type": "string",
                    "nullable": true
                  },
                  "country": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "iso2": {
                        "type": "string"
                      },
                      "iso3": {
                        "type": "string"
                      }
                    }
                  },
                  "coordinates": {
                    "type": "object",
                    "properties": {
                      "latitude": {
                        "type": "number",
                        "nullable": true
                      },
                      "longitude": {
                        "type": "number",
                        "nullable": true
                      }
                    }
                  },
                  "timeZone": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "utcOffsetMin": {
                        "type": "string"
                      },
                      "utcOffsetMax": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "carrier": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              },
              "blocklisting": {
                "type": "object",
                "properties": {
                  "blocked": {
                    "type": "boolean"
                  },
                  "blockCode": {
                    "type": "number"
                  },
                  "blockDescription": {
                    "type": "string"
                  }
                }
              },
              "risk": {
                "type": "object",
                "description": "Overall risk score and recommendation.",
                "properties": {
                  "level": {
                    "type": "string",
                    "example": "medium-low"
                  },
                  "recommendation": {
                    "type": "string",
                    "example": "allow"
                  },
                  "score": {
                    "type": "number",
                    "example": 301
                  }
                }
              }
            }
          }
        }
      },
      "VerificationRequest": {
        "type": "object",
        "required": [
          "method"
        ],
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Recipient's phone number in international format, no spaces or special characters. Required if method = sms.",
            "example": "436501234567",
            "pattern": "^[0-9]+$",
            "minLength": 6,
            "maxLength": 20
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Recipient's email address. Required if method = email.",
            "example": "test@test.com"
          },
          "method": {
            "type": "string",
            "description": "The delivery method to use.",
            "enum": [
              "sms",
              "email"
            ],
            "example": "email"
          },
          "securityFactor": {
            "type": "string",
            "description": "A custom numeric OTP (3–10 digits). If omitted, a 6-digit OTP is auto-generated.",
            "pattern": "^[0-9]{3,10}$",
            "example": "123456"
          },
          "externalId": {
            "type": "string",
            "description": "Customer-defined transaction ID. Max length: 100 characters.",
            "maxLength": 100,
            "example": "12312"
          },
          "messageTemplate": {
            "type": "object",
            "description": "Optional template details for this verification.",
            "properties": {
              "name": {
                "type": "string",
                "description": "Template name (lowercase letters and underscores only).",
                "pattern": "^[a-z_]+$",
                "example": "welcome_otp"
              },
              "verificationTemplate": {
                "type": "string",
                "description": "Template content to be used for this verification.",
                "example": "Your code is {{code}}. It expires in 5 minutes."
              }
            },
            "additionalProperties": false
          },
          "voiceLang": {
            "type": "string",
            "description": "Language code for OTP delivery (e.g., 'en-US'). Defaults to English if not provided.",
            "example": "en-US"
          }
        },
        "allOf": [
          {
            "oneOf": [
              {
                "properties": {
                  "method": {
                    "const": "sms"
                  }
                },
                "required": [
                  "phoneNumber"
                ]
              },
              {
                "properties": {
                  "method": {
                    "const": "email"
                  }
                },
                "required": [
                  "email"
                ]
              }
            ]
          }
        ],
        "additionalProperties": false
      },
      "VerificationResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates whether the request was successful (true/false).",
            "example": true
          },
          "data": {
            "type": "object",
            "required": [
              "recipient",
              "referenceId",
              "state",
              "status"
            ],
            "properties": {
              "mobileAppToken": {
                "type": "string",
                "description": "Token used to authenticate the mobile app session.",
                "example": "a1378b455f3048059a7be9df6a9da3aa",
                "minLength": 16,
                "maxLength": 128
              },
              "recipient": {
                "type": "object",
                "required": [
                  "phoneNumber"
                ],
                "properties": {
                  "phoneNumber": {
                    "type": "string",
                    "description": "Recipient's phone number in international format.",
                    "example": "436501234567"
                  }
                },
                "additionalProperties": false
              },
              "referenceId": {
                "type": "string",
                "description": "Unique 32-character hex string that identifies the verification process.",
                "example": "366691874BD00250933424F72F7C50CB",
                "pattern": "^[A-F0-9]{32}$"
              },
              "state": {
                "type": "string",
                "description": "Current state of the verification process.",
                "enum": [
                  "CREATED",
                  "ONGOING",
                  "REJECTED",
                  "FAILED",
                  "VERIFIED",
                  "CANCELED"
                ],
                "example": "CREATED"
              },
              "status": {
                "type": "object",
                "required": [
                  "code",
                  "description",
                  "updatedOn"
                ],
                "properties": {
                  "code": {
                    "type": "integer",
                    "description": "Numeric code representing the transaction status.",
                    "example": 3901
                  },
                  "description": {
                    "type": "string",
                    "description": "Human-readable description of the transaction status.",
                    "example": "Request in progress"
                  },
                  "updatedOn": {
                    "type": "string",
                    "format": "date-time",
                    "description": "ISO 8601 timestamp indicating when the status was last updated.",
                    "example": "2025-10-02T10:04:58.505000Z"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "VerificationMatchRequest": {
        "type": "object",
        "required": [
          "securityFactor"
        ],
        "properties": {
          "securityFactor": {
            "type": "string",
            "description": "The OTP provided by the end user (3–10 digits).",
            "pattern": "^\\d{3,10}$",
            "example": "12345"
          }
        },
        "additionalProperties": false
      },
      "VerificationMatchResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates whether the request was successful (true or false).",
            "example": true
          },
          "data": {
            "type": "object",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "type": "object",
                "required": [
                  "code",
                  "description"
                ],
                "properties": {
                  "code": {
                    "type": "integer",
                    "description": "Numeric code representing the verification result.",
                    "example": 3900
                  },
                  "description": {
                    "type": "string",
                    "description": "Human-readable description of the verification result.",
                    "example": "Verified"
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false,
        "example": {
          "status": true,
          "data": {
            "status": {
              "code": 3900,
              "description": "Verified"
            }
          }
        }
      },
      "FullPhoneIntelligenceRequest": {
        "type": "object",
        "required": [
          "phoneNumber"
        ],
        "properties": {
          "phoneNumber": {
            "type": "string",
            "description": "Phone number to check, including country code (E.164).",
            "example": "+436501234567"
          }
        }
      },
      "FullPhoneIntelligenceResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates if the API request was successful."
          },
          "data": {
            "type": "object",
            "properties": {
              "referenceId": {
                "type": "string",
                "description": "Unique reference ID for the transaction."
              },
              "externalId": {
                "type": "string",
                "nullable": true,
                "description": "External reference ID (nullable)."
              },
              "status": {
                "type": "object",
                "properties": {
                  "updatedOn": {
                    "type": "string",
                    "description": "Timestamp of the last update (ISO 8601 format)."
                  },
                  "code": {
                    "type": "number",
                    "description": "Status code (e.g., 300 for success)."
                  },
                  "description": {
                    "type": "string",
                    "description": "Status description message."
                  }
                }
              },
              "numbering": {
                "type": "object",
                "properties": {
                  "original": {
                    "type": "object",
                    "properties": {
                      "completePhoneNumber": {
                        "type": "string"
                      },
                      "countryCode": {
                        "type": "string"
                      },
                      "phoneNumber": {
                        "type": "string"
                      }
                    }
                  },
                  "cleansing": {
                    "type": "object",
                    "properties": {
                      "call": {
                        "type": "object",
                        "properties": {
                          "countryCode": {
                            "type": "string"
                          },
                          "phoneNumber": {
                            "type": "string"
                          },
                          "cleansedCode": {
                            "type": "number"
                          },
                          "minLength": {
                            "type": "number"
                          },
                          "maxLength": {
                            "type": "number"
                          }
                        }
                      },
                      "sms": {
                        "type": "object",
                        "properties": {
                          "countryCode": {
                            "type": "string"
                          },
                          "phoneNumber": {
                            "type": "string"
                          },
                          "cleansedCode": {
                            "type": "number"
                          },
                          "minLength": {
                            "type": "number"
                          },
                          "maxLength": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "riskInsights": {
                "type": "object",
                "description": "Risk assessment details.",
                "properties": {
                  "status": {
                    "type": "number"
                  },
                  "category": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "a2P": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "p2P": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "numberType": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "ip": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  },
                  "email": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    }
                  }
                }
              },
              "phoneType": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              },
              "location": {
                "type": "object",
                "properties": {
                  "city": {
                    "type": "string",
                    "nullable": true
                  },
                  "state": {
                    "type": "string",
                    "nullable": true
                  },
                  "zip": {
                    "type": "string",
                    "nullable": true
                  },
                  "metroCode": {
                    "type": "string",
                    "nullable": true
                  },
                  "county": {
                    "type": "string",
                    "nullable": true
                  },
                  "country": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "iso2": {
                        "type": "string"
                      },
                      "iso3": {
                        "type": "string"
                      }
                    }
                  },
                  "coordinates": {
                    "type": "object",
                    "properties": {
                      "latitude": {
                        "type": "number",
                        "nullable": true
                      },
                      "longitude": {
                        "type": "number",
                        "nullable": true
                      }
                    }
                  },
                  "timeZone": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "utcOffsetMin": {
                        "type": "string"
                      },
                      "utcOffsetMax": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "carrier": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                }
              },
              "blocklisting": {
                "type": "object",
                "properties": {
                  "blocked": {
                    "type": "boolean"
                  },
                  "blockCode": {
                    "type": "number"
                  },
                  "blockDescription": {
                    "type": "string"
                  }
                }
              },
              "risk": {
                "type": "object",
                "description": "Overall risk score and recommendation.",
                "properties": {
                  "level": {
                    "type": "string",
                    "example": "medium-low"
                  },
                  "recommendation": {
                    "type": "string",
                    "example": "allow"
                  },
                  "score": {
                    "type": "number",
                    "example": 301
                  }
                }
              }
            }
          }
        }
      },
      "CreateSessionLinkRequest": {
        "type": "object",
        "required": [
          "email",
          "phoneNumber",
          "redirectUrl",
          "docUrl"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "User's email address.",
            "format": "email",
            "example": "user@example.com"
          },
          "phoneNumber": {
            "type": "string",
            "description": "User's phone number (E.164 format).",
            "example": "+436769556026",
            "pattern": "^\\+?[1-9]\\d{1,14}$"
          },
          "redirectUrl": {
            "type": "string",
            "description": "URL to redirect user to after signing.",
            "format": "uri",
            "example": "https://example.com/onboarding/success"
          },
          "docUrl": {
            "type": "string",
            "description": "Public HTTPS URL of the PDF to sign. Must be accessible without auth headers.",
            "format": "uri",
            "example": "https://example.com/pdf/onb-t3.pdf",
            "pattern": "^https://"
          },
          "signForms": {
            "type": "array",
            "description": "Signature fields in the PDF (AcroForm field IDs).",
            "items": {
              "type": "object",
              "required": [
                "fieldId",
                "actorId"
              ],
              "properties": {
                "fieldId": {
                  "type": "string",
                  "description": "AcroForm signature field ID."
                },
                "actorId": {
                  "type": "string",
                  "description": "Identifier of the signer (e.g., 'userToIdentify')."
                }
              }
            }
          },
          "fillForm": {
            "type": "array",
            "description": "Pre-fillable text fields in the PDF.",
            "items": {
              "type": "object",
              "required": [
                "fieldId",
                "value"
              ],
              "properties": {
                "fieldId": {
                  "type": "string",
                  "description": "AcroForm text field ID."
                },
                "value": {
                  "type": "string",
                  "description": "Value to insert (supports template vars like ${identification.firstName})."
                }
              }
            }
          }
        }
      },
      "CreateSessionLinkResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Whether the request was successful."
          },
          "data": {
            "type": "object",
            "required": [
              "url",
              "expiresAfter",
              "requestId"
            ],
            "properties": {
              "requestId": {
                "type": "string",
                "description": "Unique identifier for the created session.",
                "example": "123e4567-e89b-12d3-a456-426614174000"
              },
              "url": {
                "type": "string",
                "description": "URL to redirect user to the signing wizard.",
                "format": "uri",
                "example": "https://example.com/api/v2/actorTrip/urlback?t=EXAMPLE_TOKEN"
              },
              "expiresAfter": {
                "type": "string",
                "format": "date-time",
                "description": "ISO timestamp for session expiration.",
                "example": "2025-07-30T08:55:52.520909994Z"
              }
            }
          }
        }
      },
      "ConfigureWebhookRequest": {
        "type": "object",
        "required": [
          "webhookUrl"
        ],
        "properties": {
          "webhookUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to receive status pings.",
            "example": "https://example.com/webhooks/onboarding"
          }
        }
      },
      "ConfigureWebhookResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates if webhook was saved."
          },
          "data": {
            "type": "object",
            "required": [
              "id",
              "url",
              "createdAt"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Internal webhook ID.",
                "example": "74884fe3-c9e1-4462-b60f-c461e422000c"
              },
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Registered webhook URL.",
                "example": "https://example.com/webhooks/onboarding"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp of creation.",
                "example": "2025-05-08T16:39:28.339Z"
              }
            }
          }
        }
      },
      "WebhookEventPayload": {
        "type": "object",
        "description": "Payload your webhook endpoint will receive for status updates.",
        "required": [
          "requestId",
          "type",
          "status"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "ID of the related onboarding session.",
            "example": "xxxxxxxxx"
          },
          "type": {
            "type": "string",
            "description": "Event type.",
            "enum": [
              "STATUS_UPDATE"
            ],
            "example": "STATUS_UPDATE"
          },
          "status": {
            "type": "string",
            "description": "Outcome of the onboarding session.",
            "enum": [
              "COMPLETED",
              "FAILED",
              "CANCELLED"
            ],
            "example": "COMPLETED"
          }
        }
      },
      "VerificationResultResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "description": "Indicates whether the request succeeded."
          },
          "data": {
            "type": "object",
            "description": "Verification payload.",
            "properties": {
              "isVerified": {
                "type": "boolean",
                "description": "Whether the verification was successful."
              },
              "status": {
                "type": "string",
                "description": "High-level status of the verification.",
                "enum": [
                  "completed",
                  "cancelled",
                  "error"
                ]
              },
              "message": {
                "type": "string",
                "description": "Status message."
              },
              "requestId": {
                "type": "string",
                "description": "Unique ID for the verification request."
              },
              "signature": {
                "type": "object",
                "description": "Signature metadata and resources.",
                "properties": {
                  "content": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "method": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "pageMode": {
                          "type": "string"
                        },
                        "signedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "plainResource": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "type": {
                              "type": "string"
                            },
                            "family": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "subType": {
                              "type": "string"
                            },
                            "filename": {
                              "type": "string"
                            },
                            "metadata": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "mimeType": {
                              "type": "string"
                            },
                            "sizeBytes": {
                              "type": "integer"
                            },
                            "resourceUri": {
                              "type": "string"
                            },
                            "resourceUrl": {
                              "type": "string",
                              "format": "uri"
                            },
                            "urlValidBefore": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        },
                        "signedResource": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "type": {
                              "type": "string"
                            },
                            "family": {
                              "type": "string"
                            },
                            "status": {
                              "type": "string"
                            },
                            "filename": {
                              "type": "string"
                            },
                            "metadata": {
                              "type": "object",
                              "additionalProperties": true
                            },
                            "mimeType": {
                              "type": "string"
                            },
                            "sizeBytes": {
                              "type": "integer"
                            },
                            "resourceUri": {
                              "type": "string"
                            },
                            "resourceUrl": {
                              "type": "string",
                              "format": "uri"
                            },
                            "urlValidBefore": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "additionalProperties": true
                        }
                      },
                      "additionalProperties": true
                    }
                  }
                }
              },
              "identification": {
                "type": "object",
                "description": "KYC / identification results.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "actor": {
                    "type": "string",
                    "description": "Role of the actor in session (e.g., userToIdentify)."
                  },
                  "idSelf": {
                    "type": "object",
                    "properties": {
                      "artifacts": {
                        "type": "object",
                        "properties": {
                          "biometry": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "document": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          }
                        }
                      },
                      "biometryCheck": {
                        "type": "object",
                        "properties": {
                          "keysWithError": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "controlsSummary": {
                            "type": "integer"
                          }
                        }
                      },
                      "documentCheck": {
                        "type": "object",
                        "properties": {
                          "documentType": {
                            "type": "string"
                          },
                          "documentTypeFamily": {
                            "type": "string"
                          },
                          "keysWithError": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "controlsSummary": {
                            "type": "integer"
                          }
                        }
                      }
                    },
                    "additionalProperties": true
                  },
                  "source": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "personData": {
                    "type": "object",
                    "properties": {
                      "email": {
                        "type": "string",
                        "format": "email"
                      },
                      "gender": {
                        "type": "string"
                      },
                      "firstName": {
                        "type": "string"
                      },
                      "lastName": {
                        "type": "string"
                      },
                      "birthDate": {
                        "type": "string",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                      },
                      "birthPlace": {
                        "type": "string"
                      },
                      "nationality": {
                        "type": "string"
                      },
                      "phoneNumber": {
                        "type": "string"
                      },
                      "documentDetails": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string"
                          },
                          "number": {
                            "type": "string"
                          },
                          "issuedOn": {
                            "type": "string"
                          },
                          "expiryDate": {
                            "type": "string"
                          },
                          "issuanceCountry": {
                            "type": "string"
                          },
                          "issuanceAuthority": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "additionalProperties": true
                  },
                  "finalizedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "organizationId": {
                    "type": "string"
                  },
                  "validationDetail": {
                    "type": "object",
                    "description": "Per-field validation indicators.",
                    "additionalProperties": {
                      "type": "object",
                      "properties": {
                        "otpValidated": {
                          "type": "string"
                        },
                        "byRequestInput": {
                          "type": "string"
                        },
                        "requestMatched": {
                          "type": "string"
                        },
                        "byIdentificationSource": {
                          "type": "string"
                        }
                      },
                      "additionalProperties": true
                    }
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          }
        }
      },
      "CleansingDetails": {
        "type": "object",
        "properties": {
          "countryCode": {
            "type": "string"
          },
          "phoneNumber": {
            "type": "string"
          },
          "cleansedCode": {
            "type": "integer"
          },
          "minLength": {
            "type": "integer"
          },
          "maxLength": {
            "type": "integer"
          }
        }
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ValidateRequest": {
        "properties": {
          "iban": {
            "type": "string",
            "maxLength": 64,
            "title": "Iban",
            "examples": [
              "NL91 ABNA 0417 1643 00"
            ]
          }
        },
        "type": "object",
        "required": [
          "iban"
        ],
        "title": "ValidateRequest"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "Layer": {
        "type": "object",
        "required": [
          "name",
          "passed",
          "detail"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "syntax",
              "checksum",
              "bank",
              "existence"
            ]
          },
          "passed": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "true = passed, false = failed, null = not checkable or not applicable."
          },
          "detail": {
            "type": "string"
          }
        }
      },
      "ValidateResponse": {
        "type": "object",
        "required": [
          "input",
          "normalized",
          "valid",
          "layers",
          "existence_note"
        ],
        "properties": {
          "input": {
            "type": "string",
            "description": "The string as sent."
          },
          "normalized": {
            "type": "string",
            "description": "Spaces and hyphens removed, upper-cased."
          },
          "country": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2 prefix."
          },
          "valid": {
            "type": "boolean",
            "description": "true only when syntax and checksum both pass. Bank identification is informational; existence is never part of it."
          },
          "layers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Layer"
            }
          },
          "check_digits": {
            "type": [
              "string",
              "null"
            ]
          },
          "bank_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "account_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "bic": {
            "type": [
              "string",
              "null"
            ]
          },
          "bank_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "existence_note": {
            "type": "string",
            "description": "States that account existence and ownership are not checked."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string"
          }
        }
      },
      "Address": {
        "properties": {
          "formatted": {
            "type": "string",
            "title": "Formatted"
          },
          "street": {
            "type": "string",
            "title": "Street",
            "default": ""
          },
          "house_number": {
            "type": "string",
            "title": "House Number",
            "default": ""
          },
          "postal_code": {
            "type": "string",
            "title": "Postal Code",
            "default": ""
          },
          "city": {
            "type": "string",
            "title": "City",
            "default": ""
          },
          "district": {
            "type": "string",
            "title": "District",
            "default": ""
          },
          "state": {
            "type": "string",
            "title": "State",
            "default": ""
          },
          "country": {
            "type": "string",
            "title": "Country",
            "default": ""
          },
          "country_code": {
            "type": "string",
            "title": "Country Code",
            "default": ""
          },
          "lat": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Lat"
          },
          "lng": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Lng"
          },
          "precision": {
            "type": "string",
            "enum": [
              "house",
              "street",
              "area"
            ],
            "title": "Precision",
            "default": "area",
            "description": "house: a house number was resolved. street: street known, number not. area: city or postcode only. Gate on it rather than on empty fields."
          }
        },
        "type": "object",
        "required": [
          "formatted"
        ],
        "title": "Address"
      },
      "LatLng": {
        "properties": {
          "lat": {
            "type": "number",
            "title": "Lat"
          },
          "lng": {
            "type": "number",
            "title": "Lng"
          }
        },
        "type": "object",
        "required": [
          "lat",
          "lng"
        ],
        "title": "LatLng"
      },
      "PredictRequest": {
        "properties": {
          "input": {
            "type": "string",
            "maxLength": 200,
            "title": "Input",
            "examples": [
              "Musterstr 1 Ber"
            ],
            "description": "What the user has typed so far. Under 3 characters returns an empty suggestion list, not an error."
          },
          "countries": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Countries",
            "examples": [
              [
                "DE",
                "AT"
              ]
            ],
            "description": "ISO 3166-1 alpha-2 codes. Defaults to the service default countries (DE, AT). A country that is not enabled returns 422 with a string detail."
          },
          "session": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ],
            "title": "Session",
            "description": "Value returned by the previous predict call of the same address entry. Omit on the first call. A value that is not letters and digits is silently replaced with a new session."
          },
          "language": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8
              },
              {
                "type": "null"
              }
            ],
            "title": "Language",
            "description": "BCP 47 language tag. Defaults to de."
          },
          "near": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/LatLng"
              },
              {
                "type": "null"
              }
            ],
            "description": "Bias results toward a point."
          }
        },
        "type": "object",
        "required": [
          "input"
        ],
        "title": "PredictRequest"
      },
      "PredictResponse": {
        "properties": {
          "session": {
            "type": "string",
            "title": "Session",
            "description": "Send this back on every following predict and on the final resolve of the same address entry."
          },
          "suggestions": {
            "items": {
              "$ref": "#/components/schemas/Suggestion"
            },
            "type": "array",
            "title": "Suggestions"
          },
          "attribution": {
            "type": "string",
            "title": "Attribution",
            "default": "",
            "description": "Text you must display next to the suggestion list when it is non-empty. Required by the data licence."
          }
        },
        "type": "object",
        "required": [
          "session",
          "suggestions"
        ],
        "title": "PredictResponse"
      },
      "ResolveRequest": {
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 512,
            "title": "Id",
            "description": "A suggestions[].id from a predict response. Opaque; do not parse it."
          },
          "session": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 64
              },
              {
                "type": "null"
              }
            ],
            "title": "Session",
            "description": "The session value from predict. Send it so the interaction is grouped."
          },
          "language": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 8
              },
              {
                "type": "null"
              }
            ],
            "title": "Language",
            "description": "BCP 47 language tag. Defaults to de."
          }
        },
        "type": "object",
        "required": [
          "id"
        ],
        "title": "ResolveRequest"
      },
      "ResolveResponse": {
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "verification": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Verification"
              },
              {
                "type": "null"
              }
            ],
            "description": "Present only when a second reference source is enabled on the service (a service-wide setting); null otherwise."
          }
        },
        "type": "object",
        "required": [
          "address"
        ],
        "title": "ResolveResponse"
      },
      "Suggestion": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "description": "Opaque identifier. Store it if you must store something, never the text."
          },
          "text": {
            "type": "string",
            "title": "Text"
          },
          "main_text": {
            "type": "string",
            "title": "Main Text"
          },
          "secondary_text": {
            "type": "string",
            "title": "Secondary Text",
            "default": ""
          }
        },
        "type": "object",
        "required": [
          "id",
          "text",
          "main_text"
        ],
        "title": "Suggestion"
      },
      "Verification": {
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "differs",
              "unavailable"
            ],
            "title": "Status",
            "description": "confirmed: a second source agrees on postcode, city, house number and position (within 150 m). differs: it disagrees on the fields in differs. unavailable: no second source answered; treat as unverified, not as wrong."
          },
          "filled": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Filled",
            "default": [],
            "description": "Fields the primary source left empty and the second source supplied. Already merged into address."
          },
          "differs": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Differs",
            "default": [],
            "description": "Fields on which the sources disagree: postal_code, city, house_number, location."
          }
        },
        "type": "object",
        "required": [
          "status"
        ],
        "title": "Verification"
      },
      "AutocompleteError": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string"
          }
        },
        "title": "Error"
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "description": "Descriptive error message."
          }
        }
      },
      "AccountCheckRequest": {
        "type": "object",
        "required": [
          "accountId"
        ],
        "description": "`name` is required unless `companyIds` is present. Unknown fields are passed through to the upstream provider unchanged.",
        "properties": {
          "accountId": {
            "$ref": "#/components/schemas/AccountID"
          },
          "name": {
            "type": "string",
            "description": "Name of the account holder, as filled in by the end user. Not required when companyIds is present.",
            "maxLength": 140
          },
          "accountType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AccountRequestTypeEnum"
              }
            ],
            "description": "The type of the provided account: ORG for organisation or NP for natural person."
          },
          "birthDate": {
            "type": "string",
            "format": "date",
            "description": "Account holder's date of birth."
          },
          "companyIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyIDRequest"
            }
          }
        }
      },
      "AccountID": {
        "type": "object",
        "required": [
          "type",
          "value"
        ],
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AccountIDTypeEnum"
              }
            ],
            "description": "The type of the account identifier to be checked."
          },
          "value": {
            "type": "string",
            "description": "The identifier of the account to be checked. Maximum allowed length and pattern depend on the identifier type."
          },
          "bic": {
            "type": "string",
            "pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
            "description": "BIC for SWIFT use. Mandatory for the AccountNumber identifier type."
          },
          "secondaryReferenceId": {
            "type": "string",
            "pattern": "^.{1,140}$",
            "description": "Secondary reference data used together with a SortCodeAccountNumber identifier."
          }
        }
      },
      "AccountIDTypeEnum": {
        "type": "string",
        "enum": [
          "IBAN",
          "SortCodeAccountNumber",
          "AccountNumber",
          "ShortenedAccount",
          "Phone",
          "Email"
        ]
      },
      "CompanyIDRequest": {
        "type": "object",
        "required": [
          "companyIdType",
          "companyIdValue"
        ],
        "properties": {
          "companyIdType": {
            "$ref": "#/components/schemas/CompanyIDEnum"
          },
          "companyIdValue": {
            "type": "string",
            "description": "The value of the company identifier."
          }
        }
      },
      "CompanyIDEnum": {
        "type": "string",
        "enum": [
          "NL_KVK",
          "NL_KVK_BRANCH",
          "FR_SIREN",
          "FR_SIRET",
          "FR_TVAINTRA",
          "UK_CRN",
          "EU_VAT"
        ]
      },
      "AccountRequestTypeEnum": {
        "type": "string",
        "enum": [
          "NP",
          "ORG"
        ]
      },
      "AccountCheckResponse": {
        "type": "object",
        "required": [
          "nameMatchResult",
          "account"
        ],
        "description": "Returned as received from the upstream provider, with the scheme key removed (D10).",
        "properties": {
          "nameMatchResult": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExtendedMatchEnum"
              }
            ],
            "description": "The result of the account name check."
          },
          "dataUsedForMatching": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DataUsedForMatchingEnum"
              }
            ],
            "description": "Whether the data used for matching is VERIFIED (held at the bank) or DERIVED (based on historical transactions)."
          },
          "nameSuggestion": {
            "type": "string",
            "description": "A suggested account holder name, present when the result is a close match."
          },
          "birthDateMatchResult": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BasicMatchEnum"
              }
            ],
            "description": "The result of the birth date check, when requested."
          },
          "companyIds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyIDResponse"
            }
          },
          "account": {
            "$ref": "#/components/schemas/AccountResponse"
          },
          "schemeData": {
            "type": "object",
            "description": "Scheme-specific detail data, when returned."
          }
        }
      },
      "ExtendedMatchEnum": {
        "type": "string",
        "enum": [
          "MATCH",
          "CLOSE_MATCH",
          "NO_MATCH",
          "COULD_NOT_MATCH",
          "NAME_TOO_SHORT"
        ]
      },
      "BasicMatchEnum": {
        "type": "string",
        "enum": [
          "MATCH",
          "NO_MATCH",
          "COULD_NOT_MATCH"
        ]
      },
      "DataUsedForMatchingEnum": {
        "type": "string",
        "enum": [
          "VERIFIED",
          "DERIVED"
        ]
      },
      "CompanyIDResponse": {
        "type": "object",
        "required": [
          "type",
          "matchResult"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/CompanyIDEnum"
          },
          "matchResult": {
            "$ref": "#/components/schemas/BasicMatchEnum"
          },
          "knownAtBankId": {
            "type": "string",
            "description": "A suggested identifier known at the bank, returned when type is NL_KVK and matchResult is NO_MATCH."
          }
        }
      },
      "AccountResponse": {
        "type": "object",
        "properties": {
          "accountNumberValidation": {
            "$ref": "#/components/schemas/AccountNumberValidationEnum"
          },
          "paymentPreValidation": {
            "$ref": "#/components/schemas/PaymentPreValidationEnum"
          },
          "optedOut": {
            "type": "boolean"
          },
          "status": {
            "$ref": "#/components/schemas/AccountStatusEnum"
          },
          "iban": {
            "type": "string",
            "description": "The IBAN of the requested account. Only returned on a MATCH or CLOSE_MATCH when the identifier type was Email, Phone or ShortenedAccount."
          },
          "accountType": {
            "$ref": "#/components/schemas/AccountResponseTypeEnum"
          },
          "accountTypeMatchResult": {
            "$ref": "#/components/schemas/BasicMatchEnum"
          },
          "accountAge": {
            "$ref": "#/components/schemas/AccountAgeEnum"
          },
          "city": {
            "type": "string"
          },
          "jointAccount": {
            "type": "boolean"
          },
          "numberOfAccountHolders": {
            "type": "integer",
            "format": "int32"
          },
          "countryCode": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2
          },
          "switchingInformation": {
            "$ref": "#/components/schemas/SwitchingInformationResponse"
          }
        }
      },
      "AccountNumberValidationEnum": {
        "type": "string",
        "enum": [
          "VALID",
          "NOT_VALID"
        ]
      },
      "PaymentPreValidationEnum": {
        "type": "string",
        "enum": [
          "PASS",
          "WILL_FAIL",
          "WARNING"
        ]
      },
      "AccountStatusEnum": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "INACTIVE",
          "UNKNOWN",
          "NOT_SUPPORTED",
          "NOT_FOUND"
        ]
      },
      "AccountResponseTypeEnum": {
        "type": "string",
        "enum": [
          "NP",
          "ORG",
          "UNKNOWN"
        ]
      },
      "AccountAgeEnum": {
        "type": "string",
        "enum": [
          "LESS_THAN_ONE_WEEK",
          "ONE_WEEK_TO_ONE_MONTH",
          "ONE_MONTH_TO_THREE_MONTHS",
          "THREE_MONTHS_TO_SIX_MONTHS",
          "SIX_MONTHS_TO_ONE_YEAR",
          "GREATER_THAN_ONE_YEAR",
          "UNKNOWN"
        ]
      },
      "SwitchingInformationResponse": {
        "type": "object",
        "properties": {
          "switchingServiceForAccount": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "EXPIRED"
            ]
          },
          "switchedToIban": {
            "type": "string"
          }
        }
      },
      "ExpectedName": {
        "type": "object",
        "description": "Either `firstName` + `lastName` (natural person) or `companyName` (business account). Enables the name match.",
        "properties": {
          "firstName": {
            "type": "string",
            "example": "Erika"
          },
          "lastName": {
            "type": "string",
            "example": "Mustermann"
          },
          "companyName": {
            "type": "string",
            "example": "Beispiel GmbH"
          }
        }
      },
      "InitiateRequest": {
        "type": "object",
        "required": [
          "referenceId",
          "returnUrl"
        ],
        "properties": {
          "referenceId": {
            "type": "string",
            "description": "Your unique identifier for this session. Used for `POST /ais/status`.",
            "example": "onboarding-000123"
          },
          "returnUrl": {
            "type": "string",
            "format": "uri",
            "description": "Where the user lands after the hosted flow (success, cancel or error).",
            "example": "https://example.com/onboarding/return"
          },
          "language": {
            "type": "string",
            "enum": [
              "DE",
              "EN"
            ],
            "default": "DE",
            "description": "Language of the hosted flow."
          },
          "expectedName": {
            "$ref": "#/components/schemas/ExpectedName"
          },
          "expectedIban": {
            "type": "string",
            "description": "If set, the user must select this account in the flow. The result reports `ibanMatch`.",
            "example": "DE89370400440532013000"
          },
          "webhookUrl": {
            "type": "string",
            "format": "uri",
            "description": "Receives the result when the session reaches a final status.",
            "example": "https://example.com/webhooks/ais"
          },
          "nameMatchLogic": {
            "type": "string",
            "enum": [
              "fuzzy",
              "exact"
            ],
            "default": "fuzzy",
            "description": "`fuzzy` tolerates typos, transliterations and reordered name parts and can return `CLOSE_MATCH`. `exact` returns only `MATCH` or `NO_MATCH`."
          },
          "returnPii": {
            "type": "boolean",
            "default": true,
            "description": "`true` (PII output): the result includes IBAN, BIC, bank name and holder name(s). `false` (standard output): the result carries only the match results, decision, `xs2aReference` and `auditTrail`, without personal data."
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "default": "DE",
            "description": "Pre-selects the bank country in the flow (ISO 3166-1 alpha-2)."
          }
        }
      },
      "InitiateResponse": {
        "type": "object",
        "required": [
          "requestId",
          "redirectUrl",
          "expiresAt"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Identifier of the session on our side.",
            "example": "ais_7f3c2a9e5b1d4c08"
          },
          "redirectUrl": {
            "type": "string",
            "format": "uri",
            "description": "Hosted-flow URL. Redirect the user here."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "Session expiry (30 minutes), ISO 8601 UTC."
          }
        }
      },
      "StatusRequest": {
        "type": "object",
        "required": [
          "referenceId"
        ],
        "properties": {
          "referenceId": {
            "type": "string",
            "example": "onboarding-000123"
          }
        }
      },
      "Account": {
        "type": "object",
        "description": "Account data as read from the bank.",
        "properties": {
          "iban": {
            "type": "string",
            "example": "DE89370400440532013000"
          },
          "bic": {
            "type": "string",
            "example": "COBADEFFXXX"
          },
          "bankName": {
            "type": "string",
            "example": "Example Bank"
          },
          "holders": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Holder name(s) as returned by the bank. Several entries for joint accounts. Empty when the bank returns no name.",
            "example": [
              "Erika Mustermann"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "PRIVATE",
              "BUSINESS",
              "UNKNOWN"
            ],
            "description": "Account type where the bank reports it, otherwise `UNKNOWN`."
          },
          "userRole": {
            "type": "string",
            "enum": [
              "HOLDER",
              "CO_HOLDER",
              "AUTHORISED_USER",
              "UNKNOWN"
            ],
            "description": "The user's relationship to the account (holder, co-holder, or authorised user such as a power of attorney) where the bank reports it, otherwise `UNKNOWN`."
          }
        }
      },
      "NameMatch": {
        "type": "object",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "MATCH",
              "CLOSE_MATCH",
              "NO_MATCH",
              "NOT_CHECKED",
              "NOT_AVAILABLE"
            ],
            "description": "`MATCH`, `CLOSE_MATCH`, `NO_MATCH`; `NOT_CHECKED` when no `expectedName` was sent; `NOT_AVAILABLE` when the bank returned no holder name. For joint accounts the expected name is matched against every holder."
          },
          "score": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 100,
            "description": "Match score 0 to 100. `null` when the match did not run."
          }
        }
      },
      "AuditStep": {
        "type": "object",
        "properties": {
          "step": {
            "type": "string",
            "enum": [
              "BANK_SELECTION",
              "CONSENT",
              "SCA",
              "DATA_RETRIEVAL",
              "NAME_MATCH",
              "RESULT"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "StatusResponse": {
        "type": "object",
        "required": [
          "referenceId",
          "requestId",
          "status"
        ],
        "properties": {
          "referenceId": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "COMPLETED",
              "ABORTED",
              "EXPIRED",
              "FAILED"
            ],
            "description": "`PENDING` while the user is in the flow. `COMPLETED` when account data was retrieved. `ABORTED`, `EXPIRED` and `FAILED` are final without account data."
          },
          "statusReason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "USER_CANCELLED",
              "CONSENT_DENIED",
              "SCA_FAILED",
              "BANK_NOT_SUPPORTED",
              "BANK_UNAVAILABLE",
              "TIMEOUT",
              null
            ],
            "description": "Set when `status` is not `COMPLETED` or `PENDING`."
          },
          "xs2aReference": {
            "type": "string",
            "description": "Reference of the consent at the bank (XS2A). Present once consent was given."
          },
          "account": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Account"
              }
            ],
            "description": "The account the user selected in the flow. Omitted when `returnPii` is `false`."
          },
          "nameMatch": {
            "$ref": "#/components/schemas/NameMatch"
          },
          "ibanMatch": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the selected account equals `expectedIban`. `null` when none was sent."
          },
          "decision": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "CONFIRMED",
              "REVIEW",
              "NOT_CONFIRMED",
              null
            ],
            "description": "`CONFIRMED`: completed, and name and IBAN match where supplied. `REVIEW`: close match, or a name was requested but the bank returned none (`NOT_AVAILABLE`). `NOT_CONFIRMED`: no match, IBAN mismatch, or the session ended without data. `null` while `PENDING`."
          },
          "consentAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 UTC."
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 UTC."
          },
          "auditTrail": {
            "type": "array",
            "description": "Timestamped flow steps, for your records.",
            "items": {
              "$ref": "#/components/schemas/AuditStep"
            }
          }
        }
      },
      "AisIdentError404": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Reference ID not recognized"
          }
        }
      },
      "AisDataInitiateRequest": {
        "type": "object",
        "required": [
          "referenceId",
          "returnUrl"
        ],
        "properties": {
          "referenceId": {
            "type": "string",
            "description": "Your unique identifier for this session. Used for `POST /ais/data/status`.",
            "example": "affordability-000123"
          },
          "returnUrl": {
            "type": "string",
            "format": "uri",
            "description": "Where the user lands after the hosted flow (success, cancel or error).",
            "example": "https://example.com/affordability/return"
          },
          "language": {
            "type": "string",
            "enum": [
              "DE",
              "EN"
            ],
            "default": "DE",
            "description": "Language of the hosted flow."
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "default": "DE",
            "description": "Pre-selects the bank country in the flow (ISO 3166-1 alpha-2)."
          },
          "accessTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "ACCOUNTS",
                "BALANCES",
                "TRANSACTIONS"
              ]
            },
            "default": [
              "ACCOUNTS",
              "BALANCES",
              "TRANSACTIONS"
            ],
            "description": "The data the user consents to share. `ACCOUNTS` is always included. The consent screen lists exactly these types."
          },
          "transactionsFrom": {
            "type": "string",
            "format": "date",
            "description": "First booking date of the transactions to read (ISO 8601). Only with `TRANSACTIONS`. If omitted, the bank's default range applies.",
            "example": "2026-07-01"
          },
          "transactionsTo": {
            "type": "string",
            "format": "date",
            "description": "Last booking date of the transactions to read (ISO 8601). Defaults to today.",
            "example": "2026-09-30"
          },
          "webhookUrl": {
            "type": "string",
            "format": "uri",
            "description": "Receives the data when the session reaches a final status.",
            "example": "https://example.com/webhooks/ais-data"
          }
        }
      },
      "AisDataInitiateResponse": {
        "type": "object",
        "required": [
          "requestId",
          "redirectUrl",
          "expiresAt"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Identifier of the session on our side.",
            "example": "aisd_4b7e1c9a3f2d4a16"
          },
          "redirectUrl": {
            "type": "string",
            "format": "uri",
            "description": "Hosted-flow URL. Redirect the user here."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "Session expiry (30 minutes), ISO 8601 UTC."
          }
        }
      },
      "AisDataStatusRequest": {
        "type": "object",
        "required": [
          "referenceId"
        ],
        "properties": {
          "referenceId": {
            "type": "string",
            "example": "affordability-000123"
          }
        }
      },
      "Amount": {
        "type": "object",
        "required": [
          "value",
          "currency"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "Decimal amount as a string. Negative for debits.",
            "example": "-87.42"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 currency code.",
            "example": "EUR"
          }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "current": {
            "$ref": "#/components/schemas/Amount"
          },
          "available": {
            "$ref": "#/components/schemas/Amount"
          }
        }
      },
      "Transaction": {
        "type": "object",
        "required": [
          "id",
          "date",
          "amount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Transaction identifier as returned by the bank."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Booking date (ISO 8601)."
          },
          "description": {
            "type": "string",
            "description": "Remittance information or booking text as returned by the bank."
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          }
        }
      },
      "DataAccount": {
        "type": "object",
        "description": "One account the user shared, as read from the bank.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Account name as the bank shows it.",
            "example": "Girokonto"
          },
          "type": {
            "type": "string",
            "enum": [
              "CURRENT",
              "SAVINGS",
              "OTHER"
            ],
            "description": "Account type where the bank reports it, otherwise `OTHER`."
          },
          "iban": {
            "type": "string",
            "example": "DE89370400440532013000"
          },
          "bic": {
            "type": "string",
            "example": "TESTDEFFXXX"
          },
          "accountHolderName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Holder name as returned by the bank. `null` when the bank returns no name."
          },
          "balance": {
            "description": "Present when `BALANCES` was requested. `null` when the bank returned none.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Balance"
              },
              {
                "type": "null"
              }
            ]
          },
          "transactions": {
            "type": "array",
            "description": "Present when `TRANSACTIONS` was requested. Newest first.",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          }
        }
      },
      "DataAuditStep": {
        "type": "object",
        "properties": {
          "step": {
            "type": "string",
            "enum": [
              "BANK_SELECTION",
              "CONSENT",
              "SCA",
              "DATA_RETRIEVAL",
              "RESULT"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AisDataStatusResponse": {
        "type": "object",
        "required": [
          "referenceId",
          "requestId",
          "status"
        ],
        "properties": {
          "referenceId": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "COMPLETED",
              "ABORTED",
              "EXPIRED",
              "FAILED"
            ],
            "description": "`PENDING` while the user is in the flow. `COMPLETED` when account data was retrieved. `ABORTED`, `EXPIRED` and `FAILED` are final without account data."
          },
          "statusReason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "USER_CANCELLED",
              "CONSENT_DENIED",
              "SCA_FAILED",
              "BANK_NOT_SUPPORTED",
              "BANK_UNAVAILABLE",
              "TIMEOUT",
              null
            ],
            "description": "Set when `status` is not `COMPLETED` or `PENDING`."
          },
          "xs2aReference": {
            "type": "string",
            "description": "Reference of the consent at the bank (XS2A). Present once consent was given."
          },
          "accessTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "ACCOUNTS",
                "BALANCES",
                "TRANSACTIONS"
              ]
            },
            "description": "The access types the user consented to."
          },
          "accounts": {
            "type": "array",
            "description": "The accounts the user shared. Present when `status` is `COMPLETED`.",
            "items": {
              "$ref": "#/components/schemas/DataAccount"
            }
          },
          "consentAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 UTC."
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 UTC."
          },
          "auditTrail": {
            "type": "array",
            "description": "Timestamped flow steps, for your records.",
            "items": {
              "$ref": "#/components/schemas/DataAuditStep"
            }
          }
        }
      },
      "AisDataError404": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Reference ID not recognized"
          }
        }
      },
      "KybErrorResponse": {
        "type": "object",
        "description": "The exact shape depends on which layer produced the error; see each response's description. Not every field is present on every error. Clients branch on the HTTP status and on `code` when present, never on the text of `error` or `message`.",
        "properties": {
          "status": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Open set. Known: `DAILY_LIMIT_REACHED`, `RATE_LIMITED`, `COMPANY_NOT_IN_TRANSACTION` (details 400: the `company_id` is not held by that `transaction_id`; search again instead)."
          },
          "provider": {
            "type": "string",
            "description": "Set with `DAILY_LIMIT_REACHED`, and on a 429 from a provider."
          },
          "limit": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          }
        }
      },
      "KybSearchRequest": {
        "type": "object",
        "description": "Exactly one of `name`, `identifier` or `pick` (the variants below are mutually exclusive: a body with two of them, or none, matches no variant). `country` is required for a name search, and for an identifier search unless the scheme is `VAT` or `EUID`, where the value's two-letter prefix gives it (a `country` that conflicts with the prefix is a 400). A pick carries its own country.",
        "oneOf": [
          {
            "title": "By name",
            "required": [
              "name",
              "country"
            ],
            "properties": {
              "identifier": false,
              "pick": false
            }
          },
          {
            "title": "By identifier (VAT or EUID, country optional)",
            "required": [
              "identifier"
            ],
            "properties": {
              "identifier": {
                "required": [
                  "scheme"
                ],
                "properties": {
                  "scheme": {
                    "enum": [
                      "VAT",
                      "EUID"
                    ]
                  }
                }
              },
              "name": false,
              "pick": false
            }
          },
          {
            "title": "By identifier (other schemes, country required)",
            "required": [
              "identifier",
              "country"
            ],
            "properties": {
              "identifier": {
                "required": [
                  "scheme"
                ],
                "properties": {
                  "scheme": {
                    "enum": [
                      "REGISTRATION_NUMBER",
                      "LEI",
                      "DUNS",
                      "TAX",
                      "REA"
                    ]
                  }
                }
              },
              "name": false,
              "pick": false
            }
          },
          {
            "title": "Pick a suggestion",
            "required": [
              "pick"
            ],
            "properties": {
              "name": false,
              "identifier": false
            }
          }
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2
          },
          "identifier": {
            "type": "object",
            "required": [
              "scheme",
              "value"
            ],
            "properties": {
              "scheme": {
                "type": "string",
                "enum": [
                  "REGISTRATION_NUMBER",
                  "VAT",
                  "LEI",
                  "DUNS",
                  "TAX",
                  "EUID",
                  "REA"
                ],
                "description": "Validated by the service. Only the combinations in the operation description are supported; others are a 400."
              },
              "value": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          "pick": {
            "type": "object",
            "required": [
              "provider",
              "id",
              "name",
              "country"
            ],
            "properties": {
              "provider": {
                "type": "string",
                "description": "Provider code; the values are pending in the KYB API."
              },
              "id": {
                "type": "string",
                "minLength": 1,
                "description": "The `provider_id` of a suggestion (trimmed, at least one character)."
              },
              "name": {
                "type": "string",
                "minLength": 2
              },
              "country": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2
              }
            }
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO2. Required for a name search."
          },
          "court": {
            "type": "string",
            "minLength": 2,
            "description": "Register court, DE identifier searches."
          },
          "locality": {
            "type": "string",
            "minLength": 2,
            "description": "Required by the gateway when `country` is given and not DE, GB, FR or AT."
          },
          "provider": {
            "type": "string",
            "description": "Overrides routing by country. The returned `company_id` carries the provider's prefix. For an identifier search it must be a provider that serves the identifier's country (some providers). `example-provider` searches IT and FR by name; elsewhere `name` must be a VAT or registration number. A provider that is not enabled is a 400. Provider code; the values are pending in the KYB API."
          },
          "company_no": {
            "type": "string",
            "description": "Accepted by the gateway and ignored."
          },
          "min_token_overlap": {
            "type": "number",
            "description": "Accepted by the gateway and ignored."
          },
          "min_token_ratio": {
            "type": "number",
            "description": "Accepted by the gateway and ignored."
          }
        }
      },
      "KybSearchResponse": {
        "type": "object",
        "required": [
          "status",
          "data",
          "metadata"
        ],
        "properties": {
          "status": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KybSearchRow"
            }
          },
          "metadata": {
            "$ref": "#/components/schemas/SearchMetadata"
          },
          "suggestions": {
            "type": "array",
            "description": "Only on a name search that found nothing. Same items as `/kyb/suggest`.",
            "items": {
              "$ref": "#/components/schemas/KybSuggestion"
            }
          },
          "warnings": {
            "type": "array",
            "description": "Only with `suggestions`; sources that failed or timed out.",
            "items": {
              "$ref": "#/components/schemas/SuggestWarning"
            }
          }
        }
      },
      "KybSearchRow": {
        "type": "object",
        "required": [
          "transaction_id",
          "company_id",
          "name"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "format": "uuid",
            "description": "Identical on all rows of one response."
          },
          "company_id": {
            "type": "string",
            "description": "Provider-prefixed id (`xxxx:` then the provider's id). In the sandbox a UUID. Pass unchanged to details."
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "registration_number": {
            "type": [
              "string",
              "null"
            ]
          },
          "address_line": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "matched_by": {
            "type": "object",
            "description": "Set on identifier, pick and spelling-variant results.",
            "properties": {
              "scheme": {
                "type": "string",
                "description": "An identifier scheme, `PROVIDER_ID` or `NAME_VARIANT`. Open set."
              },
              "value": {
                "type": "string"
              }
            }
          },
          "warnings": {
            "type": "array",
            "description": "Set when the stored register number clashes with another company (`REGISTER_NUMBER_CLASH`).",
            "items": {
              "$ref": "#/components/schemas/Warning"
            }
          }
        }
      },
      "SearchMetadata": {
        "type": "object",
        "required": [
          "paid_provider_calls",
          "billable_features"
        ],
        "properties": {
          "paid_provider_calls": {
            "type": "object",
            "description": "Paid provider requests this search made, per provider. `{}` for a free search.",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "billable_features": {
            "type": "array",
            "description": "Always empty for search.",
            "items": {
              "type": "string"
            }
          },
          "warnings": {
            "type": "array",
            "description": "`PROVIDER_UNAVAILABLE_SERVED_FROM_STORAGE` when the provider could not answer and the rows are companies already stored from that provider. The rows can be out of date.",
            "items": {
              "$ref": "#/components/schemas/Warning"
            }
          }
        }
      },
      "KybSuggestResponse": {
        "type": "object",
        "required": [
          "status",
          "data"
        ],
        "properties": {
          "status": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/KybSuggestion"
            }
          },
          "warnings": {
            "type": "array",
            "description": "Present only when a source failed or took longer than 1.5 s.",
            "items": {
              "$ref": "#/components/schemas/SuggestWarning"
            }
          }
        }
      },
      "KybSuggestion": {
        "type": "object",
        "required": [
          "name",
          "country",
          "source"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "description": "Where the suggestion comes from, for example `store`, some providers, `sandbox`. Open set."
          },
          "identifier": {
            "type": "object",
            "description": "Present only when the source gave a number that parses.",
            "properties": {
              "scheme": {
                "type": "string"
              },
              "value": {
                "type": "string"
              }
            }
          },
          "court": {
            "type": "string",
            "description": "German register court, when the source knew it."
          },
          "lei": {
            "type": "string"
          },
          "provider_id": {
            "type": "string",
            "description": "Pass in `pick` when there is no `identifier`."
          },
          "score": {
            "type": "number"
          }
        }
      },
      "SuggestWarning": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "`SOURCE_FAILED` or `SOURCE_TIMEOUT`. Open set."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "KybDetailsRequest": {
        "type": "object",
        "required": [
          "transaction_id",
          "company_id"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "format": "uuid"
          },
          "company_id": {
            "type": "string",
            "minLength": 1,
            "description": "A `company_id` from a search under this `transaction_id`, or one read from a company already fetched under it. Live, it must match `^[a-z]{4}:.+$` (`xxxx:<CC>:<number>`), else 400. In the sandbox it is the fixture UUID a sandbox search returned, and the prefix pattern does not apply. An empty string is a 400 in both."
          },
          "visibility": {
            "type": "string",
            "enum": [
              "minimal",
              "basic",
              "extended"
            ],
            "default": "minimal",
            "description": "`basic` is an alias of `minimal`."
          },
          "include": {
            "$ref": "#/components/schemas/KybInclude"
          },
          "refresh_policy": {
            "type": "string",
            "enum": [
              "cached",
              "refresh"
            ],
            "default": "cached",
            "description": "`cached` reuses stored provider data younger than 30 days. `refresh` fetches again and is billed. Any other value is a 400 live; the sandbox does not validate it."
          },
          "timeout_ms": {
            "type": "number",
            "description": "Accepted by the gateway and ignored."
          }
        }
      },
      "KybInclude": {
        "type": "object",
        "description": "Packages to fetch. All default to false; see the operation description for what each gates.",
        "properties": {
          "officers": {
            "type": "boolean"
          },
          "addresses": {
            "type": "boolean"
          },
          "ownerships": {
            "type": "boolean"
          },
          "transparency": {
            "type": "boolean"
          },
          "documents": {
            "type": "boolean"
          },
          "financials": {
            "type": "boolean"
          },
          "representation_chain": {
            "type": "boolean",
            "description": "Billed feature. For a Austrian GmbH & Co KG: the Komplementaer and the people who sign for it, with the combined signing rule. Costs up to one extra provider report per Komplementaer level (at most 3 per request, 2 levels), reports stored in the last 30 days are free. Implies `officers`."
          }
        }
      },
      "KybDetailsResponse": {
        "type": "object",
        "required": [
          "status",
          "data",
          "metadata"
        ],
        "properties": {
          "status": {
            "type": "boolean"
          },
          "data": {
            "description": "`UnifiedCompany` for visibility `minimal` or `basic`, `UnifiedCompanyExtended` for `extended`.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/UnifiedCompany"
              },
              {
                "$ref": "#/components/schemas/UnifiedCompanyExtended"
              }
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/DetailsMetadata"
          }
        }
      },
      "DetailsMetadata": {
        "type": "object",
        "required": [
          "paid_provider_calls",
          "billable_features"
        ],
        "properties": {
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "description": "Match score of the search row, 0 to 1. Null for some providers and for a company reached by walking a chain."
          },
          "completeness": {
            "type": [
              "number",
              "null"
            ],
            "description": "Data quality score, 0 to 1. Null for example-provider. Reduced by 20 percent when `OWNERSHIP_PARTIAL` is reported."
          },
          "source": {
            "type": "string",
            "description": "Provider label, for example `example-provider`. Open set."
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Time of this response."
          },
          "from_cache": {
            "type": "boolean",
            "description": "True when the root company payload was reused from storage instead of fetched. It says nothing else: it is not \"no provider call\" and never means zero cost. A chain step or another slice can be fetched (and billed) on a call whose root was reused, and a fully reused call that returns a chain still lists `representation_chain` in `billable_features`. Read the cost from `paid_provider_calls` and `billable_features`."
          },
          "source_fetched_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Time the root company payload was fetched. It is not the oldest payload across the response: each `representation_chain` step carries its own `fetched_at`."
          },
          "warnings": {
            "description": "Slices that failed or did not finish, and other notes. For example-provider this is one string (empty when nothing to report); for every other provider an array, absent when empty.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Warning"
                }
              }
            ]
          },
          "paid_provider_calls": {
            "type": "object",
            "description": "Paid provider requests this call made, per provider, for example `{\"example-provider\": 2}`; `{}` when everything was reused. Counted as the daily spend limit counts them. A run that continues in the background after the answer is not in it.",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "billable_features": {
            "type": "array",
            "description": "Billed features used by this call. At present `[\"representation_chain\"]` when at least one chain step was read, else `[]`. Open set.",
            "items": {
              "type": "string"
            }
          },
          "sandbox": {
            "type": "boolean",
            "description": "Sandbox only. Always true there."
          },
          "note": {
            "type": "string",
            "description": "Sandbox only. States what the sandbox does not simulate."
          }
        }
      },
      "Warning": {
        "type": "object",
        "description": "Consumers key on `code`, never on `message`. The set of codes is open. Known: `PENDING_SLICE` (a section did not finish within the bound; a later call completes it), `SLICE_FAILED` (the provider run failed; not bought again for 24 hours unless `refresh`), `OWNERSHIP_PARTIAL` (the ownership walk stopped early; `stop_reason`, `max_depth` say why), `REGISTER_NUMBER_CLASH`, `REGISTER_DOCUMENT_UNAVAILABLE` (the register document holding a signing rule could not be read; nothing was bought), `REPRESENTATION_CHAIN_UNRESOLVED` (a chain step could not be resolved; `reason` says why), `PROVIDER_UNAVAILABLE_SERVED_FROM_STORAGE`.",
        "properties": {
          "code": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "section": {
            "type": "string",
            "description": "`profile`, `officers`, `ownership`, `financials`, `transparency`, `signature`, `representation_chain`. Open set."
          },
          "message": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "stop_reason": {
            "type": "string"
          },
          "stop_reason_detail": {
            "type": "string"
          },
          "max_depth": {
            "type": "integer"
          },
          "level": {
            "type": "integer"
          },
          "company_id": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "PartialDate": {
        "type": "string",
        "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$",
        "description": "YYYY, YYYY-MM or YYYY-MM-DD."
      },
      "Iso2": {
        "type": "string",
        "pattern": "^[A-Z]{2}$"
      },
      "Money": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "number"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          }
        }
      },
      "Share": {
        "description": "Percent. An exact figure or a band.",
        "oneOf": [
          {
            "type": "object",
            "required": [
              "exact"
            ],
            "properties": {
              "exact": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              }
            }
          },
          {
            "type": "object",
            "required": [
              "min",
              "max"
            ],
            "properties": {
              "min": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              },
              "max": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "PersonName": {
        "type": "object",
        "required": [
          "full"
        ],
        "properties": {
          "full": {
            "type": "string"
          },
          "given": {
            "type": "string"
          },
          "middle": {
            "type": "string"
          },
          "family": {
            "type": "string"
          },
          "native_script": {
            "type": "string"
          }
        }
      },
      "NativeValue": {
        "type": "object",
        "description": "The provider's own text, untouched.",
        "properties": {
          "value": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "The provider's own code for the value."
          }
        }
      },
      "Localized": {
        "type": "object",
        "description": "`native` is the provider's text; `modeled` is our normalised value with the scheme it follows (legal form: ISO 20275 code; officer role: ISO 5009 code, or `idcanopy` when the provider sent none). Read `modeled` when present, else `native`. Scheme values are open.",
        "properties": {
          "native": {
            "$ref": "#/components/schemas/NativeValue"
          },
          "modeled": {
            "type": "object",
            "required": [
              "value",
              "scheme"
            ],
            "properties": {
              "value": {
                "type": "string"
              },
              "scheme": {
                "type": "string"
              }
            }
          }
        }
      },
      "KybAddress": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "registered",
              "business",
              "correspondence",
              "residential"
            ]
          },
          "single_line": {
            "type": "string"
          },
          "structured": {
            "type": "object",
            "properties": {
              "line1": {
                "type": "string"
              },
              "line2": {
                "type": "string"
              },
              "street": {
                "type": "string"
              },
              "house_number": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "postal_code": {
                "type": "string"
              },
              "region": {
                "type": "string"
              },
              "country": {
                "$ref": "#/components/schemas/Iso2"
              },
              "care_of": {
                "type": "string"
              },
              "po_box": {
                "type": "string"
              }
            }
          },
          "geo": {
            "type": "object",
            "properties": {
              "lat": {
                "type": "number"
              },
              "lon": {
                "type": "number"
              }
            }
          }
        }
      },
      "Identifier": {
        "type": "object",
        "required": [
          "scheme",
          "value"
        ],
        "properties": {
          "scheme": {
            "type": "string",
            "description": "Open. Known: REGISTRATION_NUMBER, VAT, LEI, DUNS, TAX, EUID, REA."
          },
          "value": {
            "type": "string"
          },
          "country": {
            "$ref": "#/components/schemas/Iso2"
          },
          "issuer": {
            "type": "object",
            "properties": {
              "authority": {
                "type": "string"
              },
              "court": {
                "type": "string"
              },
              "register_type": {
                "type": "string",
                "description": "For example HRA, HRB, PR, GnR, VR, FN."
              }
            }
          },
          "valid_from": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "valid_to": {
            "$ref": "#/components/schemas/PartialDate"
          }
        }
      },
      "IndustryCode": {
        "type": "object",
        "required": [
          "scheme",
          "code"
        ],
        "properties": {
          "scheme": {
            "type": "string",
            "description": "For example NACE, SIC, NAICS, WZ2008, ATECO, NAF."
          },
          "code": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "rank": {
            "type": "integer",
            "minimum": 1,
            "description": "1 is the primary activity."
          }
        }
      },
      "Contact": {
        "type": "object",
        "required": [
          "type",
          "value"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "phone",
              "email",
              "pec",
              "fax",
              "website",
              "social"
            ]
          },
          "value": {
            "type": "string"
          },
          "rank": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "SignatureRule": {
        "type": "object",
        "required": [
          "basis"
        ],
        "properties": {
          "native": {
            "$ref": "#/components/schemas/NativeValue"
          },
          "modeled": {
            "type": "object",
            "description": "Structured rule, so a client can decide \"can this person sign alone\" without parsing text. Never guessed. Absent when neither the register text nor the legal form supports a rule; for such an officer `basis` still says where the answer stands and the `native` side is absent too.",
            "properties": {
              "quality": {
                "type": "string",
                "enum": [
                  "individual",
                  "joint"
                ]
              },
              "min_signatories": {
                "type": "integer",
                "minimum": 1
              },
              "jointly_with_roles": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "represented_by_roles": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Roles that represent the company, only where the register text says so."
              },
              "conditions": {
                "type": "array",
                "description": "Alternatives that depend on the number of directors. When present, `quality` and `min_signatories` are unset.",
                "items": {
                  "type": "object",
                  "properties": {
                    "when": {
                      "type": "string",
                      "enum": [
                        "sole_director",
                        "several_directors"
                      ]
                    },
                    "quality": {
                      "type": "string",
                      "enum": [
                        "individual",
                        "joint"
                      ]
                    },
                    "min_signatories": {
                      "type": "integer"
                    },
                    "jointly_with_roles": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "scheme": {
                "type": "string"
              }
            }
          },
          "is_legal_representative": {
            "type": "boolean"
          },
          "basis": {
            "type": "string",
            "description": "How the rule was obtained. Open set: clients must ignore values they do not know.\n- `register_text`: read from the register's wording. `native` holds that wording and `modeled` is parsed from it.\n- `provider_asserted`: the provider states the rule in a field.\n- `inferred_heuristic`: a heuristic estimate, not firm.\n- `legal_form`: derived from the legal form by law, with no register text. Example: the Inhaber of a sole trader (AT e.U., DE e.K.) represents alone (`modeled.quality: individual`). No `native` text exists for it.\n\nexample-provider answers with no rule text carry no `modeled` rule: the rule is unknown, with a reason, and is never guessed as `joint`.\n\nProvenance: `native` is the text exactly as the source gives it; `modeled` is IDCanopy's structured reading of it. A rule from `register_text` has both; a `legal_form` rule has only `modeled`."
          },
          "producer": {
            "type": "string"
          }
        }
      },
      "Party": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "source_keys",
          "identifiers",
          "addresses"
        ],
        "description": "A person or company, once. Officerships and shareholdings point to it by `id`.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "person",
              "company"
            ]
          },
          "company_id": {
            "type": "string",
            "format": "uuid"
          },
          "source_keys": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "name": {
            "$ref": "#/components/schemas/PersonName"
          },
          "date_of_birth": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "birthplace": {
            "type": "string"
          },
          "country_of_birth": {
            "$ref": "#/components/schemas/Iso2"
          },
          "nationality": {
            "type": "string"
          },
          "country_of_residence": {
            "$ref": "#/components/schemas/Iso2"
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KybAddress"
            }
          },
          "pep_status": {
            "type": "string",
            "enum": [
              "none",
              "pep",
              "rca",
              "sca"
            ]
          }
        }
      },
      "Officership": {
        "type": "object",
        "required": [
          "id",
          "company_id",
          "party_id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "company_id": {
            "type": "string"
          },
          "party_id": {
            "type": "string",
            "format": "uuid"
          },
          "role": {
            "$ref": "#/components/schemas/Localized"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          },
          "from": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "to": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "signature_right": {
            "$ref": "#/components/schemas/SignatureRule"
          },
          "can_represent": {
            "$ref": "#/components/schemas/CanRepresent"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        }
      },
      "CanRepresent": {
        "type": "object",
        "description": "Whether this officership's role may represent the company at all. Derived, not a claim, and the same plain object in the `minimal` and `extended` views. It is not the signature count: how many people must sign stays `signature_right`. Returned with `include.officers` (no extra include) and not billed. Enabled per customer; not enabled in production yet; clients must not require it. When it is not enabled for you the key is absent, never null.",
        "required": [
          "value",
          "basis",
          "rule_id",
          "source",
          "note"
        ],
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": "string",
            "description": "Open set: clients must treat a value they do not know as `unknown`.\n- `yes`: the role represents the company under the cited norm.\n- `no`: the role never does (for example a supervisory board member, a limited partner, an auditor).\n- `unknown`: the combination is not covered. Never guessed: version 1 covers AT, DE and GB; any other country, role or legal form is `unknown`.",
            "enum": [
              "yes",
              "no",
              "unknown"
            ]
          },
          "basis": {
            "type": "string",
            "description": "Open set: clients must ignore values they do not know. `role_rule` (a rule for this role, country and legal form), `legal_form` (a sole trader's owner, from the legal form) or `unknown`.",
            "enum": [
              "role_rule",
              "legal_form",
              "unknown"
            ]
          },
          "rule_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "`<COUNTRY>.<FORM>.<ROLE>.v<n>`, for example `AT.KG.KOMPLEMENTAER.v1`. A match through a fallback adds a suffix: `@fn:<code>` (AT: the register's function code decided) or `@<provider>:<native>` (a provider's own role label decided). `null` when `value` is `unknown`."
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "description": "The norm the rule rests on, for example `UGB § 170`. `null` when unknown."
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Short English remark, or `null`. `null` is allowed inside this object only."
          }
        },
        "example": {
          "value": "yes",
          "basis": "role_rule",
          "rule_id": "AT.KG.KOMPLEMENTAER.v1",
          "source": "UGB §§ 125, 161, 170",
          "note": "signs through its own organs (representation chain)"
        }
      },
      "Shareholding": {
        "type": "object",
        "required": [
          "id",
          "owner_party_id",
          "target_company_id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_party_id": {
            "type": "string",
            "format": "uuid"
          },
          "target_company_id": {
            "type": "string"
          },
          "share": {
            "$ref": "#/components/schemas/Share"
          },
          "voting_share": {
            "$ref": "#/components/schemas/Share"
          },
          "capital": {
            "$ref": "#/components/schemas/Money"
          },
          "shares_count": {
            "type": "integer",
            "minimum": 0
          },
          "verbal": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "shares",
                    "voting"
                  ]
                },
                "text": {
                  "$ref": "#/components/schemas/Localized"
                }
              }
            }
          },
          "control": {
            "type": "object",
            "description": "Control that is not a percentage.",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "votes",
                  "board",
                  "contract",
                  "other"
                ]
              },
              "text": {
                "$ref": "#/components/schemas/NativeValue"
              }
            }
          },
          "as_of": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "basis": {
            "type": "string",
            "enum": [
              "register_text",
              "provider_asserted",
              "inferred_heuristic",
              "legal_form"
            ],
            "description": "How the holding was obtained, set only on a holding IDCanopy derived; absent on a holding the provider reported. Scalar in both views (never `{claims, resolved}`). Open enum: clients must ignore values they do not know.\n- `legal_form`: derived from the legal form. The Inhaber of a registered sole trader owns 100% (`share.exact: 100`, `interest_type: sole_proprietor`). This is not a UBO assessment and creates no `ubo` entry. Returned only with `include.ownerships`.\n- `register_text`, `provider_asserted`, `inferred_heuristic`: as for `SignatureRule.basis`."
          },
          "role": {
            "$ref": "#/components/schemas/Localized"
          },
          "interest_type": {
            "type": "string"
          }
        }
      },
      "Ubo": {
        "type": "object",
        "required": [
          "party_id",
          "company_id",
          "is_ubo",
          "basis",
          "source",
          "fetched_at"
        ],
        "properties": {
          "party_id": {
            "type": "string",
            "format": "uuid"
          },
          "company_id": {
            "type": "string"
          },
          "is_ubo": {
            "type": "string",
            "enum": [
              "yes",
              "no",
              "potential"
            ]
          },
          "basis": {
            "type": "string",
            "enum": [
              "declared",
              "computed",
              "fictitious"
            ]
          },
          "rule_applied": {
            "type": "string",
            "enum": [
              "25pct",
              "jurisdictional",
              "custom"
            ]
          },
          "explanations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Financials": {
        "type": "object",
        "required": [
          "company_id",
          "fiscal_year"
        ],
        "description": "One row per company and fiscal year.",
        "properties": {
          "company_id": {
            "type": "string"
          },
          "fiscal_year": {
            "type": "integer"
          },
          "revenue": {
            "$ref": "#/components/schemas/Money"
          },
          "ebit": {
            "$ref": "#/components/schemas/Money"
          },
          "ebitda": {
            "$ref": "#/components/schemas/Money"
          },
          "net_income": {
            "$ref": "#/components/schemas/Money"
          },
          "assets": {
            "$ref": "#/components/schemas/Money"
          },
          "liabilities": {
            "$ref": "#/components/schemas/Money"
          },
          "equity": {
            "$ref": "#/components/schemas/Money"
          },
          "headcount": {
            "type": "integer",
            "minimum": 0
          },
          "cash": {
            "$ref": "#/components/schemas/Money"
          },
          "receivables": {
            "$ref": "#/components/schemas/Money"
          },
          "derived": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DerivedFigure"
            }
          }
        }
      },
      "DerivedFigure": {
        "type": "object",
        "required": [
          "name",
          "value",
          "unit",
          "basis",
          "source_filing"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "number"
          },
          "unit": {
            "type": "string"
          },
          "basis": {
            "type": "string",
            "enum": [
              "filed",
              "idcanopy_calculated"
            ]
          },
          "formula": {
            "type": "string",
            "description": "Required when `basis` is `idcanopy_calculated`."
          },
          "source_filing": {
            "type": "string"
          }
        },
        "if": {
          "required": [
            "basis"
          ],
          "properties": {
            "basis": {
              "const": "idcanopy_calculated"
            }
          }
        },
        "then": {
          "required": [
            "formula"
          ],
          "properties": {
            "formula": {
              "type": "string"
            }
          }
        }
      },
      "Document": {
        "type": "object",
        "required": [
          "id",
          "company_id",
          "source",
          "fetched_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "company_id": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "For example `register_extract`. Open set."
          },
          "code": {
            "type": "string"
          },
          "file_url": {
            "type": "string"
          },
          "file_hash": {
            "type": "string"
          },
          "file_url_hosting": {
            "type": "string",
            "description": "`provider_hosted`: the link is the provider's, not ours."
          },
          "file_url_expires": {
            "type": "boolean",
            "description": "True when the link is time-limited. Download promptly."
          },
          "as_of": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Filing": {
        "type": "object",
        "required": [
          "id",
          "company_id",
          "source"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "company_id": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "registry": {
            "type": "string"
          },
          "filed_at": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "category": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "document": {
            "$ref": "#/components/schemas/Document"
          }
        }
      },
      "Relationship": {
        "type": "object",
        "required": [
          "type",
          "from_company_id",
          "to_company_id",
          "source",
          "fetched_at"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "`parent`, `subsidiary`, `affiliate`, `partner`. Open set."
          },
          "from_company_id": {
            "type": "string"
          },
          "to_company_id": {
            "type": "string"
          },
          "as_of": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "source": {
            "type": "string"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Group": {
        "type": "object",
        "properties": {
          "is_headquarter": {
            "type": "boolean"
          },
          "is_global_ultimate": {
            "type": "boolean"
          },
          "is_domestic_ultimate": {
            "type": "boolean"
          },
          "is_subsidiary": {
            "type": "boolean"
          },
          "belongs_to_group": {
            "type": "boolean"
          },
          "group_name": {
            "type": "string"
          },
          "holding_company_name": {
            "type": "string"
          }
        }
      },
      "EffectiveRule": {
        "type": "object",
        "required": [
          "basis",
          "modeled"
        ],
        "properties": {
          "basis": {
            "type": "string",
            "const": "derived"
          },
          "modeled": {
            "type": "object",
            "required": [
              "quality",
              "min_signatories",
              "scheme"
            ],
            "properties": {
              "quality": {
                "type": "string",
                "enum": [
                  "individual",
                  "joint"
                ]
              },
              "min_signatories": {
                "type": "integer",
                "minimum": 1
              },
              "jointly_with_roles": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "scheme": {
                "type": "string"
              }
            }
          }
        }
      },
      "RepresentationStep": {
        "type": "object",
        "required": [
          "level",
          "represented_company_id",
          "basis",
          "source",
          "status",
          "representative"
        ],
        "description": "One step of the signing chain of a GmbH & Co KG: `representative` is the company that represents `represented_company_id`; `representatives` are the people that company's own register lists. Always resolved values, in both views. An unresolved step is listed with its `reason`, never dropped, and has a matching `REPRESENTATION_CHAIN_UNRESOLVED` warning.",
        "properties": {
          "level": {
            "type": "integer",
            "minimum": 1
          },
          "represented_company_id": {
            "type": "string"
          },
          "basis": {
            "type": "string",
            "description": "`register_text`. Open set."
          },
          "source": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "resolved",
              "unresolved"
            ]
          },
          "reason": {
            "type": "string",
            "description": "Why a step is unresolved. Known: no_provider_id, fetch_failed, daily_limit, depth_limit, fetch_limit, no_representatives, company_representative. Open set."
          },
          "rule_reason": {
            "type": "string",
            "description": "`register_document_unavailable`: the representative's own rule is absent because the register document could not be read."
          },
          "fetch": {
            "type": "string",
            "enum": [
              "fetched",
              "reused"
            ],
            "description": "`fetched`: the report was bought for this request. `reused`: read from storage (at most 30 days old), see `fetched_at`. Absent when no report was read."
          },
          "fetched_at": {
            "type": "string"
          },
          "representative": {
            "type": "object",
            "required": [
              "name",
              "identifiers"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "company_id": {
                "type": "string"
              },
              "identifiers": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Identifier"
                }
              },
              "role": {
                "$ref": "#/components/schemas/Localized"
              },
              "signature_right": {
                "$ref": "#/components/schemas/SignatureRule"
              }
            }
          },
          "company_rule": {
            "$ref": "#/components/schemas/SignatureRule"
          },
          "representatives": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name"
              ],
              "properties": {
                "name": {
                  "$ref": "#/components/schemas/PersonName"
                },
                "date_of_birth": {
                  "$ref": "#/components/schemas/PartialDate"
                },
                "role": {
                  "$ref": "#/components/schemas/Localized"
                },
                "from": {
                  "$ref": "#/components/schemas/PartialDate"
                },
                "signature_right": {
                  "$ref": "#/components/schemas/SignatureRule"
                },
                "effective_rule": {
                  "$ref": "#/components/schemas/EffectiveRule"
                },
                "effective_rule_reason": {
                  "type": "string",
                  "description": "Why `effective_rule` is absent: register_document_unavailable, no_komplementaer_rule, no_person_rule, rule_not_modeled. Sole signing is never assumed. Open set."
                }
              }
            }
          }
        }
      },
      "UnifiedCompany": {
        "type": "object",
        "description": "The company in the `minimal` view. snake_case. A value that is not known is an absent key, never null. Lists that hold nothing are `[]`. Provider-specific ids are in `source_ids`. `company_id` is the same value as the `company_id` of the search.",
        "required": [
          "company_id",
          "country",
          "source_ids",
          "parties",
          "officerships",
          "shareholdings",
          "ubo",
          "financials",
          "documents",
          "filings",
          "relationships",
          "trading_names",
          "addresses",
          "identifiers",
          "industry_codes",
          "contacts"
        ],
        "properties": {
          "company_id": {
            "type": "string"
          },
          "country": {
            "$ref": "#/components/schemas/Iso2"
          },
          "source_ids": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "source",
                "source_key"
              ],
              "properties": {
                "source": {
                  "type": "string"
                },
                "source_key": {
                  "type": "string"
                },
                "match_score": {
                  "type": "number"
                }
              }
            }
          },
          "legal_name": {
            "type": "string"
          },
          "trading_names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "status": {
            "$ref": "#/components/schemas/Localized"
          },
          "legal_form": {
            "$ref": "#/components/schemas/Localized"
          },
          "incorporation_date": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "registration_date": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "dissolution_date": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "share_capital": {
            "$ref": "#/components/schemas/Money"
          },
          "business_purpose": {
            "$ref": "#/components/schemas/Localized"
          },
          "free_float": {
            "$ref": "#/components/schemas/Share"
          },
          "ownership_walk": {
            "type": "object",
            "description": "Why the ownership walk ended. Only with `include.ownerships`, example-provider.",
            "properties": {
              "max_depth": {
                "type": "integer",
                "minimum": 0
              },
              "stop_reason": {
                "type": "string"
              },
              "stop_reason_detail": {
                "type": "string"
              },
              "extracted_at": {
                "type": "string",
                "format": "date-time"
              },
              "root_company_id": {
                "type": "string"
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KybAddress"
            }
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          },
          "industry_codes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IndustryCode"
            }
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          },
          "signature_rules": {
            "$ref": "#/components/schemas/SignatureRule"
          },
          "group": {
            "$ref": "#/components/schemas/Group"
          },
          "registered_address": {
            "$ref": "#/components/schemas/KybAddress"
          },
          "business_address": {
            "$ref": "#/components/schemas/KybAddress"
          },
          "registration_number": {
            "$ref": "#/components/schemas/Identifier"
          },
          "estimated_fields": {
            "type": "array",
            "description": "Fields whose chosen value is not firm: a key field not from a register, or a value its source marked as an estimate.",
            "items": {
              "type": "string"
            }
          },
          "field_notes": {
            "type": "object",
            "description": "Minimal view only. A source's remark for a field, by field name.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "representation_chain": {
            "type": "array",
            "description": "Only with `include.representation_chain`.",
            "items": {
              "$ref": "#/components/schemas/RepresentationStep"
            }
          },
          "parties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Party"
            }
          },
          "officerships": {
            "type": "array",
            "description": "Empty unless requested (see the operation description).",
            "items": {
              "$ref": "#/components/schemas/Officership"
            }
          },
          "shareholdings": {
            "type": "array",
            "description": "Empty unless `include.ownerships`.",
            "items": {
              "$ref": "#/components/schemas/Shareholding"
            }
          },
          "ubo": {
            "type": "array",
            "description": "Empty unless `include.transparency` (example-provider Italy).",
            "items": {
              "$ref": "#/components/schemas/Ubo"
            }
          },
          "financials": {
            "type": "array",
            "description": "Empty unless `include.financials` (and a provider with figures).",
            "items": {
              "$ref": "#/components/schemas/Financials"
            }
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          },
          "filings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Filing"
            }
          },
          "relationships": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Relationship"
            }
          }
        }
      },
      "Claim": {
        "type": "object",
        "required": [
          "value",
          "source",
          "fetched_at"
        ],
        "description": "One source's answer for one field.",
        "properties": {
          "value": {
            "description": "The value, shaped as the field is in the `minimal` view."
          },
          "source": {
            "type": "string"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the provider section the value was read from was fetched."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "verification_status": {
            "type": "string",
            "enum": [
              "direct",
              "cross_verified",
              "estimated",
              "self_proclaimed"
            ]
          },
          "as_of": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "snapshot_id": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "ResolvedField": {
        "type": "object",
        "required": [
          "value",
          "method",
          "claim_index",
          "conflicts"
        ],
        "properties": {
          "value": {
            "description": "The chosen value, shaped as the field is in the `minimal` view."
          },
          "method": {
            "type": "string",
            "enum": [
              "authority",
              "recency",
              "consensus",
              "heuristic",
              "manual_review"
            ]
          },
          "claim_index": {
            "type": "integer",
            "minimum": 0,
            "description": "Index in `claims` of the claim that won."
          },
          "conflicts": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of distinct competing values that lost."
          },
          "estimated": {
            "type": "boolean",
            "const": true
          }
        }
      },
      "ExtendedField": {
        "type": "object",
        "required": [
          "claims",
          "resolved"
        ],
        "properties": {
          "claims": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "resolved": {
            "$ref": "#/components/schemas/ResolvedField"
          }
        }
      },
      "UnifiedCompanyExtended": {
        "type": "object",
        "description": "The company in the `extended` view. Same keys and the same meaning as `UnifiedCompany`, with two differences. Every scalar or object field that is a plain value in `minimal` is an `ExtendedField`: `{claims, resolved}`. This covers `legal_name`, `status`, `legal_form`, the dates, `share_capital`, `registered_address` and the like, and the fields inside `parties`, `officerships`, `shareholdings` and `financials` as typed in `PartyExtended`, `OfficershipExtended`, `ShareholdingExtended` and `FinancialsExtended`. Every list of values (`trading_names`, `addresses`, `identifiers`, `industry_codes`, `contacts`, and the matching lists inside parties, `shareholdings[].verbal` and `financials[].derived`) is a list of `Claim`, one per source and value, instead of distinct values.\n\nFields that stay plain (not wrapped) in the extended view: `country`, `company_id`, `source_ids`, the ids and link fields (`id`, `party_id`, `owner_party_id`, `target_company_id`, `company_id`), party `kind` and `source_keys`, shareholding `as_of` and `basis`, financials `fiscal_year`, `representation_chain`, `ubo`, `documents`, `filings`, `relationships` and `estimated_fields`. `field_notes` is not present; the note is on the claim. `estimated_fields` is present as in `minimal`, and `resolved.estimated` is also set on the field.",
        "required": [
          "company_id",
          "country",
          "source_ids",
          "parties",
          "officerships",
          "shareholdings",
          "ubo",
          "financials",
          "documents",
          "filings",
          "relationships",
          "trading_names",
          "addresses",
          "identifiers",
          "industry_codes",
          "contacts"
        ],
        "properties": {
          "company_id": {
            "type": "string"
          },
          "country": {
            "$ref": "#/components/schemas/Iso2"
          },
          "source_ids": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "source_key": {
                  "type": "string"
                },
                "match_score": {
                  "type": "number"
                }
              }
            }
          },
          "legal_name": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "trading_names": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "status": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "legal_form": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "incorporation_date": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "registration_date": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "dissolution_date": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "share_capital": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "business_purpose": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "free_float": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "ownership_walk": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "industry_codes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "signature_rules": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "group": {
            "type": "object",
            "description": "Each member is an `ExtendedField`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/ExtendedField"
            }
          },
          "registered_address": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "business_address": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "registration_number": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "estimated_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "representation_chain": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RepresentationStep"
            }
          },
          "parties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartyExtended"
            }
          },
          "officerships": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OfficershipExtended"
            }
          },
          "shareholdings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShareholdingExtended"
            }
          },
          "ubo": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ubo"
            }
          },
          "financials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FinancialsExtended"
            }
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          },
          "filings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Filing"
            }
          },
          "relationships": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Relationship"
            }
          }
        }
      },
      "PartyExtended": {
        "type": "object",
        "description": "`Party` in the extended view. `kind`, `source_keys`, `id` and `company_id` stay plain; the other fields are `ExtendedField`; `identifiers` and `addresses` are lists of `Claim`.",
        "required": [
          "id",
          "kind",
          "source_keys",
          "identifiers",
          "addresses"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "person",
              "company"
            ]
          },
          "company_id": {
            "type": "string",
            "format": "uuid"
          },
          "source_keys": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "name": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "date_of_birth": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "birthplace": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "country_of_birth": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "nationality": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "country_of_residence": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "pep_status": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          }
        }
      },
      "OfficershipExtended": {
        "type": "object",
        "description": "`Officership` in the extended view. The ids and `can_represent` stay plain; every other field is an `ExtendedField`.",
        "required": [
          "id",
          "company_id",
          "party_id"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "company_id": {
            "type": "string"
          },
          "party_id": {
            "type": "string",
            "format": "uuid"
          },
          "role": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "status": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "from": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "to": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "signature_right": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "can_represent": {
            "$ref": "#/components/schemas/CanRepresent"
          },
          "phone": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "email": {
            "$ref": "#/components/schemas/ExtendedField"
          }
        }
      },
      "ShareholdingExtended": {
        "type": "object",
        "description": "`Shareholding` in the extended view. The ids, `as_of` and `basis` stay plain; `verbal` is a list of `Claim`; every other field is an `ExtendedField`.",
        "required": [
          "id",
          "owner_party_id",
          "target_company_id"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_party_id": {
            "type": "string",
            "format": "uuid"
          },
          "target_company_id": {
            "type": "string"
          },
          "basis": {
            "type": "string",
            "enum": [
              "register_text",
              "provider_asserted",
              "inferred_heuristic",
              "legal_form"
            ],
            "description": "Plain, as in `Shareholding.basis`."
          },
          "as_of": {
            "$ref": "#/components/schemas/PartialDate"
          },
          "share": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "voting_share": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "capital": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "shares_count": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "control": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "role": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "interest_type": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "verbal": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          }
        }
      },
      "FinancialsExtended": {
        "type": "object",
        "description": "`Financials` in the extended view. `company_id` and `fiscal_year` stay plain; `derived` is a list of `Claim` whose values are `DerivedFigure`; every figure is an `ExtendedField`.",
        "required": [
          "company_id",
          "fiscal_year"
        ],
        "additionalProperties": false,
        "properties": {
          "company_id": {
            "type": "string"
          },
          "fiscal_year": {
            "type": "integer"
          },
          "revenue": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "ebit": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "ebitda": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "net_income": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "assets": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "liabilities": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "equity": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "headcount": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "cash": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "receivables": {
            "$ref": "#/components/schemas/ExtendedField"
          },
          "derived": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Claim"
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request payload, for example a missing required field.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error400"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The bearer token is missing, invalid or expired.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error401"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The authenticated customer does not have access to this product.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error403"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too many requests.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error429"
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server issue.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error500"
            }
          }
        }
      },
      "Unavailable": {
        "description": "Service is temporarily unavailable. Retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error503"
            }
          }
        }
      },
      "GatewayTimeout": {
        "description": "Gateway has timed out. Retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error504"
            }
          }
        }
      },
      "KybUnauthorized": {
        "description": "Unauthorized. The bearer token is missing (`{error}` without `status`) or invalid or expired (`{status:false,error}`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      },
      "KybForbidden": {
        "description": "Forbidden. The customer has no access to the KYB product. Envelope `{status:false,message}`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      },
      "PassedThrough": {
        "description": "Passed through from the KYB service with its message and `code` when it sends one. The service does not currently send this status; it is reserved, so handle it like any other 4xx.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      },
      "KybTooManyRequests": {
        "description": "Too many requests: a provider's daily limit (`DAILY_LIMIT_REACHED`, `provider` set), a limit upstream (`Retry-After` set when sent), or the account's transaction limit (`{status:false,message,limit,remaining}`).",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      },
      "Unexpected": {
        "description": "Unexpected error in the gateway route, for example a body that is not valid JSON. Envelope `{status:false,error}`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      },
      "BadGateway": {
        "description": "Bad gateway. The KYB service answered 401 or 403 to the gateway, which means a configuration problem on our side, not a problem with your request. Envelope `{status:false,error:\"External Service failure\"}`.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      },
      "KybUnavailable": {
        "description": "Service unavailable. The KYB service answered with a server error or did not answer (including a provider failure it did not handle). Envelope `{status:false,error:\"Service temporarily unavailable\"}`. Retry later.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/KybErrorResponse"
            }
          }
        }
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  },
  "paths": {
    "/auth": {
      "post": {
        "summary": "Authenticate",
        "description": "Obtain a Bearer token using your `Api-Key` and `Customer-Id` headers. The token is valid for 60 minutes and must be included as `Authorization: Bearer <access_token>` in all subsequent requests.",
        "parameters": [
          {
            "in": "header",
            "name": "Api-Key",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Your API key.",
            "example": "40ab0d69-fc3e-5fea-bfa8-b94e93462ad9"
          },
          {
            "in": "header",
            "name": "Customer-Id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Your customer ID.",
            "example": "16a6c3e7-7a76-4714-9b34-97135ab4bdcd"
          },
          {
            "in": "header",
            "name": "Content-Type",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "application/x-www-form-urlencoded"
              ]
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {}
        },
        "responses": {
          "200": {
            "description": "Authentication successful.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "description": "JWT Bearer token for use in subsequent requests."
                    },
                    "expires_in": {
                      "type": "integer",
                      "description": "Token validity in seconds.",
                      "example": 3600
                    },
                    "token_type": {
                      "type": "string",
                      "example": "Bearer"
                    }
                  }
                },
                "example": {
                  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                  "expires_in": 3600,
                  "token_type": "Bearer"
                }
              }
            }
          }
        },
        "security": [],
        "tags": [
          "Authentication"
        ]
      }
    },
    "/address/verify": {
      "post": {
        "summary": "Verify Address",
        "description": "Verifies if an individual can be matched to a given address, including validation, a match quality score, and potential corrections.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddressVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully verified address. In the sandbox, a request that matches no test case also returns 200, with {\"success\": false, \"message\": ...} instead of this shape.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddressVerificationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Authorization information is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "403": {
            "description": "The account is not enabled for address verification, or the gateway check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "message"
                  ],
                  "properties": {
                    "status": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "example": {
                    "status": false,
                    "message": "Access denied: You cannot access this product. Please contact support."
                  }
                }
              }
            }
          },
          "429": {
            "description": "The account's transaction limit is used up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "message"
                  ],
                  "properties": {
                    "status": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "remaining": {
                      "type": "integer"
                    }
                  },
                  "example": {
                    "status": false,
                    "message": "Transaction limit exceeded",
                    "limit": 1000,
                    "remaining": 0
                  }
                }
              }
            }
          },
          "500": {
            "description": "The verification source failed, or the request was missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "status": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "example": {
                    "status": false,
                    "error": "An error occurred during processing"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Address"
        ]
      }
    },
    "/aml/checkIndividual": {
      "post": {
        "summary": "Check Individual",
        "description": "Checks an individual in the AML system to see if there are any matches for the provided details.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AMLIndividualCheckRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON array of matching individuals.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AMLIndividualCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request due to missing or invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "API key is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error403"
                }
              }
            }
          },
          "500": {
            "description": "An internal server error occurred.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          }
        },
        "tags": [
          "AML"
        ]
      }
    },
    "/aml/ongoingMonitoring/registerIndividual": {
      "post": {
        "summary": "Register Individual for Monitoring",
        "description": "Registers an individual for ongoing monitoring in the AML system.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AMLRegisterIndividualRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully registered individual for monitoring."
          },
          "400": {
            "description": "Invalid request provided."
          },
          "401": {
            "description": "Authorization information is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "AML"
        ]
      }
    },
    "/aml/ongoingMonitoring/registerEntity": {
      "post": {
        "summary": "Register Entity for Monitoring",
        "description": "Registers an entity for ongoing monitoring in the AML system.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AMLRegisterEntityRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully registered entity for monitoring."
          },
          "400": {
            "description": "Invalid request provided."
          }
        },
        "tags": [
          "AML"
        ]
      }
    },
    "/aml/ongoingMonitoring/removeSearchProfile": {
      "post": {
        "summary": "Remove Search Profile",
        "description": "Removes a search profile from the AML ongoing monitoring system.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AMLRemoveProfileRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully removed search profile."
          },
          "400": {
            "description": "Invalid request provided."
          }
        },
        "tags": [
          "AML"
        ]
      }
    },
    "/openJourney": {
      "post": {
        "summary": "Open Journey",
        "description": "Starts a new verification journey where the customer can submit documents in steps.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "passThroughData": {
                    "type": "object",
                    "description": "Optional metadata to be carried through the journey."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully opened verification journey.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "journeyId": {
                      "type": "string",
                      "description": "Unique identifier for the verification journey.",
                      "example": "uniqueJourneyIdentifier"
                    },
                    "passThroughData": {
                      "type": "object",
                      "description": "Optional metadata to be carried through the journey."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request due to missing or invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "API key is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "Document verification"
        ]
      }
    },
    "/addImage": {
      "post": {
        "summary": "Add Image",
        "description": "Adds an image (front, back, or selfie) to the ongoing journey. Images can be submitted as base64-encoded strings or as file uploads.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "journeyId",
                  "imageName",
                  "imageSide",
                  "imageData"
                ],
                "properties": {
                  "journeyId": {
                    "type": "string",
                    "description": "Unique identifier for the verification journey.",
                    "example": "uniqueJourneyIdentifier"
                  },
                  "imageName": {
                    "type": "string",
                    "description": "Name of the uploaded image file.",
                    "example": "uploadedFileName"
                  },
                  "imageSide": {
                    "type": "string",
                    "description": "Specifies which side of the document (front, back, selfie).",
                    "enum": [
                      "front",
                      "back",
                      "selfie"
                    ],
                    "example": "front"
                  },
                  "storeOnly": {
                    "type": "boolean",
                    "description": "If true, stores the image without classification.",
                    "example": true
                  },
                  "imageData": {
                    "type": "string",
                    "description": "Base64-encoded image or multipart file.",
                    "example": "base64EncodedImagestring"
                  },
                  "passThroughData": {
                    "type": "object",
                    "description": "Custom metadata (e.g., user ID).",
                    "example": {
                      "userId": "12345"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully added image to journey."
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Journey not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          }
        },
        "tags": [
          "Document verification"
        ]
      }
    },
    "/verify": {
      "post": {
        "summary": "Verify Documents",
        "description": "Initiates the verification of all images submitted in this journey. Returns a detailed verification result.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "journeyId"
                ],
                "properties": {
                  "journeyId": {
                    "type": "string",
                    "description": "Unique identifier for the verification journey.",
                    "example": "uniqueJourneyIdentifier"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully verified documents.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "journeyId": {
                      "type": "string",
                      "description": "Unique identifier for the verification journey."
                    },
                    "status": {
                      "type": "string",
                      "description": "Status of the verification process.",
                      "example": "verificationComplete"
                    },
                    "identitySubject": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "description": "Type of identity subject.",
                          "example": "person"
                        },
                        "fullName": {
                          "type": "string",
                          "description": "Full name as extracted from the document.",
                          "example": "Max Mustermann"
                        },
                        "nameStructure": {
                          "type": "object",
                          "properties": {
                            "firstName": {
                              "type": "string",
                              "description": "First name of the individual.",
                              "example": "Max"
                            },
                            "lastName": {
                              "type": "string",
                              "description": "Last name of the individual.",
                              "example": "Mustermann"
                            },
                            "nativeFullName": {
                              "type": "string",
                              "description": "Native full name of the individual.",
                              "example": "Max Mustermann"
                            }
                          }
                        },
                        "gender": {
                          "type": "string",
                          "description": "Gender (M, F, or X).",
                          "enum": [
                            "M",
                            "F",
                            "X"
                          ],
                          "example": "M"
                        },
                        "nationality": {
                          "type": "string",
                          "description": "Nationality code (ISO 3166).",
                          "example": "DE"
                        },
                        "dob": {
                          "type": "string",
                          "description": "Date of birth (YYYY/MM/DD).",
                          "example": "1990/01/01"
                        },
                        "addressSingleLine": {
                          "type": "string",
                          "description": "Extracted address in single-line format.",
                          "example": "123 Main St, City, Country"
                        },
                        "email": {
                          "type": "string",
                          "description": "Extracted email (if available).",
                          "example": "max.mustermann@example.com"
                        },
                        "mobileNumber": {
                          "type": "string",
                          "description": "Extracted mobile number (if available).",
                          "example": "+1234567890"
                        }
                      }
                    },
                    "authoritativeData": {
                      "type": "object",
                      "properties": {
                        "identityDocument": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "description": "Type of document.",
                              "example": "passport"
                            },
                            "idNumber": {
                              "type": "string",
                              "description": "Document ID number.",
                              "example": "123456789"
                            },
                            "issuingCountry": {
                              "type": "string",
                              "description": "Country that issued the document.",
                              "example": "DE"
                            },
                            "expeditor": {
                              "type": "string",
                              "description": "Issuing authority.",
                              "example": "BH Neunkirchen"
                            },
                            "expirationDate": {
                              "type": "string",
                              "description": "Expiry date of the document (YYYY/MM/DD).",
                              "example": "2030/01/01"
                            },
                            "verificationChannel": {
                              "type": "string",
                              "description": "How verification was performed.",
                              "example": "optical"
                            }
                          }
                        }
                      }
                    },
                    "proofOfWork": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "description": "Type of proof.",
                          "example": "image"
                        },
                        "titleOfProof": {
                          "type": "string",
                          "description": "Title describing the proof.",
                          "example": "IDFront"
                        },
                        "timestampOfProof": {
                          "type": "string",
                          "description": "Timestamp when the proof was collected.",
                          "example": "2024/08/01T10:00:00Z"
                        }
                      }
                    },
                    "auditTrail": {
                      "type": "object",
                      "properties": {
                        "workId": {
                          "type": "string",
                          "description": "Unique ID of the verification attempt.",
                          "example": "abc123"
                        },
                        "workStatus": {
                          "type": "string",
                          "description": "Status of the work.",
                          "enum": [
                            "PASS",
                            "FAIL"
                          ],
                          "example": "PASS"
                        },
                        "workStartTst": {
                          "type": "string",
                          "description": "Timestamp when the verification started.",
                          "example": "2024/08/01T10:00:00Z"
                        },
                        "workEndTst": {
                          "type": "string",
                          "description": "Timestamp when the verification ended.",
                          "example": "2024/08/01T10:01:00Z"
                        },
                        "workResult": {
                          "type": "string",
                          "description": "Summary of the verification result.",
                          "example": "Verification successful"
                        }
                      }
                    },
                    "fraudAlerts": {
                      "type": "object",
                      "properties": {
                        "fraudAlertDetail": {
                          "type": "array",
                          "description": "List of detected fraud alerts (if any).",
                          "items": {
                            "type": "object"
                          }
                        },
                        "aggregateFraudAlertScore": {
                          "type": "number",
                          "description": "Overall fraud risk score (0 = no risk).",
                          "example": 0
                        }
                      }
                    },
                    "croppedImages": {
                      "type": "object",
                      "properties": {
                        "front": {
                          "type": "string",
                          "description": "Base64-encoded image of the front side."
                        },
                        "portrait": {
                          "type": "string",
                          "description": "Base64-encoded portrait image from the document."
                        },
                        "signature": {
                          "type": "string",
                          "description": "Base64-encoded signature image."
                        },
                        "back": {
                          "type": "string",
                          "description": "Base64-encoded image of the back side."
                        },
                        "selfie": {
                          "type": "string",
                          "description": "Base64-encoded selfie image (if applicable)."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Journey not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          }
        },
        "tags": [
          "Document verification"
        ]
      }
    },
    "/verify/age": {
      "post": {
        "summary": "Verify Age and Disability",
        "description": "Performs an optional age/disability verification after documents are submitted. Checks if the user meets certain age or disability thresholds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "journeyId"
                ],
                "properties": {
                  "journeyId": {
                    "type": "string",
                    "description": "Unique identifier for the verification journey.",
                    "example": "uniqueJourneyIdentifier"
                  },
                  "ageFrom": {
                    "type": "number",
                    "description": "Minimum age for eligibility (can't combine with ageTo).",
                    "example": 21
                  },
                  "ageTo": {
                    "type": "number",
                    "description": "Maximum age for eligibility (can't combine with ageFrom).",
                    "example": 65
                  },
                  "minDisabilityPercentage": {
                    "type": "number",
                    "description": "Minimum disability percentage required for eligibility.",
                    "example": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully verified age and disability.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "journeyId": {
                      "type": "string",
                      "description": "Unique identifier for the verification journey."
                    },
                    "status": {
                      "type": "string",
                      "description": "Status of the verification process.",
                      "example": "ageAndDisabilityVerificationComplete"
                    },
                    "ageResult": {
                      "type": "string",
                      "description": "Indicates if the individual meets the age requirement.",
                      "enum": [
                        "yes",
                        "no"
                      ],
                      "example": "yes"
                    },
                    "disabilityResult": {
                      "type": "string",
                      "description": "Indicates if the individual meets the disability criteria.",
                      "enum": [
                        "eligible",
                        "not eligible"
                      ],
                      "example": "eligible"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Journey not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          }
        },
        "tags": [
          "Document verification"
        ]
      }
    },
    "/verifySingle": {
      "post": {
        "summary": "Single-Step Document Verification",
        "description": "Upload all document images in a single request and get instant verification results.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "imageName",
                    "imageSide",
                    "imageData"
                  ],
                  "properties": {
                    "imageName": {
                      "type": "string",
                      "description": "Name of the uploaded image file"
                    },
                    "imageSide": {
                      "type": "string",
                      "enum": [
                        "front",
                        "back",
                        "selfie"
                      ],
                      "description": "Specifies which side of the document (front, back, selfie)"
                    },
                    "storeOnly": {
                      "type": "boolean",
                      "description": "If true, stores the image without classification"
                    },
                    "imageData": {
                      "type": "string",
                      "description": "Base64-encoded image or multipart file"
                    },
                    "passThroughData": {
                      "type": "object",
                      "description": "Custom metadata (e.g., user ID)"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResultResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "Document verification"
        ]
      }
    },
    "/identity/verify": {
      "post": {
        "summary": "Verify Identity",
        "description": "Verify identity information by matching it against external and internal databases.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IdentityVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved the verification results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdentityVerificationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Authorization information is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "Identity"
        ]
      }
    },
    "/payments/initiate": {
      "post": {
        "summary": "Initiate Payment",
        "description": "Initiates a payment by redirecting the user to a hosted payment page.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiatePaymentRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "amount": "100.50",
                    "currency": "EUR",
                    "referenceId": "uniqueRefId123",
                    "transactionDescription": "Payment for Order #12345",
                    "returnUrl": "https://example.com/callback",
                    "IBAN": "DE89370400440532013000",
                    "storedBIC": "BOFIIE2D",
                    "language": "DE"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment successfully initiated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiatePaymentResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "requestId": "req123456789",
                      "redirectUrl": "https://example.com/app/req_123456789"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "Payments"
        ]
      }
    },
    "/payments/status": {
      "post": {
        "summary": "Retrieve Transaction Status",
        "description": "Retrieves the status of a transaction.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrieveStatusRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "referenceId": "uniqueRefId123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved transaction status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrieveStatusResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": "PENDING",
                      "statusReasonInformation": "User redirected to bank."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid Request: Missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "403": {
            "description": "Permission to access this endpoint is denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error403"
                }
              }
            }
          },
          "404": {
            "description": "Not Found: Reference ID not recognized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error429"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error: Unexpected server issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "501": {
            "description": "The operation was not implemented.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error501"
                }
              }
            }
          },
          "503": {
            "description": "Service is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error503"
                }
              }
            }
          },
          "504": {
            "description": "Gateway has timed out.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error504"
                }
              }
            }
          }
        },
        "tags": [
          "Payments"
        ]
      }
    },
    "/payments/challenge-deposit": {
      "post": {
        "summary": "Initiate Challenge Deposit",
        "description": "Initiates a challenge deposit to verify user identity by sending a small amount to the bank account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChallengeDepositRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "amount": "0.10",
                    "currency": "EUR",
                    "description": "merchantId19887-65",
                    "firstName": "John",
                    "lastName": "Doe",
                    "piiToggle": 1,
                    "nameMatchLogic": "fuzzy"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully initiated challenge deposit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChallengeDepositResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "transactionId": "e5c81c78-272b-4307-9197-3ace19109fd3",
                      "description": "merchantId19887-65",
                      "status": "OK",
                      "globalResult": {
                        "overall": "review",
                        "totalScore": 100
                      },
                      "nameMatchScore": 85,
                      "iban": "DE44500105175407324931",
                      "returnedFirstName": "John",
                      "returnedLastName": "Doe"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "Payments"
        ]
      }
    },
    "/phone-service/phoneStatus": {
      "post": {
        "summary": "Phone Status Check",
        "description": "Get insights about a phone number such as whether it is active or disconnected, whether its associated device is reachable or unreachable, and its associated device's roaming status.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneStatusRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "phoneNumber": "+4915123456789"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved phone status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneStatusResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "referenceId": "ABC123XYZ789",
                      "subResource": "live",
                      "status": {
                        "code": 300,
                        "description": "Transaction successfully completed",
                        "updatedOn": "2025-08-01T14:32:10Z"
                      },
                      "errors": [],
                      "phoneType": {
                        "code": "2",
                        "description": "MOBILE"
                      },
                      "blocklisting": {
                        "blocked": false,
                        "blockCode": 0,
                        "blockDescription": "Not blocked"
                      },
                      "numbering": {
                        "cleansing": {
                          "call": {
                            "countryCode": "49",
                            "phoneNumber": "15123456789",
                            "cleansedCode": 100,
                            "minLength": 7,
                            "maxLength": 13
                          },
                          "sms": {
                            "countryCode": "49",
                            "phoneNumber": "15123456789",
                            "cleansedCode": 100,
                            "minLength": 7,
                            "maxLength": 13
                          }
                        },
                        "original": {
                          "completePhoneNumber": "+4915123456789",
                          "countryCode": "49",
                          "phoneNumber": "15123456789"
                        }
                      },
                      "location": {
                        "city": "Berlin",
                        "state": "Berlin",
                        "zip": "10115",
                        "metroCode": null,
                        "county": "Berlin County",
                        "country": {
                          "name": "Germany",
                          "iso2": "DE",
                          "iso3": "DEU"
                        },
                        "coordinates": {
                          "latitude": "52.5200",
                          "longitude": "13.4050"
                        },
                        "timeZone": {
                          "name": "Europe/Berlin",
                          "utcOffsetMax": "+2",
                          "utcOffsetMin": "+1"
                        }
                      },
                      "carrier": {
                        "name": "Generic Mobile GmbH"
                      },
                      "live": {
                        "subscriberStatus": "ACTIVE",
                        "deviceStatus": "REACHABLE",
                        "roaming": "UNAVAILABLE",
                        "roamingCountry": null,
                        "roamingCountryIso2": null
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error403"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          }
        },
        "tags": [
          "Phone intelligence"
        ]
      }
    },
    "/phone-service/phoneid": {
      "post": {
        "summary": "Phone ID",
        "description": "The Phone ID service provides identity checks and enriched data linked to a phone number. It includes optional modules like age verification, breached data, call forwarding detection, contact info, contact match, number deactivation, subscriber status, porting history, porting status, and SIM swap.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneIDRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "phoneNumber": "15555550100",
                    "accountLifecycleEvent": "create",
                    "externalId": "CustomExternalID7349",
                    "originatingIp": "203.0.113.45",
                    "addons": {
                      "ageVerify": {
                        "ageThreshold": 21
                      },
                      "contact": {
                        "email": "test@example.com"
                      },
                      "contactMatch": {
                        "firstName": "string",
                        "lastName": "string",
                        "address": "string",
                        "city": "string",
                        "postalCode": "string",
                        "state": "string",
                        "country": "string",
                        "inputUsed": "email"
                      },
                      "contactPlus": {
                        "billingPostalCode": "95110"
                      },
                      "numberDeactivation": {},
                      "portingHistory": {
                        "pastXDays": 10
                      },
                      "breachedData": {},
                      "callForwardDetection": {},
                      "subscriberStatus": {},
                      "portingStatus": {},
                      "simSwap": {}
                    },
                    "consent": {
                      "method": 1,
                      "timestamp": "2018-05-05T00:00:00Z"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved phone ID information.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneIDResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": true,
                      "data": {
                        "referenceId": "0123456789ABCDEF0123456789ABCDEF",
                        "externalId": "CustomExternalID7349",
                        "status": {
                          "code": 300,
                          "description": "Transaction successfully completed",
                          "updatedOn": "2025-01-01T00:00:00Z"
                        },
                        "location": {
                          "city": "Example City",
                          "state": "Example State",
                          "zip": "00000",
                          "metroCode": null,
                          "county": "Example County",
                          "country": {
                            "name": "United States",
                            "iso2": "US",
                            "iso3": "USA"
                          },
                          "coordinates": {
                            "latitude": null,
                            "longitude": null
                          },
                          "timeZone": {
                            "name": null,
                            "utcOffsetMax": "+0",
                            "utcOffsetMin": "+0"
                          }
                        },
                        "blocklisting": {
                          "blocked": false,
                          "blockCode": 0,
                          "blockDescription": "Not blocked"
                        },
                        "numbering": {
                          "cleansing": {
                            "call": {
                              "countryCode": "1",
                              "phoneNumber": "555550100",
                              "cleansedCode": 100,
                              "minLength": 7,
                              "maxLength": 13
                            },
                            "sms": {
                              "countryCode": "1",
                              "phoneNumber": "555550100",
                              "cleansedCode": 100,
                              "minLength": 7,
                              "maxLength": 13
                            }
                          },
                          "original": {
                            "completePhoneNumber": "+15555550100",
                            "countryCode": "1",
                            "phoneNumber": "555550100"
                          }
                        },
                        "phoneType": {
                          "code": "2",
                          "description": "MOBILE"
                        },
                        "carrier": {
                          "name": "Example Mobile Ltd"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Malformed syntax in the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - The server could not find the requested resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error429"
                }
              }
            }
          },
          "500": {
            "description": "Invalid Transaction - Transaction not attempted due to a system issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable - System is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error503"
                }
              }
            }
          }
        },
        "tags": [
          "Phone intelligence"
        ]
      }
    },
    "/phone-service/phoneRiskScore": {
      "post": {
        "summary": "Phone Risk Score",
        "description": "Detects potentially fraudulent activity by analyzing the transaction risk associated with a phone number. Returns a risk score, level, and recommendation, along with detailed risk insights.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneRiskScoreRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "phoneNumber": "+436501234567",
                    "accountLifecycleEvent": "create",
                    "externalId": "1234567890",
                    "originatingIp": "192.168.1.1",
                    "deviceId": "1234567890",
                    "accountId": "1234567890",
                    "emailAddress": "test@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved phone risk score.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhoneRiskScoreResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": true,
                      "data": {
                        "referenceId": "3661FDC7EAA8111C93048FA6FB8C300C",
                        "externalId": null,
                        "status": {
                          "updatedOn": "2025-08-06T12:53:53.082687Z",
                          "code": 300,
                          "description": "Transaction successfully completed"
                        },
                        "numbering": {
                          "original": {
                            "completePhoneNumber": "+436501234567",
                            "countryCode": "43",
                            "phoneNumber": "6501234567"
                          },
                          "cleansing": {
                            "call": {
                              "countryCode": "43",
                              "phoneNumber": "6501234567",
                              "cleansedCode": 100,
                              "minLength": 7,
                              "maxLength": 13
                            },
                            "sms": {
                              "countryCode": "43",
                              "phoneNumber": "6501234567",
                              "cleansedCode": 100,
                              "minLength": 7,
                              "maxLength": 13
                            }
                          }
                        },
                        "riskInsights": {
                          "status": 800,
                          "category": [
                            10010
                          ],
                          "a2P": [
                            22001,
                            20011,
                            20101
                          ],
                          "p2P": [
                            30201
                          ],
                          "numberType": [],
                          "ip": [],
                          "email": []
                        },
                        "phoneType": {
                          "code": "2",
                          "description": "MOBILE"
                        },
                        "location": {
                          "city": "Countrywide",
                          "state": null,
                          "zip": null,
                          "metroCode": null,
                          "county": null,
                          "country": {
                            "name": "Austria",
                            "iso2": "AT",
                            "iso3": "AUT"
                          },
                          "coordinates": {
                            "latitude": null,
                            "longitude": null
                          },
                          "timeZone": {
                            "name": null,
                            "utcOffsetMin": "+1",
                            "utcOffsetMax": "+1"
                          }
                        },
                        "carrier": {
                          "name": "T-Mobile Austria GmbH"
                        },
                        "blocklisting": {
                          "blocked": false,
                          "blockCode": 0,
                          "blockDescription": "Not blocked"
                        },
                        "risk": {
                          "level": "medium-low",
                          "recommendation": "allow",
                          "score": 301
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Malformed syntax in the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - The server could not find the requested resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error429"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - An error occurred while processing the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable - The service is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error503"
                }
              }
            }
          }
        },
        "tags": [
          "Phone intelligence"
        ]
      }
    },
    "/phone-service/verification": {
      "post": {
        "summary": "Verification",
        "description": "Deliver a one-time verification code to a user via SMS or Email.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationRequest"
              },
              "examples": {
                "email": {
                  "value": {
                    "phoneNumber": "436501234567",
                    "method": "email",
                    "email": "test@test.com",
                    "externalId": "12312",
                    "securityFactor": "12345"
                  }
                },
                "sms": {
                  "value": {
                    "phoneNumber": "436501234567",
                    "method": "sms",
                    "externalId": "12312",
                    "securityFactor": "123456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully initiated verification.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": true,
                      "data": {
                        "mobileAppToken": "a1378b455f3048059a7be9df6a9da3aa",
                        "recipient": {
                          "phoneNumber": "436501234567"
                        },
                        "referenceId": "366691874BD00250933424F72F7C50CB",
                        "state": "CREATED",
                        "status": {
                          "code": 3901,
                          "description": "Request in progress",
                          "updatedOn": "2025-10-02T10:04:58.505000Z"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Malformed syntax in the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - The server could not find the requested resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error429"
                }
              }
            }
          },
          "500": {
            "description": "Invalid Transaction - Transaction not attempted due to a system issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable - System is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error503"
                }
              }
            }
          }
        },
        "tags": [
          "Phone intelligence"
        ]
      }
    },
    "/phone-service/verification/{referenceId}": {
      "patch": {
        "summary": "Verification Match",
        "description": "Validate the one-time passcode (OTP) provided by the end user and update the state of an active verification process. If the OTP is correct, the process is marked as VERIFIED; otherwise an error is returned and the process may remain ONGOING, FAILED, or another relevant state.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "referenceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Unique identifier for the verification process."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationMatchRequest"
              },
              "examples": {
                "finalize": {
                  "value": {
                    "securityFactor": "12345"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationMatchResponse"
                },
                "examples": {
                  "verified": {
                    "value": {
                      "status": true,
                      "data": {
                        "status": {
                          "code": 3900,
                          "description": "Verified"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Malformed syntax in the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - The server could not find the requested resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error429"
                }
              }
            }
          },
          "500": {
            "description": "Invalid Transaction - Transaction not attempted due to a system issue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable - System is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error503"
                }
              }
            }
          }
        },
        "tags": [
          "Phone intelligence"
        ]
      }
    },
    "/phone-service/fullPhoneIntelligence": {
      "post": {
        "summary": "Full Phone Intelligence",
        "description": "Comprehensive risk and identity assessment for a phone number combining behavioral signals, telecom intelligence, and historical data.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FullPhoneIntelligenceRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "phoneNumber": "+436501234567"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully retrieved full phone intelligence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FullPhoneIntelligenceResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": true,
                      "data": {
                        "referenceId": "3661FDC54750091C93078058241C3036",
                        "externalId": null,
                        "status": {
                          "updatedOn": "2025-08-06T12:53:09.929413Z",
                          "code": 300,
                          "description": "Transaction successfully completed"
                        },
                        "numbering": {
                          "original": {
                            "completePhoneNumber": "+436501234567",
                            "countryCode": "43",
                            "phoneNumber": "6501234567"
                          },
                          "cleansing": {
                            "call": {
                              "countryCode": "43",
                              "phoneNumber": "6501234567",
                              "cleansedCode": 100,
                              "minLength": 7,
                              "maxLength": 13
                            },
                            "sms": {
                              "countryCode": "43",
                              "phoneNumber": "6501234567",
                              "cleansedCode": 100,
                              "minLength": 7,
                              "maxLength": 13
                            }
                          }
                        },
                        "riskInsights": {
                          "status": 800,
                          "category": [
                            10010
                          ],
                          "a2P": [
                            22007,
                            20011,
                            20101
                          ],
                          "p2P": [
                            30201
                          ],
                          "numberType": [],
                          "ip": [],
                          "email": []
                        },
                        "phoneType": {
                          "code": "2",
                          "description": "MOBILE"
                        },
                        "location": {
                          "city": "Countrywide",
                          "state": null,
                          "zip": null,
                          "metroCode": null,
                          "county": null,
                          "country": {
                            "name": "Austria",
                            "iso2": "AT",
                            "iso3": "AUT"
                          },
                          "coordinates": {
                            "latitude": null,
                            "longitude": null
                          },
                          "timeZone": {
                            "name": null,
                            "utcOffsetMin": "+1",
                            "utcOffsetMax": "+1"
                          }
                        },
                        "carrier": {
                          "name": "T-Mobile Austria GmbH"
                        },
                        "blocklisting": {
                          "blocked": false,
                          "blockCode": 0,
                          "blockDescription": "Not blocked"
                        },
                        "risk": {
                          "level": "medium-low",
                          "recommendation": "allow",
                          "score": 301
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Malformed syntax in the request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Not Found - The server could not find the requested resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error429"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error500"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable - System is temporarily unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error503"
                }
              }
            }
          }
        },
        "tags": [
          "Phone intelligence"
        ]
      }
    },
    "/onboarding/createSessionLink": {
      "post": {
        "summary": "Create QES Session Link",
        "description": "Starts a QES signing session for a specified user. Returns a URL that redirects the user to the signing wizard. The backend will send this session link to the user for document signing.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSessionLinkRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "email": "support@idcanopy.com",
                    "phoneNumber": "+436508021530",
                    "redirectUrl": "https://example.com/onboarding/success",
                    "docUrl": "https://example.com/pdf/onb-t3.pdf",
                    "signForms": [
                      {
                        "fieldId": "Signature1",
                        "actorId": "userToIdentify"
                      },
                      {
                        "fieldId": "Signature2",
                        "actorId": "userToIdentify"
                      }
                    ],
                    "fillForm": [
                      {
                        "fieldId": "name",
                        "value": "${identification.firstName}"
                      },
                      {
                        "fieldId": "surname",
                        "value": "${identification.lastName}"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session link successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateSessionLinkResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": true,
                      "data": {
                        "requestId": "123e4567-e89b-12d3-a456-426614174000",
                        "url": "https://example.com/api/v2/actorTrip/urlback?t=EXAMPLE_TOKEN",
                        "expiresAfter": "2025-07-30T08:55:52.520909994Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          }
        },
        "tags": [
          "QES onboarding"
        ]
      }
    },
    "/onboarding/configureWebhook": {
      "post": {
        "summary": "Configure Webhook",
        "description": "Registers a webhook URL to receive onboarding status updates such as completed verification, signing, or failures.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConfigureWebhookRequest"
              },
              "examples": {
                "default": {
                  "value": {
                    "webhookUrl": "https://example.com/webhooks/onboarding",
                    "metadata": {
                      "authHeader": {
                        "Authorization": "Bearer EXAMPLE_TOKEN_1234567890abcdef",
                        "Api-Key": "fQVZSAp18GqvbwId8LotQl"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook successfully configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfigureWebhookResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "status": true,
                      "data": {
                        "id": "74884fe3-c9e1-4462-b60f-c461e422000c",
                        "url": "https://example.com/webhooks/onboarding",
                        "createdAt": "2025-05-08T16:39:28.339Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "409": {
            "description": "Webhook configuration already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error409"
                }
              }
            }
          }
        },
        "tags": [
          "QES onboarding"
        ]
      }
    },
    "/onboarding/getVerification/{sessionId}": {
      "get": {
        "summary": "Get QES Verification Result",
        "description": "Retrieves identity and signature verification results for a given onboarding session ID.",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID from the onboarding session."
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResultResponse"
                },
                "examples": {
                  "completed": {
                    "value": {
                      "status": true,
                      "data": {
                        "isVerified": true,
                        "status": "completed",
                        "message": "Verification completed",
                        "requestId": "64d35e63-fdf4-43f6-8459-1216787fb34e",
                        "signature": {
                          "content": [
                            {
                              "id": "e919520e-bb24-41c3-8a7b-88b3c8b0008b",
                              "method": "RemoteSignatureLongLivedDisposableCertificate",
                              "status": "COMPLETED",
                              "pageMode": "headless",
                              "signedAt": "2025-06-11T11:53:04.107687Z",
                              "plainResource": {
                                "id": "5a28c0e7-a57e-4bb5-88f3-6b6bb47c2cf7",
                                "name": "Document To Sign",
                                "type": "CONTRACT_DOCUMENT",
                                "family": "DOCUMENT_TO_SIGN",
                                "status": "AVAILABLE",
                                "subType": "DOCUMENT_FLATTENED",
                                "filename": "Onboarding_TEST.pdf",
                                "metadata": {
                                  "sourceTemplateUrl": "https://files.example.com/Onboarding_TEST.pdf"
                                },
                                "mimeType": "application/pdf",
                                "sizeBytes": 138763,
                                "resourceUri": "nor://example/resource/5a28c0e7",
                                "resourceUrl": "https://example.com/storage/data/Onboarding_TEST.pdf",
                                "urlValidBefore": "2025-06-16T11:53:34.028Z"
                              },
                              "signedResource": {
                                "id": "60ab66ba-3b03-477c-8936-be55b15e890f",
                                "type": "CONTRACT_DOCUMENT",
                                "family": "SIGNED_DOCUMENT",
                                "status": "AVAILABLE",
                                "filename": "Onboarding_TEST.pdf",
                                "metadata": {
                                  "fileId": "8168e8d7-ab7b-4c6f-b19e-2fe1418da0d1",
                                  "workstep": "EXAMPLE_WORKSTEP_ID"
                                },
                                "mimeType": "application/pdf",
                                "sizeBytes": 207066,
                                "resourceUri": "nor://example/resource/60ab66ba",
                                "resourceUrl": "https://example.com/storage/data/Onboarding_TEST_signed.pdf",
                                "urlValidBefore": "2025-06-16T11:53:34.028Z"
                              }
                            }
                          ]
                        },
                        "identification": {
                          "id": "2b307448-4880-4d3d-b9ab-0a438298c77a",
                          "actor": "userToIdentify",
                          "idSelf": {
                            "artifacts": {
                              "biometry": [],
                              "document": []
                            },
                            "biometryCheck": {
                              "keysWithError": [],
                              "controlsSummary": 0
                            },
                            "documentCheck": {
                              "documentType": "PASSPORT",
                              "documentTypeFamily": "IDENTITY_DOCUMENT",
                              "keysWithError": [],
                              "controlsSummary": 0
                            }
                          },
                          "source": "ID-SELF",
                          "status": "COMPLETED",
                          "personData": {
                            "email": "max.mustermann@example.com",
                            "gender": "M",
                            "firstName": "Max",
                            "lastName": "Mustermann",
                            "birthDate": "1971-01-01",
                            "birthPlace": "Musterstadt",
                            "nationality": "DE",
                            "phoneNumber": "+491234567890",
                            "documentDetails": {
                              "type": "Passport",
                              "number": "X1234567",
                              "issuedOn": "2016-01-01",
                              "expiryDate": "2026-01-01",
                              "issuanceCountry": "DE",
                              "issuanceAuthority": "Example Authority"
                            }
                          },
                          "finalizedAt": "2025-06-11T11:52:29.961249669Z",
                          "organizationId": "example-org-id",
                          "validationDetail": {
                            "email": {
                              "otpValidated": "SKIPPED",
                              "byRequestInput": "OK",
                              "requestMatched": "SKIPPED",
                              "byIdentificationSource": "SKIPPED"
                            }
                          }
                        }
                      }
                    }
                  },
                  "failed": {
                    "value": {
                      "status": true,
                      "data": {
                        "isVerified": false,
                        "status": "cancelled",
                        "message": "Sorry, we were unable to identify you automatically. You can now try again."
                      }
                    }
                  },
                  "error": {
                    "value": {
                      "status": true,
                      "data": {
                        "isVerified": false,
                        "status": "error",
                        "message": "Verification error"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error401"
                }
              }
            }
          },
          "404": {
            "description": "Session not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error404"
                }
              }
            }
          }
        },
        "tags": [
          "QES onboarding"
        ]
      }
    },
    "/iban/validate": {
      "post": {
        "tags": [
          "IBAN validation"
        ],
        "summary": "Validate an IBAN",
        "operationId": "validatePost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "description": "Body {\"iban\": \"...\"}. Checks syntax, the ISO 7064 MOD-97 checksum and, for NL, resolves the bank. Never asserts that the account exists."
      },
      "get": {
        "tags": [
          "IBAN validation"
        ],
        "summary": "Validate an IBAN (query form)",
        "description": "Convenience GET form: /validate?iban=NL91ABNA0417164300",
        "operationId": "validateGet",
        "parameters": [
          {
            "name": "iban",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Iban"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/address/autocomplete/predict": {
      "post": {
        "tags": [
          "Address autocomplete"
        ],
        "summary": "Suggest addresses",
        "operationId": "predict",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PredictRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suggestions, possibly empty.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PredictResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutocompleteError"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. detail is a list of objects (loc, msg, type) for field validation, or a string when a country is not enabled.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/HTTPValidationError"
                    },
                    {
                      "$ref": "#/components/schemas/AutocompleteError"
                    }
                  ]
                }
              }
            }
          },
          "502": {
            "description": "The address source is unavailable. Show a try-again message; do not mark the address invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutocompleteError"
                }
              }
            }
          }
        },
        "description": "Partial text to up to 5 address suggestions. Call once per debounced keystroke, passing the returned session back.",
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/address/autocomplete/resolve": {
      "post": {
        "tags": [
          "Address autocomplete"
        ],
        "summary": "Resolve a suggestion",
        "operationId": "resolve",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The structured address.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolveResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutocompleteError"
                }
              }
            }
          },
          "404": {
            "description": "The id is unknown or expired. Run predict again and let the user pick again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutocompleteError"
                }
              }
            }
          },
          "422": {
            "description": "Validation error. detail is a list of objects (loc, msg, type) for field validation, or a string when a country is not enabled.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/HTTPValidationError"
                    },
                    {
                      "$ref": "#/components/schemas/AutocompleteError"
                    }
                  ]
                }
              }
            }
          },
          "502": {
            "description": "The address source is unavailable. Show a try-again message; do not mark the address invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutocompleteError"
                }
              }
            }
          }
        },
        "description": "Turn a chosen suggestion id into a structured address.",
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/account/check": {
      "post": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "tags": [
          "Verification of Payee"
        ],
        "operationId": "postAccountCheck",
        "summary": "Check an account identifier and name",
        "description": "Checks if the account identifier and name combination corresponds to the account holder records held at the connected bank. Also checks whether the account is valid and known. When the name is a close match, the response includes a name suggestion. Company identifiers can be checked in addition to, or instead of, the name.\n\nThe request body is forwarded to the upstream provider as sent, after validating that the required fields are present. Unknown fields are passed through unchanged. On a 200 response, the response body is returned exactly as received from the upstream provider.",
        "parameters": [
          {
            "in": "header",
            "name": "X-Correlation-Id",
            "description": "Optional correlation ID for this request. If provided it must match `^[a-zA-Z0-9-]{1,70}$`; otherwise our own request ID is used instead. Not required.",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 70,
              "pattern": "^[a-zA-Z0-9-]{1,70}$"
            }
          }
        ],
        "requestBody": {
          "description": "Account check request",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountCheckRequest"
              },
              "examples": {
                "Full match - Natural Person": {
                  "value": {
                    "accountId": {
                      "value": "NL87MOYO9876543212",
                      "type": "IBAN"
                    },
                    "name": "John Paul Waldo"
                  }
                },
                "Close match - Natural Person": {
                  "value": {
                    "accountId": {
                      "value": "NL87MOYO9876543212",
                      "type": "IBAN"
                    },
                    "name": "John P. Wildo"
                  }
                },
                "Organisation with company IDs": {
                  "value": {
                    "accountId": {
                      "value": "NL96ABNA7998733292",
                      "type": "IBAN"
                    },
                    "companyIds": [
                      {
                        "companyIdValue": "12345678",
                        "companyIdType": "NL_KVK"
                      }
                    ],
                    "name": "Voorbeeld Verpakkingen B.V."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK. The check completed; see nameMatchResult for the outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountCheckResponse"
                },
                "examples": {
                  "Match result - Natural Person": {
                    "value": {
                      "nameMatchResult": "MATCH",
                      "dataUsedForMatching": "VERIFIED",
                      "account": {
                        "accountNumberValidation": "VALID",
                        "paymentPreValidation": "PASS",
                        "numberOfAccountHolders": 1,
                        "jointAccount": false,
                        "status": "ACTIVE",
                        "accountType": "NP",
                        "countryCode": "NL"
                      }
                    }
                  },
                  "Close match result": {
                    "value": {
                      "nameMatchResult": "CLOSE_MATCH",
                      "dataUsedForMatching": "VERIFIED",
                      "nameSuggestion": "John P Waldo",
                      "account": {
                        "accountNumberValidation": "VALID",
                        "paymentPreValidation": "PASS",
                        "status": "ACTIVE",
                        "accountType": "NP",
                        "jointAccount": false,
                        "numberOfAccountHolders": 1,
                        "countryCode": "NL"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. Either our own request validation failed (missing required fields), or the upstream provider rejected the request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. The Umbrella bearer token is missing or invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden. The authenticated customer does not have access to this product.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity. The request body failed field validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Bad gateway. The upstream provider rejected our credentials; this is not caused by the caller's request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable. The upstream provider returned a server error, timed out, or the service is not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/ais/initiate": {
      "post": {
        "tags": [
          "AIS Ident"
        ],
        "summary": "Initiate identification",
        "description": "Starts an identification session and returns the hosted-flow URL. Redirect the end user to `redirectUrl`. There they select their bank, log in at the bank, give a one-time read-only consent and confirm it with strong customer authentication (SCA). Afterwards the user is sent to your `returnUrl` and the result is available via `POST /ais/status` (and pushed to `webhookUrl` if set). The session expires 30 minutes after `expiresAt` is issued.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateRequest"
              },
              "examples": {
                "withName": {
                  "summary": "With expected name (enables the name match)",
                  "value": {
                    "referenceId": "onboarding-000123",
                    "returnUrl": "https://example.com/onboarding/return",
                    "language": "EN",
                    "country": "DE",
                    "expectedName": {
                      "firstName": "Erika",
                      "lastName": "Mustermann"
                    },
                    "webhookUrl": "https://example.com/webhooks/ais"
                  }
                },
                "withIban": {
                  "summary": "With expected IBAN (user must pick this account)",
                  "value": {
                    "referenceId": "mandate-000456",
                    "returnUrl": "https://example.com/mandate/return",
                    "expectedName": {
                      "companyName": "Beispiel GmbH"
                    },
                    "expectedIban": "DE89370400440532013000",
                    "returnPii": false
                  }
                },
                "minimal": {
                  "summary": "Minimal",
                  "value": {
                    "referenceId": "onboarding-000789",
                    "returnUrl": "https://example.com/onboarding/return"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created. Redirect the user to `redirectUrl`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiateResponse"
                },
                "example": {
                  "requestId": "ais_7f3c2a9e5b1d4c08",
                  "redirectUrl": "https://sandbox-umbrella-api.api-umbrella.io/ais/flow/ais_7f3c2a9e5b1d4c08",
                  "expiresAt": "2026-10-02T10:30:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/ais/status": {
      "post": {
        "tags": [
          "AIS Ident"
        ],
        "summary": "Retrieve result",
        "description": "Returns the state of an identification session and, once `COMPLETED`, the account data read from the bank, the name match and the decision. Note this is **POST**, not GET, as in the payments API.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusRequest"
              },
              "example": {
                "referenceId": "onboarding-000123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session state and, when completed, the result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                },
                "examples": {
                  "confirmed": {
                    "summary": "COMPLETED, name match, CONFIRMED",
                    "value": {
                      "referenceId": "onboarding-000123",
                      "requestId": "ais_7f3c2a9e5b1d4c08",
                      "status": "COMPLETED",
                      "statusReason": null,
                      "xs2aReference": "c0n5-3n7-8a41e2",
                      "account": {
                        "iban": "DE89370400440532013000",
                        "bic": "COBADEFFXXX",
                        "bankName": "Example Bank",
                        "holders": [
                          "Erika Mustermann"
                        ],
                        "type": "PRIVATE",
                        "userRole": "HOLDER"
                      },
                      "nameMatch": {
                        "result": "MATCH",
                        "score": 100
                      },
                      "ibanMatch": null,
                      "decision": "CONFIRMED",
                      "consentAt": "2026-10-02T10:02:55Z",
                      "completedAt": "2026-10-02T10:03:15Z",
                      "auditTrail": [
                        {
                          "step": "BANK_SELECTION",
                          "at": "2026-10-02T10:01:40Z"
                        },
                        {
                          "step": "CONSENT",
                          "at": "2026-10-02T10:02:55Z"
                        },
                        {
                          "step": "SCA",
                          "at": "2026-10-02T10:03:12Z"
                        },
                        {
                          "step": "DATA_RETRIEVAL",
                          "at": "2026-10-02T10:03:14Z"
                        },
                        {
                          "step": "NAME_MATCH",
                          "at": "2026-10-02T10:03:15Z"
                        },
                        {
                          "step": "RESULT",
                          "at": "2026-10-02T10:03:15Z"
                        }
                      ]
                    }
                  },
                  "review": {
                    "summary": "COMPLETED, close match, REVIEW",
                    "value": {
                      "referenceId": "onboarding-000124",
                      "requestId": "ais_1b9d0e7a2c6f4a31",
                      "status": "COMPLETED",
                      "statusReason": null,
                      "xs2aReference": "c0n5-3n7-91bd07",
                      "account": {
                        "iban": "DE02120300000000202051",
                        "bic": "BYLADEM1001",
                        "bankName": "Example Bank",
                        "holders": [
                          "Erika Musterman"
                        ],
                        "type": "UNKNOWN",
                        "userRole": "UNKNOWN"
                      },
                      "nameMatch": {
                        "result": "CLOSE_MATCH",
                        "score": 92
                      },
                      "ibanMatch": null,
                      "decision": "REVIEW",
                      "consentAt": "2026-10-02T11:13:40Z",
                      "completedAt": "2026-10-02T11:14:05Z",
                      "auditTrail": [
                        {
                          "step": "BANK_SELECTION",
                          "at": "2026-10-02T11:12:48Z"
                        },
                        {
                          "step": "CONSENT",
                          "at": "2026-10-02T11:13:40Z"
                        },
                        {
                          "step": "SCA",
                          "at": "2026-10-02T11:14:02Z"
                        },
                        {
                          "step": "DATA_RETRIEVAL",
                          "at": "2026-10-02T11:14:04Z"
                        },
                        {
                          "step": "NAME_MATCH",
                          "at": "2026-10-02T11:14:05Z"
                        },
                        {
                          "step": "RESULT",
                          "at": "2026-10-02T11:14:05Z"
                        }
                      ]
                    }
                  },
                  "standardOutput": {
                    "summary": "COMPLETED with returnPii false (no personal data)",
                    "value": {
                      "referenceId": "mandate-000456",
                      "requestId": "ais_3c8e1f6a0b2d4e97",
                      "status": "COMPLETED",
                      "statusReason": null,
                      "xs2aReference": "c0n5-3n7-4f2a90",
                      "nameMatch": {
                        "result": "MATCH",
                        "score": 97
                      },
                      "ibanMatch": true,
                      "decision": "CONFIRMED",
                      "consentAt": "2026-10-02T12:20:22Z",
                      "completedAt": "2026-10-02T12:20:44Z",
                      "auditTrail": [
                        {
                          "step": "BANK_SELECTION",
                          "at": "2026-10-02T12:19:30Z"
                        },
                        {
                          "step": "CONSENT",
                          "at": "2026-10-02T12:20:22Z"
                        },
                        {
                          "step": "SCA",
                          "at": "2026-10-02T12:20:41Z"
                        },
                        {
                          "step": "DATA_RETRIEVAL",
                          "at": "2026-10-02T12:20:43Z"
                        },
                        {
                          "step": "NAME_MATCH",
                          "at": "2026-10-02T12:20:44Z"
                        },
                        {
                          "step": "RESULT",
                          "at": "2026-10-02T12:20:44Z"
                        }
                      ]
                    }
                  },
                  "pending": {
                    "summary": "PENDING, user still in the flow",
                    "value": {
                      "referenceId": "onboarding-000125",
                      "requestId": "ais_5e2f8c1d9a7b4e60",
                      "status": "PENDING",
                      "statusReason": null,
                      "decision": null
                    }
                  },
                  "aborted": {
                    "summary": "ABORTED, user cancelled",
                    "value": {
                      "referenceId": "onboarding-000126",
                      "requestId": "ais_9a4c7e2b1f0d4c85",
                      "status": "ABORTED",
                      "statusReason": "USER_CANCELLED",
                      "decision": "NOT_CONFIRMED"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Unknown `referenceId`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AisIdentError404"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/ais/data/initiate": {
      "post": {
        "tags": [
          "AIS Data"
        ],
        "summary": "Initiate account data access",
        "description": "Starts an account data session and returns the hosted-flow URL. Redirect the end user to `redirectUrl`. There they select their bank, log in at the bank, give a one-time read-only consent to the data in `accessTypes` and confirm it with strong customer authentication (SCA). Afterwards the user is sent to your `returnUrl` and the data is available via `POST /ais/data/status` (and pushed to `webhookUrl` if set). The session expires 30 minutes after `expiresAt` is issued.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AisDataInitiateRequest"
              },
              "examples": {
                "full": {
                  "summary": "Accounts, balances and transactions for a date range",
                  "value": {
                    "referenceId": "affordability-000123",
                    "returnUrl": "https://example.com/affordability/return",
                    "language": "EN",
                    "country": "DE",
                    "accessTypes": [
                      "ACCOUNTS",
                      "BALANCES",
                      "TRANSACTIONS"
                    ],
                    "transactionsFrom": "2026-07-01",
                    "transactionsTo": "2026-09-30",
                    "webhookUrl": "https://example.com/webhooks/ais-data"
                  }
                },
                "balancesOnly": {
                  "summary": "Accounts and balances only",
                  "value": {
                    "referenceId": "affordability-000124",
                    "returnUrl": "https://example.com/affordability/return",
                    "accessTypes": [
                      "ACCOUNTS",
                      "BALANCES"
                    ]
                  }
                },
                "minimal": {
                  "summary": "Minimal (all access types)",
                  "value": {
                    "referenceId": "affordability-000125",
                    "returnUrl": "https://example.com/affordability/return"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session created. Redirect the user to `redirectUrl`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AisDataInitiateResponse"
                },
                "example": {
                  "requestId": "aisd_4b7e1c9a3f2d4a16",
                  "redirectUrl": "https://sandbox-umbrella-api.api-umbrella.io/ais/flow/aisd_4b7e1c9a3f2d4a16",
                  "expiresAt": "2026-10-02T10:30:00Z"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/ais/data/status": {
      "post": {
        "tags": [
          "AIS Data"
        ],
        "summary": "Retrieve account data",
        "description": "Returns the state of an account data session and, once `COMPLETED`, the accounts with the balances and transactions requested in `accessTypes`. Note this is **POST**, not GET, as in the payments API.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AisDataStatusRequest"
              },
              "example": {
                "referenceId": "affordability-000123"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session state and, when completed, the account data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AisDataStatusResponse"
                },
                "examples": {
                  "completed": {
                    "summary": "COMPLETED, two accounts with balances and transactions",
                    "value": {
                      "referenceId": "affordability-000123",
                      "requestId": "aisd_4b7e1c9a3f2d4a16",
                      "status": "COMPLETED",
                      "statusReason": null,
                      "xs2aReference": "c0n5-3n7-7d21c4",
                      "accessTypes": [
                        "ACCOUNTS",
                        "BALANCES",
                        "TRANSACTIONS"
                      ],
                      "accounts": [
                        {
                          "name": "Girokonto",
                          "type": "CURRENT",
                          "iban": "DE89370400440532013000",
                          "bic": "TESTDEFFXXX",
                          "accountHolderName": "Erika Mustermann",
                          "balance": {
                            "current": {
                              "value": "4850.42",
                              "currency": "EUR"
                            },
                            "available": {
                              "value": "4820.42",
                              "currency": "EUR"
                            }
                          },
                          "transactions": [
                            {
                              "id": "t1",
                              "date": "2026-09-30",
                              "description": "Gehalt Beispiel AG",
                              "amount": {
                                "value": "3200.00",
                                "currency": "EUR"
                              }
                            },
                            {
                              "id": "t2",
                              "date": "2026-09-28",
                              "description": "Miete Oktober",
                              "amount": {
                                "value": "-1150.00",
                                "currency": "EUR"
                              }
                            },
                            {
                              "id": "t3",
                              "date": "2026-09-25",
                              "description": "Supermarkt",
                              "amount": {
                                "value": "-87.42",
                                "currency": "EUR"
                              }
                            },
                            {
                              "id": "t4",
                              "date": "2026-09-22",
                              "description": "Bahnticket",
                              "amount": {
                                "value": "-64.90",
                                "currency": "EUR"
                              }
                            }
                          ]
                        },
                        {
                          "name": "Sparkonto",
                          "type": "SAVINGS",
                          "iban": "DE02120300000000202051",
                          "bic": "TESTDEFFXXX",
                          "accountHolderName": "Erika Mustermann",
                          "balance": {
                            "current": {
                              "value": "18500.00",
                              "currency": "EUR"
                            },
                            "available": {
                              "value": "18500.00",
                              "currency": "EUR"
                            }
                          },
                          "transactions": [
                            {
                              "id": "s1",
                              "date": "2026-09-30",
                              "description": "Zinsgutschrift Q3",
                              "amount": {
                                "value": "41.25",
                                "currency": "EUR"
                              }
                            },
                            {
                              "id": "s2",
                              "date": "2026-09-01",
                              "description": "Übertrag vom Girokonto",
                              "amount": {
                                "value": "500.00",
                                "currency": "EUR"
                              }
                            }
                          ]
                        }
                      ],
                      "consentAt": "2026-10-02T10:02:55Z",
                      "completedAt": "2026-10-02T10:03:18Z",
                      "auditTrail": [
                        {
                          "step": "BANK_SELECTION",
                          "at": "2026-10-02T10:01:40Z"
                        },
                        {
                          "step": "CONSENT",
                          "at": "2026-10-02T10:02:55Z"
                        },
                        {
                          "step": "SCA",
                          "at": "2026-10-02T10:03:12Z"
                        },
                        {
                          "step": "DATA_RETRIEVAL",
                          "at": "2026-10-02T10:03:17Z"
                        },
                        {
                          "step": "RESULT",
                          "at": "2026-10-02T10:03:18Z"
                        }
                      ]
                    }
                  },
                  "noHolderName": {
                    "summary": "COMPLETED, balances only, bank returned no holder name",
                    "value": {
                      "referenceId": "affordability-000124",
                      "requestId": "aisd_8c2a5f0e1b9d4c73",
                      "status": "COMPLETED",
                      "statusReason": null,
                      "xs2aReference": "c0n5-3n7-2e8b61",
                      "accessTypes": [
                        "ACCOUNTS",
                        "BALANCES"
                      ],
                      "accounts": [
                        {
                          "name": "Girokonto",
                          "type": "CURRENT",
                          "iban": "DE12500105170648489890",
                          "bic": "TESTDEFFXXX",
                          "accountHolderName": null,
                          "balance": {
                            "current": {
                              "value": "1210.05",
                              "currency": "EUR"
                            },
                            "available": {
                              "value": "1210.05",
                              "currency": "EUR"
                            }
                          }
                        }
                      ],
                      "consentAt": "2026-10-02T11:13:40Z",
                      "completedAt": "2026-10-02T11:14:06Z",
                      "auditTrail": [
                        {
                          "step": "BANK_SELECTION",
                          "at": "2026-10-02T11:12:48Z"
                        },
                        {
                          "step": "CONSENT",
                          "at": "2026-10-02T11:13:40Z"
                        },
                        {
                          "step": "SCA",
                          "at": "2026-10-02T11:14:02Z"
                        },
                        {
                          "step": "DATA_RETRIEVAL",
                          "at": "2026-10-02T11:14:05Z"
                        },
                        {
                          "step": "RESULT",
                          "at": "2026-10-02T11:14:06Z"
                        }
                      ]
                    }
                  },
                  "pending": {
                    "summary": "PENDING, user still in the flow",
                    "value": {
                      "referenceId": "affordability-000125",
                      "requestId": "aisd_2f6d9b3e7a1c4e58",
                      "status": "PENDING",
                      "statusReason": null
                    }
                  },
                  "aborted": {
                    "summary": "ABORTED, consent denied",
                    "value": {
                      "referenceId": "affordability-000126",
                      "requestId": "aisd_6a1e4c8b2d0f4b97",
                      "status": "ABORTED",
                      "statusReason": "CONSENT_DENIED"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Unknown `referenceId`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AisDataError404"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          },
          "504": {
            "$ref": "#/components/responses/GatewayTimeout"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/kyb/search": {
      "post": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "tags": [
          "KYB"
        ],
        "operationId": "postKybSearch",
        "summary": "Search for a company by name, identifier or picked suggestion",
        "description": "Send exactly one of `name`, `identifier` or `pick`; any other combination is a 400. Each result row carries the `transaction_id` and `company_id` that `/kyb/company/details` needs.\n\nName search: `country` is required (ISO2). The provider is chosen by country unless `provider` is sent. A name search that finds nothing also returns free `suggestions` (same shape as `/kyb/suggest`); no second paid call is made.\n\nIdentifier search: one exact lookup. `country` is required except for schemes `VAT` and `EUID`, where the value's prefix gives it (a conflicting `country` is a 400). `court` is optional and used for DE. Supported: `REGISTRATION_NUMBER` for DE (`HRB 12345`, `HRA 123`), GB (8 characters, a company number), AT (Firmenbuch number with check letter, `999999z`) and FR (SIREN, 9 digits). Any other scheme or country is a 400 naming the expected format. Live rows carry `matched_by` with the canonical value (the sandbox sets none, see the sandbox paragraph at the top).\n\nPick: selects a suggestion from `/kyb/suggest` that has no identifier (a `provider_id`). Returns the row with that id, with `matched_by.scheme` `PROVIDER_ID`. If that id is not among the results, the full result list comes back without `matched_by`. Not simulated in the sandbox (a pick is a 400 there).\n\nThe gateway also requires `locality` whenever `country` is given and is not DE, GB, FR or AT.\n\nSearching by name is free for some providers and paid for others. What this request paid for is in `metadata.paid_provider_calls`. A name search never bills a feature (`billable_features` is always empty).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KybSearchRequest"
              },
              "examples": {
                "By name": {
                  "value": {
                    "name": "Example Holding GmbH",
                    "country": "AT"
                  }
                },
                "By identifier": {
                  "value": {
                    "identifier": {
                      "scheme": "REGISTRATION_NUMBER",
                      "value": "HRB 00000"
                    },
                    "country": "DE",
                    "court": "Beispielstadt"
                  }
                },
                "Pick a suggestion": {
                  "value": {
                    "pick": {
                      "provider": "example-provider",
                      "id": "co_at_000000000000000a",
                      "name": "Example Holding GmbH",
                      "country": "AT"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK. `data` is empty when nothing matched. `warnings` at the top level belongs to `suggestions`; warnings about the search itself are in `metadata.warnings`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybSearchResponse"
                },
                "examples": {
                  "Candidates": {
                    "value": {
                      "status": true,
                      "data": [
                        {
                          "transaction_id": "11111111-2222-4333-8444-555555555555",
                          "company_id": "xxxx:co_at_000000000000000a",
                          "name": "Example Holding GmbH",
                          "status": "active",
                          "registration_number": "000000a",
                          "address_line": "Beispielgasse 1, 1010 Wien",
                          "country": "AT"
                        }
                      ],
                      "metadata": {
                        "paid_provider_calls": {},
                        "billable_features": []
                      }
                    }
                  },
                  "No match, with suggestions": {
                    "value": {
                      "status": true,
                      "data": [],
                      "metadata": {
                        "paid_provider_calls": {},
                        "billable_features": []
                      },
                      "suggestions": [
                        {
                          "name": "Example Holding GmbH",
                          "country": "AT",
                          "source": "example-provider",
                          "provider_id": "co_at_000000000000000a",
                          "score": 0.9
                        }
                      ]
                    }
                  },
                  "Served from storage": {
                    "value": {
                      "status": true,
                      "data": [
                        {
                          "transaction_id": "11111111-2222-4333-8444-555555555555",
                          "company_id": "xxxx:co_at_000000000000000a",
                          "name": "Example Holding GmbH",
                          "status": "active",
                          "registration_number": "000000a",
                          "address_line": "Beispielgasse 1, 1010 Wien",
                          "country": "AT"
                        }
                      ],
                      "metadata": {
                        "paid_provider_calls": {},
                        "billable_features": [],
                        "warnings": [
                          {
                            "code": "PROVIDER_UNAVAILABLE_SERVED_FROM_STORAGE",
                            "provider": "example-provider",
                            "reason": "http_503",
                            "message": "example-provider could not answer (http_503); results are companies already stored from example-provider."
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. The service rejected the request and says why in `error`: `Send exactly one of name, identifier or pick`, an identifier that is invalid or not supported for the country (the message states the expected format), `Provider \"<x>\" is not enabled`, or a gateway validation (`Validation failed: ...`, `Locality is required for countries other than DE and GB`). In the sandbox also `Failed to retrieve test cases` when no test case matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/KybUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/KybForbidden"
          },
          "404": {
            "$ref": "#/components/responses/PassedThrough"
          },
          "409": {
            "$ref": "#/components/responses/PassedThrough"
          },
          "429": {
            "$ref": "#/components/responses/KybTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/Unexpected"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/KybUnavailable"
          }
        }
      }
    },
    "/kyb/suggest": {
      "get": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "tags": [
          "KYB"
        ],
        "operationId": "getKybSuggest",
        "summary": "Type-ahead company suggestions",
        "description": "Free suggestions for a search box. No paid provider is called, no search transaction is created and nothing is billed or counted against your transaction limit. Meant for a debounced input.\n\nEach suggestion is picked in one of three ways: with an `identifier`, call `POST /kyb/search` with that `identifier` (plus `country` and, when present, `court`); with a `provider_id` and no identifier, call it with `pick`; otherwise search by `name` and `country`.\n\nResults are merged across sources, ranked and capped at 10. A source that fails or takes longer than 1.5 seconds is skipped and reported in `warnings`; the call still answers.\n\nRate limit: per customer, 120 requests per minute by default, counted in a fixed one-minute window and applied in the sandbox too. Over the limit the answer is 429 with code `RATE_LIMITED` and a `Retry-After` header (seconds).",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": true,
            "description": "Text to complete. 3 to 100 characters.",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 100
            }
          },
          {
            "in": "query",
            "name": "country",
            "required": false,
            "description": "ISO2 country code to limit suggestions.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. `data` is empty when nothing matched.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybSuggestResponse"
                },
                "examples": {
                  "Suggestions": {
                    "value": {
                      "status": true,
                      "data": [
                        {
                          "name": "Example Holding GmbH",
                          "country": "AT",
                          "source": "example-provider",
                          "provider_id": "co_at_000000000000000a",
                          "score": 0.9
                        },
                        {
                          "name": "Example Trading GmbH",
                          "country": "DE",
                          "source": "example-provider",
                          "lei": "00000000000000000000",
                          "identifier": {
                            "scheme": "REGISTRATION_NUMBER",
                            "value": "HRB 00000"
                          },
                          "court": "Beispielstadt",
                          "score": 0.8
                        }
                      ],
                      "warnings": [
                        {
                          "source": "example-provider",
                          "code": "SOURCE_TIMEOUT",
                          "message": "example-provider did not answer within 1500 ms"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. `q needs at least 3 characters`, `q` longer than 100, or `country must be an ISO2 code`. Envelope `{status:false,error}` (gateway validation prefixes `Validation failed:`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybErrorResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/KybUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/KybForbidden"
          },
          "404": {
            "$ref": "#/components/responses/PassedThrough"
          },
          "409": {
            "$ref": "#/components/responses/PassedThrough"
          },
          "429": {
            "description": "Too many requests. Either your suggest rate limit (code `RATE_LIMITED`, `Retry-After` set) or the transaction limit of the account (`{status:false,message,limit,remaining}`).",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybErrorResponse"
                },
                "examples": {
                  "Rate limited": {
                    "value": {
                      "status": false,
                      "error": "Too many suggest requests, slow down",
                      "code": "RATE_LIMITED"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Unexpected"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/KybUnavailable"
          }
        }
      }
    },
    "/kyb/company/details": {
      "post": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "tags": [
          "KYB"
        ],
        "operationId": "postKybCompanyDetails",
        "summary": "Get the unified company record",
        "description": "Returns the unified company for a `company_id` returned by a previous search under the same `transaction_id`. A `company_id` is also accepted when it was read from a company you already fetched under this `transaction_id` (an owner, or a Komplementaer), so you can walk an ownership chain without searching again; this is limited in depth (default 5) and only to ids of the same `transaction_id`.\n\n`visibility`: `minimal` (default; `basic` is an alias) returns each field as its resolved value. `extended` returns each field as `{claims, resolved}`: every provider's answer with its source and time, and the value chosen.\n\n`include` selects packages. A section that was not requested is an EMPTY ARRAY under its key, never a missing key and never null: `officerships`, `shareholdings`, `financials` and `ubo` are always present; the parties only they referenced are left out of `parties`. `ownership_walk` and `free_float` appear only with `ownerships`. Which flag gates which section, per provider:\n\n- `officers` gates `officerships` for every provider. some providers read officers with the base company payload, but the response still leaves `officerships` empty without the flag.\n- `ownerships` gates `shareholdings`, `ownership_walk` and `free_float` for every provider. This includes the holding derived from the legal form of a sole trader (`basis: legal_form`): without `ownerships` it is not returned.\n- `financials` gates `financials` for some providers. some providers return no `financials`.\n- `transparency` gates `ubo` (example-provider Italy only; other providers return an empty `ubo`).\n- `addresses` and `documents` gate nothing: addresses are always returned and `documents` carries what the provider's company report already contains (the example-provider register extract, a time-limited provider link).\n- `representation_chain` adds `representation_chain` (see below) and implies `officers`.\n\nDetails are slow: the call answers within about 25 seconds with everything available. A section that was still running at that point is reported as a `PENDING_SLICE` warning and is completed from storage on a later call, without buying it twice. Use a client timeout of at least 90 seconds (600 seconds when you request chains).\n\nStored provider data younger than 30 days is reused instead of fetched again, and `metadata.from_cache` is then true. That flag describes the root company payload only. It never means that nothing was billed: a chain step or another slice can still be fetched on a call whose root was reused. Read the cost from `paid_provider_calls` and `billable_features`. `refresh_policy: refresh` fetches everything again (billed).\n\nBilling facts are in `metadata`: `paid_provider_calls` (paid provider requests this call made, per provider) and `billable_features` (for example `representation_chain`). For a call that hit the 25 second bound, `paid_provider_calls` is not the authoritative cost.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/KybDetailsRequest"
              },
              "examples": {
                "Minimal profile": {
                  "value": {
                    "transaction_id": "11111111-2222-4333-8444-555555555555",
                    "company_id": "xxxx:co_at_000000000000000a"
                  }
                },
                "Officers and ownership, extended view": {
                  "value": {
                    "transaction_id": "11111111-2222-4333-8444-555555555555",
                    "company_id": "xxxx:co_at_000000000000000a",
                    "visibility": "extended",
                    "include": {
                      "officers": true,
                      "ownerships": true
                    }
                  }
                },
                "With the signing chain of a GmbH & Co KG": {
                  "value": {
                    "transaction_id": "11111111-2222-4333-8444-555555555555",
                    "company_id": "xxxx:co_at_000000000000000b",
                    "include": {
                      "representation_chain": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK. `data` is a `UnifiedCompany` for `minimal` or `UnifiedCompanyExtended` for `extended`. The example is abbreviated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybDetailsResponse"
                },
                "examples": {
                  "Minimal": {
                    "value": {
                      "status": true,
                      "data": {
                        "company_id": "xxxx:co_at_000000000000000a",
                        "country": "AT",
                        "source_ids": [
                          {
                            "source": "example-provider",
                            "source_key": "co_at_000000000000000a"
                          }
                        ],
                        "legal_name": "Example Holding GmbH",
                        "trading_names": [],
                        "status": {
                          "native": {
                            "value": "aktiv",
                            "language": "de"
                          },
                          "modeled": {
                            "value": "active",
                            "scheme": "idcanopy"
                          }
                        },
                        "addresses": [],
                        "identifiers": [
                          {
                            "scheme": "REGISTRATION_NUMBER",
                            "value": "000000a",
                            "country": "AT"
                          }
                        ],
                        "industry_codes": [],
                        "contacts": [],
                        "registered_address": {
                          "type": "registered",
                          "single_line": "Beispielgasse 1, 1010 Wien, AT",
                          "structured": {
                            "line1": "Beispielgasse 1",
                            "city": "Wien",
                            "postal_code": "1010",
                            "country": "AT"
                          }
                        },
                        "registration_number": {
                          "scheme": "REGISTRATION_NUMBER",
                          "value": "000000a",
                          "country": "AT"
                        },
                        "parties": [],
                        "officerships": [],
                        "shareholdings": [],
                        "ubo": [],
                        "financials": [],
                        "documents": [],
                        "filings": [],
                        "relationships": []
                      },
                      "metadata": {
                        "confidence": null,
                        "completeness": 0.7,
                        "source": "example-provider",
                        "generated_at": "2026-10-13T09:00:00.000Z",
                        "from_cache": false,
                        "source_fetched_at": "2026-10-13T08:59:41.000Z",
                        "warnings": [],
                        "paid_provider_calls": {
                          "example-provider": 1
                        },
                        "billable_features": []
                      }
                    }
                  },
                  "Ownership only partly known": {
                    "value": {
                      "status": true,
                      "data": {
                        "company_id": "xxxx:co_at_000000000000000a",
                        "country": "AT",
                        "source_ids": [
                          {
                            "source": "example-provider",
                            "source_key": "co_at_000000000000000a"
                          }
                        ],
                        "trading_names": [],
                        "addresses": [],
                        "identifiers": [],
                        "industry_codes": [],
                        "contacts": [],
                        "parties": [],
                        "officerships": [],
                        "shareholdings": [],
                        "ubo": [],
                        "financials": [],
                        "documents": [],
                        "filings": [],
                        "relationships": []
                      },
                      "metadata": {
                        "completeness": 0.56,
                        "source": "example-provider",
                        "generated_at": "2026-10-13T09:00:00.000Z",
                        "from_cache": false,
                        "source_fetched_at": "2026-10-13T08:59:41.000Z",
                        "warnings": [
                          {
                            "provider": "example-provider",
                            "section": "ownership",
                            "code": "OWNERSHIP_PARTIAL",
                            "message": "Ownership walk stopped before the end.",
                            "stop_reason": "upstream_unavailable",
                            "max_depth": 1
                          }
                        ],
                        "paid_provider_calls": {
                          "example-provider": 2
                        },
                        "billable_features": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. The service rejects every invalid details request with 400 and a message: `transaction_id` is not a UUID, `company_id` has no valid prefix, `company_id does not belong to transaction_id` (the message lists the ids of that transaction), `refresh_policy must be \"cached\" or \"refresh\"`, a chain deeper than the limit, `Provider \"<x>\" is not enabled`, or `Could not build the unified <view> response`. The gateway adds `Transaction ID must be a UUID`. In the sandbox also `Failed to retrieve test cases` when no test case matches. The refusal for a `company_id` that the `transaction_id` does not hold carries `code` `COMPANY_NOT_IN_TRANSACTION`; branch on the code, not the text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybErrorResponse"
                },
                "examples": {
                  "Company not in transaction": {
                    "value": {
                      "status": false,
                      "error": "company_id does not belong to transaction_id. Provided company_id=xxxx:co_at_000000000000000z, known company_ids for transaction_id=11111111-2222-4333-8444-555555555555: xxxx:co_at_000000000000000a",
                      "code": "COMPANY_NOT_IN_TRANSACTION"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/KybUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/KybForbidden"
          },
          "404": {
            "$ref": "#/components/responses/PassedThrough"
          },
          "409": {
            "$ref": "#/components/responses/PassedThrough"
          },
          "429": {
            "description": "Too many requests. Either a provider's daily spend limit is reached (code `DAILY_LIMIT_REACHED`, `provider` names it, no `Retry-After`: try again after 00:00 UTC), a limit on the upstream service (`Retry-After` set when it sends one), or the transaction limit of the account (`{status:false,message,limit,remaining}`). No provider call was made for the daily limit; what an earlier step of the same call had already bought is not stored.",
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KybErrorResponse"
                },
                "examples": {
                  "Daily limit": {
                    "value": {
                      "status": false,
                      "error": "The daily limit for provider example-provider is reached. Try again after 00:00 UTC.",
                      "code": "DAILY_LIMIT_REACHED",
                      "provider": "example-provider"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Unexpected"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/KybUnavailable"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "webhooks": {
    "aisResult": {
      "post": {
        "summary": "Result push to webhookUrl",
        "description": "Sent to the `webhookUrl` from the initiate call when the session reaches a final status (`COMPLETED`, `ABORTED`, `EXPIRED`, `FAILED`). The body is the same object as the `POST /ais/status` response. Answer with any 2xx. You can always fetch the result again with `POST /ais/status`.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusResponse"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Received."
          }
        },
        "tags": [
          "AIS Ident"
        ]
      }
    },
    "aisDataResult": {
      "post": {
        "summary": "Account data push to webhookUrl",
        "description": "Sent to the `webhookUrl` from the initiate call when the session reaches a final status (`COMPLETED`, `ABORTED`, `EXPIRED`, `FAILED`). The body is the same object as the `POST /ais/data/status` response. Answer with any 2xx. You can always fetch the data again with `POST /ais/data/status`.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AisDataStatusResponse"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Received."
          }
        },
        "tags": [
          "AIS Data"
        ]
      }
    }
  },
  "tags": [
    {
      "name": "Authentication",
      "description": "Obtain an access token for the other endpoints."
    },
    {
      "name": "Address",
      "description": "Verify a postal address."
    },
    {
      "name": "Address autocomplete",
      "description": "Type-ahead address entry for Germany and Austria: predict while the user types, resolve a picked suggestion. Gateway path pending verification."
    },
    {
      "name": "AML",
      "description": "Individual AML checks and ongoing monitoring."
    },
    {
      "name": "Identity",
      "description": "Verify an identity and address against authoritative datasources."
    },
    {
      "name": "Document verification",
      "description": "Open a journey, add images and verify documents, age or a single document."
    },
    {
      "name": "KYB",
      "description": "Company search by name or register number, free type-ahead suggestions, and the unified company record (3.0.0, snake_case). Provider-specific keys and values (`provider_id`, `PROVIDER_ID`, the `provider` request field, `metadata.source` labels, `paid_provider_calls` keys) are shown as placeholders in this reference. Live responses carry the real provider codes; treat them as opaque values."
    },
    {
      "name": "QES onboarding",
      "description": "Qualified electronic signature onboarding sessions and results."
    },
    {
      "name": "Payments",
      "description": "Initiate payments and check transaction status."
    },
    {
      "name": "Verification of Payee",
      "description": "Check that a name belongs to an IBAN at the account-holding bank before a payment is sent."
    },
    {
      "name": "AIS Ident",
      "description": "Identification by account access: the user logs in to their bank, the result confirms the account and matches the holder name."
    },
    {
      "name": "AIS Data",
      "description": "Account data by account access: accounts, balances and transactions the user shares from their bank."
    },
    {
      "name": "Phone intelligence",
      "description": "Phone status, ID, risk score and verification."
    },
    {
      "name": "IBAN validation",
      "description": "Syntax, checksum and bank resolution from the IBAN string alone; never asserts that the account exists. Gateway path pending verification."
    }
  ]
}
