hepster API Implementation Guide

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

Overview

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.

Request

POST
{
  "policyHolder": {
    "insuredLegalEntity": "",
    "VATId": "",
    "taxId": "",
    "insuranceUserFirstName": "Muster",
    "insuranceUserLastName": "Mustername",
    "country": "DE",
    "email": "placeholder@mail.de"
  },
  "Contract": {
    "externalOrderReference": "TBD",
    "contractStart": "2025-12-22",
    "contractEnd": null,
    "legalwarrantyEnd": null,
    "productCode": "HEP_Repair_599,99",
    "duration": "3Y",
    "costsharing": 10
  },
  "insuredObject": {
    "serialNumber": "8C555625",
    "objectType": "Notebook",
    "itemsalesPrice": 555.0,
    "manufacturer": "HP",
    "model": "HP OmniBook 5 Flip 14",
    "undamagedConfirmed": true
  }
  
}

About the Data

• policyHolder: Subscription holder / insured person.
  Contains personal or company data depending on customer type.
• insuredLegalEntity: Company name (only if customer is a company)
• VATId: VAT ID (only if customer is a company)
• taxId: Tax ID (only if customer is a company)
• insuranceUserFirstName: First name (only if customer is a private person)
• insuranceUserLastName: Last name (only if customer is a private person)
• country: ISO 3166-1 alpha-2 country code
• email: Customer contact email
• Contract: Contract and product configuration.
• externalOrderReference: External / partner-internal order reference
• contractStart: Contract start date (00:00 o'clock)
• contractEnd: Contract end date (only for fixed-term contracts)
• legalwarrantyEnd: Legal warranty end (for warranty extension products)
• voluntarywarrantyEnd: Voluntary warranty end (for warranty extension products)
• productCode: Product identifier
• type: recurring = subscription, fix = fixed-term or warranty extension
• duration: Duration in months (recurring renewal or fixed term)
• costsharing: Deductible (customer share) in %
• insuredObject: Insured item details.
• serialNumber: Serial number of the insured item
• objectType: Item type (e.g. Phone, Notebook – extendable)
• itemsalesPrice: Sales price of the item
• manufacturer: Manufacturer of the insured item
• model: Model of the Item
• undamagedConfirmed: Confirms whether the item is undamaged

Sample Response

{
"status": {
"id": 200,
"text": "OK"
},
"message": "We received your n orders. You will receive a message once the booking process is done.",
"count": n
}

Error Handling

Responses include status codes and descriptive messages.

Error Response Example

{
  "message": "Validation error - errors in booking payload.",
  "detailMessage": "Errors in: Booking - contract_start_date is over 28 days ago.",
  "code": 1001
}

Error Response to webhook

{
  "status": {
  "id": 1005
  },
  "messages": [
    {
      "message": "Product not found",
      "type": "error"
    }
  ]
}

Code Types

Document Retrieval

Fetch documents for a specific certificate number. You can retrieve all documents or filter by type (certificate, PIB/IPID). The documents are delivered as a ZIP file.

All Documents

https://staging.hepster-services.com/services/documents/<CertificateNumber>
          

Certificate and PIB (IPID)

https://staging.hepster-services.com/services/integrator/documents/<CertificateNumber>?filter=certificate;pib
          

Certificate Only

https://staging.hepster-services.com/services/integrator/documents/<CertificateNumber>?filter=certificate
          

PIB (IPID) Only

https://staging.hepster-services.com/services/integrator/documents/<CertificateNumber>?filter=pib
          

Contract Overview

Retrieve all active contracts and their details. Optional parameters allow filtering by date, page, and sorting.

Lookup Contracts

https://staging.hepster-services.com/services/integrator/contracts/lookup/organisation?size=2&page=1&sortBy=CREATED_DATE&sortDirection=DESC
        
          

Optional parameters:

• size: contracts per page (default: 10)
• page: page number (default: 0)
• sortBy: CREATED_DATE (default), START_DATE, END_DATE
• sortDirection: ASC, DESC (default)

Contact and Support

For technical assistance or customizations, reach out to: