openapi: 3.0.0
info:
  title: aml.api.lifeishard.ro
  description: AML API Documentation
  contact:
    email: api.support@lifeishard.ro
  version: 0.1.0
servers:
  - url: https://aml.api.lifeishard.ro
    description: AML Api PROD
  - url: https://aml-qa.api.lifeishard.ro
    description: AML Api QA
paths:
  /broker/action-logs:
    post:
      tags:
        - Broker
      summary: Get broker action logs
      description: >-
        Returns action logs for the broker identified by X-Broker-Name and
        X-Broker-Instance headers (via broker_headers middleware). Optionally
        filter by date range.
      operationId: 6a7ea46fd493c9b9509f1bd516abbc94
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrokerActionLogsRequest'
      responses:
        '200':
          description: Broker action logs
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/BrokerActionLogsResponse'
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /kyc:
    post:
      tags:
        - KYC
      summary: Generate KYC declaration document
      description: >-
        Generates a KYC declaration document (PDF, base64) for a given KYC
        payload.
      operationId: c565ebc4f0804f524b5b04f9f6b3e82f
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KYCRequest'
      responses:
        '200':
          description: KYC declaration successfully generated
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/BeneficiaryDocumentResponse'
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          $ref: '#/components/responses/ApiUnprocessableEntity'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /kyc/{cnp}:
    get:
      tags:
        - KYC
      summary: Get KYC by CNP
      description: >-
        Returns stored KYC data for a given CNP. Response format matches the
        POST /kyc request schema.
      operationId: 61d173ece74af68aea98d6a6d6b1f5b3
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
        - name: cnp
          in: path
          description: Unique identifier (CNP)
          required: true
          schema:
            type: string
            example: '1740819314981'
      responses:
        '200':
          description: KYC record
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/KYCRequest'
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '404':
          description: Not found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidationErrorResponse'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /nomenclature/sanctionType:
    get:
      tags:
        - Nomenclature
      summary: Get all sanction types
      description: >-
        Returns a list of distinct sanction types available into the
        /sanctions/search endpoint.
      operationId: 34a9e87621d16079271432daa5af8617
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      responses:
        '200':
          description: List of sanction types
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      types:
                        type: array
                        items:
                          type: string
                        example:
                          - aircraft
                          - country
                          - enterprise
                          - person
                          - vessel
                    type: object
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
  /nomenclature/controlTypeCode:
    get:
      tags:
        - Nomenclature
      summary: Get all control type codes
      description: >-
        Returns a list of control type codes with their explanations, used to
        describe how control is exercised over a company or legal entity.
      operationId: 739f9461ecf72d6095105351a9f662d5
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      responses:
        '200':
          description: List of control type codes
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      types:
                        type: array
                        items:
                          $ref: '#/components/schemas/ControlTypeItem'
                    type: object
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
  /nomenclature/identificationType:
    get:
      tags:
        - Nomenclature
      summary: Get identification types
      description: Returns identification document types as (code, explanation).
      operationId: 5620bcd4780a0223cacfd059b5dab915
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      responses:
        '200':
          description: Identification types list
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      types:
                        type: array
                        items:
                          required:
                            - code
                            - explanation
                          properties:
                            code:
                              type: string
                              example: ID_CARD
                            explanation:
                              type: string
                              example: Carte de identitate
                          type: object
                    type: object
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
  /nomenclature/residencyStatus:
    get:
      tags:
        - Nomenclature
      summary: Get residency statuses
      description: Returns residency statuses as (code, explanation).
      operationId: 7236a5beb9c387c2449944434d185ea3
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      responses:
        '200':
          description: Residency statuses list
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      types:
                        type: array
                        items:
                          required:
                            - code
                            - explanation
                          properties:
                            code:
                              type: string
                              example: RESIDENT
                            explanation:
                              type: string
                              example: Rezident
                          type: object
                    type: object
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
  /nomenclature/sourceOfFunds:
    get:
      tags:
        - Nomenclature
      summary: Get sources of funds
      description: Returns sources of funds as (code, explanation).
      operationId: 74bbe4c2b27cd86e11afbd08960745bc
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      responses:
        '200':
          description: Sources of funds list
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      types:
                        type: array
                        items:
                          required:
                            - code
                            - explanation
                          properties:
                            code:
                              type: string
                              example: SALARY
                            explanation:
                              type: string
                              example: Salariu
                          type: object
                    type: object
                type: object
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
  /pep/profiles:
    post:
      tags:
        - PEP
      summary: Create PEP profile (idempotent)
      description: >-
        Creates a PEP profile if it does not exist, otherwise returns the
        existing profile. Response is wrapped in a top-level 'data' object which
        contains { created, data }.
      operationId: ff9701ee19770bc3e9595f1d40420eeb
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PepProfileRequest'
      responses:
        '200':
          description: Profile already existed (created=false)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PepProfileStoreResponseEnvelope'
        '201':
          description: Profile created (created=true)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PepProfileStoreResponseEnvelope'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /premium/alert:
    post:
      tags:
        - Premium
      summary: Evaluate premium alert
      description: >-
        Evaluates a premium amount against configured thresholds and returns
        whether an alert is triggered. The ruleApplied field uses the
        PremiumAlertRule enum.
      operationId: 64e1be6d4deeac35ead78895e79f30da
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PremiumAlertRequest'
      responses:
        '200':
          description: Premium alert evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PremiumAlertResponseEnvelope'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidationErrorResponse'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /beneficiaries/declaration:
    post:
      tags:
        - Beneficiaries
      summary: Generate real beneficiaries declaration document
      description: >-
        Generates a real beneficiaries declaration document (PDF, base64) for a
        given company and its beneficiaries. ControlTypeCode values are defined
        by the ControlTypeCode enum; the official list with explanations is
        available via GET /nomenclature/controlTypeCode.
      operationId: b4142a06cdd03600068a7cab49330fbc
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BeneficiaryCompanyRequest'
      responses:
        '200':
          description: Declaration successfully generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryDocumentResponseEnvelope'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiValidationErrorResponse'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /beneficiaries/{cui}:
    get:
      tags:
        - Beneficiaries
      summary: Get company and beneficiaries by CUI
      description: Returns company data and its real beneficiaries for the given CUI.
      operationId: 67a35a42d3c227ae577caf304d84d4c3
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
        - name: cui
          in: path
          description: Company CUI (unique tax identifier)
          required: true
          schema:
            type: string
            example: RO12345678
      responses:
        '200':
          description: Company with real beneficiaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryCompanyResponseEnvelope'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundMessageResponse'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /sanctions/search:
    post:
      tags:
        - Sanctions
      summary: Search sanctions list
      description: >-
        Searches for persons, companies, countries, vessels, or aircraft against
        sanctions data (EU, UN, US OFAC, FATF). Includes fuzzy name matching and
        alias searching. Use GET /nomenclature/sanctionType to get available
        types.
      operationId: 1fface6017318f148ca0fce67191fec5
      parameters:
        - $ref: '#/components/parameters/Token'
        - $ref: '#/components/parameters/X-Broker-Name'
        - $ref: '#/components/parameters/X-Broker-Instance'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SanctionsSearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanctionsSearchResponseEnvelope'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '500':
          $ref: '#/components/responses/ApiInternalServerError'
      security:
        - bearerAuth: []
  /auth:
    post:
      tags:
        - Authentication
      summary: Authenticate
      description: Authenticate an account by account/password
      operationId: authPost
      parameters:
        - name: account
          in: query
          description: Account
          required: true
          schema:
            type: string
        - name: password
          in: query
          description: Password
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/ApiCoreLibAuthResponse200'
    delete:
      tags:
        - Authentication
      summary: Deautenticate
      description: Deautenticate an existing and valid auth token
      operationId: authDelete
      responses:
        '202':
          description: Deleted
    patch:
      tags:
        - Authentication
      summary: Renew token
      description: Renew an authentication token
      operationId: authPatch
      parameters:
        - name: Token
          in: header
          description: >-
            The Refresh token received from the `POST /auth` or `PATCH /auth`
            endpoint's response field name `refresh_token`.
          required: true
          schema:
            type: string
            example: Refresh [refresh_token]
          example: Refresh [refresh_token]
      responses:
        '200':
          $ref: '#/components/responses/ApiCoreLibAuthResponse200'
components:
  schemas:
    BeneficiaryCompanyRequest:
      title: Beneficiary company declaration request
      description: >-
        Company data and list of beneficial owners used to generate the
        declaration.
      required:
        - declarationDate
        - companyName
        - companyRegNo
        - companyCui
        - repFirstName
        - repLastName
        - repCnp
        - beneficialOwners
      properties:
        declarationDate:
          description: Declaration date (YYYY-MM-DD)
          type: string
          format: date
          example: '2025-11-28'
        companyName:
          description: Company legal name
          type: string
          example: Example SRL
        companyRegNo:
          description: Company registration number
          type: string
          example: J40/1234/2020
        companyCui:
          description: Company CUI (unique tax identifier)
          type: string
          example: RO12345678
        repFirstName:
          description: Legal representative first name
          type: string
          example: Ion
        repLastName:
          description: Legal representative last name
          type: string
          example: Popescu
        repIdSeries:
          description: Representative identity document series (optional)
          type: string
          example: DX
          nullable: true
        repIdNumber:
          description: Representative identity document number (optional)
          type: string
          example: '123456'
          nullable: true
        repCnp:
          description: Representative personal numeric code / national ID
          type: string
          example: '1234567890123'
        repSignature:
          description: >-
            Representative signature (optional). It is used in case the document
            will be electronically signed. If not provided, send null.
          type: string
          example: null
          nullable: true
        beneficialOwners:
          description: List of real beneficiaries associated with the company
          type: array
          items:
            $ref: '#/components/schemas/BeneficiaryDataRequest'
          minItems: 1
        storeInDatabase:
          description: >-
            Whether to persist the company and beneficiaries in DB. Optional;
            defaults to true.
          type: boolean
          example: true
      type: object
    BeneficiaryDataRequest:
      title: Beneficiary data
      description: Details about a real beneficiary.
      required:
        - firstName
        - lastName
        - birthDate
        - placeOfBirthCity
        - placeOfBirthCountry
        - cnp
        - citizenship
        - addressCountry
        - addressCity
        - addressStreet
        - addressNumber
        - controlTypeCode
      properties:
        firstName:
          description: Beneficiary first name
          type: string
          example: Ion
        lastName:
          description: Beneficiary last name
          type: string
          example: Popescu
        birthDate:
          description: Birth date (YYYY-MM-DD)
          type: string
          format: date
          example: '1985-01-01'
        placeOfBirthCity:
          description: City of birth
          type: string
          example: București
        placeOfBirthCountry:
          description: >-
            Country of birth. Accepts ISO 3166-1 alpha-2 (e.g. RO), ISO 3166-1
            alpha-3 (e.g. ROU) or country name (e.g. Romania).
          type: string
          example: RO
        cnp:
          description: Personal numeric code / national ID
          type: string
          example: '1234567890123'
        idSeries:
          description: Identity document series (optional). If not available, send null.
          type: string
          example: DX
          nullable: true
        idNumber:
          description: Identity document number (optional). If not available, send null.
          type: string
          example: '123456'
          nullable: true
        citizenship:
          description: >-
            Country of birth. Accepts ISO 3166-1 alpha-2 (e.g. RO), ISO 3166-1
            alpha-3 (e.g. ROU) or country name (e.g. Romania).
          type: string
          example: RO
        addressCountry:
          description: >-
            Country of birth. Accepts ISO 3166-1 alpha-2 (e.g. RO), ISO 3166-1
            alpha-3 (e.g. ROU) or country name (e.g. Romania).
          type: string
          example: RO
        addressCity:
          description: Residence address city
          type: string
          example: București
        addressStreet:
          description: Residence address street
          type: string
          example: Str. Exemplu
        addressNumber:
          description: Residence address number
          type: string
          example: '10'
        addressDetails:
          description: >-
            Additional address details (optional). E.g. building, entrance,
            floor, apartment.
          type: string
          example: Bl. A, Sc. 1, Et. 2, Ap. 10
          nullable: true
        controlTypeCode:
          $ref: '#/components/schemas/ControlTypeCodeEnum'
      type: object
    BrokerActionLogsRequest:
      title: Broker action logs request
      description: >-
        Optional date range filter for broker action logs. Dates are inclusive
        and expected in YYYY-MM-DD format.
      properties:
        start_date:
          description: Inclusive start date (YYYY-MM-DD).
          type: string
          format: date
          example: '2026-01-01'
          nullable: true
        end_date:
          description: >-
            Inclusive end date (YYYY-MM-DD). Must be >= start_date if both are
            provided.
          type: string
          format: date
          example: '2026-01-14'
          nullable: true
      type: object
    BrokerData:
      description: Common broker data for incoming requests
      required:
        - brokerName
        - brokerInstance
      properties:
        brokerName:
          type: string
          example: SomeBroker
        brokerInstance:
          type: string
          example: instance-1
      type: object
    AddressData:
      title: Address
      required:
        - country
        - city
        - street
        - number
      properties:
        country:
          type: string
          example: România
        city:
          type: string
          example: Cluj-Napoca
        street:
          type: string
          example: Str. Memorandumului
        number:
          type: string
          example: '10'
        details:
          type: string
          example: Bl. A, Sc. 1, Et. 2, Ap. 14
          nullable: true
      type: object
    ContactData:
      title: Contact
      required:
        - phone
        - email
      properties:
        phone:
          type: string
          example: '8989989'
        email:
          type: string
          format: email
          example: test@test.com
      type: object
    DobData:
      title: Date of birth
      required:
        - birthDate
        - placeOfBirthCity
        - placeOfBirthCountry
      properties:
        birthDate:
          type: string
          format: date
          example: '1997-03-18'
        placeOfBirthCity:
          type: string
          example: București
        placeOfBirthCountry:
          type: string
          example: România
      type: object
    FatcaData:
      title: FATCA
      required:
        - usCitizen
        - usFiscalResidency
      properties:
        usCitizen:
          type: boolean
          example: true
        usFiscalResidency:
          type: boolean
          example: true
      type: object
    FiscalResidencyData:
      title: Fiscal residency
      required:
        - countryOfFiscalResidency
        - TINNumbers
      properties:
        countryOfFiscalResidency:
          type: array
          items:
            type: string
          minItems: 1
          example:
            - Romania
            - USA
        TINNumbers:
          type: array
          items:
            type: string
          minItems: 1
          example:
            - '1123443'
            - '2234333'
      type: object
    IdentificationData:
      title: Identification
      required:
        - cnp
        - type
        - number
        - issueAuthority
        - issueDate
        - expiryDate
        - citizenship
        - residencyStatus
      properties:
        cnp:
          type: string
          example: '2830520123456'
        type:
          $ref: '#/components/schemas/IdentificationType'
        series:
          type: string
          example: CJ
          nullable: true
        number:
          type: string
          example: '111222'
        issueAuthority:
          type: string
          example: SPCLEP Cluj
        issueDate:
          description: YYYY-MM-DD, must be <= today
          type: string
          format: date
          example: '2025-01-01'
        expiryDate:
          description: YYYY-MM-DD, must be > issueDate
          type: string
          format: date
          example: '2026-01-01'
        citizenship:
          type: string
          example: Română
        residencyStatus:
          $ref: '#/components/schemas/ResidencyStatus'
      type: object
    KYCRequest:
      title: KYC request
      description: KYC payload
      required:
        - firstName
        - lastName
        - dob
        - identification
        - homeAddress
        - contact
        - work
        - pep
        - fiscalResidency
        - FATCA
        - intermediaryName
        - ASFCode
      properties:
        firstName:
          type: string
          example: Marius
        lastName:
          type: string
          example: Ion
        dob:
          $ref: '#/components/schemas/DobData'
        identification:
          $ref: '#/components/schemas/IdentificationData'
        homeAddress:
          $ref: '#/components/schemas/AddressData'
        mailingAddress:
          oneOf:
            - $ref: '#/components/schemas/AddressData'
          nullable: true
          description: Optional, only if different than homeAddress
        contact:
          $ref: '#/components/schemas/ContactData'
        work:
          $ref: '#/components/schemas/WorkData'
        pep:
          $ref: '#/components/schemas/PepData'
        realBeneficiaryOfPolicy:
          oneOf:
            - $ref: '#/components/schemas/RealBeneficiaryOfPolicyData'
          nullable: true
          description: Optional, only if beneficiary != contractor
        fiscalResidency:
          $ref: '#/components/schemas/FiscalResidencyData'
        FATCA:
          $ref: '#/components/schemas/FatcaData'
        intermediaryName:
          type: string
          example: Asigurator Georgel
        ASFCode:
          type: string
          example: G123
      type: object
    PepData:
      title: PEP information
      properties:
        holdsPublicOffice:
          type: string
          example: President, Romania
          nullable: true
        hasHoldPublicOffice:
          type: string
          example: President, Romania
          nullable: true
        familyMemberOfPep:
          type: string
          example: Son of President of Romania
          nullable: true
        closeAssociateOfPep:
          type: string
          example: Husband of First Lady of Romania
          nullable: true
      type: object
    RealBeneficiaryOfPolicyData:
      title: Real beneficiary of policy
      required:
        - firstName
        - lastName
        - cnp
        - relationWithContractor
      properties:
        firstName:
          type: string
          example: Joe
        lastName:
          type: string
          example: Dow
        cnp:
          type: string
          example: '1111111111'
        relationWithContractor:
          type: string
          example: husband
      type: object
    WorkData:
      title: Work information
      required:
        - occupation
        - profession
        - employerName
        - activityNature
        - sourceOfFunds
      properties:
        occupation:
          type: string
          example: Siio
        profession:
          type: string
          example: Siio
        employerName:
          type: string
          example: My Company SRL
        activityNature:
          type: string
          example: Software Development
        sourceOfFunds:
          $ref: '#/components/schemas/SourceOfFunds'
      type: object
    PepProfileRequest:
      title: PEP profile request
      description: Request used to create a PEP profile if it does not already exist.
      required:
        - firstName
        - lastName
        - identification
        - isPep
        - isRelativeToPep
      properties:
        firstName:
          type: string
          example: Ion
        lastName:
          type: string
          example: Popescu
        identification:
          description: Unique identifier (e.g., CNP / internal identifier).
          type: string
          example: '1234567890123'
        isPep:
          description: Exactly one of isPep or isRelativeToPep must be true.
          type: boolean
          example: true
        isRelativeToPep:
          description: Exactly one of isPep or isRelativeToPep must be true.
          type: boolean
          example: false
      type: object
    PremiumAlertRequest:
      title: Premium alert request
      description: >-
        Input used to determine whether a premium triggers an alert based on
        configured thresholds.
      required:
        - insuranceCategoryCode
        - premiumAmount
        - occasionalTransaction
        - multipleInstallments
      properties:
        offerId:
          description: Optional offer identifier (if available).
          type: integer
          format: int32
          example: 12345
          nullable: true
        insuranceCategoryCode:
          description: Insurance category code used to apply category-specific rules.
          type: string
          example: C1
        premiumAmount:
          description: Premium amount used to evaluate the alert.
          type: number
          format: float
          example: 25000.5
        occasionalTransaction:
          description: True if the premium is for an occasional transaction.
          type: boolean
          example: false
        multipleInstallments:
          description: True if the premium is paid in multiple installments.
          type: boolean
          example: true
      type: object
    SanctionsSearchRequest:
      title: Sanctions search request
      description: |-
        Search sanctions list. Conditional fields are required based on type:
         * - type=person: firstName and lastName required, birthDate optional
         * - type=enterprise: companyName required
         * - type=country: countryName required (country name, ISO2, or ISO3 code)
         * - type=vessel/aircraft/other: companyName used for matching
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/SanctionsSearchTypeEnum'
        firstName:
          description: Required when type=person. Person's first name.
          type: string
          example: Maria
          nullable: true
        lastName:
          description: Required when type=person. Person's last name.
          type: string
          example: PANKRATOVA
          nullable: true
        birthDate:
          description: Optional birth date filter (YYYY-MM-DD). Only used with type=person.
          type: string
          format: date
          example: '1980-05-10'
          nullable: true
        companyName:
          description: Required when type=enterprise. Company/organization name.
          type: string
          example: Star Sapphire
          nullable: true
        countryName:
          description: >-
            Required when type=country. Country name, ISO2 (e.g. 'BG'), or ISO3
            code (e.g. 'BGR').
          type: string
          example: BGR
          nullable: true
      type: object
    ValidationErrorResponse:
      title: Validation error response
      description: Standard Laravel validation error response (HTTP 422).
      required:
        - message
        - errors
      properties:
        message:
          description: Standard API error response shape returned by the API.
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            schema: ApiResponseError
            type: array
            items:
              type: string
      type: object
    ApiResponseError:
      type: array
      items:
        type: string
    ApiValidationErrorResponse2:
      title: Validation error response
      description: >-
        Standard validation error response (HTTP 422). Includes both
        machine-friendly `errors` and UI-friendly `errors_ui`.
      required:
        - message
        - errors
        - errors_ui
      properties:
        message:
          description: Summary message of the validation failure.
          type: string
        errors:
          description: Machine-friendly errors map (keyed by field path).
          type: object
          additionalProperties:
            schema: ApiValidationErrorResponse
            type: array
            items:
              type: string
        errors_ui:
          description: UI-friendly list of validation errors.
          type: array
          items:
            $ref: '#/components/schemas/ValidationUiErrorItem'
      type: object
    ApiValidationErrorResponse:
      type: array
      items:
        type: string
    BeneficiaryCompanyResponse:
      title: Company with real beneficiaries
      description: Company data and its stored real beneficiaries.
      required:
        - declarationDate
        - companyName
        - companyRegNo
        - companyCui
        - repFirstName
        - repLastName
        - repCnp
        - beneficialOwners
      properties:
        declarationDate:
          description: >-
            Most recent update date between company and its beneficiaries
            (YYYY-MM-DD)
          type: string
          format: date
          example: '2026-01-23'
        companyName:
          type: string
          example: Example SRL
        companyRegNo:
          type: string
          example: J40/1234/2020
        companyCui:
          type: string
          example: RO12345678
        repFirstName:
          description: Legal representative first name
          type: string
          example: Ion
        repLastName:
          description: Legal representative last name
          type: string
          example: Popescu
        repIdSeries:
          description: Representative identity document series (optional)
          type: string
          example: DX
          nullable: true
        repIdNumber:
          description: Representative identity document number (optional)
          type: string
          example: '123456'
          nullable: true
        repCnp:
          description: Representative personal numeric code / national ID
          type: string
          example: '1234567890123'
        beneficialOwners:
          description: List of real beneficiaries associated with the company
          type: array
          items:
            $ref: '#/components/schemas/BeneficiaryDataResponse'
      type: object
    BeneficiaryDataResponse:
      title: Real beneficiary
      description: Stored details about a real beneficiary.
      required:
        - firstName
        - lastName
        - birthDate
        - placeOfBirthCity
        - placeOfBirthCountry
        - cnp
        - citizenship
        - addressCountry
        - addressCity
        - addressStreet
        - addressNumber
        - controlTypeCode
      properties:
        firstName:
          type: string
          example: Ion
        lastName:
          type: string
          example: Popescu
        birthDate:
          description: Birth date (YYYY-MM-DD) if available
          type: string
          format: date
          example: '1985-01-01'
          nullable: true
        placeOfBirthCity:
          type: string
          example: București
        placeOfBirthCountry:
          description: >-
            Country of birth. Accepts ISO 3166-1 alpha-2 (e.g. RO), ISO 3166-1
            alpha-3 (e.g. ROU) or country name (e.g. Romania).
          type: string
          example: RO
        cnp:
          type: string
          example: '1234567890123'
        idSeries:
          type: string
          example: DX
          nullable: true
        idNumber:
          type: string
          example: '123456'
          nullable: true
        citizenship:
          description: Citizenship (ISO 3166-1 alpha-2)
          type: string
          example: RO
        addressCountry:
          description: Residence address country (ISO 3166-1 alpha-2)
          type: string
          example: RO
        addressCity:
          type: string
          example: București
        addressStreet:
          type: string
          example: Str. Exemplu
        addressNumber:
          type: string
          example: '10'
        addressDetails:
          description: Additional address details (optional)
          type: string
          example: Bl. A, Sc. 1, Et. 2, Ap. 10
          nullable: true
        controlTypeCode:
          $ref: '#/components/schemas/ControlTypeCodeEnum'
      type: object
    BeneficiaryDocumentResponse:
      title: Beneficiary declaration document
      description: Result of generating a beneficiaries declaration document.
      required:
        - content
        - name
        - mimeType
      properties:
        content:
          description: Base64-encoded PDF content of the generated declaration
          type: string
          example: JVBERi0xLjMKJcTl8uXrp/Og0MTGCjEgMCBvYmoKPDwv...
        name:
          description: Suggested file name
          type: string
          example: declaratie_beneficiar_real.pdf
        mimeType:
          description: MIME type of the generated document
          type: string
          example: application/pdf
      type: object
    BrokerActionLogItemResponse:
      title: Broker action log item
      properties:
        correlation_id:
          type: string
          example: c-123
          nullable: true
        action:
          type: string
          example: sanctions_search_request
        target_type:
          type: string
          example: App\\Models\\SomeModel
          nullable: true
        target_id:
          type: integer
          example: 123
          nullable: true
        payload:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
          example: '2026-01-14T10:11:12.000000Z'
      type: object
    BrokerActionLogsResponse:
      title: Broker action logs response
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BrokerActionLogItemResponse'
      type: object
    PremiumAlertResponse:
      title: Premium alert response
      description: Result of evaluating the premium against configured thresholds.
      required:
        - offerId
        - insuranceCategoryCode
        - premiumAmount
        - alert
        - threshold
        - ruleApplied
      properties:
        offerId:
          description: Echo of the request offerId.
          type: integer
          format: int32
          example: 12345
          nullable: true
        insuranceCategoryCode:
          description: Echo of the request insuranceCategoryCode.
          type: string
          example: C1
        premiumAmount:
          description: Echo of the request premiumAmount.
          type: number
          format: float
          example: 25000.5
        alert:
          description: True if premiumAmount is above the computed threshold.
          type: boolean
          example: true
        threshold:
          description: Threshold used for the evaluation.
          type: number
          format: float
          example: 20000
        ruleApplied:
          $ref: '#/components/schemas/PremiumAlertRuleEnum'
        message:
          description: Optional human-readable message.
          type: string
          example: null
          nullable: true
      type: object
    SanctionMatch:
      title: Sanction match item
      description: A single sanction record match. The structure of aliases varies by type.
      required:
        - id
        - source
        - sourceUniqueId
        - type
        - fullName
      properties:
        id:
          type: integer
          example: 123
        source:
          description: Sanctions list source (e.g. EU, UN, US_OFAC, FATF)
          type: string
          example: EU
        sourceUniqueId:
          type: string
          example: EU12345
        type:
          description: 'Entity type: person, enterprise, vessel, aircraft, country, other'
          type: string
          example: person
        fullName:
          type: string
          example: PANKRATOVA Maria
        firstName:
          type: string
          example: Maria
          nullable: true
        lastName:
          type: string
          example: PANKRATOVA
          nullable: true
        birthDate:
          description: Primary birth date (if available)
          type: string
          format: date
          example: '1980-05-10'
          nullable: true
        birthDates:
          description: >-
            Array of birth date records (for persons). May include partial
            dates.
          type: array
          items:
            $ref: '#/components/schemas/SanctionBirthDateItem'
          nullable: true
        aliases:
          description: >-
            Aliases structure varies by type. For persons: array of name
            objects. For countries: object with iso2/iso3 codes.
          nullable: true
          oneOf:
            - description: Person/enterprise aliases
              type: array
              items:
                $ref: '#/components/schemas/SanctionAliasPersonItem'
            - $ref: '#/components/schemas/SanctionAliasCountryItem'
        addresses:
          description: Known addresses
          type: array
          items:
            $ref: '#/components/schemas/SanctionAddressItem'
          nullable: true
        citizenship:
          description: Citizenship (ISO2 or country name)
          type: string
          example: RU
          nullable: true
        nationality:
          description: Nationality (ISO2 or country name)
          type: string
          example: RU
          nullable: true
        identifications:
          description: Identification documents (passports, VAT numbers, etc.)
          type: array
          items:
            $ref: '#/components/schemas/SanctionIdentificationItem'
          nullable: true
        remarks:
          description: Additional remarks or notes about the sanction
          type: string
          example: Listed pursuant to Article X
          nullable: true
      type: object
    SanctionsSearchResponse:
      title: Sanctions search response (inner)
      description: Search result payload containing array of matches.
      required:
        - matches
      properties:
        matches:
          description: Array of sanction matches. Empty if no matches found.
          type: array
          items:
            $ref: '#/components/schemas/SanctionMatch'
      type: object
    ValidationUiErrorItem:
      title: Validation UI error item
      description: Human-readable validation error item designed for UI display.
      required:
        - path
        - label
        - message
      properties:
        path:
          description: Machine-friendly field path (same keys as in `errors`).
          type: string
          example: beneficialOwners.0.cnp
        label:
          description: Human-friendly label for UI.
          type: string
          example: 'Beneficiar real #1 – CNP beneficiar real'
        message:
          description: Localized error message for UI display.
          type: string
          example: Numărul de identificare este invalid.
      type: object
    IdentificationType:
      title: Identification type
      description: Nomenclature for identification document type
      type: string
      enum:
        - ID_CARD
        - PASSPORT
        - RESIDENCE_PERMIT
      example: ID_CARD
    ResidencyStatus:
      title: Residency status
      description: Resident or non-resident
      type: string
      enum:
        - RESIDENT
        - NON_RESIDENT
      example: RESIDENT
    SourceOfFunds:
      title: Source of funds
      description: Nomenclature for source of funds
      type: string
      enum:
        - SALARY
        - DIVIDENDS
        - SAVINGS
        - INVESTMENTS
        - INHERITANCE
        - OTHER
      example: SALARY
    ControlTypeCodeEnum:
      description: >-
        Control type code. The list of codes (with explanations) is returned by
        GET /nomenclature/controlTypeCode.
      type: string
      enum:
        - OWNERSHIP_25_PLUS
        - SENIOR_MANAGING_OFFICIAL
        - TRUST_CONSTITUTOR
        - TRUST_FIDUCIARY
        - TRUST_BENEFICIARY
        - TRUST_OTHER_CONTROLLER
        - FUND_BENEFICIARY_25
        - FUND_GROUP_INTEREST
        - FUND_CONTROL_25
        - ART_4_2_D_4
    PremiumAlertRuleEnum:
      description: Rule used to determine the premium alert threshold.
      type: string
      enum:
        - HIGH_PREMIUM_GENERAL
        - HIGH_PREMIUM_OCCASIONAL_TRANSACTIONS
        - HIGH_PREMIUM_LIFE_INSTALLMENTS_ANNUAL
    SanctionsSearchTypeEnum:
      description: >-
        Type of entity to search in sanctions. Available types returned by GET
        /nomenclature/sanctionType.
      type: string
      enum:
        - person
        - enterprise
        - vessel
        - aircraft
        - country
        - other
    ControlTypeItem:
      title: Control type item
      description: >-
        Control type code with its explanation. Used by GET
        /nomenclature/controlTypeCode.
      required:
        - code
        - explanation
      properties:
        code:
          description: Control type code (matches ControlTypeCodeEnum values)
          type: string
          example: OWNERSHIP_25_PLUS
        explanation:
          description: Human-readable / legal explanation
          type: string
          example: Deține sau controlează în ultimă instanță...
      type: object
    BeneficiaryDocumentResponseEnvelope:
      title: Beneficiary declaration response (enveloped)
      description: >-
        Successful response wrapper. Payload is returned under the 'data'
        property.
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/BeneficiaryDocumentResponse'
      type: object
    BeneficiaryCompanyResponseEnvelope:
      title: Company with beneficiaries response (enveloped)
      description: >-
        Successful response wrapper. Payload is returned under the 'data'
        property.
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/BeneficiaryCompanyResponse'
      type: object
    PremiumAlertResponseEnvelope:
      title: Premium alert response (enveloped)
      description: >-
        Successful response wrapper. Payload is returned under the 'data'
        property.
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/PremiumAlertResponse'
      type: object
    PepProfile:
      title: PEP profile
      description: Stored PEP profile record.
      required:
        - id
        - first_name
        - last_name
        - identification
        - is_pep
        - is_relative_to_pep
        - created_at
        - updated_at
      properties:
        id:
          type: integer
          format: int64
          example: 1
        first_name:
          type: string
          example: Ionel
        last_name:
          type: string
          example: Popoviciu
        identification:
          type: string
          example: '1920719285079'
        is_pep:
          type: boolean
          example: true
        is_relative_to_pep:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
          example: '2025-12-15T12:06:43.000000Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-12-15T12:06:43.000000Z'
      type: object
    PepProfileStoreInner:
      title: PEP profile create result (inner payload)
      description: Inner payload returned under the top-level 'data' wrapper.
      required:
        - created
        - data
      properties:
        created:
          description: True if a new profile was created; false if it already existed.
          type: boolean
          example: false
        data:
          $ref: '#/components/schemas/PepProfile'
      type: object
    PepProfileStoreResponseEnvelope:
      title: PEP profile create response (enveloped)
      description: Top-level response wrapper. The inner result is returned under 'data'.
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/PepProfileStoreInner'
      type: object
    SanctionBirthDateItem:
      title: Sanction birth date item
      description: Birth date record (may be partial).
      properties:
        date:
          type: string
          format: date
          example: '1980-05-10'
          nullable: true
        year:
          type: integer
          example: 1980
          nullable: true
        month:
          type: integer
          example: 5
          nullable: true
        day:
          type: integer
          example: 10
          nullable: true
        city:
          type: string
          example: Moscow
          nullable: true
        countryIso2:
          type: string
          example: RU
          nullable: true
        circa:
          description: True if date is approximate
          type: boolean
          example: false
          nullable: true
      type: object
    SanctionAliasPersonItem:
      title: Sanction alias (person/enterprise)
      description: Name alias for person or enterprise.
      properties:
        whole_name:
          type: string
          example: IVAN PETROV
          nullable: true
        first_name:
          type: string
          example: IVAN
          nullable: true
        last_name:
          type: string
          example: PETROV
          nullable: true
        quality:
          description: Alias quality (e.g. 'a.k.a.', 'formerly known as')
          type: string
          example: a.k.a.
          nullable: true
      type: object
    SanctionAliasCountryItem:
      title: Sanction alias (country)
      description: ISO codes for sanctioned country.
      properties:
        iso2:
          description: ISO 3166-1 alpha-2 code
          type: string
          example: BG
          nullable: true
        iso3:
          description: ISO 3166-1 alpha-3 code
          type: string
          example: BGR
          nullable: true
      type: object
    SanctionAddressItem:
      title: Sanction address item
      description: Address record for sanctioned entity.
      properties:
        street:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        zipCode:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        countryIso2:
          type: string
          nullable: true
      type: object
    SanctionIdentificationItem:
      title: Sanction identification item
      description: Identification document (passport, VAT, etc.).
      properties:
        type:
          description: Document type
          type: string
          example: passport
          nullable: true
        number:
          description: Document number
          type: string
          example: AB123456
          nullable: true
        country:
          description: Issuing country
          type: string
          example: RU
          nullable: true
        issuedBy:
          type: string
          nullable: true
        issueDate:
          type: string
          nullable: true
        expiryDate:
          type: string
          nullable: true
      type: object
    SanctionsSearchResponseEnvelope:
      title: Sanctions search response (enveloped)
      description: >-
        Successful response wrapper. Payload is returned under the 'data'
        property.
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/SanctionsSearchResponse'
      type: object
    NotFoundMessageResponse:
      title: Not found response
      description: Minimal not-found response containing only a message.
      required:
        - message
      properties:
        message:
          type: string
          example: Company not found
      type: object
  responses:
    ApiUnauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseError'
          example:
            message: Unauthorized
            code: 401
            data: null
            errorCode: '401'
    ApiUnprocessableEntity:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    ApiInternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponseError'
          example:
            message: Internal server error
            code: 500
            data: null
            errorCode: '500'
    ApiCoreLibAuthResponse200:
      description: Auth result
      content:
        application/json:
          schema:
            properties:
              error:
                type: boolean
                example: 'false'
              status:
                type: number
                example: '200'
              data:
                properties:
                  token:
                    description: >-
                      The JSON Web Token (JWT) to be used as the `Token` header
                      value in all subsequent API requests.
                    example: '---JWT Token---'
                  expires_at:
                    description: >-
                      The expiration date and time of the JWT token, in ISO 8601
                      format.
                    example: '2021-09-03 19:41:27'
                  refresh_token:
                    description: A token used to refresh the JWT token when it expires.
                    type: string
                    example: '---Refresh Token---'
                type: object
            type: object
  parameters:
    Token:
      name: Token
      in: header
      description: Login Token
      required: true
      schema:
        type: string
    X-Broker-Name:
      name: X-Broker-Name
      in: header
      description: Broker name identifier (required)
      required: true
      schema:
        type: string
        example: MyBroker
    X-Broker-Instance:
      name: X-Broker-Instance
      in: header
      description: Broker instance identifier (required)
      required: true
      schema:
        type: string
        example: production
    HeaderToken:
      name: Token
      in: header
      description: >-
        The JWT token received from the `POST /auth` endpoint's response field
        name `token`. This should be included in the header as `Token: <JWT
        Token>`.
      required: true
      schema:
        type: string
        format: jwt
  securitySchemes:
    bearerAuth:
      type: http
      bearerFormat: JWT
      scheme: bearer
tags:
  - name: Nomenclature
    description: Endpoints for retrieving nomenclature/lookup data
  - name: Beneficiaries
    description: Endpoints related to company real beneficiaries
  - name: Sanctions
    description: Endpoints for searching sanctions lists
  - name: Broker
    description: Broker
  - name: KYC
    description: KYC
  - name: PEP
    description: PEP
  - name: Premium
    description: Premium
  - name: Authentication
    description: Authentication
