Authentication, API Keys and General Notes

The ClearLife REST API uses JSON as its communication format and the standard HTTP methods like GET, PUT, POST, and DELETE.

Activating the Public API

To activate the Public API, ClearLife need to add the Public API role to your account on clarinetlive.com. It’s assigned to the Client Administrator, who can then assign it appropriately. Permissions/roles are inherited from the Client Administrator, so once the Public API role has been added to your account, the Client Administrator will be able to assign this Public API role to other users, if required, or create new users with it.

Authentication

The individual user MFA setting or the company-wide setting on MFA only affects access via the website, not via the Public API, so it can remain enabled.

You can generate an API Key for an existing user, but note that any Audit Log will show activity under that username, without any difference if a human logged in or if the API was accessed. This can be appropriate if your third party tool activity (such as Salesforce) is per “human” user/employee, for example each user on that tool has its own ClariNet LS API key, then that can be followed on ClariNet LS. To set this up, login as that user and generate the API key, see Creating an API Key below.

You can also create a new account with only the necessary permissions required for API access. This might be advisable if all activity is recorded as a single “machine” user. To set this up, login as a Client Administrator on clarinetlive.com to create that user, then login on clarinetlive using that new user and password to generate the API Key, see Creating an API Key below.

Creating an API Key

Start by clicking the menu item showing your Username and selecting the Change Security Details option.

Now on the Change Security Details page, in the bottom right you will see the API Keys section. If you do not see the section, ensure you have been granted the "Public API" role.

Click on Create API Key. In the popup that has just opened, enter a name. This name is for your own reference and is not used in the authentication.

Click Create - You will now be shown your API key. Make sure you copy the API Key using the Copy button as once the popup is closed, you will not able to see the API key again. Now click Close and you will see you new API Key in the API Keys list.

If you need to revoke an API Key, do so by clicking the delete icon in the API Keys list and selecting Ok in the confirmation box.

Examples

Place the API Key into the headers with header key Authorization and value "ApiKey XXXXXXXXXXXXXXXXXXXXXXXX".

See below two examples using Postman, the first one using the Authorization tab:

And a second one using the Headers tab:

Versions

The current API version is 3. However, not all endpoints are supported in every version. For example:

• https://www.clarinetlive.com/api/v2/carriers
• https://www.clarinetlive.com/api/v3/cases
• https://www.clarinetlive.com/api/latest/carriers

We no longer recommend using latest as a “version” indicator when querying the ClariNet LS API. In order to make sure we can deliver great new features to you quickly, but without breaking any existing processes you have that depend on the ClariNet API, it is better to specify the version that you want to use explicitly. That way, you won’t be caught out by unexpected changes, but we can still roll out changes so they’re there when you’re ready to make the switch.

The ClariNet LS™ API supports versions /v1 /v2 /v3 and /latest. The documentation for each endpoint lists the available versions for each endpoint, e.g. Import/Export (Create and Update a Case) .

ClariNet LS™ LS demo can also be used as a Staging environment to test changes. The URL there would be:

https://www.clarinetdemo.com/api/v3/cases

Dates and Times

The API expects the request to contains dates and times in UTC, and will also return all Dates and time in UTC.

Substitutions

Where parts of a URL are shown between angle brackets < and >, that portion of the URL should be replaced by the named item, such as a case reference or portfolio name. Certain characters, such as spaces and ampersands may need to be replaced via URL Encoding.

Visibility

Some Endpoints, notably report creation ones, create resources that are only visible to the creating user by default. These Endpoints allow customization using any of the following additional fields added to the JSON object:

AdditionalUsers - a JSON array of ClariNet LS Usernames. You may only specify users who belong to the same company as the creating user.

SubscriberWide - a boolean specifying that all users who belong to the same company as the creating user should have visibility.

E.g.:

{
    "AdditionalUsers": ["user1","user2"],
    "SubscriberWide": true
}

It should be noted, in this example, that the list of additional users is redundant since SubscriberWide has been set to true.