Introduction

In instances where there is a need to create a new broker within a specific account utilizing the Thinksurance Public API V1, henceforth referred to as "the API," a dedicated endpoint facilitates this capability. This endpoint is accessible at the path /api/ipn/brokers. It anticipates a comprehensive payload as part of the HTTP request, encompassing the requisite broker data.

Endpoint

To create a broker via the API, it is imperative to send an HTTP POST request to the endpoint /api/ipn/brokers. The rest of the HTTP request is a JSON payload of the request body.

Action name	create broker
HTTP path	/api/ipn/brokers
HTTP method	POST

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-Account-Token	string	required	An unique identifier of the account.

Broker Parameters

The initial set of parameters pertains to broker data. Only specific elements within this data subset are mandatory for delivery. These required elements assist the API in providing critical information for the broker creation.

Explanations: ¹ required if bCompany is not set ² required if bLastName is not set
type	int	required	Enumeration value that defines the way for mapping broker data from the request: 1 - it requires to have broker’s ID from the partner system provided to Thinksurance System 2 - it doesn’t requires to have broker’s ID from the partner system provided to Thinksurance System
bExternalId	string	required	Broker’s ID from the partner system.
bGender	int	optional	Enumeration value that defines salutation of the broker person: 1 - Mr 2 - Ms
bFirstName	string	optional	Broker person’s first name.
bLastName	string	required¹	Broker person’s last name.
bEmail	string	required	Broker person’s email address.
bCompany	string	required²	Broker company’s name.
bStreet	string	optional	Broker company’s street name.
bStreetNumber	string	optional	Broker company’s street number.
bZip	string	optional	Broker company’s postcode.
bCity	string	optional	Broker company’s city.
bPhone	string	optional	Broker company’s phone number.
bCompanyRegNumber	string	optional	Broker company’s commercial register number.
bRegNumber	string	optional	Broker company’s IHK register number.

Attributes of the HTTP response

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

Examples

As previously stated, to execute Broker Create, it is imperative to dispatch a POST HTTP request to the /api/ipn/brokers endpoint of the API. Below, instances of potential communication between the API and consumers are provided.

HTTP Request with minimal data for company

# HTTP POST
# https://ipn.dev.thinksurance.de/api/ipn/brokers
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
# 'Authorization': 'Bearer <some long string value>'
# 'X-Account-Token': '<some hash>'
{
  "type": 1,
  "bExternalId": "T5",
  "bEmail": "awesome.gmbh@email.com",
  "bCompany": "Awesome GmbH"
}

HTTP Request with minimal data for a person

# HTTP POST
# https://ipn.dev.thinksurance.de/api/ipn/brokers
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
# 'Authorization': 'Bearer <some long string value>'
# 'X-Account-Token': '<some hash>'
{
  "type": 1,
  "bExternalId": "T5",
  "bEmail": "mustermann@email.com",
  "bLastName": "Mustermann"
}

Successful HTTP Response

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "status": "Broker Api: broker created succesfully.",
  "bToken": "some hashed string"
}

Failed HTTP Response

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

Create Broker