NAV Navbar

Introduction

Welcome to the Oper API Reference. This API is used for Contact2Contract loan provisioning.

We have language bindings in Shell and Python as well as JSON examples.

Authentication

POST /api/token/

Request

{
  "username": "user@site.com",
  "password": "safepassword"
}

Response

{
  "token": "veryLongAndSecureToken123456"
}

Oper uses Token authentication to connect to any non-public endpoint. A token can be requested for any registered user of the application.

You can request a user from our info address.

Oper expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Token <your-api-key>

General structure

Oper is build upon two main endpoints.

All Oper API endpoints use camel-case structure in their responses. API endpoints use camel_case buy with dashed for improved readability.

API structure

The API is separated in several large blocks. Each of the APIs in this chapter should be under the /api subpath.

API Conventions

Objects and resources

Any static resource has an id to reference, as well as a definition. This definition is a camelCase definition of the internal representation. The definition is an internal usage and will be explained in its resource documentation.

Translations are not provided by Oper and only these definitions are available.

RIGHT

{
  "client": {
    "id": 1
  },
  "language": {
    "id": 1
  }
}
{
  "client.id": 1,
  "language.id": 1
}

WRONG

{
  "client": 1,
  "language": 1
}

All references and resources are embedded in objects and thus should not be referenced directly. Always include an "id" tag in your resource object.

This allows us to return additional information such as resource definitions and object properties.

id values might change over time, thus it's important to do the mapping based on definitions and not on id. All changes on definition will be communicated to all users and documented clearly.

Nested lists

Simple list

"purposes": [
  {
    "id": 1
  },
  {
    "id": 2
  }
]

List with additional properties

"clients": [
  {
    "client": {
      "id": 1
    },
    "type": {
      "id": 1
    }
  },
  {
    "client": {
      "id": 2
    },
    "type": {
      "id": 1
    }
  }
]

For any list fields, Oper strives to keep the API as simple as possible and put the resources directly in a list format. However, for any list fields with additional properties, such as providing an extra type, the lists must both provide the client object and the type object.

Data formats

TODO Date format TODO File formats TODO Percentage formats

Clients

A Client represents a person that requires the services of a broker to obtain a loan. The broker interacts with Oper to stores all the relevant data. A client can be related to several other clients in the system. Their incomes and liabilities are also stored in the system.

Fields
Here is an overview of the fields in a Client object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the client
first_name
string
Required
The first name of the client
middle_name
string
Required
The middle name of the client
last_name
string
Required
The last name of the client
nationality
Country
Required
The country the client was born. The country of the client. A dictionary with id as key and Country ID as value
language
Language
Required
The first language of the client. A dictionary with id as key and Language ID as value
civil_status
CivilStatus
Required
The civil status or marital status of the client. A dictionary with id as key and CivilStatus ID as value
birth_date
Date
Required
The date of birth of the client.
birth_city
string
Required
The city the client was born
birth_country
Country
Required
The country the client was born. A dictionary with id as key and Country ID as value
sex
Sex
Required
The sex of the client. A dictionary with id as key and Sex ID as value
national_number
string
Required
The national number of the client
id_issuance_date
Date
Required
The date the ID was issued
id_expiration_date
Date
Required
The date of expiration of the ID card
id_card_number
string
Required
The ID card number of the client
compliance_terror
boolean
Optional
Whether or not the client is on the terrorist list. true or false
compliance_bank
boolean
Optional
Whether or not the client is compliant at their bank. true or false
compliance_fraud
boolean
Optional
Whether or not the client is on the fraud list. true or false

Client

The following endpoints provides a list of all clients that were created by the currently logged-in broker. Brokers can only access the clients they create.

The HTTP request returns JSON structured like this

{
    "id": 1,
    "first_name": "John",
    "middle_name": "Jane",
    "last_name": "Doe",
    "nationality": {
        "id": 1,
        "definition": "CH"
    },
    "language": {
        "id": 1,
        "definition": "en-uk"
    },
    "civil_statis": {
        "id": 1,
        "definition": "single"
    },
    "birth_date": "1990-01-01",
    "birth_city": "Basel",
    "birth_country": {
        "id": 1,
        "definition": "CH"
    },
    "sex": {
        "id": 1,
        "definition": "F"
    },
    "national_number": "999.88.11-99.12",
    "id_issuance_date": "2015-01-01",
    "id_expiration_date": "2025-01-01",
    "id_card_number": "55667744556612",
    "compliance_terror": null,
    "compliance_bank": null,
    "compliance_fraud": null,
    "emails": [
        {
        "email": {
            "id": 1,
            "value": "john.jane.doe@interestingsite.com"
        },
        "email_type": {
            "id": 1,
            "definition": "main"
        }
        }
    ],
    "phone_numbers": [
        {
        "phone_number": {
            "id": 1,
            "value": "0499881122",
            "country_code": {
            "id": 1,
            "code": "+32",
            "country": "BE"
            }
        },
        "phone_type": {
            "id": 1,
            "definition": "main"
        }
        }
    ],
    "addresses": [
        {
        "address": {
            "id": 1,
            "country": {
            "id": 1,
            "definition": "CH"
            },
            "street": "Kirchstrasse",
            "house_number": "100",
            "box": "AB",
            "city": "Basel",
            "zip_code": "1000"
        },
        "address_type": {
            "id": 1,
            "definition": "main"
        }
        }
    ],
    "created_by": {
        "id": 1
    }
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client

Client Relationships

The following endpoints provides a list of all the relationships of a specific client.

The HTTP request returns JSON structured like this

{
    "id": 22,
    "client_to": {
        "id": 49
    },
    "relationship": {
        "id": 5,
        "definition": "livingWith"
    }
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
relationship_id The ID of the relationship

Fields

Here is an overview of the fields in a Client object. This table can also be references for the create and update endpoints.

Field Description
client_to Client
relationship Relationship

Income

An Income Object represents a client's income. Oper supports several types of incomes, namely;

These types of incomes are exposed through one polymorphic endpoint. See the documentation for the details on each income type.

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
income_id The ID of the income

Fields

The following table provides a generalised look at an Income object although each of the income types have fields that are special to them. This means that not all these fields will be present in one object.

Field Description
id
integer
Read-only
The id of the income.
income_type
IncomeType
Required
The income type.
amount
float
Required
The amount of the income. Calculated automatically based on amount and periodicity.
periodicity
Periodicity
Required
The time interval of the income
monthly_amount
float
Read-only
The monthly amount
client
ClientProfile
Required
The owner of the income
employer
CompanyProfile
Required
The company the client works for
start_date
Date
Required
The start date of the employement.
is_stable
boolean
Required
Whether or not this is a stable employment
wage_garnishment
boolean
Required
Whether or not this income is being used to pay off another loan.
employment_type
EmploymentType
Required
This field is to indicate what the employment type is of a borrower in case he has an invalidity benefit or health insurance income
contract_type
EmploymentContractType
Required
The employment contract type
job_function
string
Required
The job function of the client
age
float
Required
The age of the dependant
applicable
boolean
Required
Whether or not this dependent income can be relied upon for total income
company
CompanyProfile
Required
The company the client owns
comment
string
Optional
Any additional information that the client provides about the income

Employment Income

An Employment Income object represents a client's income from their employment.

The HTTP request returns JSON structured like this

{
  "id": 380,
  "employer": {
    "id": 1033,
    "sector": {
      "id": 1,
      "definition": "construction"
    },
    "name": "",
    "profile_type": 1,
    "vat_number": "210039203920"
  },
  "employment_type": {
    "id": 3,
    "definition": "employee"
  },
  "contract_type": {
    "id": 1,
    "definition": "indefinite"
  },
  "periodicity": {
    "id": 4,
    "definition": "yearly"
  },
  "client": {
    "id": 878
  },
  "income_type": {
    "id": 1,
    "definition": "salaryEmployed"
  },
  "monthly_amount": 250,
  "amount": 3000,
  "start_date": "2000-09-20",
  "is_stable": true,
  "wage_garnishment": true,
  "job_function": "Analyst"
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
income_id The ID of the income

Fields

Here is an overview of the fields in an Employment Income object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
income_type
IncomeType
Required
The income type.
amount
float
Required
The amount of the income. Calculated automatically based on amount and periodicity.
periodicity
Periodicity
Required
The time interval of the income
monthly_amount
float
Read-only
The monthly amount
client
ClientProfile
Required
The owner of the income
employer
CompanyProfile
Required
The company the client works for
start_date
Date
Required
The start date of the employement.
is_stable
boolean
Required
Whether or not this is a stable employment
wage_garnishment
boolean
Required
Whether or not this income is being used to pay off another loan.
employment_type
EmploymentType
Required
This field is to indicate what the employment type is of a borrower in case he has an invalidity benefit or health insurance income
contract_type
EmploymentContractType
Required
The employment contract type
job_function
string
Required
The job function of the client

Dependent Income

A Dependent Income object represents a client's income as a result of having a dependant.

The HTTP request returns JSON structured like this

{
    "id": 443,
    "periodicity": {
        "id": 2,
        "definition": "trimestrial"
    },
    "client": {
        "id": 885
    },
    "income_type": {
        "id": 2,
        "definition": "childBenefit"
    },
    "monthly_amount": 500,
    "amount": 2000,
    "age": 12,
    "applicable": true
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
income_id The ID of the income

Fields

Here is an overview of the fields in a Dependent Income object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
income_type
IncomeType
Required
The income type.
amount
float
Required
The amount of the income. Calculated automatically based on amount and periodicity.
periodicity
Periodicity
Required
The time interval of the income
monthly_amount
float
Read-only
The monthly amount
client
ClientProfile
Required
The owner of the income
age
float
Required
The age of the dependant
applicable
boolean
Required
Whether or not this dependent income can be relied upon for total income

Company Income

A Company Income object represents a client's income as a result of owning a company.

The HTTP request returns JSON structured like this

{
  "id": 23,
  "company": {
      "id": 50,
      "sector": {
          "id": 31,
          "definition": "it"
      },
      "name": "La-Frozan",
      "profile_type": 1,
      "vat_number": "709999899"
  },
  "periodicity": {
      "id": 9,
      "definition": "yearly"
  },
  "client": {
      "id": 49
  },
  "income_type": {
      "id": 22,
      "definition": "salarySelfEmployed"
  },
  "monthly_amount": 250,
  "amount": 3000
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
income_id The ID of the income

Fields

Here is an overview of the fields in a Company Income object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
income_type
IncomeType
Required
The income type.
amount
float
Required
The amount of the income. Calculated automatically based on amount and periodicity.
periodicity
Periodicity
Required
The time interval of the income
monthly_amount
float
Read-only
The monthly amount
client
ClientProfile
Required
The owner of the income
company
CompanyProfile
Required
The company the client owns

Other Income

Other Income object represents other types of incomes that a client's may have that do not fit into the other object types.

The HTTP request returns JSON structured like this

{
    "id": 27,
    "income_type": {
        "id": 24,
        "definition": "other"
    },
    "employment_type": {
        "id": 23,
        "definition": "student"
    },
    "periodicity": {
        "id": 6,
        "definition": "monthly"
    },
    "client": {
        "id": 49
    },
    "monthly_amount": 2500,
    "comment": "Freelance student job",
    "amount": 2500
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
income_id The ID of the income

Fields

Here is an overview of the fields in Other Income object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
income_type
IncomeType
Required
The income type.
amount
float
Required
The amount of the income. Calculated automatically based on amount and periodicity.
periodicity
Periodicity
Required
The time interval of the income
monthly_amount
float
Read-only
The monthly amount
client
ClientProfile
Required
The owner of the income
employment_type
EmploymentType
Required
This field is to indicate what the employment type is of a borrower in case they have an invalidity benefit or health insurance income
comment
string
Optional
Any additional information that the client provides about the income

Liability

A Liability object represents a client's liability. Oper supports several types of liabilities, namely;

These types of liabilities are exposed through one polymorphic endpoint. See the documentation for the details on each liability type.

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
liability_id The ID of the liability

The following table provides a generalised look at a Liability object although each of the liability types have fields that are special to them. This means that not all these fields will be present in one object.

Field Description
id
integer
Read-only
The id of the income.
liability_type
LiabilityType
Required
The type of liability.
amount
float
Required
The amount of the liability.
periodicity
Periodicity
Required
The time interval of the liability
monthly_amount
float
Read-only
The monthly amount. Calculated automatically based on amount and periodicity.
client
ClientProfile
Required
The owner of the liability
duration
integer
Optional
The duration months of the credit. Credit cards are infinite, therefore duration can be left empty.
initial_amount
float
Optional
The initial amount of the credit at the time of closing.
interest_rate
float
Optional
The interest rate of the credit.
balance
float
Optional
The balance of the credit. For credit cards no balance is needed.
takeover
CreditTakeOver
Required
Whether or not this credit will be taken over after the loan.
handling_costs
CreditTakeOver
Required
The costs to remove the mortgage from the deed (handlichtingskosten).
early_repayment_fee
float
Required
The costs to be allowed to change credit provider (wederbeleggingsvergoeding).
credit_provider
CreditProvider
Required
The credit provider.
regularity
RegularityType
Required
The regularity of the clients payoffs towards the credit.
contract_number
string
Required
The identifier of the contract.
start_date
Date
Required
The start date of the credit.
gone_after_request
boolean
Required
Whether or not this liability will be gone after the loan is granted.

Credit Liability

A Credit liability object represents a client's liability as a result of having a credit.

The HTTP request returns JSON structured like this

{
    "id": 7,
    "client": {
        "id": 49
    },
    "periodicity": {
        "id": 9,
        "definition": "yearly"
    },
    "takeover": {
        "id": 5,
        "definition": "no"
    },
    "credit_provider": {
        "id": 38,
        "definition": "hellobank"
    },
    "regularity": {
        "id": 6,
        "definition": "regularized"
    },
    "liability_type": {
        "id": 15,
        "definition": "creditCard"
    },
    "monthly_amount": 41.666666666666664,
    "amount": 500,
    "duration": 20,
    "initial_amount": 0,
    "interest_rate": 1.2,
    "balance": 90,
    "handling_costs": 12,
    "early_repayment_fee": 20,
    "contract_number": "A23442323",
    "start_date": "2017-11-11"
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
liability_id The ID of the liability

Fields
Here is an overview of the fields in a Credit Liability object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
liability_type
LiabilityType
Required
The type of liability.
amount
float
Required
The amount of the liability.
periodicity
Periodicity
Required
The time interval of the liability
monthly_amount
float
Read-only
The monthly amount. Calculated automatically based on amount and periodicity.
client
ClientProfile
Required
The owner of the liability
duration
integer
Optional
The duration months of the credit. Credit cards are infinite, therefore duration can be left empty.
initial_amount
float
Optional
The initial amount of the credit at the time of closing.
interest_rate
float
Optional
The interest rate of the credit.
balance
float
Optional
The balance of the credit. For credit cards no balance is needed.
takeover
CreditTakeOver
Required
Whether or not this credit will be taken over after the loan.
handling_costs
CreditTakeOver
Required
The costs to remove the mortgage from the deed (handlichtingskosten).
early_repayment_fee
float
Required
The costs to be allowed to change credit provider (wederbeleggingsvergoeding).
credit_provider
CreditProvider
Required
The credit provider.
regularity
RegularityType
Required
The regularity of the clients payoffs towards the credit.
contract_number
string
Required
The identifier of the contract.
start_date
Date
Required
The start date of the credit.

Rental liability

A Rental liability object represents a client's liability as a result of pay rent.

The HTTP request returns JSON structured like this

{
    "id": 8,
    "client": {
        "id": 49
    },
    "periodicity": {
        "id": 9,
        "definition": "yearly"
    },
    "liability_type": {
        "id": 6,
        "definition": "rent"
    },
    "monthly_amount": 41.666666666666664,
    "amount": 500,
    "gone_after_request": true
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
liability_id The ID of the liability

Fields
Here is an overview of the fields in a Rental Liability object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
liability_type
LiabilityType
Required
The type of liability.
amount
float
Required
The amount of the liability.
periodicity
Periodicity
Required
The time interval of the liability
monthly_amount
float
Read-only
The monthly amount. Calculated automatically based on amount and periodicity.
client
ClientProfile
Required
The owner of the liability
gone_after_request
boolean
Required
Whether or not this liability will be gone after the loan is granted.

Dependent liability

A Dependent liability object represents a client's liability as a result of having dependent.

The HTTP request returns JSON structured like this

{
    "id": 4,
    "client": {
        "id": 52
    },
    "periodicity": {
        "id": 9,
        "definition": "yearly"
    },
    "liability_type": {
        "id": 7,
        "definition": "dependent"
    },
    "monthly_amount": 41.666666666666664,
    "amount": 500
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
liability_id The ID of the liability

Fields
Here is an overview of the fields in a Dependent Liability object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
liability_type
LiabilityType
Required
The type of liability.
amount
float
Required
The amount of the liability.
periodicity
Periodicity
Required
The time interval of the liability
monthly_amount
float
Read-only
The monthly amount. Calculated automatically based on amount and periodicity.
client
ClientProfile
Required
The owner of the liability

Other liability

A Other liability object represents a client's liability that do not fit into the other types of liability.

The HTTP request returns JSON structured like this

{
    "id": 6,
    "client": {
        "id": 52
    },
    "periodicity": {
        "id": 9,
        "definition": "yearly"
    },
    "liability_type": {
        "id": 8,
        "definition": "alimony"
    },
    "monthly_amount": 416.6666666666667,
    "amount": 5000
}

HTTP Requests

URL Parameters

Parameter Description
client_id The ID of the client
liability_id The ID of the liability

Fields
Here is an overview of the fields in Other Liability object. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the income.
liability_type
LiabilityType
Required
The type of liability.
amount
float
Required
The amount of the liability.
periodicity
Periodicity
Required
The time interval of the liability
monthly_amount
float
Read-only
The monthly amount. Calculated automatically based on amount and periodicity.
client
ClientProfile
Required
The owner of the liability

Loan requests

Loan requests are the heart of the 0per API. Almost everything you do in 0per is related in some way to a loan request.

This section will go over how to create loan requests, get data from them add realties, update products and more.

Loan requests

The general loan request information is present in the /api/loan-request calls. It contains the total of each part of the loan request, a list of relevant dates, identifying information, the purposes and relevant users and third parties.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "status": {
        "id": 1,
        "definition": "lead"
    },
    "external_reference": "1901010001",
    "analyst": {
        "id": 1
    },
    "broker": {
        "name": "Broker Nick",
        "vat_number": "CH 0000.000.001"
    },
    "co_broker": {
        "name": "Broker Woeter",
        "vat_number":  "CH 0000.000.002"
    },
    "notary": {
        "name": "Notary Barno",
        "vat_number": "CH 000.000.003"
    },
    "loan_amount": 100000.00,
    "created": "2019-01-01T12:00:00.000000+02:00",
    "last_modified": "2019-01-01T12:00:00.000000+02:00",
    "cost_purchase": 200000.00,
    "cost_renovation": 25000.00,
    "cost_building": 0,
    "cost_buyout": 0,
    "cost_credit_takeover": 0,
    "cost_insurance": 25000,
    "cost_registration": 30000,
    "cost_handling": 2000,
    "cost_notary": 10000,
    "cost_distribution": 0,
    "cost_file": 800,
    "liquidities": 0,
    "own_funds": 125000.00,
    "business_capital": 0,
    "planned_deed_date": "2019-06-30",
    "effective_deed_date": "2019-06-30",
    "date_funds_requested": "2019-06-30",
    "date_funds_provisioned": "2019-06-30",
    "date_contract": "2019-06-30",
    "date_initial_agreement": "2019-06-30",
    "date_contract_allowed": "2019-06-30",
    "purposes": [
        {
            "id": 1,
            "definition": "purchase"
        },
        {
            "id": 1,
            "definition": "renovation"
        }
    ]
}

Each loan request has a unique identifier in ìd, which can be used to call a specific loan request on GET /api/loan-requests/<id>/.

As discussed in the third party section, they are represented by a name and company number. An analyst is a user of the system, and is represented by a User object with an ID.

Here is an overview of the fields. This table can also be references for the create and update endpoints.

Field Description
id
integer
Read-only
The id of the loan request
status
Status
Optional
The status of the loan request
external_reference
string
Read-only
The external reference for the loan request
analyst
User
Optional
The analyst working on the loan request
broker
Broker
Read-only
The broker of the loan request
co-broker
Broker
Optional
The co-broker of the loan request
notary
Notary
Optional
The notary of the loan request
loan_amount
float
Read-only
The total loan amount of the request. See notice for more info.
created
DateTime
Read-only
The date and time the loan request was created
last_modified
DateTime
Read-only
The date and time the loan request was last modified
cost_purchase
float
Read-only
The sum of the prices of all realties with purpose purchase and which are not new
cost_renovation
float
Read-only
The sum of the renovations of all realties with purpose renovation
cost_building
float
Read-only
The sum of the prices of all realties with purpose purchase and which are new
cost_buyout
float
Read-only
The sum of the prices of all realties with purpose buy-out
cost_credit_takeover
float
Read-only
The sum of the balance and the early payment fee of all credits that need to be taken over
cost_insurance
float
Read-only
The sum of the premiums of all liability insurances that need to be included in the loan
cost_registration
float
Optional
The registration costs (taxes) for all buildings with purpose purchase
cost_handling
float
Optional
The sum of the handling fees of all credits that need to be taken over
cost_notary
float
Optional
The sum of all notary costs for the loan request. Includes costs for the mortgage, costs for a purchase and costs for a buyout
cost_distribution
float
Optional
The sum of the price of the distribution taxes on realties that need to be bought out
cost_file
float
Optional
The file costs for the loan request
liquidities
float
Optional
The liquidities the client(s) request
business_capital
float
Optional
The liquidities the business client(s) request
own_funds
float
Optional
The own funds the client(s) will bring in themselves
planned_deed_date
Date
Optional, nullable
The date the deed is planned
effective_deed_date
Date
Optional, nullable
The date the deed has been effected
date_funds_requested
Date
Optional, nullable
The date the funds for the loan request have been requested from the credit provider
date_funds_provisioned
Date
Optional, nullable
The date the funds for the loan request have been provisioned by the credit provider
date_contract
Date
Optional, nullable
The date the contract has been signed
date_initial_agreement
Date
Optional, nullable
The date the initial agreement has been signed
date_contract_allowed
Date
Optional, nullable
The date from which a contract can be provided to the client(s)
purposes
list of LoanRequestPurpose
Optional, nullable
The list of purposes for this loan request. See LoanRequestPurpose in resources to get the list of possibilities

Requests

GET /api/loan-requests/

To get a list of the loan requests that you created, call the GET endpoint without an id.

GET /api/loan-requests/1/

To get a specific loan request, add the id to the endpoints.

POST /api/loan-requests/

To create a loan request, POST the fields to the endpoints. It's possible to send an empty object to the api, it will create an empty loan request for you.

PATCH /api/loan-requests/1/q?calc=False

PUT /api/loan-requests/1/q?calc=False

To update your loan request, you can either PATCH or PUT it. A PATCH only updates the selected values, a PUT replaces the entire object. In a PUT all fields that are not provided, are put to default (0 or null)

PATCH and PUT also support a query parameter calc, which is a boolean (True, true or 1, False, false, or 0). The next paragraph will explain what it does.

Automatic cost calculations

Some costs are automatically calculated. However, a part of the costs are also manually updatable. This provides a complexity, as you sometimes want to overwrite the existing values, but not always.

To solve this issue, a query parameter is provided, calc. When this is provided as True/true/1, recalculation will happen. If calcis not provided, it is assumed False.

Which costs are recalculated is determined by the following table:

Attribute Action
loan_amount Is always recalculated, based on the entire LoanRequest
cost_building Is always recalculated, based on Realties
cost_buyout Is always recalculated, based on Realties
cost_purchase Is always recalculated, based on Realties
cost_renovation Is always recalculated, based on Realties
cost_credit_takeover Is always recalculated, based on CreditLiabilities
cost_insurance Is always recalculated, based on LiabilityInsurance
cost_registration Recalculated based on query parameter and input
cost_handling Is always recalculated, based on CreditLiabilities
cost_notary Recalculated based on query parameter and input
cost_distribution Recalculated based on query parameter and input
cost_file Only recalculated when new ProductItems are posted

The logic for the four editable cost is as follows:

This means that if the editable costs of a loan request need to be updated based on requests that are not on /api/loan-requests/ directly, you need to do an empty PATCH request. Else the calculated costs will be based on the previous objects or states of objects.

Clients

Clients can be linked to a loan request via the /api/loan-requests/<lr-id>/client/API. This links the clients to the loan request with a specific role. A client can be linked to multiple loan requests and a loan request can have multilpe clients. A client cannot be in the same loan request multiple times, even with a different role.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "client": {
        "id": 1
    },
    "loan_request": {
        "id": 1,
        "external_reference": "1901010001"
    },
    "role": {
        "id": 1,
        "definition": "borrower"
    }
}

The structure has the following fields:

Field Description
id
integer
Read-only
The id of the many to many object. Used for retrieving the relationship.
client
ReducedClient
Required
The client whom to link. Only the id is required and provided.
loan_request
ReducedLoanRequest
Read-only
The loan request to which to link the client to. Implied from the URL and thus read only.
role
Clientrole
Required
The role the client plays in this loan request.

Comment

Comments can be added to a loan request via the /api/loan_request/<lr_id>/comments/ endpoint.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "loan_request": {
        "id": 1,
        "external_reference": "1901010001"
    },
    "user": {
        "id": 1
    },
    "comment_type": {
        "id": 1,
        "definition": "broker"
    },
    "created": "2019-01-01T12:00:00.000000+02:200",
    "last_modified": "2019-01-01T12:00:00.000000+02:200",
    "content": "'Hello there.' - General Kenobi",
    "link_id": 1
}

The structure has the following fields:

Field Description
id
integer
Read-only
The id of the comment. Used for retrieving the relationship.
user
ReducedUser
Read-only
The user whom made the comment. Implied from the authorisation.
loan_request
ReducedLoanRequest
Read-only
The loan request to which to link the client to. Implied from the URL and thus read only.
comment_type
CommentType
Required
The comment type
created
DateTime
Read-only
The creation date of the comment.
last_modified
DateTime
Read-only
The date the comment was last modified.
comment
string
Required
The comment the user provided.
link
integer
Required for some types
The id of the object to link the comment to
Comment type Link id object
broker Loan request
loanRequest Loan request
decisionRecommendation Loan request
decision Loan request
income Income
client Client
liability Liability
nbb Client
insurance Insurance (fire or liability)
realty Realty
estimator Realty
metric Loan request
document Document
products Loan request

Liability insurance

Liability insurances can be added to a loan request via the /api/loan-requests/<lr-id>/liability-insurances/API. Liability insurances can be added even when they are not to be financed.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "loan_request": {
        "id": 1,
        "external_reference": "1901010001"
    },
    "provider": {
        "id": 1,
        "name": "Insurance provider ABC",
        "vat_number": "CH000.000.0002",
        "fsma_reference": "ABC001021",
        "address": {
            "id": 1,
            "country": {
                "id": 1,
                "definition": "CH"
            },
            "street": "Kirckstrasse",
            "house_number": "99",
            "box": "",
            "city": "Basel",
            "zip_code": "1000"
        }
    },
    "periodicity": {
        "id": 1,
        "definition": "monthly"
    },
    "policy_number": "ABCDEF1234567890",
    "to_be_financed": false,
    "premium": 250,
    "covered_percentage": 1,
    "duration": 120,
    "clients": [
        {
            "id": 1
        }
    ]
}

The structure has the following fields:

Field Description
id
integer
Read-only
The id of the liability insurance.
loan_request
ReducedLoanRequest
Read-only
The loan request the liability insurance is linked to.
provider
InsuranceProvider
Required
The insurance provider of the insurance.
periodicity
Periodicity
Required
The periodicity of the insurance payments.
policy_number
string
Optional
The policy number of the insurance contract.
to_be_financed
boolean
Required
Whether this insurance needs to be financed in the loan.
premium
float
Required
The premium of the insurance that needs to be paid every period.
covered_percentage
float
Required
How much the liability insurance covers of the loan.
duration
integer
Required
For how long the liability insurance is active.
clients
list of ReducedClientProfile
Required
Which clients are covered by the liability insurance.

Offers

Offers are the actual instantiation of which loan you will get. The loan request is the container of the what you want, the offer represents an instance of a product offer (configuration) that the client has selected and the the product items provides which loans you get, which durations and which interest rates. Loan types and interest rates are based on the chosen product and the rest of your loan request.

For example, Billy wants to buy a house of 200.000. He has 50.000 own funds. In the end he selects one annuity product item of 100.000 on 15 years, with fixed variability, and one bullet product item of 50.000 on 5 years with a yearly-changeable variability.

Oper provides three methods to create product items, all on the same endpoint api/loan-requests/<lr-id>/offer. The first one is an automatic suggestion. This one will provide the best loan based on the current information. The second way is that a client selects a product_offer from the list of allowed offers, but not extra information. Oper will then create a suggestion for that product_offer. The third way is customising your product_offer manually. This is done by providing the product_offer id as well as duration, variability, amount and product.

The latest product items can be found in api/loan-requests/<lr-id>/offer/.

Before any product items are created, the general acceptance rules are run through. If the loan request doesn't meet one of these rules, the response will just include these errors and no product items. If the loan request does meet these rules, the second check over product rules is run. These rules don't prevent your product items to be created but should present warnings to the user.

HTTP Requests

Structure and definitions

The GET requests get the latests prodcut items and configuration. The response structure is provided after the POST explanation.

As mentioned, there are three ways to create items in the /offer/ api. They go from an empty to a fully detailed request. The response for each of the three ways is the same and detailed later.

offer INPUT - fully automated suggestion

{

}

offer INPUT - only product offer

{
    "offer_configuration": {
        "id": 1
    }
}

offer INPUT - fully customised

{
    "offer_configuration": {
        "id": 1
    },
    "product_items": [
        {
            "amount": 50000,
            "duration": 240,
            "product": {
                "id": 1
            },
            "variability": {
                "id": 1
            },
        },
        {
            "amount": 70000,
            "duration": 180,
            "product": {
                "id": 2
            },
            "variability": {
                "id": 3
            },
        }
    ]
}
Field Description
offer_configuration
ProductOffer
Optional
The product offer id to take as template.
product_items
list of ProductItem
Optional
The list of product items.
duration
integer
Optional
The duration of the product item
amount
float
Optional
The amount of the product item.
product
Product
Required
Which product the product item uses.
variability
Variability
Required
The variability of the product item.

For the fully customisable endpoint, with the product items, there are some additional leeways.

Amount

Duration

Variability

Response

All three endpoints provide the same structure if results.

RESPONSE offer

{
    "offer_item": {
        "id": 1,
        "offer_configration": {
            "id": 1
        },
        "product_items": [
            {
                "id": 1,
                "duration": 180,
                "interest_rate": 0.055,
                "amount": 100000,
                "end_amount": 0,
                "amortization": 701.534301604594,
                "amortization_calc": 701.534301604594,
                "total_costs": 0,
                "aprc": 0.06,
                "fiscality": 50000,
                "product": {
                    "id": 1,
                    "name": "Annuity",
                    "credit_provider": {
                        "id": 1,
                        "name": "0per Bank"
                    },
                    "loan_type": {
                        "id": 1,
                        "definition": "mensuality"
                    }
                },
                "variability": {
                    "id": 1,
                    "definition": "fixed"
                }
            },
            {
                "id": 2,
                "duration": 60,
                "interest_rate": 0.030,
                "amount": 50000,
                "end_amount": 0,
                "amortization": 0,
                "amortization_calc": 900.432,
                "total_costs": 0,
                "aprc": 0.06,
                "fiscality": 70000,
                "product": {
                    "id": 2,
                    "name": "Bullet",
                    "credit_provider": {
                        "id": 1,
                        "name": "0per Bank"
                    },
                    "loan_type": {
                        "id": 2,
                        "definition": "bullet"
                    }
                },
                "variability": {
                    "id": 2,
                    "definition": "1_1_1_cap_5"
                }
            }
        ],
        "dti": {
            "value": 0.3,
            "risk": "LOW"
        },
        "ltv": {
            "value": 0.8,
            "risk": "MEDIUM"
        },
        "surplus": {
            "value": 1000,
            "risk": "HIGH"
        },
        "minimum_living_surplus": 1100
    },
    "errors": [
        {
            "definition": "code1",
            "error_type": "Product acceptance error",
            "entity": "LoanRequest",
            "message": "Liquidities (100000.00) must be smaller than or equal to 10.00% of the loan amount.",
            "parameters": [
                {
                    "field_name": "percentage",
                    "value": "0.1"
                },
                {
                    "field_name": "liquidities",
                    "value": "100000.0"
                }
            ]
        }
    ]
}

The response for the three end points is exactly the same.

Object Field Description
body offer_item
ProductOfferItem
The container of the product offer item
ProductOfferItem id
integer
The id of the offer item
ProductOfferItem product_items
list of ProductItem
The list container of the product items
ProductItem id
integer
The id of the product item
ProductItem duration
integer
The duration of the product item
ProductItem interest_rate
integer
The interest rate of the product item
ProductItem amount
float
The amount of the product item
ProductItem end_amount
float
The amount that needs to be repaid at the end of the duration
ProductItem amortization
float
The amortization that needs to be paid every period
ProductItem amortization_calc
float
The amortization that is used for DTI and surplus calculations
ProductItem total_costs
float
The total costs for the whole of the product item
ProductItem aprc
float
The Annual Rate Percentage of Costs of the product item
ProductItem fiscality
float
How much the product item can be considered for tax purposes
ProductItem product
BaseProduct
The product on which the item is based
ProductItem variability
Variability
The variability of the product item
BaseProduct id
integer
The id of the product
BaseProduct name
string
The name of the product
BaseProduct credit_provider
CreditProvider
The credit provider of the product
BaseProduct loan_type
LoanType
The loan type of the product and thus also for the product item
ProductOfferItem dti
float
The Debt-to-Income object of the offer item
DTI value
float
The value of the DTI
DTI risk
string
The risk level of the DTI. One of "low", "medium" and "high"
ProductOfferItem minimum_living_surplus
float
The minimum living surplus that the borrowers should have even with the loan
ProductOfferItem surplus
float
The surplus object if the current product items would be selected
Surplus value
float
The value of the surplus
Surplus risk
string
The risk level of the surplus. One of "low", "medium" and "high"
ProductOfferItem ltv
string
The Loan-to-Value object of the the offer item
LTV value
float
The value of the LTV
LTV risk
string
The risk level of the LTV. One of "low", "medium" and "high"
body errors
list of Error
A list of errors
Error definition
string
A uniquely code of the error
Error error_type
string
The type of error
Error entity
string
The object on which the error applies
Error message
string
A human readable explanation of the error
Error parameters
list of Parameters
A list of parameters, about the error
Parameter field_name
string
The field or attribute the parameter refers to
Parameter value
float
The value of the field

Allowed offers

The api/loan-requests/<lr-id>/allowed-offers endpoint provides the product offers that the client can choose from. A product offer can contain one or two products and has a name.

Not all product are available all the time, and not all base product are available on their own for offering.

As with product items, first the loan request will check the general acceptance rules and will provide errors if one of them is not accepted.

HTTP Requests

Structure and definitions

{
    "product_offers": [
        {
            "id": 1,
            "main_product": {
                "id": 1,
                "name": "Annuity",
                "credit_provider": {
                    "id": 1,
                    "name": "0per bank"
                },
                "loan_type": {
                    "id": 1,
                    "definition": "mensuality"
                }
            },
            "additional_product": {
                "id": 2,
                "name": "balloon",
                "credit_provider": {
                    "id": 1,
                    "name": "0per bank"
                },
                "loan_type": {
                    "id": 2,
                    "definition": "balloonCredit"
                }
            },
            "name": "Mensuality and balloon",
            "main_weight": 0.7,
            "additional_weight": 0.3,
            "weight_editable": true,
            "all_same_duration": false
        }
    ],
    "errors": [
        {
            "definition": "code1",
            "error_type": "Product acceptance error",
            "entity": "LoanRequest",
            "message": "Liquidities (100000.00) must be smaller than or equal to 10.00% of the loan amount.",
            "parameters": [
                {
                    "field_name": "percentage",
                    "value": "0.1"
                },
                {
                    "field_name": "liquidities",
                    "value": "100000.0"
                }
            ]
        }
    ]
}

You can only do a GETrequest and no input parameters are required. This means that all attributes are read-only.

Object Field Description
body product_offers
list of ProductOffer
The list of product offer that the client can select from
ProductOffer id
integer
The id of the product offer
ProductOffer main_product
BaseProduct
The first product in the product offer
ProductOffer additional_product
BaseProduct
nullable
The second product in the product offer. This is not always present
ProductOffer name
string
The marketable name of the product offer
ProductOffer main_weight
float
nullable
The fractional weight of the main product. If there is no additional_product, this is null. Sum must not be 1
ProductOffer additional_weight
float
nullable
The fractional weight of the additional product. If there is no additional_product, this is null. Sum must not be 1
ProductOffer weight_editable
boolean
nullable
Whether the product items of a loan request with this product offer can be changed versus the default weights
ProductOffer all_same_duration
boolean
nullable
Whether both the products of a loan request with this product offer need to have the same duration
BaseProduct id
integer
The id of the product
BaseProduct name
string
The name of the product
BaseProduct credit_provider
CreditProvider
The credit provider of the product
BaseProduct loan_type
LoanType
The loan type of the product and thus also for the product item
body errors
list of Error
A list of errors
Error definition
string
A uniquely code of the error
Error error_type
string
The type of error
Error entity
string
The object on which the error applies
Error message
string
A human readable explanation of the error
Error parameters
list of Parameters
A list of parameters, about the error
Parameter field_name
string
The field or attribute the parameter refers to
Parameter value
float
The value of the field

Realties

Realties are used to buy, sell or provide as collateral. They help the loan get a good LTV ensuring the credibility of the client.

Realties are always linked to a loan request, and cannot exist separately.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "address": {
        "id": 2,
        "country": {
            "id": 1,
            "definition": "CH"
        },
        "street": "Bahnhofstrasze",
        "house_number": "130",
        "box": "",
        "city": "Zürich",
        "zip_code": "4000"
    },
    "cadastral_location": "BAHNHOFSTRASZE ZÜRICH 130 A 1 200",
    "cadastral_income": 500,
    "realty_type": {
        "id": 1,
        "definition": "apartment"
    },
    "acquisition_type": {
        "id": 1,
        "definition": "purchase"
    },
    "usage": {
        "id": 1,
        "definition": "living"
    },
    "estimator": {
        "id": 1
    },
    "mortgage_ranks": [
        {
            "amount": 200000,
            "rank": 1,
            "credit_provider": {
                "id": 2,
                "definition": "Not 0per bank"
            }
        }
    ],
    "clients": [
        {
            "id": 220,
            "client": {
                "id": 1072
            },
            "ownership_type": {
                "id": 1,
                "definition": "groundLease"
            },
            "percentage": 1
        }
    ],
    "venal_value_before": 200000,
    "venal_value_after": 200000,
    "forced_value_before": 160000,
    "forced_value_after": 160000,
    "rank": 2,
    "living_percentage": 1,
    "price": 200000,
    "renovation_price": 0,
    "surface": 0,
    "new_realty": false,
    "housing_units": 1,
    "already_estimated": true,
    "main_first_residence": true,
    "klein_beschrijf": true,
    "energetic_renovations": true,
    "purposes": [
        {
            "id": 1,
            "definition": "buy"
        },
        {
            "id": 2,
            "definition": "collateral"
        }
    ]
}

Both the input and output arrays are the same, except for some read-only values.

Field Description
id
integer
Read-only
The id of the realty
address
Address
Required
The address object of the realty
cadastral_location
string
Optional
The official government record of the realty.
cadastral_income
float
Optional
The cadastral income of the realty. Defaulted to 0 if not provided
realty_type
RealtyType
Required
The type of realty
aqcuisition_type
AqcuisitionType
Required
The manner how the realty was aqcuired, whether it is in the past or now
usage
RealtyUsageType
Required
How the realty is or will be used
estimator
Estimator
Optional
Which estimator has estimated the realty. Required if already_estimated is true
mortgage_ranks
list of MortgageRank
Optional
All other credit providers that have a higher rank than the issuing credit provider. If rank is 1, then none are required. Else rank-1 objects are required in a sequence of ranks.
mortgage_rank.amount
amount
Required
The amount of the mortgage this credit provider has on the realty
mortgage_rank.rank
integer
Required
The priority of the mortgage of the credit provider
mortgage_rank.credit_provider
CreditProvider
Required
Which credit provider has a mortgage on the realty
clients
list of RealtyOwner
Required
The owners of the realties
clients.id
integer
Read-only
The id of the many-to-many object
clients.client
ClientProfile
Required
The owner of the realty
clients.ownership_type
OwnershipType
Required
Which type of owner the client is of the realty
clients.percentage
float
Required
The fraction of the realty the client is owner of. Total of all clients need to be 100%
venal_value_before
float
Required
The venal value of the realty before renovations
venal_value_after
float
Optional
The venal value of the realty after renovations
forced_value_before
float
Optional
The value in a forced sale of the realty before the renovations
forced_value_after
float
Optional
The value in a forced sale of the realty after the renovations
rank
integer
Required
The rank of the mortgage of the realty
living_percentage
float
Required
How much of the realty will be used for living purposes
price
float
Required
The price the realty will be bought for, of the price of how much will be bought out
renovation_price
float
Required
The price of the renovations that will be done in the realty
surface
float
Required
The surface of the realty
new_realty
boolean
Required
Whether the realty is or will be newly built or not
housing_units
integer
Required
How many housing units there are in the realty
main_first_residence
boolean
Optional
Whethet the realty is or will be the first and main residence of the buyers. Used for tax calculations
klein_beschrijf
boolean
Optional
Whether the 'klein beschrijf' system applies to the realty. Used for tax calculations
energetic_renovations
boolean
Optional
Whether energetic renovations will be done in the house. Used for tax calculations.
purposes
list of RealtyPurpose
Required
The purposes of the realty

Fire insurances

A fire insurance provides an additional protection of the realty for both the client and the credit provider. Fire insurances can be added to a realty. There can be multiple fire insurances for a realty but it's not required.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "realty": {
        "id": 1
    },
    "provider": {
        "id": 1,
        "name": "Oper Insurance",
        "vat_number": "OPER001002003",
        "fsma_reference": "OPERINS001",
        "address": {
            "id": 1,
            "country": {
                "id": 1,
                "definition": "CH"
            },
            "street": "Haufstrasse",
            "house_number": "100",
            "box": "",
            "city": "Geneva",
            "zip_code": "1000"
        }
    },
    "periodicity": {
        "id": 1,
        "definition": "monthly"
    },
    "policy_number": "000101010101",
    "premium": 1000,
    "insured_amount": 200000,
    "clients": [
        {
            "id": 1
        }
    ]
  }

The APIs for all methods have the same in- and output, with the exception of read-only fields.

Field Description
id
integer
Read-only
The id of the fire insurance
provider
InsuranceProvider
Required
The provider of the insurance
periodicity
Periodicty
Required
The periodicty of the fire insurance
policy_number
string
Optional
The policy number of the insurance
premium
float
Required
The premium that is paid per period for the insurance
insured_amount
float
Required
How much value is insured by the insurance
clients
list of Client
Required
Which clients have taken the insurance

Registration rights

Taxes in Belgium depend on several input fields such as whether the realty is the owner's first and main property in Belgium, where it is located and whether certain renovations will be done. More info can be found on the website of the Belgian government (Dutch, French and German.)

The province and zip code will be extracted from the list of realties.

HTTP Requests

Structure and definitions

{
    "main_residence": true,
    "energetic_renovations": true,
    "klein_beschrijf": true,
    "loan_amount": 200000,
    "property_amount": 200000,
    "registration_rights": 31534.55,
    "new_building": false,
    "postal_code": "1000"
}

There are three input field, altough they shouldn't be valid at the same time. The inputs depend in the region of the realty to purchase.

POSTing these fields will set them on the relevant realty. In the future, the registration rigths will be recalculated based on the provided values.

Field Description
main_residence
boolean
Optional
Whether the realty to purchase is the main and first residence. Relevant and required for Flanders and Brussels
energetic_renovations
boolean
Optional
Whether significant energetic renovation will be done on the realty to purchase. Relevant and required for Flanders
klein_beschrijf
boolean
Optional
Whether the klein beschrijf ruling is valid for the realty to purchase. Relevant and required for Brussels
loan_amount
float
Read-only
The updated loan amount of the loan request
property_amount
float
Read-only
The property value of the realty to purchase.
registration_rights
float
Read-only
The taxes the client will have to pay that fall in the registration rights
new_building
boolean
Read-only
Whether the realty is being built or already exists.
postal_code
string
Read-only
The postal code of the realty to purchase

Proof

For any loan request, proof can also be uploaded. Based on configuration, several proof requirements are created in the system when loan requests, realties, clients etc are added. For any exiting request, documents can be uploaded which can be validated afterwards. Lastly, new proof requirements can also be created.

At this moment, only documents can provide proof in Oper. In the future, other integrations such as e-id, PSD2, banking platform integrations etc will also be able to validate proof requirements.

Proof categories

Several different objects will have different proof requirements. The list of objects that need proof, are called proof categories.

There are six types of objects that can have proof requirements.

Meta informtion about the object is also provided for convience's sake. More information can be found in the respective full endpoint.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "entity": {
        "id": 1,
        "meta": {
            "external_reference": "1901010001"
        },
        "category": {
            "id": 1,
            "definition": "loanRequest"
        }
    }
}

As only GET methods are allowed, no request JSON is allowed. All fields are also Read-only.

Field Description
id
integer
The id of the proof category
entity
Entity
The object the proof category is linked to
entity.id
integer
The id of the object the proof category is linked to (e.g. the loan request id)
entity.meta
object
A short summary of the object (e.g. the external reference for a loan request)
entity.category
ProofCategory
The category of the proof, as defined in the resources

The following entity types provide the following meta information.

{
    "loan_request_meta": {
        "external_reference": "1901010001"
    },
    "client_meta": {
        "first_name": "John",
        "middle_name": "Jane",
        "last_name": "Doe"
    },
    "liability_meta":{
        "amount": 1000,
        "monthly_amount": 1000,
        "periodicity": {
            "id": 1,
            "definition": "monthly"
        },
        "client": {
            "id": 1
        },
        "liability_type": {
            "id": 3,
            "definition": "mortgageImmovable"
        }
    },
    "realty_meta": {
        "address": {
           "id": 2,
            "country": {
                "id": 1,
                "definition": "CH"
            },
            "street": "Bahnhofstrasze",
            "house_number": "130",
            "box": "",
            "city": "Zürich",
            "zip_code": "4000"
        },
        "cadastral_location": "Bahnhofstrasze 130 BA/3",
        "venal_value_after": 200000,
        "forced_value_before": 160000,
        "forced_value_after": 160000
    },
    "fire_insurance_meta": {
        "provider": {
            "id": 1,
            "name": "Oper Insurance",
            "vat_number": "OPER001002003",
            "fsma_reference": "OPERINS001",
            "address": {
                "id": 1,
                "country": {
                    "id": 1,
                    "definition": "CH"
                },
                "street": "Haufstrasse",
                "house_number": "100",
                "box": "",
                "city": "Geneva",
                "zip_code": "1000"
            }
        },
        "periodicity": {
          "id": 1,
          "definition": "monthly"
        },
        "realty": {
          "id": 359
        },
        "insured_amount": 10000
    },
    "liability_insurance_meta": {
        "provider": {
            "id": 1,
            "name": "Oper Insurance",
            "vat_number": "OPER001002003",
            "fsma_reference": "OPERINS001",
            "address": {
                "id": 1,
                "country": {
                    "id": 1,
                    "definition": "CH"
                },
                "street": "Haufstrasse",
                "house_number": "100",
                "box": "",
                "city": "Geneva",
                "zip_code": "1000"
            }
        },
        "periodicity": {
          "id": 1,
          "definition": "monthly"
        },
        "policy_number": "ABCDEF1234567890",
        "loan_request": "1901010001"
    }
}

Documents

Each of the proof categories has at least one proof requirement linked to it. A document can be uploaded to this proof requirement and be analysed further. New proof requirements can also be created for a proof category.

HTTP Requests

Structure and definitions

{
    "id": 1,
    "status": {
        "id": 1,
        "definition": "requested"
    },
    "document_type": {
        "id": 1,
        "definition": "signedLoanRequest",
        "description": "The signed loan request needs to be provided before any analysis can start."
    },
    "url": "a.very.long.signed.url/with-which/you-can-read/the/document.pdf",
    "mime_type": "application/pdf"
}

Python sample for uploading

import requests
token = AUTHORIZATION_TOKEN
base_url = BASE_URL
lr_id = LOAN_REQUEST_ID
category_id = CATEGORY_ID
document_id = DOCUMENT_ID

f = open('your_file_location', 'r')
request_data = {
    "file": f
}
response = requests.patch(
    url=f"{BASE_URL}/api/loan_requests/{lr_id}/proof/{category_id}/documents/{document_id}/",
    data=request_data,
    headers= {"Authorization": f"Token {token}"}
)
Field Description
id
integer
Read-only
The id of the document
status
DocumentStatus
Optional
The status of the document
document_type
DocumentType
Required at creation, else Read-Only
The document type, with description
url
URL
Read-only, optional
A signed URL to view the document
mime_type
string
Read-only, optional
The MIME type of the document to facilitate viewing
file
File
Write-only
The file with name 'file' for uploading the document

Document type is only allowed when creating the document. After creation, the document type is not editable.

Uploading the file must be a separate PATCH request. It cannot be done during creation. When trying to both upload a file and update the status, the status update will be ignored.

PUT requests have the same restrictions as PATCH requests. The document type can not be changed once provided, and it's not possible to both upload a file and update the content.

If a file has been uploaded, the url and mime-type fields will be filled in.

Allowed document types

Document types only make sense in one context. For example, an id card does not make sense in the context of a realty, in the context of a client.

HTTP requests

Structure and definitions

{
    "id": 1,
    "definition": "signedLoanRequest",
    "description": "The signed loan request needs to be provided before any analysis can start."
}

As there are only GET requests, all attributes are Read-only.

Field Description
id
integer
The id of the resource
definition
string
The name of the document
description
string
The descrition of the document to provide

This is the general mapping as of 2019/05/21.

Document type Category
belgianIdFront Client
belgianIdBack Client
marriageCertificate Client
divorceCertificate Client
payslip Client
employerAttestation Client
taxStatement Client
childSupportAttestation Client
bankStatement Client
rentalContract Client
rentPayment Client
companyFinancialStatement Client
nationalBankFiling Client
fireInsurancePolicy Insurance
liabilityInsurancePolicy Insurance
creditDeed Liability
creditLetters Liability
creditSettlement Liability
fiscalAttestation Liability
lastStatementCreditLine Liability
initialLoanRequest Loan Request
esis Loan Request
creafixDetails Loan Request
sepaRequest Loan Request
propositionPartialFundsRelease Loan Request
finalOffer Loan Request
estimatorReport Realty
purchaseAgreement Realty
renovationDetails Realty
renovationPlans Realty
renovationPermits Realty
renovationOffers Realty
propertyTitle Realty

Notifications

Notifications are in place to inform certain users about certain events. Notifications are always generated automatically. A user can get the ‘unseen’ notifications he/she has and view them in detail. Once a notification has been viewed the ‘seen’ field will be updated to True. Notification is a polymorphic object that is implemented in different forms:

General Notification

Notification object is sub-classed based on the type of entity(e.g Income, Loan request) they point to. The General Notification is a notification that does not point to any database entity instance and its instance_type is notification.

Fields

Here is an overview of the fields in a general Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The user who will receive the notification
notification_type
NotificationType
Required
The type of the notification
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified

Endpoints

The following endpoints provides notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 6,
      "definition": "notification"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Client Notification

The Client Notification is a subclass of notification that is generated based on a change or event linked to a client instance. The instance_type of client notification is client.

Fields

Here is an overview of the fields in a client Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The system user who will receive the notification
notification_type
NotificationType
Required
The type of the notification.
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified
client
Client
Required
The client object that is linked to this notification
loan_request
Loan Request
Optional
The loan request to which the notification is linked

Endpoints

The notification module has a polymorphic structure, so all subclasses of notification have the same endpoints. They can be differentiated by their instance_type. The following endpoints provide notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 1,
      "definition": "client"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false,
    "client": {
      "id": 1
    },
    "loan_request": {
      "id": 1
    },
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Income Notification

The Income Notification is a subclass of notification that is generated based on a change or event linked to an Income instance. The instance_type of Income notification is income.

Fields

Here is an overview of the fields in an Income Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The system user who will receive the notification
notification_type
NotificationType
Required
The type of the notification.
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified
income
Income
Required
The Income object that is linked to this notification
loan_request
Loan Request
Optional
The loan request to which the notification is linked

Endpoints

The notification module has a polymorphic structure, so all subclasses of notification have the same endpoints. They can be differentiated by their instance_type. The following endpoints provide notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 1,
      "definition": "income"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false,
    "income": {
      "id": 1
    },
    "loan_request": {
      "id": 1
    },
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Liability Notification

The Liability Notification is a subclass of notification that is generated based on a change or event linked to a Liability instance. The instance_type of Liability notification is liability.

Fields

Here is an overview of the fields in a Liability Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The system user who will receive the notification
notification_type
NotificationType
Required
The type of the notification.
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified
liability
Liability
Required
The Liability object that is linked to this notification
loan_request
Loan Request
Optional
The loan request to which the notification is linked

Endpoints

The notification module has a polymorphic structure, so all subclasses of notification have the same endpoints. They can be differentiated by their instance_type. The following endpoints provide notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 1,
      "definition": "liability"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false,
    "liability": {
      "id": 1
    },
    "loan_request": {
      "id": 1
    },
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Loan Request Notification

The Loan request Notification is a subclass of notification that is generated based on a change or event linked to a Loan request instance. The instance_type of Loan request notification is loanRequest.

Fields

Here is an overview of the fields in a Loan request Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The system user who will receive the notification
notification_type
NotificationType
Required
The type of the notification.
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified
loan_request
Loan Request
Required
The Income object that is linked to this notification

Endpoints

The notification module has a polymorphic structure, so all subclasses of notification have the same endpoints. They can be differentiated by their instance_type. The following endpoints provide notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 1,
      "definition": "loanRequest"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false,
    "loan_request": {
      "id": 1
    },
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Realty Notification

The Realty Notification is a subclass of notification that is generated based on a change or event linked to a Realty instance. The instance_type of Realty notification is realty.

Fields

Here is an overview of the fields in a Realty Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The system user who will receive the notification
notification_type
NotificationType
Required
The type of the notification.
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified
realty
Realty
Required
The Realty object that is linked to this notification
loan_request
Loan Request
Optional
The loan request to which the notification is linked

Endpoints

The notification module has a polymorphic structure, so all subclasses of notification have the same endpoints. They can be differentiated by their instance_type. The following endpoints provide notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 1,
      "definition": "realty"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false,
    "realty": {
      "id": 1
    },
    "loan_request": {
      "id": 1
    },
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Insurance Notification

The Insurance Notification is a subclass of notification that is generated based on a change or event linked to a Insurance instance. The instance_type of Insurance notification is insurance.

Fields

Here is an overview of the fields in a Insurance Notification object.

Field Description
id
integer
Read-only
The id of the notification
recipient
ApplicationUser
Required
The system user who will receive the notification
notification_type
NotificationType
Required
The type of the notification.
instance_type
DatabaseModelName
Required
The name of the database model that the notification points to
seen
Boolean
Required
Whether or not a notification has been seen or not
created
DateTime
Required
The date a notification was created
last_modified
DateTime
Required
The date a notification was last modified
insurance
LiabilityInsurance
or
Fire Insurance
Required
The Insurance object that is linked to this notification
loan_request
Loan Request
Optional
The loan request to which the notification is linked

Endpoints

The notification module has a polymorphic structure, so all subclasses of notification have the same endpoints. They can be differentiated by their instance_type. The following endpoints provide notifications that were assigned to currently logged-in broker. Brokers can only access the notifications assigned to them.

The HTTP request returns JSON structured like this

[
  {
    "id": 2,
    "recipient": {
      "id": 3
    },
    "notification_type": {
      "id": 1,
      "definition": "analystAssigned"
    },
    "instance_type": {
      "id": 1,
      "definition": "insurance"
    },
    "created": "2019-05-21T14:14:45.654396+02:00",
    "last_modified": "2019-05-21T14:14:45.654420+02:00",
    "seen": false,
    "insurance": {
      "id": 1
    },
    "loan_request": {
      "id": 1
    },
  }
]

HTTP Requests

URL Parameters

Parameter Description
notification_id The ID of the notification

Tasks

Task are created whenever a user needs to perform a certain action. Some tasks are generated automatically and others can be created manually by a user for themselves or for others.

Task

Users can view the tasks that are assigned to them or created by them. Users can update the status of a task.

Fields

Here is an overview of the fields in a task object.

Field Description
id
integer
Read-only
The id of the task
created_by
ApplicationUser
Required
The user that created the task
assigned_to
ApplicationUser
Required
The user that needs to perform the task
due_date
DateTime
Required
The date before which the task should be completed
status
TaskStatus
Required
The status of the task
task_type
TaskType
Required
The type of task
comment
string
Required
The comment that is added to a task
loan_request
Loan Request
Optional
The loan request to which the task is linked
created
DateTime
Required
The date a task was created
last_modified
DateTime
Required
The date a task was last modified

Endpoints

The following endpoints provides tasks that were assigned to currently logged-in broker. Brokers can only access the tasks assigned to them.

The HTTP request returns JSON structured like this

[
    {
        "id": 4,
        "status": {
            "id": 3,
            "definition": "done"
        },
        "task_type": {
            "id": 5,
            "definition": "default"
        },
        "loan_request": {
            "id": 1,
            "external_reference": "1905090000"
        },
        "assigned_to": {
            "id": 3
        },
        "created": "2019-05-22T13:42:05.158790+02:00",
        "last_modified": "2019-05-22T13:42:05.158790+02:00",
        "due_date": "2019-07-15T00:00:00+02:00",
        "comment": "Communication laoIllum autumn et iust",
        "created_by": {
            "id": 2
        }
    }
]

HTTP Requests

URL Parameters

Parameter Description
task_id The ID of the task

Third parties

For a loan, there are a number of third parties that need to be considered. For example, a notary needs to sign the deed and an estimator sets a value on the house.

These values are comparable to a CRM system, with possibilities. These can change but probably won't often. Unlike resources, these are not tied to any 0per delpoyments.

{
    "id": 1,
    "name": "Third is best NV",
    "vat_number": "0104206573210",
    "address": {
        "street": "Party Street",
        "house_number": "69",
        "box": "",
        "city": "Brussels",
        "zip_code": "1000",
        "country": {
            "id": 1,
            "definition": "BE"
        },
        "address_type": {
            "id": 1,
            "definition": "main"
        }
    }
}

All third parties follow a common structure. However, they can extend on the common structure with extra attributes.

At this moment, 0per only supports GET requests, so all fields are Read-only.

Field Description
id
integer
The id of the co-broker
name
string
The name of the co-broker
vat_number
string
The VAT number of the co-broker
address
Address
The main address of the co-broker

Co-brokers

Co-brokers help with the loan request, or provide referrals, but won't go through the whole process.

These often get a cut of the commissions, so it's important to set these on the level of loan request.

Co-brokers are defined per broker. Each broker can choose which other brokers can act as co-brokers. On the other hand, co-brokers are symmetrical, meaning that if Janssens is a co-broker of Peeters, then Peeters is also a co-broker of Janssens. Co-brokers are like Facebook, not like Instagram

HTTP Requests

Structure and definitions

The api only supports GET requests with no input parameters.

{
    "id": 1,
    "name": "Stephanie Peeters BVBA",
    "vat_number": "38452530402",
    "address": {
        "street": "Stephanie Peeters Street",
        "house_number": "100",
        "box": "",
        "city": "Brussels",
        "zip_code": "1000",
        "country": {
            "id": 1,
            "definition": "BE"
        },
        "address_type": {
            "id": 1,
            "definition": "main"
        }
    }
}

All fields are Read-only.

Field Description
id
integer
The id of the co-broker
name
string
The name of the co-broker
vat_number
string
The VAT number of the co-broker
address
Address
The main address of the co-broker

Estimators

An estimator sets a preliminary value on a realty. There are only a set list of estimators that are valid for certain credit providers.

HTTP Requests

Structure and definitions

The api only supports GET requests with no input parameters.

{
    "id": 1,
    "name": "Van Berckelaer Estimators BVBA",
    "vat_number": "010420130210",
    "address": {
        "street": "Van Berckelaer Street",
        "house_number": "100",
        "box": "",
        "city": "Brussels",
        "zip_code": "1000",
        "country": {
            "id": 1,
            "definition": "BE"
        },
        "address_type": {
            "id": 1,
            "definition": "main"
        }
    }
}

All fields are Read-only.

Field Description
id
integer
The id of the co-broker
name
string
The name of the co-broker
vat_number
string
The VAT number of the co-broker
address
Address
The main address of the co-broker

Insurance providers

Insurance providers give the insurance to the clients. While functionally, there is a difference between fire and liability insurance, or between life and non-life, the providers are set in the same API.

This is purely informational, and the correctness of the input must be done by the caller, for example, not giving a purely non-life provider as a liability insurance.

HTTP Requests

Structure and definitions

The api only supports GET requests with no input parameters.

{
    "id": 1,
    "name": "Van Berckelaer Estimators BVBA",
    "vat_number": "010420130210",
    "fsma_reference": "BE23143294291342",
    "address": {
        "street": "Van Berckelaer Street",
        "house_number": "100",
        "box": "",
        "city": "Brussels",
        "zip_code": "1000",
        "country": {
            "id": 1,
            "definition": "BE"
        },
        "address_type": {
            "id": 1,
            "definition": "main"
        }
    }
}
Field Description
id
integer
The id of the co-broker
name
string
The name of the co-broker
vat_number
string
The VAT number of the co-broker
address
Address
The main address of the co-broker

Notaries

{
    "id": 1,
    "name": "Van Berckelaer Estimators BVBA",
    "vat_number": "010420130210",
    "address": {
        "street": "Van Berckelaer Street",
        "house_number": "100",
        "box": "",
        "city": "Brussels",
        "zip_code": "1000",
        "country": {
            "id": 1,
            "definition": "BE"
        },
        "address_type": {
            "id": 1,
            "definition": "main"
        }
    }
}
Field Description
id
integer
The id of the co-broker
name
string
The name of the co-broker
vat_number
string
The VAT number of the co-broker
address
Address
The main address of the co-broker

Resources

These are the enumerated types that are used through out the system.

City

A City object represents an actual city in a country.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "Valletta"
  }
]

HTTP Requests

URL Parameters

Parameter Description
city_id The ID of the city object.

Fields

Here are the fields in a City object.

Field Description
id
integer
Read-only
The id of the city object.
definition
string
Read-only
holds the name of the city.

Definition Values

Here are the possible values of the definition of a City object.

Definition
Antwerp
Brussels

Civil Status

A Civil status object represents a person's civil status or marital status.

The HTTP request returns JSON structured like this

[
  {
    "id": 9,
    "definition": "single"
  }
]

HTTP Requests

URL Parameters

Parameter Description
civilstatus_id The ID of the civil status object

Fields

Here are the fields in a Civil status object.

Field Description
id
integer
Read-only
The id of the civil status object.
definition
string
Read-only
holds the name of the civil status.

Definition Values

Here are the possible values of the definition of a civil status object.

Definition
marriedForeignSystem
widow
divorced
marriedCombinedGoods
marriedSeparateGoods
marriedLawful
cohabiting
single

Client Role

A Client role object represents the role of a client in the loan request process.

The HTTP request returns JSON structured like this

[
  {
    "id": 4,
    "definition": "borrower"
  }
]

HTTP Requests

URL Parameters

Parameter Description
clientrole_id The ID of the client role object

Fields

Here are the fields in a Client role object.

Field Description
id
integer
Read-only
The id of the client role object.
definition
string
Read-only
holds the name of the client role.

Definition Values

Here are the possible values of the definition of a client role object.

Definition
spouse
collateralProvider
borrower

Contact Type

A Contact type object represents the type of contact information that is being provided.

The HTTP request returns JSON structured like this

[
  {
    "id": 6,
    "definition": "professional"
  }
]

HTTP Requests

URL Parameters

Parameter Description
contacttype_id The ID of the contact type object

Fields

Here are the fields in a Contact type object.

Field Description
id
integer
Read-only
The id of the contact type object.
definition
string
Read-only
holds the name of the contact type.

Definition Values

Here are the possible values of the definition of a contact type object.

Definition
professional
personal
office
legal
main

Country

A Country object represents an actual country.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "BE"
  }
]

HTTP Requests

URL Parameters

Parameter Description
country_id The ID of the country object

Fields

Here are the fields in a country object.

Field Description
id
integer
Read-only
The id of the country object.
definition
string
Read-only
holds the 2-digit ISO code of a country.

Definition Values

Here are the possible values of the definition of a contact type object.

Definition
BE
MT
EE
NG
GB

Credit Provider

A list of credit providers of existing credits or new credits.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "belfius"
  }
]

HTTP Requests

URL Parameters

Parameter Description
creditprovider_id The ID of the credit provider object

Fields

Here are the fields in a credit provider object.

Field Description
id
integer
Read-only
The id of the credit provider object.
definition
string
Read-only
The name of the credit provider.

Definition Values

Here are the possible values of the definition of a credit provider object.

Definition
belfius
beobank
bpost
hellobank
kbc

Credit Takeover

List of possible actions you can take with existing credits.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "yes"
  }
]

HTTP Requests

URL Parameters

Parameter Description
credittakeover_id The ID of the credit takeover object

Fields

Here are the fields in a credit takeover object.

Field Description
id
integer
Read-only
The id of the credit takeover object.
definition
string
Read-only
The name of the credit takeover.

Definition Values

Here are the possible values of the definition of a credit takeover object.

Definition
yes
no
repay

Database Model Name

List of database model names that are used for polymorphic relationships.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "client"
  }
]

HTTP Requests

URL Parameters

Parameter Description
databasemodelname_id The ID of the database model name object

Fields

Here are the fields in a Database Model Name object.

Field Description
id
integer
Read-only
The id of the document type object.
definition
string
Read-only
The name of the document type.

Definition Values

Here are the possible values of the definition of a Database Model Name object.

Definition
client
income
realty

Document Type

List of possible document types e.g. salary slip, ESIS, ID Card,...

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "belgianIdFront"
  }
]

HTTP Requests

URL Parameters

Parameter Description
documenttype_id The ID of the document type object

Fields

Here are the fields in a document type object.

Field Description
id
integer
Read-only
The id of the document type object.
definition
string
Read-only
The name of the document type.

Definition Values

Here are the possible values of the definition of a document type object.

Definition
belgianIdFront
belgianIdBack
payslip

Employment Contract Type

List of possible employment contract types.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "indefinite"
  }
]

HTTP Requests

URL Parameters

Parameter Description
employmentcontracttype_id The ID of the employment contract type object

Fields

Here are the fields in a employment contract type object.

Field Description
id
integer
Read-only
The id of the employment contract type object.
definition
string
Read-only
The name of the employment contract type.

Definition Values

Here are the possible values of the definition of a employment contract type object.

Definition
indefinite
definite
interim

Employment Type

List of possible employment types.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "civilServant"
  }
]

HTTP Requests

URL Parameters

Parameter Description
employmenttype_id The ID of the employment type object

Fields

Here are the fields in a employment type object.

Field Description
id
integer
Read-only
The id of the employment type object.
definition
string
Read-only
The name of the employment type.

Definition Values

Here are the possible values of the definition of a employment type object.

Definition
selfEmployedCompany
healthInsuranceSettlement
selfEmployedSoleProprietorship
unemployed
student
unclear
disabled
houseWife
retired
diplomat
cLevel
employee
worker
civilServant

Income Type

List of income types that are not defined in a specific table.

The HTTP request returns JSON structured like this

[
  {
    "id": 1,
    "definition": "salaryEmployed"
  }
]

HTTP Requests

URL Parameters

Parameter Description
incometype_id The ID of the income type object

Fields

Here are the fields in a income type object.

Field Description
id
integer
Read-only
The id of the income type object.
definition
string
Read-only
The name of the income type.

Definition Values

Here are the possible values of the definition of a income type object.

Definition
healthInsurance
other
mealVouchers
salarySelfEmployed
unemploymentBenefit
invalidity
mutuality
retirement
futureRent
rent
alimony
childBenefit
salaryEmployed

Errors

Oper uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Check the response for explanation
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The request is hidden for administrators only.
404 Not Found -- The specified request could not be found.
405 Method Not Allowed -- You tried to access a endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The request object has been removed from our servers.
418 I'm a teapot.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.