V1.1 Broker Forward

Owned by Marko Milojevic
Last updated: Nov 12, 2024 by Cedric Daunke
11 min read

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/ipn/brokers/forward.

Action name

broker forward

HTTP path

/api/ipn/brokers/forward

HTTP method

POST

Attributes of the HTTP request

HTTP Request Header

HTTP Request Header

Authorization

string

required

A security token provided from Authentication endpoint.
Required to provide as a Bearer Token (in format: “Bearer {{token}}“).

X-Broker-Token

string

required

An unique identifier of the broker.

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”

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

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

optional1

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

optional2

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.

Explanations:

1 required if fullCallback is set to 0
2 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

optional1

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

optional2

Customer person’s last name.

cBirthDate

string

optional

Customer person’s date of birth.
MySQL format for date: {{ YYYY-MM-DD }}

cEmail

string

optional2

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

optional3

Enumeration value that defines the CRM tool (Customer Relationship Management), that owns original data of the customer:

Explanations:

1 required if instantInquiryCreation is set to True
2 required if cExternalId is set
3 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

optional1

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

optional2

An identifier for the product on Thinksurance Platform. All values are visible from the API endpoint Get Products.

professionId

int

optional2

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.

Explanations:

1 available only if type is set to 1
2 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

optional1

A concrete value of the attribute from the CRM tool.

Explanations:

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

qasCustProfile

object

optional

A root object that holds information on questionnaire items. Check Questionnaire Scheme bellow.

Questionnaire Scheme

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

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

optional1

It is an unique identifier for the created inquiry.

inquiryHash

string

optional1

It is a hashed unique identifier for the created inquiry.

Failed response

error

string

required

It contains a reason for the failed request.

Explanations:

1 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

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/ipn/brokers/forward endpoint of the API. Below, instances of potential communication between the API and consumers are provided.

HTTP Request with only broker details

# HTTP POST # https://ipn.dev.thinksurance.de/api/ipn/brokers/forward # 'Content-Type': 'application/json' # 'Accept': 'application/json' # 'Authorization': 'Bearer <some long string value>' # 'X-Broker-Token': '<some hash>' { "type": 1, "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 # https://ipn.dev.thinksurance.de/api/ipn/brokers/forward # 'Content-Type': 'application/json' # 'Accept': 'application/json' # 'Authorization': 'Bearer <some long string value>' # 'X-Broker-Token': '<some hash>' { "type": 1, "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 # https://ipn.dev.thinksurance.de/api/ipn/brokers/forward # 'Content-Type': 'application/json' # 'Accept': 'application/json' # 'Authorization': 'Bearer <some long string value>' # 'X-Broker-Token': '<some hash>' { "type": 1, "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 Request with created or updated customer, created inquiry and questionnaire pre-populated

Successful HTTP Response without created inquiry

Successful HTTP Response with created inquiry

Failed HTTP Response

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.