openapi: 3.0.4
info:
  title: Cadastre Declaration API
  version: 1.0.0
  description: API for Belgian pension cadastre declarations
tags:
- name: ImportDeclaration
  description: Operations related to importing declarations. Provides endpoints to
    create, validate, and retrieve imported declarations.
paths:
  /api/v1/firstpillar/declarations/import:
    post:
      tags:
      - ImportDeclaration
      summary: Submit a cadastre declaration
      operationId: submitDeclaration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/declaration'
      responses:
        '201':
          description: Declaration accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeclarationId'
        '400':
          description: Bad request
        '409':
          description: 'Conflict: we already received a declaration with this referenceDocument'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validationError'
        '500':
          description: Internal server error
  /api/v1/firstpillar/declarations/{declarationId}/status:
    get:
      tags:
      - ImportDeclaration
      summary: Get declaration processing status
      operationId: getDeclarationStatus
      parameters:
      - in: path
        name: declarationId
        required: true
        schema:
          type: string
        description: Declaration identifier
      responses:
        '200':
          description: Current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/declarationState'
        '404':
          description: Declaration not found
        '500':
          description: Internal server error
components:
  schemas:
    Date:
      type: string
      format: date
      description: Date in ISO format (YYYY-MM-DD)
      example: '2025-07-29'
    PositiveAmount:
      type: string
      format: bigdecimal
      pattern: ^(?!0\.00$)\d+\.\d{2}$
      description: Positive amount with two decimal digits (must be > 0)
      example: '123.45'
    BooleanFlag:
      type: string
      enum:
      - '0'
      - '1'
      description: 'Boolean flag: 0 for false, 1 for true'
      example: '1'
    YearMonth:
      type: string
      format: yearmonth
      pattern: ^(\d{4})-(0[1-9]|1[0-2])$
      description: Year and month (YYYY-MM)
      example: 2025-01
    Niss:
      type: string
      format: niss
      pattern: ^[0-9][0-9](([0][0-9])|([1][0-2]))(([0-2][0-9])|([3][0-1]))(([0-9]{2}[1-9])|([0-9][1-9][0-9])|([1-9][0-9]{2}))(([0-8][0-9])|([9][0-7]))$
      description: Belgian National Register (11 digits)
      example: '85073003328'
    NumericId:
      type: string
      pattern: ^\d+$
      description: Numeric identifier
    Reference18:
      type: string
      pattern: ^\d{1,18}$
      minLength: 1
      maxLength: 18
      description: Reference number (1-18 digits)
    PensionFileNumber:
      type: string
      pattern: ^[A-Za-z0-9]{15}$
      minLength: 15
      maxLength: 15
      description: Pension file identifier
    AdvantageCode:
      type: string
      pattern: ^[A-Z0-9]{2}$
      minLength: 2
      maxLength: 2
      description: Advantage code
    EnterpriseNumber:
      type: string
      pattern: ^[0-1]\d{9}$
      description: Belgian enterprise number
    InscriptionNumber:
      type: string
      pattern: ^\d{6}$
      description: Institution registration number
    DeclarationId:
      type: integer
      format: int64
      description: ID of the declaration
    declaration:
      type: object
      properties:
        elements:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Element'
        referenceDocument:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Unique serial number of the declaration per institution.
        inscriptionNumber:
          allOf:
          - $ref: '#/components/schemas/InscriptionNumber'
          description: Registration number of the paying institution.
        documentCreationDate:
          allOf:
          - $ref: '#/components/schemas/Date'
          description: Actual date of creation of the declaration.
        enterpriseNumberPayer:
          allOf:
          - $ref: '#/components/schemas/EnterpriseNumber'
          description: Enterprise number of the paying/declaring institution
        enterpriseNumberDeclarer:
          allOf:
          - $ref: '#/components/schemas/EnterpriseNumber'
          description: Enterprise number of the paying/declaring institution
      required:
      - elements
      - referenceDocument
      - inscriptionNumber
      - documentCreationDate
      - enterpriseNumberPayer
      - enterpriseNumberDeclarer
    validationError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        validation:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    rightCreation:
      type: object
      title: Rightcreation
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        pensionStartDate:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Date from which the person is entitled to the benefit from
            the institution.
        rightStartDate:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Date from which the allocated right for the current reference
            period takes effect.
        pensionType:
          $ref: '#/components/schemas/Enum_pensionType'
        administrativeSituation:
          $ref: '#/components/schemas/Enum_administrativeSituation'
        employerType:
          $ref: '#/components/schemas/Enum_employerType'
        familyChargeCode:
          $ref: '#/components/schemas/Enum_familyChargeCode'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        advantageType:
          $ref: '#/components/schemas/Enum_advantageType'
        houseHoldCode:
          $ref: '#/components/schemas/Enum_houseHoldCode'
        originRight:
          $ref: '#/components/schemas/Enum_originRight'
        initialRightStartDate:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Date of the right has been passed to the new pensioner.
        nissOfSourceRightDonor:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number of the source right donor.
        careerFractionNumeratorDenominator:
          type: string
          pattern: ^\d{3}\.\d{4}/\d{3}\.\d{4}$
          description: Career fraction numerator and denominator.
        performanceRatio:
          type: string
          format: bigdecimal
          pattern: ^[0-9]\.[0-9]{4}$
          description: Performance ratio relevant to pension calculation.
        earlyPaid:
          allOf:
          - $ref: '#/components/schemas/BooleanFlag'
          description: Indicates whether the benefit is paid in advance.
        initialNominalAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Initial nominal amount of the benefit.
        pensionBonusMalusPercentage:
          type: string
          format: int32
          pattern: ^[0-5]$
          description: Bonus or penalty percentage applied to the pension.
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - pensionStartDate
      - rightStartDate
      - pensionType
      - administrativeSituation
      - employerType
      - familyChargeCode
      - advantageCode
      - advantageType
      - houseHoldCode
      - originRight
      - careerFractionNumeratorDenominator
      - performanceRatio
      - initialNominalAmount
      - pensionBonusMalusPercentage
      additionalProperties: false
    rightModification:
      type: object
      title: Rightmodification
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        pensionStartDate:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Date from which the person is entitled to the benefit from
            the institution.
        rightStartDate:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Date from which the allocated right for the current reference
            period takes effect.
        pensionType:
          $ref: '#/components/schemas/Enum_pensionType'
        administrativeSituation:
          $ref: '#/components/schemas/Enum_administrativeSituation'
        employerType:
          $ref: '#/components/schemas/Enum_employerType'
        familyChargeCode:
          $ref: '#/components/schemas/Enum_familyChargeCode'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        advantageType:
          $ref: '#/components/schemas/Enum_advantageType'
        houseHoldCode:
          $ref: '#/components/schemas/Enum_houseHoldCode'
        originRight:
          $ref: '#/components/schemas/Enum_originRight'
        startdateModification:
          allOf:
          - $ref: '#/components/schemas/Date'
          description: First month when the right modification takes effect
        initialRightStartDate:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Date of the right has been passed to the new pensioner.
        nissOfSourceRightDonor:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number of the source right donor.
        careerFractionNumeratorDenominator:
          type: string
          pattern: ^\d{3}\.\d{4}/\d{3}\.\d{4}$
          description: Career fraction numerator and denominator.
        performanceRatio:
          type: string
          format: bigdecimal
          pattern: ^[0-9]\.[0-9]{4}$
          description: Performance ratio relevant to pension calculation.
        earlyPaid:
          allOf:
          - $ref: '#/components/schemas/BooleanFlag'
          description: Indicates whether the benefit is paid in advance.
        initialNominalAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Initial nominal amount of the benefit.
        pensionBonusMalusPercentage:
          type: string
          format: int32
          pattern: ^[0-5]$
          description: Bonus or penalty percentage applied to the pension.
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - pensionStartDate
      - rightStartDate
      - pensionType
      - administrativeSituation
      - employerType
      - familyChargeCode
      - advantageCode
      - advantageType
      - houseHoldCode
      - originRight
      - startdateModification
      - careerFractionNumeratorDenominator
      - performanceRatio
      - initialNominalAmount
      - pensionBonusMalusPercentage
      additionalProperties: false
    rightTermination:
      type: object
      title: Righttermination
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        rightEndDate:
          allOf:
          - $ref: '#/components/schemas/Date'
          description: Last month of the right's effectiveness (closure date)
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - advantageCode
      - rightEndDate
      additionalProperties: false
    rightCancellation:
      type: object
      title: Rightcancellation
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - advantageCode
      additionalProperties: false
    paymentCreation:
      type: object
      title: Paymentcreation
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        familyChargeCode:
          $ref: '#/components/schemas/Enum_familyChargeCode'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        grossAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Gross payment amount before fiscal and social deductions
        precomptableAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Precomptable amount (base for professional withholding calculation)
        indexType:
          $ref: '#/components/schemas/Enum_indexType'
        index:
          type: string
          pattern: ^(0|[1-9].\d{4})$
          description: Index value used for calculating declared amounts
        indexCoefAugmentation:
          type: string
          pattern: ^\d+\.\d{8}$
        paymentMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Month when the payment occurred or will occur
        referencePeriodStartMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Start month of the reference period for the payment
        referencePeriodEndMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: End month of the reference period for the payment
        spouseAtChargeCode:
          $ref: '#/components/schemas/Enum_spouseAtChargeCode'
        numberOfChildrenAtCharge:
          type: string
          format: int32
          pattern: ^\d{1,2}$
          description: Number of dependent children (fiscal notion, disabled = 2)
        numberOfOthersAtCharge:
          type: string
          format: int32
          pattern: ^\d{1,2}$
          description: Number of other dependents (non-children)
        codeZivWithHolding:
          $ref: '#/components/schemas/Enum_codeZivWithHolding'
        amiZivWithholdingAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Amount of AMI/ZIV withholding deducted from payment
        solWithholdingAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Amount of AMI/ZIV withholding deducted from payment
        nominalAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Reduction amount applied to the benefit
        pensionBonusBefore2025Amount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Public sector pension bonus amount
        nominalAmountReductionExcl40bis:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Nominal amount of the benefit
        reductionArticle40bis:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Reduction amount applied to the benefit
        minimumPensionSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Minimum pension supplement amount
        nonPayableMinimumSupplementReason:
          $ref: '#/components/schemas/Enum_nonPayableMinimumSupplementReason'
        guaranteedMinimumSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Minimum pension supplement amount
        supplementHeavyHandicapAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Heavy handicap supplement amount
        totalMaximumSalaryIncludingSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Le total du traitement maximum et du supplément
        professionalActivityReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        flexiJobOverrunPercentage:
          type: string
          format: bigdecimal
          pattern: ^(?:0?\d?\d\.\d{2}|1\d\d\.\d{2}|200\.00)$
          description: Reduction amount applied to the benefit
        flexiJobReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        aifMinimumSupplementReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        replacementIncomeCumulation:
          allOf:
          - $ref: '#/components/schemas/BooleanFlag'
          description: Flag for cumulation with replacement income
        nonPayableReason:
          $ref: '#/components/schemas/Enum_nonPayableReason'
        funeralFeeAmount:
          $ref: '#/components/schemas/PositiveAmount'
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - familyChargeCode
      - advantageCode
      - grossAmount
      - precomptableAmount
      - indexType
      - index
      - indexCoefAugmentation
      - paymentMonth
      - referencePeriodStartMonth
      - referencePeriodEndMonth
      - spouseAtChargeCode
      - numberOfChildrenAtCharge
      - numberOfOthersAtCharge
      - codeZivWithHolding
      - amiZivWithholdingAmount
      - solWithholdingAmount
      - nominalAmount
      - pensionBonusBefore2025Amount
      - reductionArticle40bis
      - minimumPensionSupplementAmount
      - guaranteedMinimumSupplementAmount
      - supplementHeavyHandicapAmount
      - totalMaximumSalaryIncludingSupplementAmount
      - professionalActivityReductionPercentage
      - flexiJobOverrunPercentage
      - flexiJobReductionPercentage
      - aifMinimumSupplementReductionPercentage
      - funeralFeeAmount
      additionalProperties: false
    paymentModification:
      type: object
      title: Paymentmodification
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        familyChargeCode:
          $ref: '#/components/schemas/Enum_familyChargeCode'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        grossAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Gross payment amount before fiscal and social deductions
        precomptableAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Precomptable amount (base for professional withholding calculation)
        indexType:
          $ref: '#/components/schemas/Enum_indexType'
        index:
          type: string
          pattern: ^(0|[1-9].\d{4})$
          description: Index value used for calculating declared amounts
        indexCoefAugmentation:
          type: string
          pattern: ^\d+\.\d{8}$
        paymentMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Month when the payment occurred or will occur
        referencePeriodStartMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Start month of the reference period for the payment
        referencePeriodEndMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: End month of the reference period for the payment
        spouseAtChargeCode:
          $ref: '#/components/schemas/Enum_spouseAtChargeCode'
        numberOfChildrenAtCharge:
          type: string
          format: int32
          pattern: ^\d{1,2}$
          description: Number of dependent children (fiscal notion, disabled = 2)
        numberOfOthersAtCharge:
          type: string
          format: int32
          pattern: ^\d{1,2}$
          description: Number of other dependents (non-children)
        codeZivWithHolding:
          $ref: '#/components/schemas/Enum_codeZivWithHolding'
        amiZivWithholdingAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Amount of AMI/ZIV withholding deducted from payment
        solWithholdingAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Amount of AMI/ZIV withholding deducted from payment
        nominalAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Reduction amount applied to the benefit
        pensionBonusBefore2025Amount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Public sector pension bonus amount
        nominalAmountReductionExcl40bis:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Nominal amount of the benefit
        reductionArticle40bis:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Reduction amount applied to the benefit
        minimumPensionSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Minimum pension supplement amount
        nonPayableMinimumSupplementReason:
          $ref: '#/components/schemas/Enum_nonPayableMinimumSupplementReason'
        guaranteedMinimumSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Minimum pension supplement amount
        supplementHeavyHandicapAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Heavy handicap supplement amount
        totalMaximumSalaryIncludingSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Le total du traitement maximum et du supplément
        professionalActivityReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        flexiJobOverrunPercentage:
          type: string
          format: bigdecimal
          pattern: ^(?:0?\d?\d\.\d{2}|1\d\d\.\d{2}|200\.00)$
          description: Reduction amount applied to the benefit
        flexiJobReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        aifMinimumSupplementReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        replacementIncomeCumulation:
          allOf:
          - $ref: '#/components/schemas/BooleanFlag'
          description: Flag for cumulation with replacement income
        nonPayableReason:
          $ref: '#/components/schemas/Enum_nonPayableReason'
        funeralFeeAmount:
          $ref: '#/components/schemas/PositiveAmount'
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - familyChargeCode
      - advantageCode
      - grossAmount
      - precomptableAmount
      - indexType
      - index
      - indexCoefAugmentation
      - paymentMonth
      - referencePeriodStartMonth
      - referencePeriodEndMonth
      - spouseAtChargeCode
      - numberOfChildrenAtCharge
      - numberOfOthersAtCharge
      - codeZivWithHolding
      - amiZivWithholdingAmount
      - solWithholdingAmount
      - nominalAmount
      - pensionBonusBefore2025Amount
      - reductionArticle40bis
      - minimumPensionSupplementAmount
      - guaranteedMinimumSupplementAmount
      - supplementHeavyHandicapAmount
      - totalMaximumSalaryIncludingSupplementAmount
      - professionalActivityReductionPercentage
      - flexiJobOverrunPercentage
      - flexiJobReductionPercentage
      - aifMinimumSupplementReductionPercentage
      - funeralFeeAmount
      additionalProperties: false
    paymentCancellation:
      type: object
      title: Paymentcancellation
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        referencePeriodStartMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Start month of the reference period for the payment
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - advantageCode
      - referencePeriodStartMonth
      additionalProperties: false
    paymentPreAward:
      type: object
      title: Paymentpreaward
      properties:
        reference:
          allOf:
          - $ref: '#/components/schemas/Reference18'
          description: Internal or own reference number of the institution.
        niss:
          allOf:
          - $ref: '#/components/schemas/Niss'
          description: National registry number (or number assigned by the BCSS) of
            the benefit’s beneficiary.
        pensionFileNumber:
          allOf:
          - $ref: '#/components/schemas/PensionFileNumber'
          description: Pension file number (part of the key).
        periodicity:
          $ref: '#/components/schemas/Enum_periodicity'
        advantageCode:
          allOf:
          - $ref: '#/components/schemas/AdvantageCode'
          description: Differentiates between various benefits that make up a pension
            (part of the key).
        grossAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Gross payment amount before fiscal and social deductions
        precomptableAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Precomptable amount (base for professional withholding calculation)
        indexType:
          $ref: '#/components/schemas/Enum_indexType'
        index:
          type: string
          pattern: ^(0|[1-9].\d{4})$
          description: Index value used for calculating declared amounts
        referencePeriodStartMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: Start month of the reference period for the payment
        referencePeriodEndMonth:
          allOf:
          - $ref: '#/components/schemas/YearMonth'
          description: End month of the reference period for the payment
        nominalAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Reduction amount applied to the benefit
        pensionBonusBefore2025Amount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Public sector pension bonus amount
        nominalAmountReductionExcl40bis:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Nominal amount of the benefit
        reductionArticle40bis:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Reduction amount applied to the benefit
        minimumPensionSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Minimum pension supplement amount
        nonPayableMinimumSupplementReason:
          $ref: '#/components/schemas/Enum_nonPayableMinimumSupplementReason'
        guaranteedMinimumSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Minimum pension supplement amount
        supplementHeavyHandicapAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Heavy handicap supplement amount
        totalMaximumSalaryIncludingSupplementAmount:
          allOf:
          - $ref: '#/components/schemas/PositiveAmount'
          description: Le total du traitement maximum et du supplément
        professionalActivityReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        flexiJobOverrunPercentage:
          type: string
          format: bigdecimal
          pattern: ^(?:0?\d?\d\.\d{2}|1\d\d\.\d{2}|200\.00)$
          description: Reduction amount applied to the benefit
        flexiJobReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        aifMinimumSupplementReductionPercentage:
          type: string
          format: int32
          pattern: ^(100|[1-9]?[0-9])$
          description: Reduction amount applied to the benefit
        replacementIncomeCumulation:
          allOf:
          - $ref: '#/components/schemas/BooleanFlag'
          description: Flag for cumulation with replacement income
        nonPayableReason:
          $ref: '#/components/schemas/Enum_nonPayableReason'
      required:
      - reference
      - niss
      - pensionFileNumber
      - periodicity
      - advantageCode
      - grossAmount
      - precomptableAmount
      - indexType
      - index
      - referencePeriodStartMonth
      - referencePeriodEndMonth
      - nominalAmount
      - pensionBonusBefore2025Amount
      - reductionArticle40bis
      - minimumPensionSupplementAmount
      - guaranteedMinimumSupplementAmount
      - supplementHeavyHandicapAmount
      - totalMaximumSalaryIncludingSupplementAmount
      - professionalActivityReductionPercentage
      - flexiJobOverrunPercentage
      - flexiJobReductionPercentage
      - aifMinimumSupplementReductionPercentage
      additionalProperties: false
    Element:
      oneOf:
      - $ref: '#/components/schemas/rightCreation'
      - $ref: '#/components/schemas/rightModification'
      - $ref: '#/components/schemas/rightTermination'
      - $ref: '#/components/schemas/rightCancellation'
      - $ref: '#/components/schemas/paymentCreation'
      - $ref: '#/components/schemas/paymentModification'
      - $ref: '#/components/schemas/paymentCancellation'
      - $ref: '#/components/schemas/paymentPreAward'
    ValidationError:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
        severity:
          type: string
        code:
          type: string
        message:
          type: string
    rejectedElement:
      type: object
      properties:
        path:
          type: string
        code:
          type: string
        message:
          type: string
        value: {}
    declarationState:
      type: object
      properties:
        declarationId:
          type: string
        status:
          type: string
          enum:
          - RECEIVED
          - VALIDATING
          - ACCEPTED
          - REJECTED
        rejectedElements:
          type: array
          items:
            $ref: '#/components/schemas/rejectedElement'
      required:
      - declarationId
      - status
    Enum_periodicity:
      type: string
      enum:
      - MONTHLY
      - BIMONTHLY
      - TRIMONTHLY
      - QUARTERLY
      - BIANNUAL
      - EXCEPTIONAL
      - YEARLY
      - CAPITAL
      description: Payment periodicity of the benefit (part of the key).
    Enum_pensionType:
      type: string
      enum:
      - REST
      - SURVIVAL
      - SEPARATED_SPOUSE
      - ORPHAN_4
      - ORPHAN_5
      description: Type of pension.
    Enum_administrativeSituation:
      type: string
      enum:
      - OTHER_CATEGORIES
      - EMPLOYEE_SOCIAL_INSURANCE
      - INDEPENDANT_SOCIAL_INSURANCE
      - CIVIL_SERVANT
      - POLITICAL_AGENT
      - PENSION_FUND
      - COLLECTIVE_CONTRACT
      - INDEPENDANT_INDIVIDUAL_PENSION
      - INDEPENDANT_COMPLEMENTARY_PENSION
      description: Administrative or legal situation of the beneficiary or their right
        holder.
    Enum_employerType:
      type: string
      enum:
      - NA
      - PRIVATE
      - PUBLIC
      description: Nature of the employer initiating the contract.
    Enum_familyChargeCode:
      type: string
      enum:
      - WITH_FAMILY_CHARGES
      - WITHOUT_FAMILY_CHARGES
      description: Family charge code used to calculate social contributions.
    Enum_advantageType:
      type: string
      enum:
      - LEGAL_PENSION
      - EXTRALEGAL_PENSION
      - COMPLEMENTARY_LEGAL_PENSION
      - COMPLEMENTARY_EXTRALEGAL_PENSION
      - OTHER_LEGAL
      - OTHER_EXTRALEGAL
      description: Specifies the category of the benefit.
    Enum_houseHoldCode:
      type: string
      enum:
      - UNCOMMUNICATED_VALUE
      - HOUSEHOLD_RATE
      - SINGLE_RATE
      description: Code identifying the household situation relevant to benefit calculation.
    Enum_originRight:
      type: string
      enum:
      - NATIONAL
      - FOREIGN
      - SUPRANATIONAL
      description: Origin of the pension right.
    Enum_indexType:
      type: string
      enum:
      - NO_INDEX
      - PRIVATE_SECTOR
      - PUBLIC_SECTOR
      - NBB
      - ROSSEL
      - MIVB
      description: Indexation system used for benefit amounts
    Enum_spouseAtChargeCode:
      type: string
      enum:
      - ISOLATED_OR_MARRIED_HIGH_INCOME
      - MARRIED_MEDIUM_PENSION_INCOME
      - MARRIED_LOW_OR_NO_PENSION_INCOME
      - MARRIED_HIGH_PENSION_INCOME
      - MARRIED_LOW_OTHER_PROFESSIONAL_INCOME
      - UNKNOWN
      description: Fiscal status of spouse for tax purposes
    Enum_codeZivWithHolding:
      type: string
      enum:
      - NO_ZIV_CONTRIBUTION
      - WITH_FAMILY_CHARGE
      - WITHOUT_FAMILY_CHARGE
      - COMPUTED_UPON_INAMI_REQUEST
      - NOT_COMPUTED_ANYMORE_UPON_INAMI_REQUEST
      - NOT_SUBJECTED_TO_AMI
      description: AMI/ZIV withholding code applied to the payment
    Enum_nonPayableMinimumSupplementReason:
      type: string
      enum:
      - PRISON
      - PROFESSIONAL_ACTIVITY
      - OTHER
      description: Minimum pension supplement amount
    Enum_nonPayableReason:
      type: string
      enum:
      - ABROAD
      - WAITING_FOR_BENEFICIARY_RESPONSE
      - NO_ADDRESS_FOR_ASSIGNMENT_PAYMENT
      - RESIDENCE_CERTIFICATE_MISSING
      - LIFE_CERTIFICATE_MISSING
      - COMPENSATION_TO_EXECUTE
      - RESIDUAL_RIGHT_AND_OTHER_PENSION_CUMULATION
      - RETIREMENT_OTHER_SCHEME_AND_SURVIVOR_CUMULATION
      - SPOUSE_DEATH_NON_OFFICIAL_FOREIGN
      - SPOUSE_DEATH_OFFICIAL_BE_FOREIGN
      - BENEFICIARY_DEATH_NON_OFFICIAL_FOREIGN
      - BENEFICIARY_DEATH_OFFICIAL_BE_FOREIGN
      - ABROAD_STAY_NON_PAYABLE
      - PENSION_AMOUNT_DECREASE
      - DIVORCE
      - PRISON_OR_SOCIAL_DEFENSE_STATUS
      - NISS_MERGE_OR_SPLIT
      - MODEL_S
      - CHEQUE_PAYMENT_NOT_ALLOWED_FOR_COUNTRY
      - PAYMENT_UNDER_WRONG_NATIONAL_NUMBER
      - REMOVED_EX_OFFICIO
      - TECHNICAL_REASONS
      - REFUSAL_OR_RENUNCIATION
      - REMARRIAGE_OF_SURVIVOR_BENEFICIARY
      - SPOUSE_RESUMED_PROFESSIONAL_ACTIVITY
      - BENEFICIARY_RESUMED_PROFESSIONAL_ACTIVITY
      - RESIDENCE_IN_CARE_HOME
      - PAYMENT_RETURNS
      - NATIONAL_SECURITY_OCAM
      - SEPARATION_OR_REUNION_OF_SPOUSES
      description: Reason code for non-payable rights
