Hepster API Implementation Guide

Customer 1.0 - Seamlessly integrate insurance contract bookings into your system with our embedded insurance API.

Introduction

The hepster Embedded Insurance API allows seamless integration of insurance contract bookings into your system. This guide provides all the necessary steps and resources to integrate and test the API effectively.

Getting Started

  • You will receive your credentials (BasicAuth) and the URL for the test environment by your hepster contact person
  • Please provide us with your static IP addresses or IP ranges to be added to our whitelist
  • Your IP address will be whitelisted on our preprod environment, so you can start testing
  • After successful integration and joint testing, access to the production environment will be provided

Technical Requirements

⚙️ API Specifications
  • API Type: REST
  • Authentication: BasicAuth
  • Data Format: JSON

Overview

Policy Booking

POST /services/integrator/partner/bike/v1/order

Creates a new insurance policy

Key Request Elements

  • Customer details (e.g., name, email, address)
  • Selected tariff and pricing
  • Insured object or person details

Key Response Elements

  • Contract details (e.g., certificate number, start date)
  • Error messages in case of issues
  • Status Codes

Additional Endpoints

  • Contract Cancellation: Suspend specific contracts
  • Document Retrieval: Fetch policy documents for a contract
  • Contract Overview: Retrieve all active contracts and details

Sample Request and Responses

Policy Booking

The following request will initiate the creation of an insurance contract at hepster.

🔗 Endpoints

Staging:
https://staging.hepster-services.com/services/integrator/partner/bike/v1/order

Production:
https://api.platform.hepster-services.com/services/integrator/partner/bike/v1/order

Request

JSON 
POST
{
  "customer": {
    "firstName": "Warsten",
    "lastName": "Kitt",
    "email": "partner@hepster.com",
    "birthDate": "2000-01-01",
    "address": {
      "street": "Karsten-Witt-Straße",
      "houseNumber": "1a",
      "zipCode": "12345",
      "city": "Christian-Schwarz-Stadt",
      "countryCode": "NL"
    }
  },
  "tariff": {
    "insuranceName": "Theft_Insurance",
    "insuranceSum": 1150,
    "contractStartDate": "2025-02-10",
    "transactionId": "order12345"
  },
  "objects": {
    "bike": {
      "frameNumber": "Cert test 27.02. 10:31",
      "manufacturer": "Hersteller",
      "purchaseDate": "2025-01-02",
      "trackerId": "12345"
    }
  }
}

About the Data

  • Customer: Please fill with data on the subscription holder and insured person
  • InsuranceName: Fix, pre-defined value
  • InsuranceSum: Wholesale bike value (incl. tax) + 100€ accessory budget
  • ContractStartDate: Start of insurance cover = start of subscription
  • TransactionID: Partner-internal ID, e.g. subscription ID
  • PurchaseDate: Initial purchase date of the bike, to identify bike's age
  • Manufacturer: Please fill with manufacturer and model of the bike

Sample Response

JSON 
{
  "status": {
    "id": 200,
    "text": "OK"
  },
  "messages": [
    {
      "message": "OK",
      "type": "info"
    }
  ],
  "contracts": [
    {
      "product": "Theft_Insurance",
      "certificate_number": "I8021447222504454884439397131",
      "contract_start_date": "2025-05-01",
      "damage_number": null
    }
  ]
}

Error Handling

Responses include status codes and descriptive messages.

⚠️
Common Errors

Missing required fields, authentication failures, or whitelist restrictions

Error Response Example

JSON 
{
  "message": "Validation of request data failed",
  "detailMessage": "createOrder.payload.objects.bike.manufacturer: must not be empty, createOrder.payload.objects.bike.manufacturer: must not be null",
  "code": 1001
}

Code Types

Code Reason
1001 Payload Validation Error
1002 Product Not Found
1003 Coverage Not Found
1004 Cancellation Reason Forbidden
1005 Contract Not Found
1006 Contract Already Exists
1007 Contract Update Forbidden
1008 Contract Not Updatable
1009 Certificate not found for certificatenumber
1010 Pib not found for certificatenumber
1011 Contract not found for certificatenumber
1012 Unknown filter <filtername>
1013 Invalid request parameter
1099 Unknown Server Error

Contact and Support

For technical assistance or customizations, reach out to:

Jan Wilke

Jan Wilke

Email: jan.wilke@hepster.com

Role: Technical Support & Integration