Navigate back to Platform
Documentations

Insurer Tender API

Suggest Edits

The tender object is the medium of communication between brokers, Insurance providers, and end-user (customers) from risk assessment to accepting an offer and closing it by sealing a policy.

Every tender object has many properties and associations that are available in responses from Tender API. Here it's possible to understand the meaning and usage of each property.



List Tenders

curl https://{environment}/public/v1/tenders \
  -H "Authorization: Bearer {ACCESS_TOKEN}" 

// List of tenders
{
  "metadata": {
  		"count": "1",
      "sort": {},
      "skip": "0",
      "limit": "50"
  }, 
	"payload": [{
      "_id": "63dd2f6134fb03000831b475",
      "changes_metadata": {
        "status_changed_to_quotes_available": "2023-02-03T16:00:53.972Z"
      },
      "created_at": "2023-02-03T15:59:29.208Z",
      "product": "Special D&O Product",
      "status": "QUOTES_AVAILABLE",
      "tax_rate": 0.19,
      "updated_at": "2023-02-03T16:00:53.990Z",
      "line_of_business": {
        "_id": "8qjpJ2RE6AHhMiksB",
        "name": "Cyber Versicherung"
      },
      "customer": {
        "_id": "63da8d4466d10900066b26af",
        "address": {
          "street": "",
          "house_number": "",
          "zip": "zg",
          "city": "",
          "country": "DE"
        },
        "company_id": "63da8d4466d10900066b26af",
        "name": "Ms test test"
      },
      "broker_company": {
        "_id": "COMiDryfjsB8A",
        "address": {
          "street": "C Isaac Albeniz 9 4 28 - La Pineda",
          "house_number": "/",
          "zip": "23455",
          "city": "Vila-seca",
          "country": "DE"
        },
        "company_id": "COMiDryfjsB8A",
        "email": "[email protected]",
        "name": "Broker Q"
      },
      "person_in_charge": {
        "_id": "ACCjIBsnvffox",
        "account_id": "ACCjIBsnvffox",
        "email": "[email protected]",
        "first_name": "Broker",
        "last_name": "Q1",
        "salutation": "Mrs"
      }
  }]
}

Open Tenders

Returns the list of tenders which are QUOTES_AVAILABLE, IN_NEGOTIATION, IN_COVERNOTE or REOPENED and are not closed yet

GET https://{environment}/public/v1/tenders/open

Successful Tenders

Returns the list of tenders which are SUCCESSFUL and the contract has been finalised.

GET https://{environment}/public/v1/tenders/successful

🔎

Important Note

Successful tender is in the latest state, Insurer companies should finalise and confirm the policy documentation.

Closed

Returns the list of tenders which are CLOSED and no further action is required.

GET https://{environment}/public/v1/tenders/closed

🔒

Important Note

Closed tenders might be unsuccessful or simply closed by the broker. Further information can't be shared with insurers due to data privacy.



JSON Format

Tenders are represented as JSON objects with the following properties:

NameTypeDescription
productstring
line_of_businessstring
tax_ratenumber
statusstring
customerObject
broker_companyObject
person_in_chargeObject



Tender Status

The tender statuses are as below:

StatusDescription
QUOTES_AVAILABLETender has started and offers are generated shared with the customer.
IN_NEGOTIATIONBroker has started negotiation with Insurer.
IN_COVERNOTEBroker has requested order to cover.
SUCCESSFULTender has been successful and contract is created.
CLOSEDTender has been unsuccessful.
REOPENEDTender has been re-opened.



Tender Customer Details

The customer property contains the name and address of the customer who is the subject of the tender request. Broker has created the tender request on behalf of the specified customer.

Tender Product and Line of business

Property product has the name of the insurance product that broker is requesting the tender. Each product belongs to a certain line of business (e.g. Cyber, D&O) which is accessible via line_of_business property.

Tender Broker and Person in charge

Every tender has a broker_company and person_in_charge. The broker company is the actual broker who on behalf of the customer is requesting insurers. For most cases, the broker is request the customer to fill in the risk assessment but in some cases, broker decides to fill in the questionnaire on behalf of customer.

The person in charge is the user who created a tender request. By default, the person in charge of a tender request is the submitter submitter of the request when interacting with Finlex Platform. 

{
            "_id": "63dd2f6134fb03000831b475",
            "changes_metadata": {
                "status_changed_to_quotes_available": "2023-02-03T16:00:53.972Z"
            },
            "created_at": "2023-02-03T15:59:29.208Z",
            "product": "Special D&O Product",
            "status": "QUOTES_AVAILABLE",
            "tax_rate": 0.19,
            "updated_at": "2023-02-03T16:00:53.990Z",
            "line_of_business": {
                "_id": "8qjpJ2RE6AHhMiksB",
                "name": "Cyber Versicherung"
            },
            "customer": {
                "_id": "63da8d4466d10900066b26af",
                "address": {
                    "street": "",
                    "house_number": "",
                    "zip": "zg",
                    "city": "",
                    "country": "DE"
                },
                "company_id": "63da8d4466d10900066b26af",
                "name": "Ms test test"
            },
            "broker_company": {
                "_id": "COMiDryfjsB8A",
                "address": {
                    "street": "C Isaac Albeniz 9 4 28 - La Pineda",
                    "house_number": "/",
                    "zip": "23455",
                    "city": "Vila-seca",
                    "country": "DE"
                },
                "company_id": "COMiDryfjsB8A",
                "email": "[email protected]",
                "name": "Broker Q"
            },
            "person_in_charge": {
                "_id": "ACCjIBsnvffox",
                "account_id": "ACCjIBsnvffox",
                "email": "[email protected]",
                "first_name": "Broker",
                "last_name": "Q1",
                "salutation": "Mrs"
            }
}

Insurer Offering Integration

The Finlex platform facilitates seamless integration with insurer platforms, enabling insurers to directly generate and prepare offers within their own systems. These offers are then aggregated into the Finlex proposal overview, where brokers can conveniently view, compare offers from multiple insurers, and subsequently submit their orders to cover.

Below are the detailed steps required for integration:

1. Secure Communication with JWT Access Tokens

To securely communicate with Finlex APIs, obtain a JWT access token using your provided credentials.

Endpoint

POST https://auth.finlex.io/token

Request Payload

{
  "app_id": "your_app_id",
  "secret": "your_secret_key",
  "expiry": "2032-05-08T10:49:37.326809761Z"
}

Response

{
  "access_token": "generated_jwt_token",
  "expiry": "2032-05-08T10:49:37.326809761Z"
}

Usage

Include the JWT token in the Authorization header with each subsequent API request:

GET /your-endpoint HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

Note: more information on access token here

2. Quotation Request Endpoint

To allow Finlex to submit quotation requests to your system, create a dedicated endpoint.

Endpoint

POST {base_url}/quotes

Request Payload Example

{
  "limits": [
    {"insurance_sum": 2000000, "deductible": 500},
    {"insurance_sum": 2000000, "deductible": 100},
    {"insurance_sum": 250000000, "deductible": 500}
  ],
  "risk_information": {
    "turnover": {"amount": 30000000, "currency": "eur"},
    "type_of_business": "Insurance",
		"website_url": "http://...",
		"customer_name": "customer company name"
  }
}

Note: The available risk information may vary depending on the specific insurance product.

Response

Your system should respond immediately with:

{
  "id": "quote_request_id_generated_by_your_system",
  "status": "PROCESSING"
}

3. Webhook Notification (Callback)

Once the quotation processing is complete, notify Finlex via webhook.

Endpoint

POST https://api.finlex.io/aggregation-gateway/v1/public/producer-integration/quotes/available

Request Payload

{
  "quote_request_id": "quote_request_id_generated_by_your_system"
}

4. Fetch Generated Quote

Finlex retrieves the generated quote using the provided ID via a dedicated endpoint.

Endpoint

GET {base_url}/quotes/{id}

Response Example

{
  "id": "quote_request_id_generated_by_your_system",
  "quote_options": [
    {"insurance_sum": 1000000, "deductible": 600, "premium": 180},
    {"insurance_sum": 10000000, "deductible": 400, "premium": 200},
    {"insurance_sum": 20000000, "deductible": 300, "premium": 243}
  ]
}

5. Token Revocation

Revoke your JWT token when it is no longer needed to enhance security.

Endpoint

POST https://auth.finlex.io/token-revoke

Request

Empty request payload.

Response

Expect a success acknowledgment:

{
  "status": "revoked"
}

Integration Best Practices

  • Securely store your credentials (app_id, secret_key).
  • Regularly renew your tokens and use short-lived tokens to minimize security risks.
  • Implement error handling and logging for each endpoint.
  • Monitor API calls and webhook invocations for reliable performance and debugging.

This guide provides a structured approach to integrating with the Finlex platform, ensuring secure, efficient, and seamless data exchange for insurance quotation processes.

Updated about 2 months ago