Loan Application Flow
The Loan Application flow is the main one, performing an actual loan application with SBAB. It can be used to apply for new loans or transferring existing ones from other institutions to SBAB.
Note that, similarly to the Pre Application flow, requests for this flow requires a client credentials access token, not a end-user credentials token.
When a Loan Application request is received from the client, a Left to Live calculation is executed with the received data:
- If a negative left to live score is received, the Loan Application is rejected and the application data is not stored
- If a positive left to live score is received, the flow continues with a creation of the signing process and the
response object will contain the data to trigger BankID signing (the application is now in status
loan_application_need_signing
)
As of Q2 2022, cost of cars is included in the calculation, read more in the cost of cars section.
For the loan application to proceed, a successful BankID signature is required from the main applicant. The partner client must call the initiation of the signature in our service API. Please note that our service can not asynchronously notify the partner that an applicant has failed to do a BankID signing (caused by user interruption of BankID, request timed out, etc.), so the client must give the applicant time to do the signature and keep requesting the status.
If after 3 minutes (BankID's timeout) the application is still not signed, the partner client should offer the end user to start a new BankID signing. Such operation can be repeated multiple times without adverse effects until the main applicant successfully signs with BankID.
When reaching the expiration date of the process, received in the loan application's response, an unsigned application will automatically be rejected. This expiration date is defined as 45 days after the application is first received by the API.
PLease note that due to an upgrade from BankID, the signing endpoint that partners use to sign the loan applications requires
a mandatory header named PSU-IP-Address
.
In the response of a successful signing attempt, only an autostart_token
used for BankID triggering will be returned.
Please note that consecutive attempts to initiate a new signing, for the same user with changing PSU-IP-Address
values
within a time span of approximately 3 minutes, will result in blocking of the BankID for approximately 3 minutes.
What is PSU-IP-Address
?
PSU-IP-Address is the end user's IP address representing the user agent (the end user device) as seen by our partners.
Both IPv4 and IPv6 formats are supported. Since the `PSU-IP-Address` is mandatory, the partners should try to ensure the
correctness of the IP address and that it should represent the user agent.
If partners handle the customers over phone then the IP address of the system which initiates the signing can be used.
After signed by the applicant, the application will transition into state loan_application_received
. It will then
be processed by our internal systems and after some time, usually between 30 seconds and one minute, it will
transition into state loan_application_processing
(if not rejected by other reasons, such as credit check).
By this point, a human review of the application will take place, and the result of that is the definition of a list of documents that need to be provided by the applicant in order to fully evaluate the applicant's loan request. Such list of documents will be returned as part of the periodic status request executed by the client. The documents will be sent by the applicant to the partner in whatever format it wishes to receive them (digital or physical), and they should ultimately be sent by the client in PDF format through the API.
Once all the documents are received and approved by SBAB's Customer Service, the loan documents are printed and sent to the applicant. The applicant can also log in to sbab.se to download and print the documents. The applicant signs and sends the documents to SBAB by physical mail or e-mail. Once the documents are approved by SBAB's Customer support, the loan can finally be disbursed.
Diagrams
Sequence diagram
Flowchart for Loan Application
Flowchart for Supplement Documents
Request fields
There are two types of loan application, as defined by the purpose
field:
new-loan
: used when the customer has a new object (real estate property) they want to purchase;transfer-loan
: used when the customer has an existing object (real estate property) and want to move the loans from another financial institution to SBAB.
Note: familiarize yourself with the model of the request data for loan applications in our Sandbox environment.
For both types of applications, there are a few common fields that are applicable: loan_applicant
,
co_loan_applicants
, child_information
, collateral_for_loan
(with some difference on the content),
loan_amount
, loans_to_keep
, accommodations
, notes
and administrator
.
New loan
For new loan applications, you have to set the field payment_date
and shouldn't set loans_to_transfer
.
If you apply for a new loan you leave transfer-loans empty, this is only set when you have actual loan to transfer. The amortization rule should only be set when the purpose is new-loan. Note that for loans-to-transfer it is good to provide condition_rollover_date if you have that information.
Below you can see a snippet of a new loan application object with some sample values:
{
"purpose": "new-loan",
"payment_date": "2020-01-15",
"loan_applicant": ... ,
"co_loan_applicants": [...],
"child_information": ... ,
"collateral_for_loan": ... ,
"loan_amount": 5000000,
"loans_to_keep": [...],
"accommodations": [...],
"notes": "Information for the loan review, e.g. about down payment, household income",
"administrator": ...
}
Transfer loan
For loan transfers, payment_date
is not set and loans_to_transfer
is mandatory. The field
amortisation_rule_before_march2018
should also be set, according to the application or not of the new amortization
percentage determined by Finansinspektionen (FI).
Below you can see a snippet of a loan transfer application object with some sample values:
{
"purpose": "transfer-loan",
"loan_applicant": ... ,
"co_loan_applicants": [...],
"child_information": ... ,
"collateral_for_loan": ... ,
"loan_amount": 5000000,
"loans_to_transfer": [...] ,
"amortisation_rule_before_march2018": ... ,
"loans_to_keep": [...],
"accommodations": [...],
"notes": "Information for the loan review, e.g. about down payment, household income",
"administrator": ...
}
Other fields
For the common fields, here are some extra details about the purpose of some of them.
Administrator
In order to let SBAB know who helped the customer to send in the application, an administrator with a name and an internal ID can be informed:
{
...
"administrator": {
"name": "Sven Svensson",
"id": "123-abc"
},
...
}
Collateral for loan
There are several fields that comprise collateral_for_loan
, and which ones are required vary according to the type
of the collateral, as well as if the application is a new loan or a transfer:
house
orvacation-house
(same fields apply for both, it only differes by type):{ ... "collateral_for_loan": { "type": "house", "collateral_value": 5000000, "assess_value": 1200000, "living_space": 67, "property_designation": "Stockholm Södermalm 1:123", "postal_code": "12345" }, ... }
tenant-owned-apartment
:{ ... "collateral_for_loan": { "type": "tenant-owned-apartment", "collateral_value": 5000000, "street_address": "Drottninggatan 123", "postal_code": "12345", "apartment_number": "123", "number_of_rooms": 2, "living_space": 67, "monthly_cost": 4500, "tenant_owners_association_organisation_number": "7123456789", "tenant_owners_association_name": "BRF Namn" }, ... }
Also, the contents of collateral_value
vary according to the type of loan application being submitted:
new-loan
: the purchase value for the property (köpeskilling);transfer-loan
: estimated market value (either from the applicant or a calculated valuation).
Accommodations
Under this field is added information regarding objects that the applicant own or rent that will be kept. Loans associated to the accommodations are provided under loans to keep.
Here is an example of the described information:
{
...
"accommodations": [
{
"type": "vacation-house",
"monthly_cost": 2000,
"assess_value": 750000,
"ownership_share": 0.5
},
{
"type": "house",
"monthly_cost": 2000,
"assess_value": 1000000,
"ownership_share": 0.75
},
{
"type": "tenant-owned-apartment",
"monthly_cost": 2000
},
{
"type": "rented-housing",
"monthly_cost": 2000
}
],
"loans_to_keep": [
{
"type": "vacation-house-loan",
"ownership_share_of_loan": 0.5,
"loan_amount": 1100000
},
{
"type": "house-loan",
"ownership_share_of_loan": 0.5,
"loan_amount": 1100000
},
{
"type": "tenant-owned-apartment-loan",
"ownership_share_of_loan": 0.5,
"loan_amount": 1100000
},
{
"type": "blanco-loan",
"loan_amount": 100000
}
],
...
Applicants
When specifying the main applicant or co-applicants, required employment-related fields depend on the value of the
employment_type
field: if employed
then employer
, profession
and date_of_employment
are required;
if self-employed
then date_of_employment
is requried; if retired
, unemployed
or student
then none of these
three fields are needed.
Example:
{
...
"loan_applicant": {
"employment_type": "retired",
"email": "email@email.com",
"phone_number": "0700000000",
"personal_identity_number": "193001010000",
"marital_status": "married",
"monthly_income": 30000
},
"co_loan_applicants": [
{
"email": "mail@mail.com",
"phone_number": "0701111111",
"date_of_employment": "2017-10-01",
"personal_identity_number": "198001019999",
"marital_status": "married",
"monthly_income": 40000,
"employment_type": "employed",
"employer": "Företag AB",
"profession": "Arbetare"
}
]
}
Response examples
Here are some examples of possible responses:
- a successful application, including signing information:
{ "loan_application_id": "6c0f2e94-1311-46fb-bf15-a8b907d3c827", "signing_process": { "created_at": "2021-03-25T15:24:41.015355", "expiry_date": "2021-05-09T15:24:40.908895", "signing_applicants": [ { "personal_identity_number": "193001010000", "applicant_id": "5c8fbb72-bafa-4d20-a9b4-28089b23c2bc", "signed": false } ] } }
- a failure (
HTTP 400
) due to a failed Left to Live calculation (more likely if Left to Live is not executed before the application, or if the sent parameters are different in some way between both calls):[ { "message": "Left to live value is negative", "property_path": "LeftToLiveValue", "error_code": "Left to live value is negative", "invalid_value": "LeftToLiveValue: -189" } ]
- a failure (
HTTP 400
) due to a high loan ratio:[ { "message": "Loan Amount too high compared to Collateral Value. Maximum ratio is 95%, calculated loan distribution values: mortgage amount: 3400000 blanco amount: 400000 non approved amount: 200000", "property_path": "LoanAmount", "error_code": "Loan ratio is too high", "invalid_value": "LoanAmount: 3900000, CollateralValue: 4000000" } ]
- a failure (
HTTP 400
) due to a high debt ratio:[ { "message": "Debt ratio is higher than 5.5", "property_path": "DebtRatio", "error_code": "Debt ratio is too high", "invalid_value": "Debt ratio is : 6.39" } ]