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 delete a agency number within a specific account or broker 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 DELETE 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	DELETE

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	optional³	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	optional⁴	The actual agency number.
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.
Explanations: ¹ one headers out of X-Broker-Token or X-Account-Token is required ² one parameter out of baFinId, insurerId and supervisingAuthorityId is required ³ if agencyNumbers is provided, only those agency numbers will be deleted, otherwise all of them for this insurer ⁴ one parameter out of agencyNumber, externalInsurerId and externalUniqueId is required

Attributes of the HTTP response

Success response

Success response
JSON object containing:
result	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 Delete Agency Number, it is imperative to dispatch a DELETE 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 DELETE
# 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>'
{
   "agencyNumbers":[
      {
         "baFinId":"5405",
         "agencyNumbers": [
              {
                  "externalUniqueId": "uniqueId1",
              },
              {
                  "externalInsurerId": "insurerId2",
              }
          ]
      },
      {
         "insurerId":"5036"
      },
      {
         "supervisingAuthorityId":"61234",
         "agencyNumbers": [
              {
                  "externalUniqueId": "A2"
              }
          ]
      }
   ]
}

Successful HTTP Response

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "result": "OK"
}

Failed HTTP Response

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

Thinksurance Public WIKI

V1.1 Delete Agency Number

Introduction

Endpoint

Attributes of the HTTP request

Attributes of the HTTP response

Examples