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. |
WAITING_FOR_USER_ACTION | User action is needed in order for authentication to continue, e.g. signing in an authenticator app such as BankID. | Check if there is any extraInformation included that indicates further actions need to be taken. If no extraInformation is provided with this status inform the user to open their authenticator app and sign. |
COLLECTING | Collection of data has started. | Keep polling status. |
COMPLETED | Collection process has finished and data was successfully collected. | Fetch collected data from the GET /data 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. |
INCORRECT_CREDENTIALS | The user has entered incorrect login credentials. | 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_TIMEOUT | Authentication timed out while waiting for the user to authenticate. | Ask the user to retry if they still wish to collect their data. |
AUTHENTICATION_CANCELLED | Authentication was cancelled by the user. | Ask the user to retry if they still wish to collect their data. |
AUTHENTICATION_CONFLICT | Authentication was cancelled due to multiple ongoing authentication sessions. | Depending on loginMethod, explain to the user what may have caused conflicting authentication sessions and ask them to retry. |
AUTHENTICATION_MISMATCH | The person initiating the collection is not the person that has authenticated. | Explain to the user that there seems to be a mismatch between the user and the one who signed with BankID. See section below for further explanation on this status code. |
ACCOUNT_TEMPORARILY_LOCKED | The user's access to the company has been temporarily blocked. For example, this could happen if the user tries to authenticate multiple times with incorrect login credentials. | Explain to the user that they cannot access their account right now and suggest to try again later. The exact time to wait differs between companies but a guideline would be to try again after 15 minutes. |
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. |
THIRD_PARTY_ERROR | The collection failed due to an error on the company's end. Underlying cause could be unexpected timeouts or errors. | Explain to the user that the company was unavailable to collect data from but that they can retry the collection. |
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.