Oper Credits Webhooks API

openapi: 3.2.0
info:
  title: Oper Credits Agent Documents Webhooks API
  version: '1.0'
  description: Your Webhooks tag description
servers:
- url: https://developers.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:
    SourceType:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the source type.
        definition:
          type: string
          description: Description of the source type.
        order:
          type:
          - integer
          - 'null'
          description: Optional order of the type.
      required:
      - id
      - definition
    CostItem:
      type:
      - object
      - 'null'
      properties:
        cost_type:
          type:
          - string
          - 'null'
          enum:
          - null
          - cost_purchase
          - cost_land_purchase
          - cost_renovation
          - cost_building
          - cost_buyout
          - cost_credit_takeover
          - cost_insurance
          - cost_handling
          - cost_file
          - cost_additional_financing_need
          - cost_distribution_notary
          - cost_distribution_registration
          - cost_notary_fees
          - cost_credit_notary
          - cost_credit_notary_fees
          - cost_credit_notary_administration
          - cost_credit_notary_mortgage_registration_fee
          - cost_credit_notary_mortgage_guarantee_fee
          - cost_credit_notary_disbursements
          - cost_credit_notary_annexes
          - cost_credit_registration
          - cost_credit_notary_act
          - cost_purchase_notary
          - cost_purchase_notary_act
          - cost_purchase_notary_annexes
          - cost_purchase_notary_fees
          - cost_purchase_notary_administration
          - cost_purchase_notary_mortgage_transcript
          - cost_purchase_notary_disbursements
          - cost_purchase_registration
          - cost_land_query_fees
          - cost_stamp_duty_fees
          - cost_administration
          - cost_realtor
          - cost_land_registry
          - cost_estimation
          - cost_bank_disbursements
        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
          example: 150
        is_included_in_aprc:
          type: boolean
          description: True if the specific cost type is included in the APRC calculation of the credit
      required:
      - cost_type
      - description
      - amount_incl_vat
      - amount_excl_vat
      - vat_rate
      - amount_vat
      - is_included_in_aprc
      additionalProperties: false
    Decision:
      type: object
      properties:
        type:
          type: string
          description: Categorization or classification of the decision.
          enum:
          - seniorDecision
          - decision
          - recommendation
        description:
          type: string
          description: The actual text content of the decision.
        author:
          type: string
          description: Identifier or name of the user who posted the decision.
        timestamp:
          type: string
          format: datetime
          description: Date and time when the decision was created.
      required:
      - type
      - description
      - author
      - timestamp
    ComplianceAnswerType:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the answer type
        definition:
          type: string
          description: Description of the answer type (e.g., 'boolean', 'text')
          enum:
          - boolean
          - text
        order:
          type:
          - integer
          - 'null'
          description: Optional order of the answer type
      required:
      - id
      - definition
    RealtyValuationNewData:
      type: object
      properties:
        realty:
          $ref: '#/components/schemas/Property'
        valuation:
          $ref: '#/components/schemas/PropertyValuation'
        loan_request:
          $ref: '#/components/schemas/PropertyValuationLoanRequest'
      required:
      - action
      - loan_request
      additionalProperties: false
    FieldComparison:
      type: object
      properties:
        field_name:
          type: string
          description: Name of the compared field.
        loan_request_value:
          type: string
          description: Value from the loan request.
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SourceComparison'
      required:
      - field_name
      - loan_request_value
      - sources
    Event:
      type:
      - object
      - 'null'
      properties:
        payload_type:
          type: string
          description: This field provides more information about the type of the payload sent by the webhook.
          enum:
          - loan_request
          - loan_request_data_connection
          - client_onboarding
          - realty_valuation
          - loan_request_status
          - insurance_simulation
        created:
          type:
          - string
          - 'null'
          format: date
          description: Contains the date on which the object was made. The date should be communicated in compliance with the ISO 8601 standard, which is defined as YYYY-MM-DD.
        origin_id:
          type: string
          description: This field represents the webhook origin.
        livemode:
          type: boolean
          description: If the object exists in livemode, this will have the value 'true'. If not, this will have the value 'false'
      required:
      - id
      - created
      - livemode
      - payload_type
      additionalProperties: false
    SourceDataField:
      type: object
      properties:
        id:
          type: integer
          description: ID of the source data field.
        field_name:
          type: string
          description: Name of the extracted field.
        field_value:
          type:
          - string
          - number
          - boolean
          - object
          - array
          - 'null'
          description: Value of the extracted field.
        status:
          $ref: '#/components/schemas/SourceDataFieldStatus'
      required:
      - id
      - field_name
      - field_value
      - status
    InsuranceSimulation:
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
          description: Oper Insurance ID
          examples:
          - 1
          - 123
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
        coverage_type:
          type:
          - string
          - 'null'
          description: The insurance package coverage type
          enum:
          - null
          - packageA
          - packageB
          - packageC
        status:
          type:
          - string
          - 'null'
          description: The status of the simulation
          enum:
          - null
          - error
          - warning
          - success
          - notCalculated
        message:
          type:
          - string
          - 'null'
          description: The possible error message translation key
        product:
          $ref: '#/components/schemas/OfferItem'
        insurance_provider:
          allOf:
          - $ref: '#/components/schemas/Company'
          - type: object
            properties:
              external_reference:
                type:
                - string
                - 'null'
                example: '1234456'
                description: Partner Insurance Provider ID
        premium:
          type:
          - number
          - 'null'
          format: valuta
          description: The premium to pay for the insurance
          example: 5200.0
        periodicity:
          type:
          - string
          - 'null'
          description: The periodicity of the insurance payment
          enum:
          - null
          - monthly
          - yearly
          - one_shot
          - quarterly
          - semestrial
        covered_amount:
          type:
          - number
          - 'null'
          format: valuta
          description: The insured amount.
          example: 85000.0
        duration:
          type:
          - integer
          - 'null'
          description: Duration of the offer item. (In months)
          example: 240
        to_be_financed:
          type: boolean
          description: True if the liability insurance needs to be taken into account in the current loan request as a liability to be financed together with the new credit.
        mandatory:
          type: boolean
          description: True if the liability insurance needs to be taken because of an obligation coming from the lending company.
        policy_number:
          type:
          - string
          - 'null'
          description: The number of the contract at the insurer company for the insurance in question
          example: 345345345
        client_ids:
          type: array
          items:
            type: integer
            description: The Oper IDs of the clients, which relates to the field id in the Client schema.
      required:
      - id
      - oper_reference
      - coverage_type
      - status
      - product
      - insurance_provider
      - premium
      - periodicity
      - covered_amount
      - duration
      - to_be_financed
      - mandatory
      - policy_number
      - client_ids
    FireInsurance:
      allOf:
      - $ref: '#/components/schemas/Insurance'
      - type: object
        properties:
          has_apartment_complex_policy:
            type: boolean
            description: True if the fire insurance applies to an appartment complex.
          insurance_provider:
            allOf:
            - $ref: '#/components/schemas/Company'
            - type: object
              properties:
                external_reference:
                  type:
                  - string
                  - 'null'
                  example: '1234456'
                  description: Provider of insurance
        required:
        - has_apartment_complex_policy
      unevaluatedProperties: false
    LoanRequestStatus:
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
          description: Oper Loan Request ID
          examples:
          - 1
          - 123
        status:
          type:
          - string
          enum:
          - new_lead
          - positive_preapproval
          - negative_preapproval
          - documents_uploaded
          - analysis_ongoing
          - decision_pending
          - positive_decision
          - negative_decision
          - offer_signed
          - credit_closed
          - request_cancelled
          - dip_accepted
          - dip_rejected
          description: Current status of the loan request, values depend on the tenant.
    PropertyFinancedItem:
      allOf:
      - $ref: '#/components/schemas/FinancedItem'
      - type: object
        properties:
          financed_item_type:
            type: string
            enum:
            - realty
          property_id:
            type: integer
            description: The ID of the property being financed
            example: 1001
        required:
        - property_id
        unevaluatedProperties: false
    Broker:
      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 broker company.
          example: BrokerTrust Brussels ltd.
        is_active:
          type: boolean
          description: If the broker company is still active or not.
        parent:
          $ref: '#/components/schemas/Company'
          description: If the broker has a parent company, the company profile of that parent.
        fsma_status:
          type:
          - string
          - 'null'
          description: The status of the broker company as registered in the Financial Services and Markets Authority (FSMA).
          enum:
          - null
          - suspended
          - active
          - stopped
        commission_fee:
          type:
          - number
          - 'null'
          format: valuta
          description: The amount of commission fee that is attributed to the broker company.
          example: 300
        is_commission_to_be_confiscated:
          type: boolean
          description: Must be set to true if the commission needs to be confiscated for this specific broker.
        is_client_facing:
          type: boolean
          description: Must be set to true if the broker can be seen by the borrower in the Journey Builder tool.
          example: A borrower creates an account through the Journey Builder tool on the website of BrokerTrust Global ltd. and has the possibility to select between multiple sub-brokers (such as BrokerTrust Brussels ltd.). Brokers that are not client-facing might exist but will not appear in this specific list.
        external_reference:
          type:
          - string
          - 'null'
          example: '1234456'
          description: Partner Broker ID
        parent_external_reference:
          type:
          - string
          - 'null'
          example: '1234456'
          description: Partner Broker ID of the parent broker
        company:
          $ref: '#/components/schemas/Company'
        account_manager:
          $ref: '#/components/schemas/APUser'
      required:
      - oper_reference
      - name
      - company
      - is_active
      - parent
      - fsma_status
      - account_manager
      - commission_fee
      - is_commission_to_be_confiscated
      - is_client_facing
      - external_reference
      - parent_external_reference
      additionalProperties: false
    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
    RealtyValuationEvent:
      allOf:
      - $ref: '#/components/schemas/Event'
      - type: object
        properties:
          new_data:
            $ref: '#/components/schemas/RealtyValuationNewData'
        required:
        - new_data
    ComplianceQuestion:
      type: object
      properties:
        id:
          type: integer
          description: Unique ID of the question
        name:
          type: string
          description: Internal name of the question
        text:
          type: object
          description: Question text shown to the user in multiple languages
          additionalProperties:
            type: string
        answer:
          $ref: '#/components/schemas/ComplianceAnswer'
          description: The answer provided for this question
      required:
      - id
      - name
      - text
      - answer
    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
    LoanRequestEvent:
      allOf:
      - $ref: '#/components/schemas/Event'
      - type: object
        properties:
          new_data:
            $ref: '#/components/schemas/LoanRequestNewData'
        required:
        - new_data
    LoanRequestInsuranceSimulation:
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
          description: Oper Loan Request ID
          examples:
          - 1
          - 123
        purposes:
          type: array
          items:
            $ref: '#/components/schemas/LoanPurpose'
        offer:
          $ref: '#/components/schemas/Offer'
        clients:
          type: array
          items:
            $ref: '#/components/schemas/Client'
        credit_liabilities:
          type: array
          items:
            $ref: '#/components/schemas/CreditLiability'
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Property'
        liability_insurances:
          type: array
          items:
            $ref: '#/components/schemas/LiabilityInsurance'
      required:
      - id
      - purposes
      - clients
      - properties
      - liability_insurances
      - offer
      - credit_liabilities
      additionalProperties: false
    LenderState:
      type:
      - object
      properties:
        id:
          type: integer
          description: The unique identifier of each lender state
          example: 12345
      required:
      - id
      additionalProperties: false
    RegulatoryReporting:
      type: object
      properties:
        buy_to_let:
          type: boolean
          description: Should be true if any of the realties with property purpose that is not collateral or sell has a usage type of investmentProperty, privateRent, or professionalRent.
        owner_occupied:
          type: boolean
          description: Should be true if buy_to_let is false, and vice versa.
        first_time_buyer:
          type: boolean
          description: Should be true if all the clients with role = borrower have first_time_buyer = true.
        mortgage_guarantee:
          type: boolean
          description: True if there is a property with a mortgage guarantee type promise or inscription.
        loan_amount:
          type: number
          format: decimal
          description: The total loan amount including bridge loans.
        value:
          type: number
          format: decimal
          description: The sum of reference value of all the realties provided as collateral minus the sum of the amounts of existing mortgage ranks linked to these realties.
        loan_to_value:
          type: number
          format: decimal
          description: Calculated as loan_amount / value.
        debt_service:
          type: number
          format: decimal
          description: The total amount that the borrower pays monthly for existing and new credit (including interest and principal). Calculated as the sum of (A) amortization of all active product items in the offer and (B) monthly_amount of each credit_liability object with take_over = no linked to borrowers.
        total_income:
          type: number
          format: decimal
          description: The total yearly income of all borrowers.
        total_liabilities:
          type: number
          format: decimal
          description: The total yearly liabilities of all borrowers, including new credits. The total amount that is used to calculate DSTI.
        debt_service_to_income:
          type: number
          format: decimal
          description: Calculated as debt_service / total_income.
        debt_amount:
          type: number
          format: decimal
          description: The debt of all the existing loans and new loans. Calculated as the sum of (A) amount of all the product items in the offer where is_active = true and (B) the balance of each of the credit_liability objects where take_over = no linked to the clients with role = borrower.
        debt_to_income:
          type: number
          format: decimal
          description: Calculated as debt_amount / total_income.
        loan_to_income:
          type: number
          format: decimal
          description: Calculated as loan_amount / total_income.
        loan_service:
          type: number
          format: decimal
          description: The total monthly payment by borrowers for all product items in the new loan. Calculated as the sum of amortization of all active product items in the offer.
        loan_service_to_income:
          type: number
          format: decimal
          description: Calculated as loan_service / total_income.
        gross_annual_rental_income:
          type: number
          format: decimal
          description: The total (unweighted) rental income of all borrowers. Calculated as the sum of monthly_amount of each income object with type = TBD linked to borrowers.
        loan_to_rent:
          type: number
          format: decimal
          description: Calculated as loan_amount / gross_annual_rental_income.
        only_refinancing:
          type: boolean
          description: True in case there is only a loan request purpose linked to the loan request with type = refinance.
        annual_interest_cost:
          type: number
          format: decimal
          description: In case buy_to_let = true, this field should contain the sum of all the interest that will be paid in year 1 of all the product items in the offer where is_active = true.
        reason_threshold_exceeding:
          type: string
          description: ' '
          enum:
          - ltv_impacted_by_movable_guarantees
          - increase_in_initial_amount
          - buy_out
          - payment_of_inheritance_taxes
          - specific_professional_target_group
          - commercially_important_target_group
          - credit_committee
          - temporary_situation_bridge_loan_credit
          - guarantee_exchange
          - compliant_with_acceptance_policy
        detailed_reason_threshold_exceeding:
          type: string
          description: ' '
    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
    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.
    ComplianceAnswerBoolean:
      type: object
      properties:
        value:
          type: boolean
          description: Boolean value of the answer
        compliance_answer_type:
          $ref: '#/components/schemas/ComplianceAnswerType'
          description: Type of the compliance answer
        compliance_question_id:
          type: integer
          description: ID of the associated compliance question
        instance_type:
          type: string
          description: Instance type of the answer (e.g., 'boolean')
      required:
      - value
      - compliance_answer_type
      - compliance_question_id
      - instance_type
    Investment:
      type:
      - object
      - 'null'
      properties:
        amount_incl_vat:
          type:
          - number
          - 'null'
          example: 80000
        amount_excl_vat:
          type:
          - number
          - 'null'
          example: 50000
        amount_vat:
          type:
          - number
          - 'null'
          example: 20000
        investment_items:
          type: array
          items:
            $ref: '#/components/schemas/InvestmentItem'
      required:
      - amount_incl_vat
      - amount_excl_vat
      - amount_vat
      - investment_items
      additionalProperties: false
    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
    OtherIncome:
      allOf:
      - $ref: '#/components/schemas/Income'
      - type: object
        properties:
          income_type:
            type: string
            description: The type of income of the client
            enum:
            - variable_income
            - alimony
            - health_insurance
            - meal_vouchers
            - other
            - retirement
            - unemployment_benefit
            - company_car
          comment:
            type:
            - string
            - 'null'
            description: A free text field allowing a comment to be made and more information to be given
          payer:
            type:
            - string
            - 'null'
            description: A free text field allowing to input the paying instance of an income
      unevaluatedProperties: false
    LoanRequestStatusNewData:
      type: object
      properties:
        loan_request_status:
          $ref: '#/components/schemas/LoanRequestStatus'
        action:
          type: string
          description: Action that triggered the webhook
          enum:
          - created
      required:
      - loan_request_status
      - action
    ClientOnboardingEvent:
      allOf:
      - $ref: '#/components/schemas/Event'
      - type: object
        properties:
          new_data:
            $ref: '#/components/schemas/ClientOnboardingNewData'
        required:
        - new_data
    LoanPurpose:
      type: object
      properties:
        is_main:
          type:
          - boolean
          - 'null'
        definition:
          type:
          - string
          - 'null'
          enum:
          - null
          - purchase
          - refinance
          - new_build
          - buy_out
          - renovation
    ClientRelationship:
      type: object
      properties:
        oper_reference:
          type:
          - string
          description: Oper reference
          examples:
          - 092117b8-8c7e-4fd8-827c-cbadc3b037b9
      

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