...

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 identifier for the questionnaire category 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.
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

...

url

...

string

...

required

...

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

...

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 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 is ignored.
						On Switch action: Redirect URL points to dashboard 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 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 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 page on Advisory Suite or product page of Consult Direct. 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 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 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 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 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.

...

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
# /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
# /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
# /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 dashboard 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
# /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

Code Block

language	json

# 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": "1", 
        "questions": [ 
          { 
            "id": "100"
            "answers": [ "10001" ]
          },
          { 
            "id": "101"
            "answers": [ "10011" ]
          },
          { 
            "id": "100"
            "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 25

New Version 26

Key

Questionnaire Parameters

Attributes of the HTTP response

Redirect URL outcomes

Examples

Sequence diagram

Page Comparison

Versions Compared

Old Version 25

New Version 26

Key

Questionnaire Parameters

Attributes of the HTTP response

Redirect URL outcomes

Examples

Sequence diagram