Case Import/Export/Change

Import/Export (Create and Update a Case)

This documentation provides guidance on the usage of new functionality introduced for the Public API that enables upload of multiple Cases simultaneously.

The goal of this functionality is to improve the maximum throughput that the ClariNet LS™ Public API Case update endpoint is able to provide by adding the capability to process multiple Cases in a single request. The usage of the API is throttled to 1 request per second per user, and only 1 active request per user is allowed at a time. Thus, supporting multiple Case updates in a single call improves performance by avoiding round-trip time since fewer calls are required, and the throttling limit is less likely to be hit.

Create and Update a Case (v3)

Endpoint

POST https://www.clarinetlive.com/api/v3/cases

Request

Supports JSON or XML body (Content-Type of application/json or application/xml).

Use the Schema endpoint to get the up-to-date response format.

Responses

Below are listed some specific responses for this endpoint. General information about responses, status codes and errors can be found in Responses and Errors.

Code	Message	Description
400	Bad Request	There was a problem processing the update. The response body will contain details about the failure. If sending multiple Cases, this doesn't necessarily mean all the updates failed. See Request Parameters section.

Create and Update a Case (v1, v2)

Endpoint

POST https://www.clarinetlive.com/api/v2/cases

Role

Case Management

Request

The request accommodates the import of new Cases as well as adding or amending data points in existing Cases. If the Case Reference entered in "Id" already exists in your ClariNet LS account, the case will be modified – otherwise a new Case will be created with that Case Reference.

For a full list of fields, please see the Common Case Standard definition, available separately as an XSD (Standard v1.0.xsd). Please contact ClearLife to get the latest version. Please see the JSON and XSD mapping help page for details on that topic.

The endpoint accepts either an individual Case, or up to 100 Cases. Each Case in the request should comply with the ClearLife Common Case XML Schema (Distributed as Standard v1.0.xsd, contact ClearLife Support for an up to date copy of this), or equivalent structure if sending JSON.

json

{
  "Id": "ExampleCase",
  "Policy": {
    "Carrier": "4 Ever Life Insurance Company",
    "PolicyDate": "2015-05-05",
    "PolicyNumber": "123TEST",
    "LifePolicyType": "UniversalLife",
    "MaturityAge": "95",
    "ExtendedDbAge": "None",
    "FaceAmount": "10000000",
    "Insureds": {
      "Insured": [
        {
          "DateOfBirth": "1935-01-24",
          "FirstName": "John",
          "LastName": "ClearLife",
          "Gender": "Male",
          "UnderwritersReports": {
            "UnderwritersReport": [
              {
                "Underwriter": "ITM 21st",
                "Mortality": 120.0,
                "ReportDate": "2022-01-01",
                "SmokingStatus": "Non-Smoker",
                "MeanLE50": 44,
                "MedianLE50": 44
              }
            ]
          }
        }
      ]
    }
  }
}

Request Parameters

The /api/v2/cases POST endpoint accepts a single optional parameter and allowPartialUpload.

This is an optional parameter, the default if not supplied is false.

An example url using this parameter is https://www.clarinetdemo.com/api/v2/cases allowPartialUpload=true

When a request contains multiple Cases, if not supplied or set to false then if any Case in the request contains invalid data, then no Cases in the request will be updated. You will get a 400 response with a JSON error message containing details about which Cases prevented the request from going ahead.

If set to true, then even if 1 or more Cases in the request are deemed to be invalid, other valid Cases in the request will still be updated. You will still receive a 400 error response, but the valid Cases in the request will update. The Cases that failed to update will be listed in the body of the response. For example, the below error response can be expected for a request containing multiple Cases, where two of those have problems which mean they cannot be imported.

json

[
    {
        "caseReference": "API Test Case 3",
        "errors": [
            "Case: The element 'Policy' has incomplete content ..."
        ],
        "htmlErrorString": "Please correct the following errors: ..."
    },
    {
        "caseReference": "API Test Case 4",
        "errors": [
            "Case: The element 'Policy' has incomplete content. ..."
        ],
        "htmlErrorString": "Please correct the following errors: ..."
    }
]

Responses

Below are listed some specific responses for this endpoint. General information about responses, status codes and errors can be found in Responses and Errors.

Code	Message	Description
400	Bad Request	There was a problem processing the update. The response body will contain details about the failure. If sending multiple Cases, this doesn't necessarily mean all the updates failed. See Request Parameters section.

Examples

Sending a single, existing Case for update in JSON format

This example shows a simple existing Case for update, changing 3 fields within the Policy of the Case.

json

{
    "Id": "API Test Case 1",
    "Policy": {
    "FaceAmount": "99999",
    "PolicyDate": "2020-11-02",
    "PolicyNumber": "POL_API_TEST"
    }
}

Sending two existing Cases for update in JSON format

When sending multiple Cases in a single request using JSON, the Case objects should be contained within a JSON array, as shown below. Here we are updating two Cases. Note if you were sending a single Case for an update, you can still contain it within an outer array if you wish, though there is no need to do so.

json

[
    {
        "Id": "API Test Case 1",
        "Policy": {
        "FaceAmount": "99999",
        "PolicyDate": "2020-11-02",
        "PolicyNumber": "POL_API_TEST1"
        }
    },
    {
        "Id": "API Test Case 2",
        "Policy": {
        "FaceAmount": "12345",
        "PolicyDate": "2019-11-02",
        "PolicyNumber": "POL_API_TEST2"
        }
    }
]

Sending two existing Cases for update in XML format

If you are sending multiple Cases in XML format, the figure below shows an example of what the request body should look like. Sending multiple Cases changes the request structure, as a containing envelope is required, the Portfolio element. Note, this does not relate to a ClariNet LS™ LS Portfolio - the Cases contained within it do not have to co-exist in the same ClariNet LS™ LS Portfolio, nor will sending them as below put them into a ClariNet LS™ LS Portfolio. It is just a containing structure to deliver the Case information to the ClariNet LS™ API. There is no need to include the outer Portfolio element if you are sending just a single Case, but it will not behave any differently if you do so.

xml

<Portfolio xmlns="http://schemas.clearlifeltd.com/clarinet/standard/v1.0">
    <Case>
        <Id>API Test Case 1</Id>
            <Policy>
                <FaceAmount>12345</FaceAmount>
                <PolicyDate>2020-11-02</PolicyDate>
                <PolicyNumber>POL_API_TEST1</PolicyNumber>
            </Policy>
        </Case>
    <Case>
        <Id>API Test Case 2</Id>
            <Policy>
                <FaceAmount>54321</FaceAmount>
                <PolicyDate>2020-11-02</PolicyDate>
                <PolicyNumber>POL_API_TEST2</PolicyNumber>
            </Policy>
    </Case>
</Portfolio>

Complete Request/Response for updating two Cases in a single request using JSON

Next, is a complete example including request headers for sending 2 existing Cases for update to ClariNet LS Demo, and below that, the single response for a successful update you would get in return.

Request:

text

POST https://www.clarinetdemo.com/api/v2/cases HTTP/1.1
Authorization: ApiKey VALIDAPIKEYGOESHERE
Content-Type: text/plain
User-Agent: PostmanRuntime/7.26.5
Accept: */*
Cache-Control: no-cache
Postman-Token: b05532a1-b3bc-4860-afe6-dd750811473d
Host: www.clarinetdemo.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 412

json

[
    {
        "Id": "API Test Case 1",
        "Policy": {
        "FaceAmount": "99999",
        "PolicyDate": "2020-11-02",
        "PolicyNumber": "POL_API_TEST1"
        }
    },
    {
        "Id": "API Test Case 2",
        "Policy": {
        "FaceAmount": "12345",
        "PolicyDate": "2019-11-02",
        "PolicyNumber": "POL_API_TEST2"
        }
    }
]

Response indicating that the update was made successfully:

text

HTTP/1.1 204 No Content
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Server: Microsoft-IIS/10.0
strict-transport-security: max-age=31536000;includeSubdomains
Date: Tue, 03 Nov 2020 12:03:24 GMT

Add Case with Documents API

Create and Update a Case with Documents (v1, v2)

Endpoint

POST https://www.clarinetlive.com/api/latest/cases/zip

Role

Case Management

Request

The request should contain a single ZIP archive file. The archive file should contain a single XML file conforming to the Common Case Standard Definition.

Anywhere within the XML file where a document is referenced by name, the archive file should also contain a document with the same name which will then be attached to the appropriate entity.

The request should be sent as multipart/form-data containing the zip file as the only part. This part should be sent as application/octet-stream with a Content-Disposition header including the file name, which must end with the .zip extension.

Responses

Below are listed some specific responses for this endpoint. General information about responses, status codes and errors can be found in Responses and Errors.

Code	Message	Description
400	Bad Request	There was a problem processing the update. The response body will contain details about the failure.

Documents Controller, API to fetch documents

Fetch a document (v1, v2)

Endpoint

GET https://www.clarinetlive.com/api/v2/documents/{publicId}

Request

This endpoint will return the requested document’s content given its public ID. The public identifier of a document can be looked up using the Case export endpoint on the API. This will give you a list of the documents associated with a particular case, and then for each document you require, you can call this API endpoint to retrieve it.

Responses

Some specific responses for this endpoint are listed below. General information about responses, status codes, and errors can be found in Responses and Errors.

Code	Message	Description
404	Not Found	If the document public id parameter you requested does not exist, you will get a 404 not found response.

Example

In this example, retrieving a policy document for a given case, “My Test Case”, and work with a JSON Case representation from ClariNet.

Firstly, retrieve the Case JSON using the case endpoint, specifying the header value for Accept as application/json:

GET https://www.clarinetlive.comapi/v3/cases?caseReference=My Test Case

That would retrieve a JSON representation of the case, as shown below. In this example, there is only one document, and the public ID needed to retrieve it from the document API endpoint is highlighted below.

Then make a call to the Documents endpoint as follows:

GET https://www.clarinetlive.com/api/v2/documents/b60020d3-c48b-4256-8236-730e9d9b5d32

This returns a binary stream of the document data. The response headers look like the one below. Note the Content-Type, which indicates the format of the document (i.e. PDF, Word, Excel, etc.), and the Content-Disposition giving the filename as it was saved in ClariNet. Content-Length will indicate the size of the file.

javascript

Cache-Control: no-cache
Pragma: no-cache
Content-Length: 242822
Content-Type: application/pdf
Content-Disposition: attachment; filename=Fasano_Electronic_Terms.pdf
X-Frame-Options: SAMEORIGIN
Date: Thu, 26 Sep 2024 08:38:34 GMT

This is a standard file download response, which most major programming languages will have libraries or code samples for how to handle.

Unredacted Access

Documents can be saved in ClariNet with both redacted and unredacted versions. If the authorization context of your call has permission to retrieve unredacted data, that version of the document will be returned to you. If it does not but has access to redacted data, the redacted version will be returned to you, if there is one.

If there is no redacted version, and the caller does not have unredacted access, you will be returned a 404 error.

Changed Cases API

Request

Endpoint

GET https://www.clarinetlive.com/api/latest/cases/changed?startDate={date}&portfolioName={name}

Role

Case Management and Public API

Request

There is no body for this request. There are two query parameters available:

Name	Description	Required?	Validation
startDate	The start date for the search. All cases that have changed since this date will be returned in the response. ISO 8601 format. (YYYY-MM-DDThh:mm:ss)	Yes	Maximum 7 days if no portfolio is specified. This increases to 30 days when a portfolio name is given.
portfolioName	A name of a portfolio. If specified, only cases currently in the portfolio are returned.	No	Must be the name of an existing portfolio

Response

The response HTTP status code will be set appropriately.

400 - start date was not a valid value
404 - the given portfolio was not found
200 - success with the given body

json

[
  {
    "publicId": "79bc137a-09ba-4f40-9469-75d7568b0ea9",
    "caseReference": "test-case-1",
    "lastModified": "2023-11-16T17:11:01.63"
  },
  {
    "publicId": "5fb78b91-c02b-4e4f-97cf-53a5f709280a",
    "caseReference": "test-case-2",
    "lastModified": "2023-11-16T21:12:13.73"
  },
]

Case Import/Export/Change ​

Import/Export (Create and Update a Case)

Create and Update a Case (v3)

Endpoint

Request

Responses

Create and Update a Case (v1, v2)

Endpoint

Role

Request

Request Parameters

Responses

Examples

Sending a single, existing Case for update in JSON format

Sending two existing Cases for update in JSON format

Sending two existing Cases for update in XML format

Complete Request/Response for updating two Cases in a single request using JSON

Response indicating that the update was made successfully:

Add Case with Documents API

Create and Update a Case with Documents (v1, v2)

Endpoint

Role

Request

Responses

Documents Controller, API to fetch documents

Fetch a document (v1, v2)

Endpoint

Request

Responses

Example

Unredacted Access

Changed Cases API

Request

Endpoint

Role

Request

Response

Case Import/Export/Change