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 addressthe customer’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

...

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

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
}
# 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,
  "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

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

...

Versions Compared

Old Version 34

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

Page Comparison

Versions Compared

Old Version 34

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