1 Introduction
2 Endpoint
- 2.1 Attributes of the HTTP request
- 2.2 Attributes of the HTTP response
3 Examples

Introduction

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

Endpoint

To add a new agency number via the API, it is necessary to send an HTTP POST request to the endpoint /api/ipn/agency-numbers. The main part of the HTTP request is a JSON payload of the request body.

Action name	add agency number
HTTP path	/api/ipn/agency-numbers
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	optional¹	An unique identifier of the broker.
X-Account-Token	string	optional¹	An unique identifier of the account.
HTTP JSON body
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
baFinId	string	optional¹	An insurer’s BaFin registration number.
insurerId	string	optional¹	An insurer’s unique identifier number.
supervisingAuthorityId	string	optional¹	An insurer’s BaFin ID.
agencyNumbers	array	required	An array that holds information on all agency numbers that should be added for one insurer. Each item of the array is represented by Agency Number Scheme bellow.
Agency Number Scheme
agencyNumber	string	required	The actual agency number.
matchCode	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
externalInsurerId	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.
Explanations: ¹ one parameter out of baFinId, insurerId and supervisingAuthorityId is required

Attributes of the HTTP response

Success response

Success response
JSON object 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/ipn/agency-numbers endpoint of the API. Below, instances of potential communication between the API and consumers are provided.

HTTP Request

# HTTP POST
# https://ipn.dev.thinksurance.de/api/ipn/agency-numbers
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
# 'Authorization': 'Bearer <some long string value>'
# 'X-Broker-Token': '<some hash>'
{
   "agencyNumberSets":[
      {
         "baFinId":"5405",
         "agencyNumbers": [
              {
                  "agencyNumber": "1-agency-number", 
                  "matchCode": "comment", 
                  "externalInsurerId": "", 
                  "externalUniqueId": "uniqueId1", 
                  "defaultForTenders": false, 
                  "defaultForCalculations": false, 
                  "collectionType": "insurer_collection", 
                  "internalComment": "internal comment", 
                  "active": true 
              },
              {
                  "agencyNumber": "2-agency-number", 
                  "matchCode": "comment 2", 
                  "externalInsurerId": "insurerId2", 
                  "externalUniqueId": "", 
                  "defaultForTenders": false, 
                  "defaultForCalculations": false, 
                  "collectionType": "mga_collection", 
                  "internalComment": "internal comment 2", 
                  "active": true 
              },
              {
                  "agencyNumber": "3-agency-number", 
                  "matchCode": "comment 3", 
                  "externalInsurerId": "insurerId3", 
                  "externalUniqueId": "", 
                  "defaultForTenders": true, 
                  "defaultForCalculations": true, 
                  "collectionType": "mga_collection", 
                  "internalComment": "internal comment 3", 
                  "active": true 
              }
          ]
      },
      {
         "insurerId":"5036",
         "agencyNumbers": [
              {
                  "agencyNumber": "A1", 
                  "matchCode": "A1", 
                  "externalInsurerId": "A1", 
                  "externalUniqueId": "A1", 
                  "defaultForTenders": true, 
                  "defaultForCalculations": false, 
                  "collectionType": "insurer_collection", 
                  "internalComment": "A1", 
                  "active": true 
              }
          ]
      },
      {
         "supervisingAuthorityId":"61234",
         "agencyNumbers": [
              {
                  "agencyNumber": "A2", 
                  "matchCode": "A2", 
                  "externalInsurerId": "A2", 
                  "externalUniqueId": "A2", 
                  "defaultForTenders": false, 
                  "defaultForCalculations": true, 
                  "collectionType": "mga_collection", 
                  "internalComment": "A2", 
                  "active": true 
              }
          ]
      }
   ]
}

Successful HTTP Response

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

Failed HTTP Response

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

Thinksurance Public WIKI

V1.1 Add Agency Number

Introduction

Endpoint

Attributes of the HTTP request

Attributes of the HTTP response

Examples