Table of Contents

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.

...

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.

...

Table of Contents

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.

Notice:

Please use the correct format for email adresses. Don’t use spacings or special characters in the email.

False: “ exampleMail@mailProvider.com;”

Correct: “exampleMail@mailProvider.com”

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.

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.

Anchor

	callback
	callback

Explanations:

¹ required if fullCallback is set to 0
²required if mvpFullCallback 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.

cExternalId	string	optional¹	Unique customer’s ID in the partners system.
cSalutation	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

salutation of the customer person:

1 - Mr
2 - Ms

cFirstName

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.

AnchorcallbackcallbackExplanations:

¹ required if fullCallback is set to 0
²required if mvpFullCallback 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.

cSalutation

cExternalId

string

optional¹

Unique customer’s ID in the partners system.

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.

cTitle

int

optional

cEmail

string

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 }}

Customer person’s email addresscustomer’s title:

1 - Dr.

2 - Prof.

3 - Prof. Dr.

4 - B.A.

5 - MBA

6 - Ph.D.

7 - Mag.

8 - Dipl.-Ing.

9 - Dipl.-Inf.

10 - Dr. med.

11 - Dr.-Ing.

12 - Dipl.-Psych.

13 - Priv.-doz.

14 - Dr. Dr.

15 - M.A.

16 - Priv.-doz. Dr.

17 - Bachelor

18 - Master

19 - Dipl.-Wirt.-Ing.

20 - Dipl.-Wirt.-Inf.

21 - Dipl.-Betriebswirt

22 - Dr.med.dent

23 - Dr. jur.

24 - Dipl.-Med.

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

Anchor

	customer
	customer

Explanations:

¹ required if instantInquiryCreation is set to True
² required if cExternalId is set
³ required if cExternalReferences is not empty array

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.

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

Anchor

	inquiry
	inquiry

Explanations:

¹ available only if type is set to 1
² required if instantInquiryCreation is set to True

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.

Anchor

	references
	references

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	An A numeric identifier for the questionnaire category “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.

Anchor

	response
	response

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 dashboard 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. Profession Product is ignored.
						On Switch action: Redirect URL points to dashboard 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 new consultation 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 new consultation 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 new 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 new 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 new 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

Code Block

language	json

# HTTP POST
# 
# https://app.dev.thinksurance.de/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

Code Block

language	json

# HTTP POST
# https://app.dev.thinksurance.de/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

Code Block

language	json

# HTTP POST
# https://app.dev.thinksurance.de/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 dashboardCustomer 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

Code Block

language	json

# HTTP POST
# https://app.dev.thinksurance.de/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"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

Code Block

language	json

# HTTP POST
# https://app.dev.thinksurance.de/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"true,
  "qasCustProfile": { 
    "categories": [
      { 
        "id": "1default", 
        "questions": [ 
          { 
            "id": "100",
            "answers": [ "10001" ]
          },
          { 
            "id": "101",
            "answers": [ "10011" ]
          },
          { 
            "id": "100customer.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

Code Block

language	json

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

Successful HTTP Response with created inquiry

Code Block

language	json

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

Failed HTTP Response

Code Block

language	json

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

Drawio

mVer	2
zoom	1
simple	0
inComment	0
custContentId	3177709667
pageId	3174203411
lbox	1
diagramDisplayName	Untitled Diagram-1706778887171.drawio
contentVer	1
revision	1
baseUrl	https://thinksurance.atlassian.net/wiki
diagramName	Untitled Diagram-1706778887171.drawio
pCenter	0
width	391
links
tbstyle
height	481

Versions Compared

Old Version 26

New Version Current

Key

Introduction

Endpoint

Attributes of the HTTP request

Broker Parameters

Callback Parameters

Introduction

Endpoint

Attributes of the HTTP request

Broker Parameters

Callback Parameters

Customer Parameters

Customer Parameters

Inquiry Parameters

External References definition

Questionnaire Parameters

Attributes of the HTTP response

Redirect URL outcomes

Examples

Sequence diagram

Page Comparison

Versions Compared

Old Version 26

New Version Current

Key

Introduction

Endpoint

Attributes of the HTTP request

Broker Parameters

Callback Parameters

Introduction

Endpoint

Attributes of the HTTP request

Broker Parameters

Callback Parameters

Customer Parameters

Customer Parameters

Inquiry Parameters

External References definition

Questionnaire Parameters

Attributes of the HTTP response

Redirect URL outcomes

Examples

Sequence diagram