Migration Guide for Pre-approval API /applications to /mortgage/2.0

This is a quick guide for changes in the Preapproval API and how to migrate to the new API.
Please note that there is no sandbox environment available for the Pre-approval API yet.
Please refer the api spec for details:

Changelog

Major change in the new API is that the base url has changed from https://api.sbab.se/partner/applications to https://api.sbab.se/partner/mortgage/2.0.

The url changes for the endpoints are as follows:

Preapproval API flow

This is a quick guide for the Preapproval API flow.

1. Call POST https://api.sbab.se/partner/mortgage/2.0/pre-approval to generate pre-approval offer.

2. Call POST https://api.sbab.se/partner/mortgage/2.0/pre-approval/{id}/acceptance to accept pre-approval offer variant with or without unsecured loan.
   

   1. Response body: AcceptPreApprovalResponseV2:
      { "status": "AWAITING_ACCEPTANCE", "signing_process": { "participants": [ { "personal_number": "198410160595", "id": "b9052a54-7e40-11ee-b962-0242ac120002" }, { "personal_number": "196407166815", "id": "8be4a061-7a05-4499-8396-020806b92ee2" } ] }, "expiry_date": "2024-04-23T15:00:00Z" }
   2. Note down signing_process.participants[n].id values from the signing_process.participants list. Ex. b9052a54-7e40-11ee-b962-0242ac120002 and 8be4a061-7a05-4499-8396-020806b92ee2 above respectively.

3. Call signing api for each participant id to start signing for respective applicant.
   Refer Signing API for details.
   Request body StartSigningRequest:

   { "participant_id": "b9052a54-7e40-11ee-b962-0242ac120002" }

   OR
   

   Request body StartPhoneSigningRequest:

   { "participant_id": "8be4a061-7a05-4499-8396-020806b92ee2", "call_initiator": "RP" }

4. Call GET https://api.sbab.se/partner/mortgage/2.0/pre-approval/{id}/status to get the complete status of the pre-approval.
   Response body: PreApprovalStatusDataV2:

   { "signing_process": { "participants": [ { "personal_number": "198410160595", "id": "b9052a54-7e40-11ee-b962-0242ac120002", "signed": true, "signed_at": "2024-04-08T14:07:17Z" }, { "personal_number": "196407166815", "id": "8be4a061-7a05-4499-8396-020806b92ee2", "signed": false } ] }, "status": { "type": "SIGNING_ONGOING" }, "expiry_date": "2024-04-23T15:00:00Z" }

5. Once all the applicants have signed, the application will be submitted for further processing.

6. Call GET https://api.sbab.se/partner/mortgage/2.0/pre-approval/{id}/status to get the status and customer_service_reference for the application.
   Response body: PreApprovalStatusDataV2:

   { "signing_process": { "participants": [ { "personal_number": "198410160595", "id": "b9052a54-7e40-11ee-b962-0242ac120002", "signed": true, "signed_at": "2024-04-08T14:07:17Z" }, { "personal_number": "196407166815", "id": "8be4a061-7a05-4499-8396-020806b92ee2", "signed": true, "signed_at": "2024-04-08T14:09:17Z" } ] }, "customer_service_reference": "5060803", "status": { "type": "PROCESSING" }, "expiry_date": "2024-04-23T15:00:00Z" }

7. The application will be subsequently processed by the credit handling system and the status will be updated to APPROVED or REJECTED.

Signing API

The new signing API replaces the signature endpoint POST https://api.sbab.se/partner/applications/{id}/pre-approval/applicants/{applicant-id}/signature.
The new signing API has following endpoints:

Signing API flow

1. Initiate signing for a participant using any one of the following 3 methods

1. BankID app on the same device using autostart_token.
   1. Use POST https://api.sbab.se/partner/signing/1.0/start to start signing for an applicant.
      Use the signing_process.participants[n].id value from the PreApprovalStatusDataV2 response for participant_id.
      Request body StartSigningRequest:
      { "participant_id": "b9052a54-7e40-11ee-b962-0242ac120002" }
      This will return the autostart_token and qr_string which should be used to start signing.
      Response body StartSigningResponse:
      { "autostart_token": "41d9be69-7686-4ac4-94b4-7e78cc6f598b", "qr_string": "bankid.2e42ad1d-9867-4fe7-8480-3f749cd8d3a4.0.f13fd02ee9c9380c56920ab77ac2a578663f0745be33d7a89eda6d2bfb241438" }
   2. The BankID app should be launched using this url format. bankid://autostarttoken=<autostart_token>&redirect=null Ex. bankid://autostarttoken=41d9be69-7686-4ac4-94b4-7e78cc6f598b&redirect=null
   3. The user can sign using the BankID app.

OR

2. BankID app on another device using the qr_string.
   1. Use POST https://api.sbab.se/partner/signing/1.0/start to start signing for an applicant.
      Use the signing_process.participants[n].id value from the PreApprovalStatusDataV2 response for participant_id.
      Request body StartSigningRequest:
      { "participant_id": "b9052a54-7e40-11ee-b962-0242ac120002" }
      This will return the autostart_token and qr_string which should be used to start signing.
      Response body StartSigningResponse:
      { "autostart_token": "41d9be69-7686-4ac4-94b4-7e78cc6f598b", "qr_string": "bankid.2e42ad1d-9867-4fe7-8480-3f749cd8d3a4.0.f13fd02ee9c9380c56920ab77ac2a578663f0745be33d7a89eda6d2bfb241438" }
   2. The QR code should be displayed to the user to scan using the BankID app on another device.
      

OR

3. On a phone call with the customer using start/phone endpoint.
   1. Use POST https://api.sbab.se/partner/signing/1.0/start/phone if you are in a call with the client.
      Use the signing_process.participants[n].id value from the PreApprovalStatusDataV2 response for participant_id.
      Use call_initiator as RP if you are initiating the call. If the customer initiates the call, use call_initiator as USER.
      Request body StartPhoneSigningRequest:
      { "participant_id": "8be4a061-7a05-4499-8396-020806b92ee2", "call_initiator": "RP" }
      Response status code: 204
   2. This will automatically launch the BankID app on the user's device.
   3. The user will get a notification to confirm that they are currently in a call with the partner.
   4. Once the user confirms, they can sign through the BankID app.

2. Use the signing/collect endpoint to obtain the status of the signing or get a new qr_string

This endpoint should be used to display information about the signing for the user.
Refer our documentation for more details: Signing API

1. Use POST https://api.sbab.se/partner/signing/1.0/collect to get the status of the signing or get a new qr_string.
   Use the signing_process.participants[n].id value from the PreApprovalStatusDataV2 response for participant_id.
   Request body CollectSigningRequest:
   { "participant_id": "b9052a54-7e40-11ee-b962-0242ac120002" }
   Response body CollectSigningResponse:
   { "status": "INITIATED", "hint_code": "OUTSTANDING_TRANSACTION", "qr_string": "bankid.67df3917-fa0d-44e5-b327-edcc928297f8.0.dc69358e712458a66a7525beef148ae8526b1c71610eff2c16cdffb4cdac9bf8" }
2. Display the QR code to the user to scan using the BankID app.
3. OR use the status and hint_code to check the status of the signing.
   Refer our documentation for more details: Signing API

signing/cancel endpoint

Use POST https://api.sbab.se/partner/signing/1.0/cancel to cancel the signing.
Use the signing_process.participants[n].id value from the PreApprovalStatusDataV2 response for participant_id.
Request body CancelSigningRequest:

Response status code: 204