Insurance API

The Insurely API allows you to collect and aggregate pension and investment data from a variety of companies.

This documentation contains a description of the methods available, examples of requests and responses and details about the returned objects.

Available companies

Check the Catalog to get the full list of companies supported.

A note on data - missing/null data points do not indicate zero/nothing value but should rather be viewed as unknown value.

Due to technical issues and planned maintenance the supported companies may be unavailable time to time. Before starting a data collection, it is therefore recommended to first company statuses 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 data through the API:

Check if the 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 `CONTACT_FORM_PENDING` status

For some collections extra data about the user is needed in order to proceed with the collection. This is usually due to the collection target company not allowing the user access to their data without e.g. entering their phone number and e-mail address. If the collector supports passing this extra data the following flow will happen:

The get status call will return with "status": "CONTACT_FORM_PENDING" and contain REQUIRED_INPUT_TYPES in the extraInformation field.

After fetching the contact form data from the user, post it as a CollectionInput to the supplement-info endpoint.

If contact form input is added successfully (no 4xx) the collection will proceed and a new status will be received in a coming status call.

CONTACT_FORM_PENDING will timeout after a couple of minutes, if timeout occurs the collection terminates with status CONTACT_FORM. It is not currently possible to forcefully terminate a collection, and hence it is not possible to signal that the contact form input will not be provided. In this scenario the suggestion is to let the user proceed as if the collection has terminated without any returned data and let the contact form functionality time out.

The input types that can be required when the status is CONTACT_FORM_PENDING:

EMAIL, the user's e-mail. Expected format: <address>@<domain>, e.g. test@test.com
MOBILE_PHONE_NUMBER, the user's phone number. Expected format: only digits, e.g. 0046701234567

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.csr

Verify 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.