Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Introduction

To obtain the payload of multiple inquiries, belonging to one single broker, the Thinksurance Public API V2, denoted as "the API," offers a specialised endpoint. This endpoint allows consumers to retrieve all relevant inquiry information

Endpoint

To search for a list of inquiries belonging to the specific broker, consumers should send a HTTP POST GET request to endpoint /api/ipn/get/{:token}. The token parameter represents the security token acquired during the Authentication process on the API (see V1 Authentication). inquiries. As essential components of the JSON payload within the body of the request, consumers are required to include bToken (functioning as the broker identifier).

Action name

search inquiries

HTTP path

/api/ipn/get/{:token}

inquiries

HTTP method

POSTGET

Attributes of the HTTP request

HTTP Request Header

bToken

Authorization

string

required

An unique identifier

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

X-Broker-Token

string

optional1

An unique identifier of the broker.

iId

X-Account-Token

string

optional1

An unique identifier of

an inquiry

the account.

...

HTTP

...

JSON dictionary of key-value pairs. Each key is an

GET parameters

Success response

inquiryId

int

optional

An unique identifier of

an inquiry and value represents a concrete item with all inquiry related data. To understand the item data, check Item Scheme below.

Item Scheme

 sHash

string

required

Security check, if request comes from THINKSURANCE API (see “Security hash generation”)

data

object

required

A root object that holds information on inquiry items. Check Inquiry Scheme bellow.

customer

object

optional

A root object that holds information on customer items. Check Customer Scheme bellow.

docs

array

optional

A root object that holds a list of document metadata items Check Document Scheme bellow.

Inquiry Scheme Anchorinquiryinquiry

bToken

string

required

Broker specific token in THINKSURANCE system

bExternalId

string

required

Partner’s internal ID for this Broker

iId

int

required

Inquiry ID in THINKSURANCE system

iCreated

string

required

Date of creation of inquiry

iUpdated

string

required

Date of update of inquiry

productName

string

optional

A product’s name on Thinksurance System.

productId

int

optional

A product’s unique identifier on Thinksurance System.

industryId

int

optional

An industry’s unique identifier on Thinksurance System.

professionName

string

optional

 A profession’s name on Thinksurance System.

professionId

int

optional

 A profession’s unique identifier on Thinksurance System.

status

int

required

Enumeration value that defines the status of an inquiry. Possible values:

  • 2 - tendering (lead)

  • 3 - tendering

  • 4 - calculated

  • 6 - ordered

  • 15 - proposal created

employees

object

optional

A root object that contains information on employees in the insured company. Check Employee Scheme bellow.

revenue

string2

optional

Revenue given in Thinksurance Risk Assessment questionnaire.

bFoundDate

string

optional

Founding date of the broker’s company.
MySQL format for date: {{ YYYY-MM-DD }}

taxPercent

int

optional1

Revenue given in Thinksurance Risk Assessment questionnaire.

contractStartDate

string

optional1

The starting date of the contract start date.
MySQL format for date: {{ YYYY-MM-DD }}

contractPayDate

string

optional1

The contract’s payment date.
MySQL format for date: {{ YYYY-MM-DD }}

insuranceCompanyName

string

optional

Insurance company name selected by Customer/Partner

insuranceCompanyId

int

optional

Insurance company unique identifier on Thinksurance system.

coverage

int23

optional

Coverage amount for specific insurance company.

deductible

int2

optional

Deductible for specific insurance company

premiumYearly

int4

optional1

Yearly gross premium.

contractDuration

int

optional1

Contract period in years.

paymentInterval

int

optional1

Enumeration value that defines the payment interval in months. Possible values:

  • 1 - paid monthly

  • 3 - paid quarterly

  • 6 - paid half yearly

  • 12 - paid yearly

Employee Scheme Anchoremployeeemployee

full

string

optional

Number of full time employees given in Thinksurance Risk Assessment questionnaire.

part

string

optional

Number of part time employees given in Thinksurance Risk Assessment questionnaire.

Customer Scheme Anchorcustomercustomer

cId

int

optional

A customer unique identifier on Thinksurance System.

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.

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.

Document Scheme Anchordocumentdocument

docToken

string

optional5

Holder of a token which allows for access to documents per link. Check Documents Token Scheme bellow.

files

array

optional

List of objects. Every document has it’s own object. Check File Scheme bellow.

Documents Token Scheme Anchortokentoken

token

string

required

Token which allows for access to documents per link.

expired

string

required

Expiration date for document token

File Scheme Anchorfilefile

name

string

required

The name of the file.

fullName

string

required

The name of the file, including file extension.

hash

string

required

An unique identifier of the file.

fullFilePath

string

required

The link for downloading file.

documentPurpose

string

required

Enumeration value that defines the purpose of the file on Thinksurance System:

  • questionnaire

  • communicationModule

  • policyDocument

  • proposalDocument

  • proposalOrderDocument

  • proposalConsultationDocument

  • consultationDocument

  • orderDocument

  • orderCsvDocument

  • manualPolicyDocument

  • riskAssessmentDocument

  • signSummaryDoc

  • sepaDocument

  • inquiryOrderCsv

  • insurer_docs

  • inquiry_docs

  • inquiry_proposal_docs

  • portfolio_docs

  • export_files

  • broker_imgs

  • upload_file

  • pool_docs

  • pool_imgs

  • file_import_template

  • longtext

  • parse-file

  • partner_invoices

  • request_docs

  • proposal_docs

  • ProposalDT

  • DVAG_Bestaetigung

  • DVAG_Beraterexemplar

  • DVAG_Beitragsberechnungsblatt

  • DVAG_Beratungsprotokoll

  • DVAG_Deckungszusage

  • DVAG_Datenexport

  • DVAG Test

  • MarshDaimler_eVB Brief

  • Datenexport_Schunck

  • Mitteilung_zur_Beratungsgrundlage_egv

  • Mitteilung_zur_Beratungsgrundlage_jungFi

  • Mitteilung_zur_Beratungsgrundlage_jungFiPf

  • Mitteilung_zur_Beratungsgrundlage_jungWi

  • Mitteilung_zur_Beratungsgrundlage_jungTr

  • Ausschreibungsdokument

  • dummymailattachement_insurer_only_1

  • dummymailattachement_insurer_only_2

  • dummymailattachement_insurer_only_3

  • dummymailattachement_user_only_1

  • dummymailattachement_user_only_2

  • dummymailattachement_user_only_3

  • dummymailattachement_insurer_user_1

  • dummymailattachement_insurer_user_2

  • dummymailattachement_insurer_user_3

  • dummymailattachement_insurer_user_4

  • dummymailattachement_insurer_user_5

  • dummymailattachement_insurer_user_6

  • dummymailattachement_insurer_user_7

  • dummymailattachement_insurer_user_8

  • dummymailattachement_insurer_user_9

  • dummymailattachement_insurer_user_10

  • dummymailattachement_insurer_user_11

  • dummymailattachement_insurer_user_customer_1

  • others

  • Test

Explanations: Anchorexplanationsexplanations

1 It is not provided for inquiries in the status 2, 3, 4.

2 Value represented in EUR.

3 In some cases (specific products like Firmenrechtsschutz) it could be string(“unbegrenzt”).

4 Value represented in CENTS.

5 Required if there is at least one file in the list.

Failed response

error

string

required

It contains a reason for the failed request.

the inquiry.

lastDays

int

optional

If defined, only inquiries that were created or updated that last number of days, will be included in the result. Otherwise, inquiries created or updated in last three months will be included.

Explanations:

Anchor
request
request

1 at least one of bToken and aToken is required in the payload

Attributes of the HTTP response

See IP Notification Response

Examples

This section shows examples of different HTTP requests and responses associated with the endpoint.

HTTP Request with simple payload

Code Block
languagejson
# HTTP POSTGET
# https://appipn.dev.thinksurance.de/api/ipn/get/<some long hash>
inquiries
#
# HTTP headers
# 'Content-TypeAccept': 'application/json'
# 'AcceptAuthorization': 'application/json'
# 
{
  "bToken": "<some encrypted string>"
}Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>' 
#

HTTP Request with inquiry identifier

Code Block
languagejson
# HTTP POSTGET
# https://appipn.dev.thinksurance.de/api/ipn/get/<some long hash>
inquiries?inquiryId=123456
#
# HTTP headers
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
# 
{
  "bToken": "<some encrypted string>",
  "iId": 123456
}'Authorization': 'Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>'
#

HTTP Request with last days specified

Code Block
languagejson
# HTTP POSTGET
# https://appipn.dev.thinksurance.de/api/ipn/get/<some long hash>inquiries?inquiryId=123456&lastDays=1
#
# HTTP headers
# 'Content-TypeAccept': 'application/json'
# 'AcceptAuthorization': 'application/json'
# 
{
  "bToken": "<some encrypted string>",
  "lastDays": 1 #includes results from today and yesterday
}Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>'
#

Successful HTTP Response

Code Block
languagejson
# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "123456": {
    "sHash": "bf02dfa7c7bc64c2cfb5",
    "data": {
        "bToken": "41ba17f637177a0b34d2ac11d",
        "bExternalId": "1",
        "iId": 1878887,
        "iCreated": "2024-03-06",
        "iUpdated": "2024-03-06",
        "productName": "Cyberversicherung",
        "productId": 95,
        "industryName": "Gastronomie",
        "industryId": 113,
        "professionName": "Cafe",
        "professionId": 258,
        "status": 25,
        "iExternalReferences": [
            {
                "origin": "crm",
                "paramKey": "oV-Angebots-Nr",
                "paramValue": "4342344"
            },
            {
                "origin": "crm",
                "paramKey": "oV-Antrags-Nr",
                "paramValue": "4342344"
            },
            {
                "origin": "crm",
                "paramKey": "oV-Deckungskonzept-ID",
                "paramValue": "11052060"
            },
            {
                "origin": "crm",
                "paramKey": "oV-Vertrag-ID",
                "paramValue": "4342343"
            },
            {
                "origin": "crm",
                "paramKey": "oV-Vertrags-Nr",
                "paramValue": "4342345"
            },
            {
                "origin": "crm",
                "paramKey": "oV-Vertragsart-ID",
                "paramValue": "1021640"
            }
        ],
        "employees": {
            "full": "",
            "part": ""
        },
        "revenue": "",
        "bFoundDate": ""
    },
    "customer": {
        "cId": 520108,
        "cExternalId": "9975",
        "cSalutation": "",
        "cTitle": "",
        "cFirstName": "Testuser",
        "cLastName": "cu",
        "cBirthday": "",
        "cEmail": "cust@mer3.com",
        "cCompany": "",
        "cCompanyForm": "",
        "cStreet": "",
        "cStreetNumber": "",
        "cZip": "",
        "cCity": "",
        "cPhone": "",
        "cWebsite": "",
        "cAccountType": 0,
        "cAddressIsCompany": 1,
        "cCompanyStreet": "",
        "cCompanyStreetNumber": "",
        "cCompanyZip": "",
        "cCompanyCity": "",
        "cExternalReferences": [
            {
                "origin": "crm",
                "paramKey": "oV-Kunden-Nr",
                "paramValue": "12345"
            },
            {
                "origin": "crm",
                "paramKey": "oV-Partner-Nr",
                "paramValue": "12345"
            }
        ]
    },
    "docs": {
        "docToken": {
            "token": "<some long hash>",
            "expired": "2024-03-19 09:42:10"
        },
        "files": [
            {
                "name": "dummy_file",
                "fullName": "dummy_file.pdf",
                "hash": "<some hash>",
                "fullFilePath": "<some link>",
                "documentPurpose": "insurer_docs"
            },
            {
                "name": "dummy_document",
                "fullName": "dummy_document.pdf",
                "hash": "<some hash>",
                "fullFilePath": "<some link>",
                "documentPurpose": "upload_file"
            },
            {
                "name": "2090065_Beratungsdokumentation_Betriebshaftpflicht",
                "fullName": "2090065_Beratungsdokumentation_Betriebshaftpflicht.pdf",
                "hash": "<some hash>",
                "fullFilePath": "<some link>",
                "documentPurpose": "consultationDocument"
            },
            {
                "name": "2090065_Deckungsauftrag_Betriebshaftpflicht",
                "fullName": "2090065_Deckungsauftrag_Betriebshaftpflicht.pdf",
                "hash": "<some hash>",
                "fullFilePath": "<some link>",
                "documentPurpose": "orderDocument"
            }
        ]
     }
  }
}

Failed HTTP Response

Code Block
languagejson
# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "error": "API User is not existing or deactivated."
}