HUB Service Partner API

Introduction

About this document

This document describes integration API between Service Partner Company and ECB.

Abbreviations

Some commonly used abbreviations in this document.

Functional description

Service partner companies use internal systems for claim handling. And SPC employees need to work with ECB and internal systems at the same time. This means that they have to manually type in same information twice, and track own tasks in both systems. The intent of integration API is to reduce SPC employees time spent on administrative work.

Technical description

In general

Integration API will consist of several integration points provided by both ECB application and SPC internal system. For example, SPC can integrate some documents like damage service report from internal system to ECB application and ECB will automatically notify SPC internal system about changes on claims assigned to SPC.

API Versioning and URLs

API Versioning

To support backward compatibility when breaking changes are introduced in Integration API, ECB application supports Integration API versioning. It is supported in both directions – version is added to ECB API URLs and is configurable per SPC when sending requests to SPC internal system, so that SPC integration with ECB won’t break if new API version is introduced.

ECB Application URLs

All ECB application URLs presented in this document are relative to the common base path. Common base URL path consists of two parts: ECB web application root (example: https://sandbox.scalepoint.com/ecx/host) plus Integration API base path (example: “/api/integration/v1”).

ECB common base URL path is referred as <ECBIntegrationAPIUrl> later in this document. Example: https://sandbox.scalepoint.com/ecx/host/api/integration/v1

We strongly recommend making ECB common base URL path configurable in SPC internal system, because we can use several servers with ECB application installed (for test purposes).

Scalepoint will provide ECB application common base URL paths for test and production environments to SPC on demand.

SPC Internal System URLs

We require SPC to provide full base URL path to their integration points so that all the requests to SPC internal system are using URLs starting from this base path. It will allow to configure SPC integration point base path URL once per SPC in ECB application thus decreasing configuration complexity and increasing integration flexibility (easier to add new integration points in future).

SPC common base URL path is referred as <SPCIntegrationAPIUrl> later in this document.

SPC internal system URLs for specific integration points are defined later in this document.

Transport and Invocation

The transport layer for integration point will be implemented using JSON over HTTPS approach. JSON examples and schemas should be distributed with this document and are referenced below by their file names.

Integration points are designed in a REST-like manner, so to invoke an Integration point one will need to issue an HTTPS request to an URL with JSON payload defined in this document below. All such requests must explicitly specify Content-Type header field as “application/json”, otherwise the request will fail.

In addition to JSON payload, integration points are using HTTP status codes to report request results. Examples:

• 200 OK – when request was processed successfully;
• 201 Created – when new object was created in receiver system;
• 403 Forbidden – when authentication failed for request;
• 404 Not Found – when resource to be updated was not found;
• 500 Internal Server Error – when request processing resulted in unexpected error.

Request size should not exceed 50MB.

Security

It is vital that we provide adequate security to protect the integration. To ensure that only Scalepoint ECB and SPC systems are able to send and read the integration point messages the solution aim to protect against any intrusion and unauthorized access to data exchange. Both parties should restrict access and not allow external clients, and even limit clients within internal networks.

Security is achieved by the following rules:

• SPC should have pre-shared secret string key called Security Token¹ which will be a part of all JSON schemas. This will allow to authorize and recognize SPC and ECB application;
• TLS/HTTPS will be used for payload encryption so no sensitive data will appear in Integration Point URLs.

Error handling

Integration API endpoint call may result in network error or error on receiver side. In this situation sender (either ECB or SPC internal system) should retry sending request until it is either successfully processed or all allowed retry attempts are failed.

ECB implements retries with increasing intervals (for example: in 5 seconds, in 20 seconds, in 1 minute etc). If request can’t be delivered after a fixed amount of time, ECB will notify IT staff about an error during SPC integration.

Receiver party should be aware that, due to network connectivity errors, same request might be received twice or more (for example, if it was processed successfully but sender didn’t receive a response due to network error). Such duplicated requests must be correctly handled on receiver side (for example, no duplicate entities should be created in receiver system as a result). ECB behavior in case of request duplicates is described per integration point (see below).

Integration Points provided by ECB

Integration points to be invoked by Service Partner internal system

• Submit Damage Service Report
• Submit Damage Service Report Draft
• Can Submit Invoice
• Submit Invoice
• Submit Invoice - Dry Run
• Get File Content
• Submit FNoL
• Submit Offer

Integration Points provided by Service Partner

Integration points to be invoked by ECB application

• New Responsibilities Assigned
• Recommended Tasks Updated
• Damage Service Report Event [Deprecated]
• Report Status Changed Event
• Invoice Event
• Files Available Event
• Responsible Changed Event

Footnotes

1. Please note that Security key is unique for each Insurance Company – and for each environment ↩