Table of Contents

Introduction

When there is a need to add a agency number for an account within a specific account via the Thinksurance Public API V1, from now on referred to as "the API," a dedicated endpoint facilitates this capability. This endpoint is accessible at the path /api/broker/set/anums/. It anticipates a comprehensive payload as part of the HTTP request, encompassing the requisite account data.

Endpoint

To add a new agency number via the API, it is necessary to send an HTTP POST request to the endpoint /api/broker/set/anums/{:token}. The parameterised segment of the endpoint, denoted as "{:token}," contains the security token retrievable by the partner during the Authentication process on the API. The rest of the HTTP request is a JSON payload of the request body.

Action name

add agency number for broker

HTTP path

/api/broker/set/anums/{:token}

token - a security token retrieved from Authentication

HTTP method

POST

Attributes of the HTTP request

baFinRegNrinsurerIdagencyNumbermatchCodeexternalInsurerId

bToken

string

required

A special token used for broker to identify itself during API calls. Provided by Thinksurance Support Team.

token

string

required

A security token provided from Authentication endpoint.

agencyNumberSets

array

required

An array that holds information on all agency numbers that should be added. Each item of the array is represented by Agency Number Holder Scheme bellow.

Agency Number Holder Scheme

Anchor

	holder
	holder

baFinId

string

optional¹required

An insurer’s BaFin registration number.

e2e

stringarray

optional¹

An insurer’s unique identifier number.

supervisingAuthorityId

string

optional¹

An insurer’s BaFin ID or the “Vermittlerregister” ID for MGAs

agencyNumbers

array

requiredarray that holds information on all agency numbers that should be added for one insurer, that should be used with deals made by calculation. Each item of the array is represented by Agency Number Scheme bellow.

db

array

optional²

An array that holds information on all agency numbers that should be added for one insurer, that should be used with deals made in tendering process. Each item of the array is represented by Agency Number Scheme bellow.

Agency Number Scheme

Anchor

	agency
	agency

brokerAgencyNumber

string

required

The actual agency number.

brokerAgencyEmail

string

optional

Reference for the agency Number that is shown to user in booking process. Please make use of Reference texts that the user can understand

Broker’s contact email.

brokerAgencyName

string

optional

reference ID for insurer in an external system such as CRM system. For some CRMs it is important that the agencyNumber is associated with the right insurer Reference. This ID is also returned in our responses (such as IPN) for the external system to insure referential integrity. Normally this should not be used together with the externalUniqueID

externalUniqueId

string

optional

unique ID for the agencyNumber entry in an external system such as the CRM. This field will be returned in our response to make sure the applied agency number can be mapped back to the original entity. This number must be unique accross account/broker and cannot be used twice.

defaultForTenders

bool

required

Users get a dropdown list of all possible agency numbers. If this field is true, the respective agency number will be used as the default entry offers generated in manual tender processes. If multpile are transferred with this flag, the last will be used as default.

defaultForCalculations

bool

required

Users get a dropdown list of all possible agency numbers. If this field is true, the respective agency number will be used as the default entry for calculated offers. If multpile are transferred with this flag, the last will be used as default.

collectionType

string

optional

The preferred agency number collectionType can be defined here. Enumeration type where possible entries are:

broker_collection - Maklerinkasso
insurer_collection - Versichererinkasso
mga_collection - Assekuradeurinkasso

internalComment

string

optional

comment that is only visible in the admin portal

active

bool

required

default should be true. if false, agency number will not be available to the user in the booking process.

Broker’s contact name.

brokerAgencyPhone

string

optional

Broker’s contact phone.

Explanations:

Anchor

	explanations
	explanations

¹ one parameter out of baFinRegNr, insurerId and supervisingAuthorityId is requiredrequired if db is empty
²required if e2e is empty

Attributes of the HTTP response

Success response
JSON array of objects containing:
status	string	required	A text providing more information on the succesful operation.
Failed response
error	string	required	It contains a reason for the failed request.

Examples

As previously stated, to execute Add Agency Number, it is imperative to dispatch a POST HTTP request to the /api/broker/set/anums/{:token} endpoint of the API. Below, instances of potential communication between the API and consumers are provided.

HTTP Request

Code Block

language	json

# HTTP POST
# https://app.dev.thinksurance.de/api/broker/set/anums
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
   "bToken":"<some short hash>",
   "token":"<some short hash>"
   "agencyNumbers":[
      {
         "baFinRegNrbaFinId":"5405",
         "agencyNumberse2e": [
              {
                  "agencyNumber"brokerAgencyNumber": "1api-e2e-agencyalte-numberdeal", 
    
             "matchCodebrokerAgencyName": "comment",API 
                  "externalInsurerId": ""ALTE CONTACT",
                   "externalUniqueId"brokerAgencyPhone": "uniqueId1api-phone-alte",
                   "defaultForTenders": false, 
                  "defaultForCalculations": false,"brokerAgencyEmail":"api-e2e-test@gv24.de"
                    "collectionType": "insurer_collection", 
 },
                "internalComment": "internal comment", 
                  "active": true 
              },
              {
   "db":{
              "agencyNumberbrokerAgencyNumber": "2api-e2e-agencyalte-numberdealdb",
                   "matchCode"brokerAgencyName": "commentAPI 2", 
                  "externalInsurerId": "insurerId2", 
     ALTE CONTACTdb",
            "externalUniqueIdbrokerAgencyPhone": "api-phone-altedb", 
     
            "defaultForTendersbrokerAgencyEmail": false, 
                  "defaultForCalculations": false,"api-e2e-test@gv24db.de"
         }
         "collectionType": "mga_collection"},
      {
            "internalCommentbaFinId": "internal comment 25036", 
     
            "active": true 
              },
              {
e2e":{
                 "agencyNumberbrokerAgencyNumber": "3api-e2e-agencyarag-numberdeal", 

                 "matchCodebrokerAgencyEmail": "comment 3", 
                  "externalInsurerId": "insurerId3", 
                  "externalUniqueId": "", 
                  "defaultForTenders": true, 
                  "defaultForCalculations": true, 
                  "collectionType": "mga_collection", 
                  "internalComment": "internal comment 3", 
                  "active": true 
              }
          ]"api-e2e-arag@gv24.de"
         },
      {
         "insurerId":"5036",
         "agencyNumbers": [
              db":{
                  "agencyNumber"brokerAgencyNumber": "A1testi",
                   "matchCode"brokerAgencyName": "A1", 
                  "externalInsurerId": "A1"Herr Testi",
                   "externalUniqueId"brokerAgencyPhone": "A1", 
                  "defaultForTenders": trueHerr Telefon",
                   "defaultForCalculations": false, 
                  "collectionType": "insurer_collection", 
                  "internalComment": "A1", 
                  "active": true"brokerAgencyEmail":"testiDB@gv24db.de"
               }
          ]
      },
      {
         "supervisingAuthorityIdbaFinId":"61234",
         "agencyNumberse2e": [
              {
    
             "agencyNumberbrokerAgencyNumber": "A2"api-e2e-arag-deal1", 
                  "matchCode"brokerAgencyEmail": "A2api-e2earag1@gv24.de",
                   "externalInsurerId": "A2", 
                  "externalUniqueId": "A2", 
                  "defaultForTenders": false, 
                  "defaultForCalculations": true, 
                  "collectionType": "mga_collection", 
                  "internalComment": "A2", 
                  "active": true 
              }
          ]
      }
   ]
}

Successful HTTP Response

Code Block

language	json

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "status": "Broker Api: agency number added succesfully."
}

Failed HTTP Response

Code Block

language	json

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

Version	Old Version 8	New Version Current
Changes made by	Timm Weitzel	Timm Weitzel
Saved on	Mar 24, 2024	Apr 10, 2024

Versions Compared

Key

Introduction

Endpoint

Attributes of the HTTP request

Attributes of the HTTP response

Examples

Content Comparison

Versions Compared

Key

Introduction

Endpoint

Attributes of the HTTP request

Attributes of the HTTP response

Examples