Insurance API
The Insurely API allows you to collect and aggregate insurance data from a variety of insurance companies. This documentation contains a description of the methods available, examples of requests and responses and details about the returned insurance objects.
Available companies and insurance types
The Insurance API in Sweden currently supports the following companies
All insurance types excluding pension and other financial products are available for collection.
A note on data - missing/null datapoints do not indicate zero/nothing value but should rather be viewed as unknown value.
Service availability
Due to technical issues and planned maintenance the supported insurance companies may be unavailable from time to time. Before starting a data collection, it is therefore recommended to check the status of the insurance companies to obtain a status on which companies that are currently available.
Data collection example
Following is a step-by-step tutorial on how to obtain insurance data through the API:
Check if the insurance company is available using the company API.
If the company is available, start a data collection for a user and use the appropriate loginMethod.
Poll the status of the data collection. Polling interval speeds might vary depending on loginMethod. See CollectionRequest.
Collection statuses
| Status | Description | Action |
|---|---|---|
RUNNING | Collection process has started. | Keep polling status. |
LOGIN | Authenticating the user and signing in to the company. | Keep polling status. Check if there is any extraInformation included that indicates further actions need to be taken. |
TWO FACTOR PENDING | Waiting for the user to supply a two-factor code, see details here #definition-TwoFactorCode. | Keep polling status. |
CONTACT FORM PENDING | We have been prompted with a contact form when logging in. Use API endpoint to populate the data (collection will time out if no data is provided) without asking the user to log in manually. | Ask the user for the requested contact information or use already known information about the user. This is explained in more detail here. |
COLLECTING | Collection of data has started. | Keep polling status. |
COMPLETED | Collection process has finished and data was successfully collected. | Fetch collected data from the POST /pension-collection/collect-info endpoint. |
COMPLETED PARTIAL | Collection process has finished but not all data was collected. Might be caused by unexpected timeouts or other temporary issues. | Try again or proceed as if COMPLETED. Perhaps prompt the user with what was found and ask if a new collection is wanted. |
COMPLETED EMPTY | Collection process has finished but no data was found. A reason for this could be that the user is not a client with the company we are collecting from. Or did not have any of the products that was searched for. | Explain to the user that they do not have any products at the company they are collecting from. |
FAILED | Collection process failed. Could be caused by unexpected timeouts, site being down or other temporary issues. | Explain to the user that there was an unexpected error during the collection and ask if they want to redo the collection. |
FAILED PDF PARSE | Collection failed because of an error when trying to parse an insurance from a PDF file passed in using the PDF UPLOAD login method. | Ask the user to try again with a different PDF file or change selected line of business. Explain that the PDF file should be a document containing specific terms for their insurance. |
FAILED PDF USER INPUT | Collection failed because an unsupported PDF file was passed in using the PDF UPLOAD login method. | Ask the user to try again with a different PDF file or change selected line of business. Explain that the PDF file should be a document containing specific terms for their insurance. |
WAITING FOR AUTHENTICATION | Collection failed due to a timeout when waiting for the user to authenticate, e.g. through BankID. | Depending on loginMethod, explain to the user that authentication took too long and ask if they want to retry. |
INCORRECT CREDENTIALS | Login is done with user/password and the user has inputted the wrong details. | Explain to the user that credentials seem to be incorrect and ask to re-enter credentials. As a courtesy you can explain that the user may be blocked from services after too many retries. |
AUTHENTICATION CONFLICT | The user has started multiple authentications, e.g. BankID, and failed to complete the first one. | Depending on loginMethod, explain to the user what may have caused conflicting authentications and ask the user to retry. |
AUTHENTICATION MISMATCH | The person initiating the collection is not the person that has authenticated, e.g. scanned a BankID QR code and authenticated. | Ask the user to try again. Possibly explain that there seemed to be a mismatch between the user and the one who signed with BankID. See section below for further explanation on this status code. |
KYC FORM | When logging in we have been prompted with a KYC form with AML related questions blocking us from proceeding with the collection. This has to be filled in manually by the user by logging in to the company through the company app or website. Then the user can initiate a new collection. | Explain to the user that the collection required information to be submitted by the user. Say that it may resolve by the user themselves signing in to their account and answer a form. |
CONTACT FORM | When logging in we have been prompted with a form asking for user contact details blocking us from proceeding the collection. This has to be filled in by the user by manually logging in to the company through the native app or website. Then the user can initiate a new collection. This status is also displayed if the CONTACT FORM PENDING times out. | Same as KYC FORM. |
CUSTOMER ENROLLMENT REQUIRED | The user needs to sign up as a customer with the company before we can log in and collect data from them. This happens mostly for Handelsbanken and Futur where a user could have e.g. an occupational pension without actually being customers at the company. | Either proceed as COMPLETED EMPTY or explain to the user that we could not access any account. |
The AUTHENTICATION_MISMATCH status
During the login process we try to ensure that the person signing in with BankID, e.g. scanning the QR code and authenticating, is the same person as the one that initiated the collection.
In some cases the personal number can be verified directly in the BankID authentication flow. If that is not possible but we receive a personal number back from the company that we are collecting from we can compare that personal number with the one passed in with the CollectionRequest
If they are found to not be the same person AUTHENTICATION_MISMATCH returned and the collection flow is terminated.
In a few cases we cannot verify the personal number at all.
See the flowchart below for an illustration on in which cases the AUTHENTICATION_MISMATCH status is returned.
The SWEDISH_MOBILE_BANKID_SAME_DEVICE_ CLIENT_SIDE_AUTHENTICATION login method
The SWEDISH_MOBILE_BANKID_SAME_DEVICE_CLIENT_SIDE_AUTHENTICATION login method is different from the other BankID login
methods in that it requires the BankID flow to be initiated from the same device as the BankID authentication will be
performed on. In order to make this as streamlined as possible we will in this case supply a number of requests to be
executed from the end-user's device. These requests will be sent as
Request objects in the INSTRUCTIONS field of
the CollectionStatus extraInformation
field and the responses are to be returned as a ResponseObject to the /supplement-info endpoint. This is visualised in the chart below.
As the requests included in this login method would result in CORS errors when executed from a browser, the login method
is only supported in native environments, such as mobile apps, as it there can be executed in its own separate HTTP
context. Browser based clients should still have the SWEDISH_MOBILE_BANKID_OTHER_DEVICE login method option.
An integration for this login method should be able to handle new request URLs without crashing. However, we understand that you may not be able to support arbitrary URLs. E-mail us at support@insurely.com, or reach out in any other channel, if you need to know the current set of URLs that may appear in your context.
Authentication
To use the API you need to obtain an authentication token. This key is to be set in the header ´Authorization-token` for all requests. E-mail us at support@insurely.com and we'll provide the API key.
| Header | Header Value |
|---|---|
| Authorization-token | The auth key supplied by Insurely |
API Versioning
The API will default to the lowest running API version. If you want to use a newer version you must set the Insurely-Version header on your requests, with the date of the version that you intend to use. The API version that this document references is specified at the top of this page.
| Header | Header Value |
|---|---|
| Insurely-Version | The version of the API |
Mutual TLS (mTLS)
Our APIs have support for mTLS. These are the steps needed to enable mTLS for your client.
Create two private keys and two Certificate Signing Requests (CSR), one for test and one for production, and send them to support@insurely.com. Insurely will sign and send the certificates back.
genrsa -out my_test_client.key 2048
openssl req -new -key my_test_client.key -out my_test_client.csr
openssl genrsa -out my_prod_client.key 2048
openssl req -new -key my_prod_client.key -out my_prod_client.csrVerify your received certificates
curl --key my_test_client.key --cert my_test_client.pem 'https://mtls.api.test.insurely.com/health'
curl --key my_prod_client.key --cert my_prod_client.pem 'https://mtls.api.insurely.com/health'You should get the same response for both requests:
{ "status": "healthy" }- To enforce mTLS - prefix all urls with the mtls subdomain as shown in verification examples above.