Introduction

The primary method for redirecting to the Thinksurance Platform while concurrently transmitting all essential data is through the usage of the Broker Forward action within the Thinksurance Public API V1, hereafter referred to as "the API." This action, the first of two, facilitates the redirection and data transfer process (the second being the Switch action). The Broker Forward action assumes responsibility for updating or creating data related to the customer, consultation, or inquiry. It subsequently returns a URL directing to a dedicated payload within the Switch action, ultimately guiding partner to their intended final destination.

Endpoint

To initiate the Broker Forward action, it is imperative to dispatch an HTTP POST request to the endpoint /api/broker/fwd/{:token}. The parameterised segment of the endpoint, denoted as "{:token}," pertains to the security token retrievable by the partner during the Authentication process on the API.

Action name

broker forward

HTTP path

/api/broker/fwd/{:token}

token - a security token retrieved from Authentication

HTTP method

POST

Attributes of the HTTP request

Broker Parameters

The initial set of parameters pertains to broker data. Only specific elements within this data subset are mandatory for delivery. These required elements assist the API in accurately mapping the request to the designated broker. If supplementary data for the broker is provided, the mapped broker information will be updated accordingly.

type	int	required	Enumeration value that defines the way for mapping broker data from the request: 1 - it requires to have broker’s ID from the partner system provided to Thinksurance System 2 - it doesn’t requires to have broker’s ID from the partner system provided to Thinksurance System
bToken	string	required	A special token used for brokers to identify itself during API calls. Provided by Thinksurance Support Team.
bExternalId	string	required	Broker’s ID from the partner system.
bGender	int	optional	Enumeration value that defines salutation of the broker person: 1 - Mr 2 - Ms
bFirstName	string	optional	Broker person’s first name.
bLastName	string	optional	Broker person’s last name.
bEmail	string	optional	Broker person’s email address.
bCompany	string	optional	Broker company’s name.
bStreet	string	optional	Broker company’s street name.
bStreetNumber	string	optional	Broker company’s street number.
bZip	string	optional	Broker company’s postcode.
bCity	string	optional	Broker company’s city.
bPhone	string	optional	Broker company’s phone number.
bCompanyRegNumber	string	optional	Broker company’s commercial register number.
bRegNumber	string	optional	Broker company’s IHK register number.

Callback Parameters

All callback parameters are similarly associated with broker data. The provision of these parameters during the request will result in the corresponding values being updated.

Explanations: ¹ required if fullCallback is set to 0 ²required if mvpFullCallback is set to 0
fullCallback	int	optional	Enumeration value that defines if the partner system expects update (a callback) from the API after booking process is done: 0 - the partner system expects to get an update in a form of a callback, once the inquiry passes booking process. 1 - the partner system doesn’t expect any active update from Thinksurance side, but it will use the API to get further information on its own.
callbackUrl	string	optional¹	An endpoint on the partner side that should receive update in a form of callback. It will be used if fullCallback parameter is set to 0.
mvpFullCallback	int	optional	Enumeration value that defines if the partner’s TEST system expects update (a callback) from the API after booking process is done: 0 - the partner’s TEST system expects to get an update in a form of a callback, once the inquiry passes booking process. 1 - the partner’s TEST system doesn’t expect any active update from Thinksurance side, but it will use the API to get further information on its own.
mvpCallbackUrl	string	optional²	An endpoint on the partner’s TEST system side that should receive update in a form of callback. It will be used if mvpFullCallback parameter is set to 0.

Customer Parameters

The following parameters belong to the customer and serve the purpose of updating or creating a customer, contingent upon whether their external ID (an identifier from the partner's system) is already recognized within the Thinksurance platform.

Explanations: ¹ required if instantInquiryCreation is set to True ² required if cExternalId is set ³ required if cExternalReferences is not empty array
cExternalId	string	optional¹	Unique customer’s ID in the partners system.
cSalutation	int	optional	Enumeration value that defines salutation of the customer person: 1 - Mr 2 - Ms
cFirstName	string	optional	Customer person’s first name.
cLastName	string	optional²	Customer person’s last name.
cBirthDate	string	optional	Customer person’s date of birth. MySQL format for date: {{ YYYY-MM-DD }}
cEmail	string	optional²	Customer person’s email address.
cStreet	string	optional	Customer person’s street name.
cStreetNumber	string	optional	Customer person’s street number.
cZip	string	optional	Customer person’s postcode.
cCity	string	optional	Customer person’s city.
cWebsite	string	optional	Customer person’s website.
cPhone	string	optional	Customer person’s phone number.
cPrivateIsCompanyAddress	int	optional	Enumeration value that defines if customer person’s address should be used as actual business address for the customer: 0 - no, use address from cCompany section 1 - yes
cCompany	string	optional	Customer company’s name.
cLegalForm	int	optional	Enumeration value that defines legal form of the customer’s business: 1 - AG 2 - Einzelunternehmen 3 - GbR 4 - GmbH 5 - GmbH & Co KG 6 - KG 7 - Ltd. 8 - OHG 9 - UG (haftungsbeschränkt) 10 - Other
cCompanyStreet	string	optional	Customer business address street name.
cCompanyStreetNumber	string	optional	Customer business address street number.
cCompanyZip	string	optional	Customer business address postcode.
cCompanyCity	string	optional	Customer business address city.
cBankIban	string	optional	IBAN of the customer business bank details.
cBankBic	string	optional	BIC of the customer business bank details.
cBankName	string	optional	Bank name of the customer business bank details.
cBankAccountHolder	string	optional	Bank account holder name of the customer business bank details.
cAccountType	int	optional	Enumeration value that defines if customer is private entity or corporate: 0 - corporate 1 - private entity
cExternalReferences	array	optional	An array of objects, containing custom values requested to properly identify the customer on the partners system, for example CRM tool.
crmIdent	string	optional³	Enumeration value that defines the CRM tool (Customer Relationship Management), that owns original data of the customer: openVIVAv1 - CRM tool provided by mb Support GmbH

Inquiry Parameters

The parameters below define the data requisite for creating a consultation and inquiry. Combinations for one or both of these entities, as well as the specific time of creation, may vary, and further details are expounded upon in the document, particularly within the context of the redirect URL outcome.

Explanations: ¹ available only if type is set to 1 ² required if instantInquiryCreation is set to True
instantInquiryCreation	string	optional¹	Enumeration value that defines if a new inquiry should be created on Thinksurance Platform during Broker Forward. In case both productId and professionId are present, inquiry will be created during later, Switch action. True - new inquiry will be created if further validation rules are met (see bellow). False - skip creation.
productId	int	optional²	An identifier for the product on Thinksurance Platform. All values are visible from the API endpoint Get Products.
professionId	int	optional²	An identifier for the profession on Thinksurance Platform. All values are visible from the API endpoint Get Professions.
iExternalReferences	array	optional	An array of objects, containing custom values requested to properly identify the entity on the partners system related to the inquiry.

External References definition

This section contains the structure of the ExternalReferences object. This object serves the purpose of storing supplementary identifiers from the partner system for both the customer and inquiry. The structural design of these objects facilitates the creation of new references, updating existing ones, or deleting those deemed necessary.

origin

string

required

Enumeration value that defines to source of the external reference attached to either customer or inquiry:

crm - general CRM tool
broker_crm - CRM tool from the broker side
insurer - a tool provided by the insurer

paramKey

string

required

An unique name of the attribute that holds a value from the CRM tool.

paramValue

string

optional¹

A concrete value of the attribute from the CRM tool.

Explanations:

¹ if set to empty string, the record with same origin and paramKey will be deleted on Thinksurance side

Questionnaire Parameters

Within this section, a data structure for the questionnaire is presented. Upon transmission from the partner system, this data will be used to pre-fill a questionnaire assigned to the inquiry. In the event that an inquiry is not created, the data will be omitted.

Questionnaire Scheme
qasCustProfile	object	optional	A root object that holds information on questionnaire items. Check Questionnaire Scheme bellow.
source	string	required	Enumeration value that defines to source of the data provided for questionnaire: crm - the partner system’s CRM tool
categories	array	required	An array of objects containing clusters of questions merged into categories. Each object is defined by Questionnaire Category Scheme bellow.
Questionnaire Category Scheme
id	string	required	A numeric identifier for the questionnaire “object”category or “default” for non-object categories on Thinksurance Platform.
questions	array	required	An array of objects containing concrete combinations of questions and answers. Each object is defined by Questionnaire Question Scheme bellow.
Questionnaire Question Scheme
id	string	required	An identifier for the questionnaire question on Thinksurance Platform. It can be question ID or Tag.
answers	array	required	It is an array of strings. Each value can point either to a concrete textual answer to an open question or to an identifier for the questionnaire answer on Thinksurance Platform.

Attributes of the HTTP response

Based on the outcome of the HTTP request, the API has the capability to yield varying responses, both in successful and failed states. To comprehend the structure of these responses, the outputs are described in this section.

Success response
url	string	required	It is a redirect URL that partner system should use to redirect the user of their platform to Thinksurance system. It points to the Switch action. Its final destination is predetermined by the data provided from the partner system in Broker Forward HTTP request (check the table bellow).
inquiryId	int	optional¹	It is an unique identifier for the created inquiry.
inquiryHash	string	optional¹	It is a hashed unique identifier for the created inquiry.
Failed response
error	string	required	It contains a reason for the failed request.
Explanations: ¹ expected to be present in the response if instantInquiryCreation is set to True

Redirect URL outcomes

The underlying operation and the ultimate destination of the final redirect URL during the Switch action can vary based on the data provided to the API. The comprehensive list of all potential outcomes of the Broker Forward action is presented below. It is noteworthy that some outcomes are happening upon the complete execution of the Switch action as well.

bToken	cExternalId	professionId	productId	instantInquiryCreation	qasCustProfile	Result
						Error message will be returned.
						On Switch action: Redirect URL points to dashboard on Advisory Suite or landing page of Consult Direct.
						On Switch action: Redirect URL points to Customer information page on Advisory Suite or landing page of Consult Direct. Customer is created or updated.
						On Switch action: Redirect URL points to dashboard on Advisory Suite or landing page of Consult Direct. Product is ignored.
						On Switch action: Redirect URL points to Customer information page on Advisory Suite or landing page of Consult Direct. Customer is created or updated. Product is ignored.
						On Switch action: Redirect URL points to the product page on Advisory Suite or product page of Consult Direct. Consultation is created for the provided profession.
						On Switch action: Redirect URL points to the product page on Advisory Suite or product page of Consult Direct. Consultation is created for the provided profession. Customer is created or updated. Customer is attached for the consultation.
						On Switch action: Redirect URL points to the consultation overview page on Advisory Suite or product page of Consult Direct. On Switch action: Consultation is created for the provided profession. On Switch action: Inquiry is created for the provided product and created consultation.
						On Switch action: Redirect URL points to the consultation overview page on Advisory Suite or product page of Consult Direct. On Switch action: Consultation is created for the provided profession. Customer is created or updated. On Switch action: Customer is attached for the consultation. On Switch action: Inquiry is created for the provided product and created consultation.
						On Switch action: Redirect URL points to the consultation overview page on Advisory Suite or product page of Consult Direct. On Switch action: Consultation is created for the provided profession. Customer is created or updated. On Switch action: Customer is attached for the consultation. On Switch action: Inquiry is created for the provided product and created consultation. On Switch action: Some questions from questionnaire are pre-populated.
						Error message will be returned.
						Error message will be returned.
						Error message will be returned.
						On Switch action: Redirect URL points to the consultation overview page on Advisory Suite or questionnaire page of Consult Direct. Consultation is created for the provided profession. Customer is created or updated. Customer is attached for the consultation. Inquiry is created for the provided product and created consultation.
						On Switch action: Redirect URL points to the consultation overview page on Advisory Suite or questionnaire page of Consult Direct. Consultation is created for the provided profession. Customer is created or updated. Customer is attached for the consultation. Inquiry is created for the provided product and created consultation. Some questions from questionnaire are pre-populated.

Examples

As previously stated, to execute Broker Forward, it is imperative to dispatch a POST HTTP request to the /api/broker/fwd/{:token} endpoint of the API. Below, instances of potential communication between the API and consumers are provided.

HTTP Request with only broker details

# HTTP POST
# /api/broker/fwd/{:token}
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "type": 1,
  "bToken": "someBroketAPIToken",
  "bExternalId": "someExternalId"
}
# Expected:
# 1. Redirect URL points to dashboard on Advisory Suite or 
#    landing page of Consult Direct.

HTTP Request with update for broker data

# HTTP POST
# /api/broker/fwd/{:token}
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "type": 1,
  "bToken": "someBroketAPIToken",
  "bExternalId": "someExternalId",
  "bFirstName": "Max",
  "bLastName": "Mustermann",
  "bEmail": "max.mustermann@awesome.company.de",
  "bCompany": "Awesome Company"
}
# Expected:
# 1. Redirect URL points to dashboard on Advisory Suite or 
#    landing page of Consult Direct.
# 2. Broker data is updated

HTTP Request with created or updated customer

# HTTP POST
# /api/broker/fwd/{:token}
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "type": 1,
  "bToken": "someBroketAPIToken",
  "bExternalId": "someExternalId",
  "cFirstName": "Max",
  "cLastName": "Mustermann",
  "cExternalId": "someCustomerId",
  "cEmail": "customer@gmail.com",
  "cExternalReferences": [
    {
      "origin": "crm",
      "paramKey": "AccountNumber",
      "paramValue": "1233436547564erf5434"
    }
  ],
  "crmIdent": "openVIVAv1"
}
# Expected:
# 1. Redirect URL points to Customer information page on Advisory Suite or 
#    landing page of Consult Direct.
# 2. Customer is either created or updated if the customer with
#    the same external id exists.

HTTP Request with created or updated customer and created inquiry

# HTTP POST
# /api/broker/fwd/{:token}
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "type": 1,
  "bToken": "someBroketAPIToken",
  "bExternalId": "someExternalId",
  "cFirstName": "Max",
  "cLastName": "Mustermann",
  "cExternalId": "someCustomerId",
  "cEmail": "customer@gmail.com",
  "cExternalReferences": [
    {
      "origin": "crm",
      "paramKey": "AccountNumber",
      "paramValue": "1233436547564erf5434"
    }
  ],
  "crmIdent": "openVIVAv1",
  "professionId": 253,
  "productId": 95,
  "instantInquiryCreation": true
}
# Expected:
# 1. Redirect URL points to the consultation overview on Advisory Suite 
#    or questionnaire page of Consult Direct.
# 2. Consultation is created for the provided profession.
# 3. Customer is created or updated.
# 4. Customer is attached for the consultation.
# 5. Inquiry is created for the provided product and created consultation.

HTTP Request with created or updated customer, created inquiry and questionnaire pre-populated

# HTTP POST
# /api/broker/fwd/{:token}
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "type": 1,
  "bToken": "someBroketAPIToken",
  "bExternalId": "someExternalId",
  "cFirstName": "Max",
  "cLastName": "Mustermann",
  "cExternalId": "someCustomerId",
  "cEmail": "customer@gmail.com",
  "cExternalReferences": [
    {
      "origin": "crm",
      "paramKey": "AccountNumber",
      "paramValue": "1233436547564erf5434"
    }
  ],
  "crmIdent": "openVIVAv1",
  "professionId": 253,
  "productId": 95,
  "instantInquiryCreation": true,
  "qasCustProfile": { 
    "categories": [
      { 
        "id": "default", 
        "questions": [ 
          { 
            "id": "100"
            "answers": [ "10001" ]
          },
          { 
            "id": "101"
            "answers": [ "10011" ]
          },
          { 
            "id": "customer.fullname"
            "answers": [ "Max Mustermann" ]
          }
        ]
      },
      { 
        "id": "2", 
        "questions": [ 
          { 
            "id": "200"
            "answers": [ "20001", "20007" ]
          },
          { 
            "id": "201"
            "answers": [ "10000 eur" ]
          }
        ]
      }
    ]
  }
}
# Expected:
# 1. Redirect URL points to the consultation overview on Advisory Suite 
#    or questionnaire page of Consult Direct.
# 2. Consultation is created for the provided profession.
# 3. Customer is created or updated.
# 4. Customer is attached for the consultation.
# 5. Inquiry is created for the provided product and created consultation.
# 6. Some questions from questionnaire are pre-populated.

Successful HTTP Response without created inquiry

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "url": "https://app.thinksurance.de/api/broker/switch/abcdef1234567890"
}

Successful HTTP Response with created inquiry

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "url": "https://app.thinksurance.de/api/broker/switch/abcdef1234567890",
  "inquiryId": 12345,
  "inquiryHash": "a1b2c3d4e5f6"
}

Failed HTTP Response

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "error": "BrokerAPI: Invalid parameters"
}

Sequence diagram

Within this section, a concise sequence diagram illustrates the procedure of the Broker Forward action. The comprehensive process of transitioning from one point to another is detailed within the Switch action.