Oper Webhooks API

openapi: 3.2.0
info:
  title: Oper Agent Documents Webhooks API
  version: '1.0'
  description: Your Webhooks tag description
servers:
- url: https://api.opercredits.com
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Webhooks
  description: Your Webhooks tag description
paths:
  /your-webhook-endpoint:
    post:
      tags:
      - Webhooks
      summary: Your endpoint implementation for handling Oper Connect's webhooks
      description: This path represents the path to your API implementation of the end point that is configured in Oper Connect. It describes what Oper Connect will send to your endpoint, and what it expects in response.
      requestBody:
        description: Post information about the loan request
        content:
          application/json:
            schema:
              discriminator:
                propertyName: payload_type
                mapping:
                  loan_request: '#/components/schemas/LoanRequestEvent'
                  loan_request_data_connection: '#/components/schemas/LoanRequestDataConnectionEvent'
                  client_onboarding: '#/components/schemas/ClientOnboardingEvent'
                  realty_valuation: '#/components/schemas/RealtyValuationEvent'
                  loan_request_status: '#/components/schemas/LoanRequestStatusEvent'
                  insurance_simulation: '#/components/schemas/InsuranceSimulationEvent'
              oneOf:
              - $ref: '#/components/schemas/LoanRequestEvent'
              - $ref: '#/components/schemas/LoanRequestDataConnectionEvent'
              - $ref: '#/components/schemas/ClientOnboardingEvent'
              - $ref: '#/components/schemas/RealtyValuationEvent'
              - $ref: '#/components/schemas/LoanRequestStatusEvent'
              - $ref: '#/components/schemas/InsuranceSimulationEvent'
        required: true
      responses:
        '201':
          description: created
        '202':
          description: Updated
        '400':
          description: Generic error
        '422':
          description: Invalid input
components:
  schemas:
    ClientOnboardingNewData:
      type: object
      properties:
        loan_request:
          $ref: '#/components/schemas/LoanRequestClientOnboarding'
        action:
          type: string
          description: Action that triggered the webhook
          enum:
          - updated
      required:
      - action
      - loan_request
      additionalProperties: false
    InvestmentItem:
      type:
      - object
      - 'null'
      properties:
        investment_type:
          type:
          - string
          - 'null'
          enum:
          - null
          - cost_purchase
          - cost_renovation
          - cost_land_purchase
          - cost_building
          - cost_buyout
          - cost_credit_takeover
          - cost_additional_financing_need
        description:
          type:
          - string
          - 'null'
          description: All necessary details to describe the cost
          example: this is a cost relating to the notary's efforts when purchasing a house
        amount_incl_vat:
          type:
          - number
          - 'null'
          format: valuta
          description: The amount of the cost type including the VAT
        amount_excl_vat:
          type:
          - number
          - 'null'
          format: valuta
          description: The amount of the cost type excluding the VAT
        vat_rate:
          type:
          - number
          - 'null'
          format: percentage
          description: The percentage amount of the vat for a specific cost type
          example: 21
        amount_vat:
          type:
          - number
          - 'null'
          format: valuta
          description: The monetary amount of the vat for a specific cost type
      required:
      - investment_type
      - description
      - amount_incl_vat
      - amount_excl_vat
      - vat_rate
      - amount_vat
      additionalProperties: false
    NewDataInsuranceSimulation:
      type: object
      properties:
        loan_request:
          $ref: '#/components/schemas/LoanRequestInsuranceSimulation'
        insurance_simulation:
          $ref: '#/components/schemas/InsuranceSimulation'
        action:
          type: string
          description: Action that triggered the webhook
          enum:
          - updated
      required:
      - action
      - loan_request
      - insurance_simulation
      additionalProperties: false
    Notary:
      type:
      - object
      - 'null'
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        name:
          type:
          - string
          - 'null'
          example: Operland Notary Brussels
        is_active:
          type: boolean
          description: Is true if the notary company is still registered as an active company
          example: true
        external_reference:
          type:
          - string
          - 'null'
          example: 211698
          description: External reference of a notary
        company:
          $ref: '#/components/schemas/Company'
      required:
      - oper_reference
      - name
      - is_active
      - company
      additionalProperties: false
    SourceData:
      oneOf:
      - $ref: '#/components/schemas/GenericSourceData'
      - $ref: '#/components/schemas/RealtySourceData'
    LoanRequestEvent:
      allOf:
      - $ref: '#/components/schemas/Event'
      - type: object
        properties:
          new_data:
            $ref: '#/components/schemas/LoanRequestNewData'
        required:
        - new_data
    Ownership:
      type:
      - object
      - 'null'
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        client_id:
          type: integer
          description: The Oper Client ID in the loan request.
        share:
          type:
          - number
          - 'null'
          format: percentage
          description: The percentage of ownership, or share, of a client in the specific property.
        ownership_type:
          type:
          - string
          - 'null'
          description: The type of ownership depending on the legally accepted possibilities.
          enum:
          - null
          - full_ownership
          - ground_lease
          - building_right
          - undivided
          - free_hold
          - usufruct
      required:
      - oper_reference
      - client_id
      - share
      - ownership_type
      additionalProperties: false
    ComplianceSection:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the section
        name:
          type: string
          description: Internal name of the section
        title:
          type: object
          description: Display title of the section in multiple languages
          additionalProperties:
            type: string
        questions:
          type: array
          description: List of compliance questions
          items:
            $ref: '#/components/schemas/ComplianceQuestion'
      required:
      - id
      - name
      - title
      - questions
    BankBranch:
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
          description: Oper Bank Branch ID
          example: 123
        definition:
          type:
          - string
          - 'null'
          description: The name of the bank branch.
        order:
          type:
          - integer
          - 'null'
          description: Optional order of the bank branch.
      required:
      - id
      - definition
    AdditionalFinancingNeed:
      type: object
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        id:
          type: integer
          description: Oper Additional Financing Need ID
          examples:
          - 1
          - 123
        additional_financing_need_type:
          type:
          - string
          description: The type of additional financing need of the client
          enum:
          - executed_renovations
          - heritage_taxes_movable
          - family_debt
          - heritage_or_donation_costs
          - heritage_taxes_immovable
          - purchase_car
          - personal_taxes
          - donation_taxes_immovable
          - city_taxes
          - handling_costs
          - liquidities
          - registration_rights_and_notary_costs
        amount:
          type:
          - number
          - 'null'
          format: valuta
          description: The amount of the additional financing need
          example: 1234.56
      required:
      - oper_reference
      - id
      - additional_financing_need_type
      - amount
    DocumentDescription:
      allOf:
      - $ref: '#/components/schemas/DocumentDescriptionBase'
      unevaluatedProperties: false
    DocumentRelation:
      type: object
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        id:
          type:
          - integer
          - 'null'
          description: The Oper ID of the model that is related to the uploaded document, or null if the model is loan_request
          examples:
          - 1
          - 123
          - null
        type:
          type: string
          description: The name of the schema, as indicated in the current OpenAPI specification document, to which the specific document is related.
          enum:
          - client
          - insurance
          - income
          - liability
          - loan_request
          - property
          - financial_asset
          - additional_financing_need
      required:
      - oper_reference
      - id
      - type
      additionalProperties: false
    LoanRequestNewData:
      type: object
      properties:
        loan_request:
          $ref: '#/components/schemas/LoanRequest'
        action:
          type: string
          description: Action that triggered the webhook
          enum:
          - updated
      required:
      - action
      - loan_request
      additionalProperties: false
    LoanRequestPurpose:
      type: object
      properties:
        is_main:
          type:
          - boolean
          - 'null'
        purpose:
          type:
          - string
          - 'null'
          enum:
          - null
          - purchase
          - refinance
          - new_build
          - buy_out
          - renovation
    LoanRequestDataConnectionNewData:
      type: object
      properties:
        lender_state:
          $ref: '#/components/schemas/LenderState'
        expected_number_of_transfer_rounds:
          type:
          - number
          - 'null'
          description: Expected number of transfer rounds for this loan request.
          example: 3
        current_transfer_round:
          type: number
          description: Current transfer round number.
          example: 1
        is_marked_as_last_transfer_round:
          type: boolean
          description: Indicates whether the current transfer round is marked as the last transfer round by the user.
          example: false
        loan_request:
          $ref: '#/components/schemas/LoanRequestDataConnection'
        action:
          type: string
          description: Action that triggered the webhook
          enum:
          - created
      required:
      - lender_state
      - expected_number_of_transfer_rounds
      - current_transfer_round
      - is_marked_as_last_transfer_round
      - action
      - loan_request
      additionalProperties: false
    Comment:
      type: object
      properties:
        type:
          type: string
          description: Categorization or classification of the comment.
          enum:
          - loanRequest
          - phone
          - email
          - appointment
        description:
          type: string
          description: The actual text content of the comment.
        author:
          type: string
          description: Identifier or name of the user who posted the comment.
        timestamp:
          type: string
          format: datetime
          description: Date and time when the comment was created.
      required:
      - type
      - description
      - author
      - timestamp
    OfferItem:
      type: object
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        external_reference_base_product:
          type:
          - string
          description: External reference
        end_payment:
          type:
          - number
          - 'null'
          format: valuta
          description: Last monthly installment of the offer item.
          example: 890.0
        monthly_installment:
          type:
          - number
          - 'null'
          format: valuta
          description: First monthly installment of the offer item.
          example: 750.0
        aprc:
          type:
          - number
          - 'null'
          format: percentage
          description: APRC related to the offer item.
          example: 0.0394
        max_aprc:
          type:
          - number
          - 'null'
          format: percentage
          description: The APRC based upon the max interest rate in case of a variable interest rate.
          example: 0.049
        base_rate:
          type:
          - number
          - 'null'
          format: percentage
          description: Base interest rate related to the offer item, not taking into account any add-ons/quality adjustments.
          example: 0.034
        delta_adjustment:
          type:
          - number
          - 'null'
          format: percentage
          description: Computes the manual correction (delta) between the final rate and the expected rate (base + quality + conditional adjustments)
          example: 0.04
        applied_add_ons_rate:
          type:
          - number
          - 'null'
          format: percentage
          description: Sum of the interest rate of all add-ons of the offer item.
          example: -0.005
        adjusted_rate:
          type:
          - number
          - 'null'
          format: percentage
          description: Sum of base rate and quality adjustments.
          example: 0.036
        final_rate:
          type:
          - number
          - 'null'
          format: percentage
          description: Interest rate related to the offer item.
          example: 0.036
        amount:
          type:
          - number
          - 'null'
          format: valuta
          description: Amount allocated to the offer item.
          example: 456000.0
        duration:
          type:
          - number
          - 'null'
          format: integer
          description: Duration of the offer item. (In months)
          example: 240
        financed_items:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/PropertyFinancedItem'
            - $ref: '#/components/schemas/CreditFinancedItem'
          description: A list of items (realty/credit) that are going to be financed
        tax_deductability:
          type: boolean
          description: Indicates whether the credit qualifies for tax deducibility.
          example: true
        waive_early_repayment_fee:
          type: boolean
          description: Indicates whether the early repayment fee is waived.
          example: true
        attestation_amount:
          type:
          - number
          - 'null'
          format: valuta
          description: Registration amount that qualifies for tax deducibility.
        deductable_amount:
          type:
          - number
          - 'null'
          format: valuta
          description: Actual fiscal deductible amount of the credit.
        fiscal_purpose_type:
          type:
          - string
          - 'null'
          description: The fiscal purpose of the credit.
          enum:
          - purchase_residential_property
          - other_purpose
          - home_construction
          - inheritance_donation_rights
          - conversion_of_og_into_residential
          - loan_repayment
          - home_renovation
          - renovation
        grace_period_applicable:
          type: boolean
          description: Indicates whether a grace period is applicable.
          example: true
        payout_at_deed:
          type:
          - number
          - 'null'
          format: valuta
          description: Amount that has to be paid to the notary at deed date.
        drawdown:
          type:
          - number
          - 'null'
          format: valuta
          description: The amount of the credit that can be drawn down later in case of renovation or new construction.
        variability:
          type:
          - string
          - 'null'
          description: Variability of the offer item.
          enum:
          - null
          - 10-10-cap+2/-5
          - 20-5-5
          - 20-fix
          - 10-5-5-cap3
          - 16-5-5
          - 20-5
          - 10-5-5
          - 13-1-1-cap3
          - 10-3-3
          - 20-5-5-cap3
          - 5-5-5-cap3
          - 20-3-3
          - 15-3-3
          - 13-5-5
          - 6-1-1-cap3
          - 20-1-1-cap3
          - 3-3-3-cap2
          - 5-5-5
          - 1-1-1-cap4
          - 5-5-5-cap2
          - 5-5-5-cap5
          - 10-5-5-cap5
          - 10-5-5-cap+2/-5
          - 3-3-3-cap5
          - 15-5-5-cap+2/-5
          - fix
          - 1-1-1-cap3
          - 1-1-1-acc
          - 10-5-5-cap2
          - 5-5-5-cap4
          - 1-1-1
          - 3-3-3
          - 15-5-5-cap5
          - 12-5-5-cap3
          - 15-5-5-cap3
        product:
          type:
          - string
          - 'null'
          description: Product name allocated to the offer item.
          example: Variable Mortgage Credit
        loan_type:
          type:
          - string
          - 'null'
          description: Loan type relating to the offer item.
          enum:
          - null
          - mensuality
          - bridge_loan
          - crescendo
          - balloon_credit
          - balloon_credit_no_payment
          - progressive_amortization
        commission_amount:
          type:
          - number
          - 'null'
          format: valuta
          description: Commission amount of the offer item.
          example: 750.0
        contract_number:
          type:
          - string
          - 'null'
          description: The number of the contract as defined on the contract itself
          example: 12345678
        cost_file:
          type:
          - number
          - 'null'
          format: valuta
          description: File costs amount of the offer item.
          example: 750.0
        liability_insurance_add_on_date:
          type:
          - string
          - 'null'
          format: date
          description: Date of the liability insurance add-on.
          example: '2024-12-01'
        liability_insurance_ids:
          type: array
          items:
            type:
            - number
            - 'null'
            description: The unique identifier of the liability insurance.
            example: 123456
        loan_purpose:
          type:
          - string
          - 'null'
          enum:
          - null
          - purchase
          - refinance
          - new_build
          - buy_out
          - renovation
        loan_sub_purposes:
          type: array
          items:
            type:
            - string
            - 'null'
            description: The sub purpose of the loan.
            enum:
            - null
            - buyOut
            - heritageTaxes
            - newBuild
            - notaryFees
            - propertyDownPayment
            - purchase
            - purchaseOfGarage
            - purchaseOfLand
            - refinance
            - renovation
        applied_add_ons:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        quality_adjustments:
          type: array
          items:
            $ref: '#/components/schemas/QualityAdjustment'
        grace_period:
          type:
          - number
          - 'null'
          description: The number of months of grace period.
          example: 20
        due_day:
          type:
          - integer
          - 'null'
          description: Due day of the loan.
          example: 15
        is_interest_paid_in_grace_period:
          type:
          - boolean
          description: Indicates whether interest was paid in grace period.
          example: false
        first_principal_repayment_date:
          type:
          - string
          format: date
          description: Date of the first principal repayment.
          example: '2024-12-01'
        pricing_sheet_valid_from_date:
          type:
          - string
          - 'null'
          format: date
          description: The valid from date of the pricing sheet associated with the product item.
          example: '2025-01-01'
        pricing_sheet_version:
          type:
          - string
          - 'null'
          description: The version of the pricing sheet associated with the product item.
          example: v2.1
      required:
      - oper_reference
      - end_payment
      - monthly_installments
      - aprc
      - base_rate
      - quality_adjustments
      - adjusted_rate
      - applied_add_ons_rate
      - final_rate
      - amount
      - duration
      - variability
      - product
      - loan_type
      - applied_add_ons
      - cost_file
      - grace_period
      - due_day
      - is_interest_paid_in_grace_period
      - first_principal_repayment_date
      additionalProperties: false
    RealtySourceData:
      type: object
      properties:
        realty_id:
          type: integer
          description: ID of the realty associated with the source data.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/SourceDataField'
        source_data_type:
          $ref: '#/components/schemas/SourceDataType'
        source_type:
          $ref: '#/components/schemas/SourceType'
      required:
      - realty_id
      - fields
      - source_data_type
      - source_type
    PropertyValuationLoanRequest:
      type:
      - object
      - 'null'
      properties:
        liability_type:
          type:
          - string
          - 'null'
          description: The type of liability.
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        id:
          type: integer
          description: Oper Loan Request ID
          examples:
          - 1
          - 123
        external_reference:
          type:
          - string
          - 'null'
          description: Partner Loan Request ID
          examples:
          - ABC123456
          - '9876543210'
        loan_amount:
          type: number
          format: decimal
          description: The total loan amount
        borrowers:
          type: array
          items:
            $ref: '#/components/schemas/PropertyValuationBorrower'
      required:
      - oper_reference
      - id
      - external_reference
      - borrowers
      - loan_amount
      additionalProperties: false
    Valuation:
      type:
      - object
      - 'null'
      properties:
        fair_value:
          type:
          - number
          - 'null'
          format: valuta
          description: The fair value of the property.
        fair_value_after_renovation:
          type:
          - number
          - 'null'
          format: valuta
          description: The fair value of the renovated property.
        forced_sale_value_before_renovation:
          type:
          - number
          - 'null'
          format: valuta
          description: The forced sale fair value of the property before renovation.
        forced_sale_value_after_renovation:
          type:
          - number
          - 'null'
          format: valuta
          description: The forced sale fair value of the property.
        reference_value:
          type:
          - number
          - 'null'
          format: valuta
          description: Reference value of the property.
        is_reference_value_overridden:
          type: boolean
          description: True if the reference value was overridden by the user.
        pro_fisco_value:
          type:
          - number
          - 'null'
          format: valuta
          description: Pro fisco value of the property.
        valuation_date:
          type:
          - string
          - 'null'
          format: date
          description: The date on which the valuation of the property was done.
        valuation_expiration_date:
          type:
          - string
          - 'null'
          format: date
          description: The expiration date of the valuation.
        valuation_type:
          type: string
          enum:
          - automatic
          - desktop
          - onsite
        valuation_reference:
          type:
          - string
          description: Unique reference of the valuation.
        estimator:
          $ref: '#/components/schemas/Estimator'
        epc_reference_number:
          type:
          - string
          - 'null'
          description: The EPC contract number of the property.
        epc_validity:
          type:
          - string
          - 'null'
          format: date
          description: The date until which the EPC certificate is valid.
    APUser:
      type:
      - object
      - 'null'
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        first_name:
          type:
          - string
          - 'null'
          description: The first name (i.e. surname) of the advisor.
          example: John
        middle_name:
          type:
          - string
          - 'null'
          description: The middle name of the advisor.
          example: Mary
        last_name:
          type:
          - string
          - 'null'
          description: The last name (i.e. family name) of the advisor.
          example: Doe
        mother_maiden_name:
          type:
          - string
          - 'null'
          description: The mother's maiden name of the advisor.
          example: Jane
        birth_date:
          type:
          - string
          - 'null'
          format: date
          description: The birth date of the advisor.
        birth_city:
          type:
          - string
          - 'null'
          description: The city of birth of the advisor.
          example: Brussels
        language:
          type:
          - string
          - 'null'
          enum:
          - null
          - nl-BE
          - fr-BE
          - en-UK
          - de-CH
          - it-CH
          description: The preferred language of the advisor, which is also the language in which the Oper platform appears to the advisor after log-in.
        role:
          type:
          - string
          - 'null'
          description: The role of the advisor within its company.
          enum:
          - null
          - decider
          - account_manager
          - broker_manager
          - analyst
          - broker
          - upload
          - senior_decider
          - head_decider
          - operations_manager
          - client
        external_reference:
          type:
          - string
          - 'null'
          example: 211698
          description: External reference of the advisor.
        lender_identifier:
          type:
          - string
          - 'null'
          example: '12345678'
          description: The advisor's identifier at the lender (credit provider) associated with the loan request. Sourced from the advisor's per-lender bank ID configuration.
        is_available:
          type:
          - boolean
          - 'null'
          example: true
          description: Whether the user has marked themselves as available. Defaults to true.
        emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
        phones:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
      required:
      - oper_reference
      - first_name
      - middle_name
      - last_name
      - mother_maiden_name
      - birth_date
      - birth_city
      - emails
      - language
      - role
      additionalProperties: false
    SourceDataType:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the source data type.
        definition:
          type: string
          description: Description of the source data type.
        order:
          type:
          - integer
          - 'null'
          description: Optional order of the type.
      required:
      - id
      - definition
    Income:
      type: object
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        id:
          type: integer
          description: Oper Income ID
          examples:
          - 1
          - 123
        amount:
          type:
          - number
          - 'null'
          format: valuta
          description: The monthly amount of income
          example: 1234.56
        periodicity:
          type:
          - string
          - 'null'
          description: The periodicity to which the income is being paid or calculated
          enum:
          - null
          - yearly
          - semestrial
          - quarterly
          - monthly
          - one_shot
      required:
      - oper_reference
      - id
      - income_type
      - amount
      - periodicity
    RentalLiability:
      allOf:
      - $ref: '#/components/schemas/Liability'
      - type: object
        properties:
          liability_type:
            type:
            - string
            description: The type of liability of the client
            enum:
            - rent
          gone_after_request:
            type: boolean
            description: Is true if the liability will be gone once the loan request has been closed.
          start_date:
            type:
            - string
            - 'null'
            format: date
            description: The date on which the first payment of the liability was issued.
            example: '2020-12-02'
        required:
        - gone_after_request
        - start_date
      unevaluatedProperties: false
    Company:
      type:
      - object
      - 'null'
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        name:
          type:
          - string
          - 'null'
          description: The name of the company.
          example: Cardiff
        legal_name:
          type:
          - string
          - 'null'
          description: The legal name of the company as written on the balance sheet.
          example: Cardiff ltd.
        vat_number:
          type:
          - string
          description: The VAT number of the company (for companies operating under the legislation that uses VAT numbers).
          example: DE123456789
        company_registration_number:
          type:
          - string
          - 'null'
          description: The company registration number of the company (for companies operating under the legislation that uses company registration numbers).
          example: HRB 12345
        sector:
          type:
          - string
          - 'null'
          description: The sector in which the company operates.
          enum:
          - null
          - financial_services
          - industry
          - it
          - services
          - hosp

# --- truncated at 32 KB (139 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/oper/refs/heads/main/openapi/oper-webhooks-api-openapi.yml