Table of Contents

REST API integration

You are here:

Polonious provides an extensive set of REST APIs to query data and create various entities in the system. This document is a quick start guide to help you connect and create a case in Polonious via REST. For a full list of API calls, please see our full “Polonious REST API – Developer Documentation”.

Quick Start Guide

The following steps are generally required for a simple integration:

  1. Set up a user account for your REST service requests
  2. Use those account details to obtain an access token for your API calls
  3. Prepare the payload with case data
  4. Create data import mapping in Polonious for creating a case
  5. Send the payload to the import mapping REST API endpoint

Below sections explain required steps in detail.

Set up a REST user account 

You can either request access to our integration demo server or – if you already have your own Polonious system up and running – create a REST user in your managed Polonious instance.

Request access to our integration demo server

If you don’t have your own Polonious instance or you don’t want to use your system at this stage, you can use our integration server:

https://integration.poloniousnow.com

Please contact our Polonious support staff to set up a user account for you. We will provide you with the userID and ClientSecret or a Basic Authentication header for you to use in your backend to obtain the access token for any further REST calls to the integration system.

Set up your own Polonious system for REST integration

If you already have your own Polonious instance up and running you can configure a user account for your REST service requests yourself. Note that our API calls still check the user’s ACLs so make sure to configure the user’s security groups that are required to perform the required actions.

The difference to a normal user account is the “Client Secret” field or the “Basic Password” field and “Logon allowed”. Logon allowed should generally be set to “No” which makes sure this is a backend user only which cannot be used to log into the Polonious frontend.

For the “Client Secret” field or “Basic Password”, you can generate a random set of characters (e.g. using a password generator tool) or manually enter a random set of characters. This field is similar to a password. You will need this client secret in your backend code when obtaining an access token as explained in the next section, and the basic password will be needed for basic authentication.

Obtain an OAuth Token

Once you have the userID and ClientSecret (as explained above) you are ready to request an access token to be used in any subsequent REST calls.

The general format to request this access token is shown below. You can see the green data elements which you need to replace with your specific details.

Generic endpoint structure:

POST <hostname>/pcmsrest/oauth/token with those parameters

client_secret=<client secret>

client_id=<client id>

grant_type=client_credentials

Specific example for our integration server: 

POST https://integration.poloniousnow.com/pcmsrest/oauth/token

client_secret=dHJr7tKK3aE59Xgxx4E06ouhW

client_id=publicRestCall

grant_type=client_credentials

This call will return an OAuth Token (let’s call it <YourOAuthToken> which we will use further down in this quick start guide.) which can be used in the subsequent API calls. Below screenshot illustrates how to manually make this call via a REST browser plugin.

If it fails, it will return a JSON response with 401 HTTP status code. The response may look like this:

{“error”:”invalid_client”,”error_description”:”Bad client credentials”}

Obtain details for basic authentication header

Once the user Id and basic password are known, the basic header value can be generated by the following online tool: https://www.blitter.se/utils/basic-authentication-header-generator/

Alternatively Polonious can help you encode both user ID and password into an valid key to use for basic authentication header.

Prepare payload with case data

The minimum data required to create a case is data for all configured organisation levels as well as a case description. In our example workflow we have 4 organisation levels, so the minimal JSON payload requires five data elements to be sent to create a case. See below JSON example.

{

“orgLevel1″:”Australia”,

“orgLevel2″:”NSW”,

“orgLevel3″:”Insurance”,

“orgLevel4″:”Home”,

“description”:”API Testing”

}

Create data import mapping

Above JSON payload needs to be sent to the “Create Case” API endpoint. Since Polonious is a highly customizable system with different Case, we do not have one fixed endpoint to send data to when creating a case programmatically. Instead we have a GUI to define a named data mapping. The name of the data mapping forms part of the API endpoint. We have a separate user manual to explain the mapping feature in detail, however below screenshot illustrates a simple example of how it is used. (Note: you will need access to “Administration -> Data import” in the Polonious UI if you want to define your own mapping.)

In this screenshot you see the mapping name is defined as “example-mapping”. This name is used in below endpoint example. That way you can define multiple “Create Case” endpoints in your system for different requirements.

Generic endpoint structure:

<hostname>/public/oauth/task/v1/mapping/<mapping name>

Specific example for our integration server: 

https://integration.poloniousnow.com/public/oauth/task/v1/mapping/example-mapping

Create Case via REST call

Now that we have the token, the payload, and the data endpoint we can make the call to create a case.

To create a case you will need to trigger a POST request with the following header information:

key    :  Authorization

Value : Bearer <YourOAuthToken>

or Value : Basic <YourBasicAuthHeaderValue>

If you were to do this via the browser  plugin, your POST header would look similar to below screenshot.

For the POST request body use the desired payload (including the brackets). E.g. as depicted in below screenshot.

Please note that any date fields need to be submitted in ISO format (e.g. 1985-11-01 or 1985-11-01T12:00 or 1985-11-01T12:00:00 ).

At the bottom of the screenshot you see what a successful response can look like (if a response is configured via the data import GUI when creating the import mapping.

In our example-mapping the response was configured as below:

{

“responseText”:”${responseText}“,

“referenceNumber”:”${primaryFileNumber}“,

“taskId”:”${taskId}

}

Above configuration results in below output (obviously with different values for taskID and other dynamic fields):

{

“responseText”:”Created”,

“referenceNumber”:”1806012″,

taskId“:”150

}

Congratulations! You’ve just created your first case using the Polonious REST API!

Note if it fails, it will return an error message with 401 or 422 HTTP status code. The error message may look like this:

{

    “errors”: {

        “base”: [

            “some error message…”

        ]

    }

} or 

{

    “error”: “invalid_token”,

    “error_description”: “some error message…”

}

Next steps

If you’ve made it this far, you have created your first case in Polonious via the REST API. In the http response you have probably seen the taskID amongst other information. 

You can now use those details to make additional calls to Polonious and add information to the case or to query information about the case. Below shows an example on how to add a diary to the case. 

Create a Diary with Items

You can add a diary to a case using the taskID (which was returned by the “Create Case” API call) as the identifier of the case when adding additional information such as a diary. Remember to also set the OAuth token in the header as explained above.

Example endpoint:

https://integration.poloniousnow.com/public/oauth/taskDiary/v3

Payload:

{

“notes”:”notes test”,

“heading”:”heading test”,

“diaryTypeDescription”:”Administrative Update”,

“diaryDate”:”2018-06-04″,

“task”:150,

“taskItemResource”:[{

“itemCode”:”AdminTime”,

“textValue”:”2″

},

{

“itemCode”:”ReviewDate”,

“textValue”:”2019-11-04″

}

]

}

Below screenshot shows how this would look like in the browser plugin Postman.

If it fails, it will return something like the Create Case API.

Other supported REST APIs

Please contact support@polonious.com.au if you would like to get more detailed documentation about further supported REST APIs.

Contact us for help

If you have any questions or need help with implementing your backend integration, don’t hesitate to contact us at support@polonious.com.au. We are always happy to help!

Previous Guidewire integration
GICOP changes 2021Download the GICOP whitepaper and stay compliant.

Our whitepaper covers all aspects you need to know to stay compliant with the latest GICOP changes coming into effect in 2021. Submit below form to receive the download link and related updates going forward.

SIU Insights report 2021How do you compare to other SIUs?

Check out some interesting results from our SIU management survey. Submit below form to receive the download link and related updates going forward.