Getting Started

The Claims Portal Developer Portal is the Claims Portal platform designed to support the developers during the integration of their systems with the Claims Portal API interface. In order to have the full access to the Developer Portal website you need to contact Claims Portal following the instructions contained in the official Claims Portal website.

IMPORTANT

As a Developer you must ensure that you are aware of the clauses that your company has agreed to when registering as a user of the Claims Portal or a software house developing on behalf of Portal users, in particular clauses relating to the development of the User Interface and the requirement that your API is compliant with these technical specifications.

Abbreviations, Acronyms and Definitions

Authentication

In order to be able to use the Claims Portal API the following steps must be followed:

1. With the provided CLIENT_ID and CLIENT_SECRET an access_token must be obtained
2. With the obtained access_token and the loginAs user it is possible to call the selected method. The possibility to successfully call the selected method and the visibility of the response depend on the roles assigned to the loginAs user used to call the method.

The validity of the token is of 3600sec.

Environments

The available environments for Claims Portal system are the following

• Integration Environment: https://integration.rapidclaimsettlement.org.uk
• Production Environment: https://www.rapidclaimsettlement.org.uk

Full list of available endpoints can be found in the APIs documentation.

An additional UAT environment will be available in case of changes to the system that will require a UAT phase.

Avoid hard coding

You must not develop you're API system by hard-coding the API JSON output as it can slightly semantically change in the future: the API system must take into account logic content, not plain text representation

Operations Timeout

When an operation fails to be completed within the system timeout, the CMS must not be developed in a way that the system automatically re-tries to complete the call. The system must GET the claim status to know the current status of the claim and get the processEngineGuid. In this way, the system knows whether the operation must be re-run or not and which Guid must be used for the next call. The timeout for instances when no response is received from the portal should be set at 60 seconds

Certificate Renewal

Our security certificates are updated on an annual basis, it is important that the API systems automatically recognize and accept the new certificate without any interventions or modifications. However, users will be informed in advance when the new certificate will be installed and the certificate will be obtainable from the Help Desk if needed. To ensure that you are notified when a certificate will be deployed, sign up to the Claims Portal's Newsletter on Claims Portal website.

Insurer Indices

The Insurer Index for RTA claims is available on the Claims Portal website in the dedicated section, for Claimant Representatives to cache if they so wish. If you use this feature you must ensure that you keep the cached index up to date by taking the latest version which is published on the web site on a regular basis.

Claims Portal do not issue the Insurer Index for EL and PL claims due to the frequency of the changes. Claimant Representatives must not create a cached version as it will become out of date very quickly, it may cause issues where claims are transferred and your cached version will not contain details of new users.

Probes

If you wish to use probes in the Live site to establish that the service is operational, ensure that you use the search claim call and that you only poll the Live site a maximum of 62 times an hour. The search claim must not retrieve any claim, it must be used only to check if the system is available or not. Probes must not be used in the API Integration site.

Administrative console

Every organisation will receive a special administrative account able to login onto the administrative console in order to create/modify branches and create/modify users with specific profiles. Please note that only users with "Administrator" profile can login to the administrative console and such users cannot log in the Settlement section (the claims section of the portal) unless an additional Settlement section profile (e.g. Claim Handler, Claim Dispatcher,...) that grants the possibility to access to the Settlement section is assigned to the user. The Administrator is responsible for maintenance on the account, that the claim handler users have access and those who should no longer be accessing the portal are disabled. Please review the Administrator section of the Claims Portal website.

Description of the system design

The API system design is based on the web portal model:

• Organisations processing the claim: the claim is processed by two organisation types: the ClaimRepresentative (CR) and the Compensator (COMP). A single organisation alone is not able to complete the full claim flow: for example a COMP organisation will start processing a claim only when a CR organisation has submitted a new claim to them.
• Branches of the organisation: organisations are organised into branches, and users belong to branches. Branches are usually based on a geographical model or on existing sites/offices/agencies. On the system for COMP organisations one and only one branch is defined as CentralPoint, which is the default branch where the claim is sent after the CR add claim operation. The Portal classifies branch 01 as the CentralPoint branch.
• Profiles processing the claim:
  • COMP Profiles: the Claim Dispatcher profile (CD) will poll for claims waiting for COMP processing and will allocate the claim to the relevant branch. The Claim Handler role (CH) will actually enter data or will take decisions on the claim. The CH will receive notifications for timeouts expiring on claims being processed, or actions of the CR user on processed claims.
  • CR Profiles: The Claim Handler profile (CH) will actually enter data or will take decisions on the claim. The CH will receive notifications for timeouts expiring on claims being processed, or actions of the COMP user on processed claims. The CH will poll for claims waiting for CR processing.

End users can tailor the system to their specific needs, e.g:

• Collapsing profiles, branches, users
  • CR with one single branch and one single user belonging to the branch: all notifications will be receiver by the user which should collect and delete them from the system as soon as possible.
  • COMP with one single branch, the CentralPoint, and one single user belonging to the branch: the user will be assigned to the CH profile and the CD profile will not be assigned. In this case there is no need to root the claims that will remain assigned to the CentralPoint branch and to the CH user who will regularly monitor the list of claims. All notifications will be receiver by the user which should collect and delete them from the system as soon as possible
• Collapsing profiles, branches: in case of multiple users that belong to a single branch of the organisation (both CR and COMP), the caller should track which claims belong to which branch. Notifications are split among multiple users which should collect and delete them from the system as soon as possible.
• Collapsing profiles, branches: one single user belonging to one of the branches of the organisation (both CRI and COMP), the caller should track users' claims ownership. Notifications are split among multiple users which should collect and delete them from the system as soon as possible.

Calls frequency

The number of operations and calls made by your interface to the portal will depend on the number of claims managed by your organisation, but, when the instructions below are followed it is unnecessary to poll the portal more than around 220 times or less per hour. You must monitor the number of calls and if your application is polling more than 220 times per hour, you must establish the reason and make changes to bring the volume down to the required volume of hourly calls. CPL (Claims Portal Ltd) monitor the usage levels and the operations that are called and may contact users who are not compliant with these specifications. The portal is an interactive system it must not be used as if it were a batch system where calls are cached and then submitted to the portal in high volumes at one time. This practice impacts the performance of the service for all users. The objective must be to call the operations to manage the workflow as described below. User systems must not poll the portal with the same call multiple times every hour, the user interface must manage the workflow using the timelines indicated below. All the operations that can be executed on the Claims Portal system can be distinguished in two main types:

1. Operations aimed to work on the claim that can be found in the RTA-Comp, RTA-Cr, ELPL-Comp and ELPL-Cr APIs
2. Operations aimed to obtain possible changes of the status of the claim that can be found in the RTA-Static and ELPL-Static APIs

Operations that move the claims along the workflow (type 1) can be performed at any time. Whilst all the operations needed only to update the information on the claims (type 2) must be spaced out. As the Claims Portal workflow is based on daily operations, it is not necessary to poll the system continuously to get updated information on the claim. The correct behaviour is to poll the system hourly.

Get the claim updated

When the user wants to know the current status of the claim, that is the phase in which the claim is in, the side where it sits and so on, they must use the search functionality NOT the get functionality. The search call will obtain all the necessary information the user needs to know to check the status of the claim and promptly respond to the other party. It is also mandatory to use the search parameters (i.e. applicationID, sentDateFrom, sentDateTo). This approach provides the best time responses from the system and obtains only the desired results. The user must not attempt to download all claims held in the portal for an organisation or all accompanying documentation, i.e. attachments, PDFs etc. If there is a need to download all claims due to the migration from web browser to API, please contact the Help Desk and ask for a copy of the Bulk Download Procedures.

Workflows

The claim workflow is implemented in the system by a workflow process. Workflows are available to be downloaded in the Browse Documentation section. Each workflow process is identified by a workflow process version with a versionMajor and versionMinor numbering: for example the first deployed workflow process has version versionMajor=1 and versionMinor =0 (1.0). When a new workflow process version is deployed, previously deployed workflow process versions are not replaced or removed from the system, but are still available in the system to complete currently live claims started with previous workflow process versions. When a new claim is created, the workflow process version used is always the latest available in the system, and this workflow process version will be used to manage the claim for the whole life of the claim, regardless of subsequently deployed workflow process versions. This means that, based on the workflow process version, some requests may be applicable or not, or the signature of some requests may be different (new parameters to be supplied) for these reasons it is important that the claim workflow version is retrieved and stored in order to use this information to properly manage claim.

The current and latest workflow version can be known with the GET system process version available both in the RTA-Static and ELPL-Static APIs, and this is the version under which all claims have been created since the release. To know the workflow version of a specific claim the search claim and the POST claims/search functionalities available in the RTA-Static and ELPL-Static APIs can be used.

To track the discontinuity of workflow process versions in case of Change Request deploy, a Compatibility level table is maintained, please refer to the Interface Compatibility level paragraph. The compatibility level is reported for each request and for phases (see subsections of section 0).

PLEASE NOTE that workflow versions and API versions are not linked and will be different, e.g. workflow version 7.1 and API version 1.0. When a new workflow process version is deployed in the system to fix some workflow defects there is the possibility that this will not impact the API interfaces therefore the API version number will not change and vice versa, it is possible that in case of fixes on the API interfaces there will be no impacts on the workflows, this means that the API version will change but the workflow process version will remain the same.

Workflow steps atomicity

APIs access and Web portal access share the same workflow, so a claim can be processed with an alternation of APIs methods and web forms, allowing each organisation to freely decide its claim management approach. Please note that there are steps in the workflow which are made by few tabbed forms on the web portal and in order to complete such workflow step the user should fill-in all the fields in the various tabs. Under this circumstance, no API methods can be executed if the claim is stuck in the middle of two tabs. Web forms and API methods behave as two paths which frequently cross each other: the next API methods can be executed only when the web path reaches the intersection.

Concurrency consistency mechanism

In order to keep the system consistent, we have implemented a mechanism to make the clients always aware that there aren't concurrent actions on a claim. For each action on a claim the system sends back to the client 2 unique IDs:

• The applicationID of the claim, it does not change during the lifecycle of the claim
• The "activityEngineGuid" representing the status in which that claim is currently in. This is a unique ID representing "that claim in that specific moment" and must not be confused with the ID of the phase, i.e. if 2 different claims are in the same phase of the workflow, they have 2 different activityEngineGUIDs. These IDs must be used by the API client to perform actions on claims. The system will check if the Claim represented by the ClaimID is still in the phase represented by the activityEngineGuid:
  • IF NOT, the action fails and the system sends back an error message
  • IF YES, the action is successful and the system will give back to the API client a response containing (as stated above) also the claimID and the new "activityEngineGuid".

This mechanism is especially needed to avoid that an API client performs an action on a claim which is still in the same phase although it had been modified by someone else. E.g.:

1. claim 123 is in phase A
2. the API client gets the claim 123 to read its details
3. someone else updates the claim which goes from phase A to phase B: A → B
4. someone else updates the claim which goes from phase B to phase C: B → C
5. the API client tries to update the claim to change its phase from C to E
   1. without this mechanism, the system would allow the API client to change the phase from C to E, skipping the phase D
   2. with this mechanism, the system informs the API client that "something happened to the claim after the last time the claim details has been checked". Hence the API client is forced to retrieve the claim and the related "activityEngineGuid" to look at it before proceeding.

Maintaining updated info within the in-house CMS

It is expected practice and the portal is designed on the basis that an organisation is using a CMS (Claims Management System) which interacts with Claims Portal, an important point is to ensure that the CMS is working on up-to-date info. This means that some kind of refreshing/polling should be done in order to detect when relevant info is changed (this means there is an advance in the claim processing). With regards to the information polling there are some important aspects to be taken into consideration:

• How 'changed' info is detected
• Frequency of changed info detection
• Which parts of the claim changes when

Before proceeding it is useful to recap the principal components of a claim on the Claims Portal system:

• CNF values (always retrieved with the GET of the claim, regardless of the stage)
• CNF processing status (retrieved with the GET of the claim status)
• Attachments (retrieved with the GET of the attachments list)
• Printable Documents (retrieved with the GET of the printable document list)

All these components are subject to changes during the claim's lifecycle.

How many times changes on CNF must be monitored?

How many times the changes on CNF must be monitored depends on the number of claims being processed, the number of organisations processing the claims, the reaction time of such organisations. The recommended approach is to check for changes every hour.

Attachments

Attachments can be added at any stage of the claim, even when the claim is with the other party e.g. the CR can add an attachment when the claim in on the COMP side and the COMP can add an attachment when the claim is on CR side, however a check for new attachments must be made when the claim changes ownership., continuous search claim and GET of the attachments list are not allowed. Please refer to the RTA-Static and ELPL-Static API descriptions for further details on how the attachments can be managed on the system.

Printable documents

Updated printable documents are only generated when the claim changes ownership. Please refer to the RTA-Static and ELPL-Static API descriptions for further details on how the printable documents can be managed on the system.

CNF processing status: the role of notifications

Notifications are meant to notify one side when something relevant happened on the other side. For example, when the COMP states that Article75 applies, a notification is sent to the CR, the intention is to make the CR aware that the timeout has changed. Please note that notifications are not generated when the claim changes ownership: i.e. when the claim is sent from the CR to the COMP and vice versa, no notification is generated. Please refer to the RTA-Static and ELPL-Static API descriptions for further details on how the notifications can be managed on the system.

CNF values: how changed information is detected (detecting claims waiting for processing)

A claim can be processed only when is on is not under the ownership of the other side, and this happens when the claim moves on specific phases. Consequently there is no need to monitor any claim change while the claim is under the ownership of the other side. To detect which claims have reached a "workable" phase it is possible to search for them specifying as criteria the specific phase ID. To cover the whole life of the claim, multiple searches should be executed to cover all relevant phases. To retrieve the list of relevant phases, depending on whether you are a CR or COMP, please examine the workflows that can be downloaded from the Browse Documentation page.

How NOT TO check if CNFs are changed

Detecting any changed info by a massive re-loading of all parts of all claims currently in progress in the CMS. To do so the system should perform a massive number of GET operations of the claims information (claim, claim status, attachments and printable documents) and this will lead to exceed the maximum allowed number of request. Please note that the Claims Portal system is able to detect this approach and will react accordingly, slowing or stopping the account performing this behaviour.

Status changes in in-house CMS are not tracked within Claims Portal

Please always bear in mind that, depending on how CMS has been developed, CMS statuses may not match Claims Portal phases and Claims Portal won't track the status of claims within the CMS but only the phases according to the Claims Portal flow.

Client Implementation

Familiarise with the process using the WEB portal

Before starting the implementation it is important to be familiar with the claim workflow using the WEB portal: using the forms visualisation allows a better comprehension of the flow, required data and, output of the system.

Implement the client to allow retrieving JSON Request and JSON Response

The client must be implemented to allow for retrieval of the JSON Request and the JSON Response. This information must be supplied when raising a support request.

Implement the client against INTEGRATION environment

The implementation of the client should be finalised by sending requests to the Claims Portal system available in INTEGRATION environment. All relevant requests and different scenarios should be covered. Support team is available to help covering any functionality or scenario to ensure that the client implementation is ready to communicate with the Live environment.

Interface Compatibility level

Definition

The compatibility level is used to indicate which API interface elements are accessible by a client depending on both the release in place and the version of each claim stored in the portal (please note the workflow process versions reported below are for explanation only).

How to read the Compatibility Level information

The following table explains how to read the info about the Compatibility level:

Process version used to switch between releases

Please note that in the above section, the version numbers 2.0 and 2.1 are just examples. The first process version implemented for a new Release will be communicated in advance to all relevant audience at the latest two weeks before the deployment in the Production environment. For more info please refer to each API to check the available process versions and the correspondence with the available APIs versions.

Process versions

Please refer to each API to check the available process versions and the correspondence with the available APIs versions.

PLEASE NOTE that workflow versions and API versions are not linked and will be different, e.g. workflow version 7.1 and API version 1.0. When a new workflow process version is deployed in the system to fix some workflow defects there is the possibility that this will not impact the API interfaces therefore the API version number will not change and vice versa, it is possible that in case of fixes on the API interfaces there will be no impacts on the workflows, this means that the API version will change but the workflow process version will remain the same.

Troubleshooting

Identify if the problem is in client implementation

When the client implementation is not completely compliant with the documentation, it may not be possible to correctly communicate with the Claims Portal system and errors may be experienced. It’s important to identify if the error may be related to the client implementation.

Reproduce the issue on the WEB portal

To ensure the problem is not caused by a misunderstanding of the documentation, attempt to replicate the issue using the WEB portal.

Do not submit a query without providing JSON Request and JSON Response

When submitting a query to the Claims Portal Help Desk always include the JSON Request (and Claim ID) the JSON Response and the credentials (excluding the password and/or the token). This allows us to exactly understand which is the request, the parameters and the accounts involved, and allows the Help Desk to start investigating; unless passwords/token are specifically requested, you should omit or replace with special characters to maintain account security. This means that the client software should be designed to collect, for troubleshooting purposes, the JSON Request and JSON Response communicated with Claims Portal. The JSON Request, together with the ClaimID allows analysis of the claim life, and allows the support team to reproduce the issue. If the client is unable to provide the troubleshooting info, the user must provide as a minimum the following information:

• Request name
• Claim ID
• TraceID of the error
• API account
• UserAsID
• account Data relevant for the request

Please note that if the troubleshooting information is not provided the time taken for the investigation will be longer and we may not be able to assist the user with their query.

Allow API client design for out-of-the-process or web operations

The comprehension of the system requires some time to be fully understood, as a consequence the client should be designed to be able to allows one or more steps to be completed out of the process (for example if a specific operation requires a workaround, or should be done on the web portal).

Notes on the communication with the Claims Portal server

HTTPS protocol

Claims Portal server is configured to work in the HTTPS protocol which is an industry standard secure communication protocol to exchange requests and information.

Default communication timeout

Please note that the processing of an API request may require some time, so the client should be configured with a timeout set at 60 seconds, which is long enough to wait for the reply from the server. In case a timeout is experienced, please be aware that this only means the client stopped listening for the server response, but actually the server is still processing the request up to its completion, so a subsequent call get the claim status will confirm that the process has moved to the following step in the flow. Please bear in mind that company network devices may monitor the communications throughout the company network, and there may have special configuration to detect and close communications which appear to be idle: so in case network connection is closed despite a long client timeout configuration, network devices in the path to the server should be investigated.

Network devices (company firewall, etc.)

If the Claims Portal server is not reachable ensure relevant network devices in the middle to the network path to the Claims Portal server are correctly configured to allow network traffic to and from the server. For example, firewall may require a special configuration to open a port to the IP address of the server, depending on the protocols allowed by the company network policy. Further, the firewall may require a specific configuration to allow access to the HTTPS protocol.