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 GET request to endpoint /api/ipn/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/inquiries
HTTP method	GET

Attributes of the HTTP request

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	optional¹	An unique identifier of the broker.
X-Account-Token	string	optional¹	An unique identifier of the account.
HTTP GET parameters
inquiryId	int	optional	An unique identifier of 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: ¹ at least one of bToken and aToken is required in the payload

Attributes of the HTTP response

Success response
JSON dictionary of key-value pairs. Each key is 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
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	string²	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	optional¹	Revenue given in Thinksurance Risk Assessment questionnaire.
contractStartDate	string	optional¹	The starting date of the contract start date. MySQL format for date: {{ YYYY-MM-DD }}
contractPayDate	string	optional¹	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	int²³	optional	Coverage amount for specific insurance company.
deductible	int²	optional	Deductible for specific insurance company
premiumYearly	int⁴	optional¹	Yearly gross premium.
contractDuration	int	optional¹	Contract period in years.
paymentInterval	int	optional¹	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
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
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
docToken	string	optional⁵	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
token	string	required	Token which allows for access to documents per link.
expired	string	required	Expiration date for document token
File Scheme
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: ¹ It is not provided for inquiries in the status 2, 3, 4. ² Value represented in EUR. ³ In some cases (specific products like Firmenrechtsschutz) it could be string(“unbegrenzt”). ⁴ Value represented in CENTS. ⁵ Required if there is at least one file in the list.

Failed response
error	string	required	It contains a reason for the failed request.

Examples

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

HTTP Request with simple payload

# HTTP GET
# https://ipn.dev.thinksurance.de/api/ipn/inquiries
#
# HTTP headers
# 'Accept': 'application/json'
# 'Authorization': 'Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>' 
#

HTTP Request with inquiry identifier

# HTTP GET
# https://ipn.dev.thinksurance.de/api/ipn/inquiries?inquiryId=123456
#
# HTTP headers
# 'Accept': 'application/json'
# 'Authorization': 'Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>'
#

HTTP Request with last days specified

# HTTP GET
# https://ipn.dev.thinksurance.de/api/ipn/inquiries?inquiryId=123456&lastDays=1
#
# HTTP headers
# 'Accept': 'application/json'
# 'Authorization': 'Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>'
#

Successful HTTP Response

# 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

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

V1.1 Search Inquiries

Introduction

Endpoint

Attributes of the HTTP request

Attributes of the HTTP response

Examples