XClaim API Documentation for Partners (1.4.0)

Download OpenAPI specification:Download

Introduction

These are the API endpoints which may be required for integration.

Afterwards, you would orchestrate the collection of data from the customer for that claim type (based on the fields required - as returned by the FNOL), and when ready, create a new claim with that data. Any files should be uploaded beforehand, and their UUIDs used as the values of the respective FNOL data fields.

API Overview

This is a JSON REST API, which aims to be comatiple with the JSON:API specification.

When making API requests, please use application/json in the Content-Type header.

In terms of authentication, you would have been provided an auth token. You should use it in the Authorization header like so;

Bearer <TOKEN>

Internationalization

XClaim supports seemless translations for all content which is customer-facing. However not all content is translated (and not to every language) by default - it depends on your specific use cases. This is something to discuss with the partnerships team.

If you are in a situation where you are supporting multiple languages, you can ensure that XClaim returns translated content, by using the Accapt-Language header. The specific locales supported, depend on your integration.

Some examples;

  • Accapt-Language: zh-hans

  • Accapt-Language: zh-hant_tw

  • Accapt-Language: ru

  • Accapt-Language: pt-br

The default locale for our platform is en.

Claim Creation Workflows

There are a few steps to claim creation, regarding the API;

  • Figuring out the correct claim type to use

  • Getting the FNOL for that claim type

  • Submitting the claim

Figuring out the claim type

There are a multitude ways to do this, and it depends purely on the type of integration used. It could be any one or combination of the following;

  • You are provided the claim type UUID for the relevant claim type of your integration

  • You use the "Get Claim Types" endpoint to retrieve a list of relevant claim types given a policy name. You would then ask the customer which claim type they wish to use (or potentially pick for them based on some automated criteria)

    • Note this is generally not used for the XCover platform
  • You use a claim selector designed by the claims team, which will guide your customers to the correct claim type through a series of questions. In this case, you will be provided a claim selector UUID to use with the "Get Claim Selector" endpoint.

Submitting the claim

This is the key part of the whole process. Once you have the correct claim type UUID, you will use the "Get FNOL" endpoint to retrieve the list of questions you need to ask the customer.

How you go about collecting this information is up to you, and there is no right or wrong way, and in some cases you may already have some or all of it beforehand, which means the whole process could be automated on your end if you so choose.

Uploading files

An important process to cover is the uploading of files. If you need to attach customers' file(s) to the claim being created, you will need to actually upload the files before the "Create new claim" request, and use the UUIDs returned by the file creation endpoint, as the value of those file fields as described in the FNOL.

For any file field, you can either use a single UUID string (of an uploaded file) as the value for that field, or you can use a json array of UUID strings as the value of that field. In summary, to be flexible, each file field supports either one or an array of an arbitrary number of files.

Providing claimant details

Note that when creating a claim, you need to always include a section providing information about the claimant. This section is called "claimantSection", and it is required for new claim creation - however it is typically not found in the FNOL.

The reason for that is that in most cases you would already have some or all of this information, so for the convenience of using the FNOL as the basis of form builders, the requirement of this section is implied rather than stated explicitly.

The following is a list of fields that you can pass. All of these are string fields.

  • firstName

  • lastName

  • email

  • phone

  • stateProvince

  • city

  • postalCode

  • country

In terms of validation, there are several things to note.

  • For email, the typical email validations apply.

  • For phone, the number must be provided in E.164 format (for example +551155256325 or +61466024743)

  • The mandatory fields are firstName, and at least one of either email or phone

The email and/or phone fields are used to send claimants various communications regarding the progress of the claim, and later on payment (as applicable).

Appendix

Featue Flags

We allow feature flags to be turned on/off using headers following the pattern of

  • x-feature-fnol--name

where name is a feature. using the strings on or off to put the feature on or off.

The current available feature flags are:

  • x-feature-fnol--error-shape

This flag is off by default, and re-shapes the error array in 422 repsonses for Claim Submission, examples can be seen in the claim submission responses in this documentation

Section Field Types

These are the section field types which are possible in the FNOL

  • string

    • return a string
  • email

  • date

    • return a string representation of a date (eg. "2019-03-25")
  • datetime

    • return a string representation of a date and time (eg. "2019-09-09 12:15:31")
  • numeric

    • return a number
  • url

    • return a valid url
  • boolean

    • return true or false (JSON boolean)
  • enum

    • return one of the options for the field (eg: "red")
  • geolocation

    • return a JSON object with lattitude and longitude properties
  • file

    • return array of file UUIDs, obtained from the file upload endpoint
  • set

    • return an array of selected options for the field
  • country

    • return a ISO 3166-2 country code (eg. "AU")
  • currency

    • return a ISO 4217 currency code (eg. "AUD")

Section Field Validations

These are the validations currently supported for a section field.

  • length

    • how short/long a string field should be
    • options: min, max
  • numeric

    • how low/high a numeric field should be
    • options min, max
  • multiselect

    • how many items should be included in an array (used with set fields)
    • options min, max
  • float

    • numeric field should include decimal(s)
    • no options

Status categories / External Statuses

All claim statuses are grouped into a finite set of what we call "external statuses" or "status categories", that are used for easier communicating the status of a claim. The following is the list of these statuses:

  • Claim Submitted

  • Information Processing

  • Under Assessment

  • More Information Needed

  • Approved - Pending Payment

  • Approved - Payment Sent

  • Denied

  • Invalid

  • Duplicate

  • Closed

  • Withdrawn

Typically claims are considered completed when they are either in Denied or Approved - Payment Sent status - but in reality, it could be any of the statuses below and including the "payment sent" one.

Due to the nature of insurance claims, most claims do not truly become "closed" for a long period of time (ie. while the policy is in effect). Some of the other statuses are there to capture very special cases.

Authentication

httpBearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

First Notice Of Loss

Resources related to getting a First Notice Of Loss form

Get Claim Selector

Returns a Claim Selector that can be used to determine the best claim type for a customer to submit a claim for

You can display a decision point to a user (starting with the referenced one in decisionPointId) and use the answers to show more decision points until either a claim type id or a point with no answer is reached. Use the claim type id to get the fnol for the user to submit a claim to.

Authorizations:
path Parameters
partnerCode
required
string
claimSelectorUuid
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

200
404

Unexpected error in API call. See HTTP response body for details.

get/partners/{partnerCode}/claim-selectors/{claimSelectorUuid}
https://staging.api.xclaim.xcover.com/partners/{partnerCode}/claim-selectors/{claimSelectorUuid}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Get Claim Types

Returns a list of claim types avaiable for the given policy type, and logged in API consumer.

Use the id of the claim type you wish to make a claim for when requesting an FNOL

Authorizations:
path Parameters
partnerCode
required
string
policyTypeName
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

200
404

Unexpected error in API call. See HTTP response body for details.

get/partners/{partnerCode}/policy-types/{policyTypeName}/claim-types
https://staging.api.xclaim.xcover.com/partners/{partnerCode}/policy-types/{policyTypeName}/claim-types

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Get Fnol

Returns data required to build a form to collect data needed to submit a claim.

Each FNOL includes 1 to n sections which contain 1 to m sectionFields.

Each sectionField has a type, which you can use to build a form element and validate the data input by cutomers. Check the Appendix for the data types currently supported.

When submitting the claim, the data should match the field type, and any of the validations it contains. Check the Appendix for a list of possible validations.

Authorizations:
path Parameters
partnerCode
required
string
claimTypeUuid
required
string
header Parameters
Content-Type
required
string
Example: application/json

Responses

200
404

Unexpected error in API call. See HTTP response body for details.

get/partners/{partnerCode}/fnol/{claimTypeUuid}
https://staging.api.xclaim.xcover.com/partners/{partnerCode}/fnol/{claimTypeUuid}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {