Claim API

Listing a customer’s claims

URL	/api/v3/claim/all/?page=<page number>&per_page=<page size>
Methods	GET

Key	Type	Description
page number	Integer	Optional GET parameter to indicate the page of policies to be returned. Defaults to 1 if no page number is provided, or is not greater than 0.
per page	Integer	Optional GET parameter to indicate the size of each page in response. Default value is 100 records per page

Calling the above endpoint will return a list of claims that the currently authenticated customer has made.

If the customer has more than 100 claims, then the results will automatically be paginated into blocks of 100 claims. Different pages of claims can be requested by using the option “page” GET parameter.

In addition, you can request larger sets of data by using the “per_page” GET parameter. The maximum page size is 1000.

Here is an example response for a customer that has made a single claim

{
    "claims": [
        {
            "claim_number": "CLAIM_1",
            "policy_number": "POLICY_1",
            "product_name": "Product 1",
            "subproduct_name": "Subproduct A",
            "coverage_item": "Lost luggage",
            "status": "new",
            "created_timestamp": "2001-01-01T13:58:44.715344+00:00",
            "amount": "100.00",
            "reserve_amount": "50.00",
            "deductible_amount": "50.00",
            "currency": "USD",
            "age_since_submitted": 12,
            "age_in_current_state": 2
        }
    ]
}

Key	Type	Description
claim_number	String	The unique number assigned to this claim.
policy_number	String	The unique policy number associated to with this claim
product_name	String	The name of the product which the claim is against
subproduct_name	String	The name of the subproduct which the claim is against
status	String	The current state of the claim. See Claim Statuses for currently supported states.
created_timestamp	String	An string which contains the ISO formatted timestamp for when the claim was created. The timezone for this timestamp is UTC.
amount	Decimal	The amount the claim is for
reserve_amount	Decimal	The initial estimate amount the claim is for
deductible_amount	Decimal	The difference from amount the claim is for
approved_amount	Decimal	The amount that been approved for this claim
currency	String	A string representing the currency the claim amount is in
coverage_item	String	The name of the coverage item which the claim is against.
age_since_submitted	Integer	The number of days since the claim was confirmed and submitted to the system.
age_in_current_state	Integer	The number of days the claim has been in the current state
partnership	String	A string representation of the partnership that is associated with the policy product. If no partnerships is defined this value will be null.

Errors

This endpoint will raise a 401 error code if you attempt to access it without previously authenticating a customer user with your session.

Code	Reason
401	Customer not authenticated.

Please refer to the Error Handling section for further details, on errors and error handling.

View a claim

URL	/api/v3/claim/<claim number>/
Methods	GET

Key	Type	Description
claim number	String	The unique claim number for the specific claim you wish to view.

You can view the details of an existing claim by making a call to the above endpoint. You can only access claims for the currently authenticated customer.

The following shows an example of a response to view a claim.

{
    "claim_number": "CLAIM_1",
    "policy_number": "POLICY_1",
    "product_name": "Product 1",
    "subproduct_name": "Subproduct A",
    "status": "submit",
    "created_timestamp": "2001-01-01T13:58:44.715344+00:00",
    "amount": "100.00",
    "reserve_amount": "50.00",
    "deductible_amount": "50.00",
    "currency": "USD",
    "coverage_item": "Lost luggage",
    "notes": [
        {
            "description": "Claim created",
            "timestamp": "2001-01-01T13:58:44.715344+00:00"
        },
        {
            "description": "Additional information required",
            "timestamp": "2001-01-01T14:30:00.105210+00:00"
        }
    ],
    "parternship": "Partner A"
}

Key	Type	Description
claim_number	String	The unique number assigned to this claim.
policy_number	String	The policy number that the claim is against.
product_name	String	The name of the product which the claim is against
subproduct_name	String	The name of the subproduct which the claim is against
status	String	The current state of the claim. See Claim Statuses for currently supported states.
created_timestamp	String	An string which contains the ISO formatted timestamp for when the claim was created. The timezone for this timestamp is UTC.
amount	Decimal	The amount the claim is for.
reserve_amount	Decimal	The initial estimate amount the claim is for
deductible_amount	Decimal	The difference from amount the claim is for
approved_amount	Decimal	The amount that been approved for this claim
currency	String	A string representing the currency the claim amount is in
coverage_item	String	The name of the coverage item which the claim is against.
notes	List	A list of objects each representing information about the claim and the states it has progressed through. Each object will have a description and timestamp key
partnership	String	A string representation of the partnership that is associated with the policy product. If no partnerships is defined this value will be null.

Errors

This endpoint will raise a 404 error code if the claim number submitted doesn’t exist on the platform.

Code	Reason
404	The claim you requested doesn’t exist

Please refer to the Error Handling section for further details, on errors and error handling.

Claim meta data

URL	/api/v3/claim/meta/<coverage item slug>/
Methods	GET

Key	Type	Description
coverage item slug	String	The unique coverage item slug which you wish to create a claim for.

Along with helpful information e.g. the the steps in form sequence to file a claim with the system. The insurer can also define additional introductory information (see “intro” key) which should be presented to the user before the are shown the first form in the sequence. If, however, the insurer has not defined any introduction information, then the user can be moved onto the first form in sequence.

{
    "name": "Sub Product A",
    "intro": {
        "image": "http://www.democrance.com/brand.jpg",
        "title": "Claim",
        "content": "Introductory information to be displayed to the user",
    },
    "terms_and_conditions": {
        "short": "",
        "long": ""
    },
    "attachments": {
        "terms_and_conditions": "http://www.democrance.com/tandc.pdf",
        "schedule_of_benefits": "",
        "claims_form": "TBC"
    },
    "form_sequence": [
        {"id": "form_1", "title": "Your Details"},
        {"id": "form_2", "title": "Additional Information"}
    ]
}

Key	Type	Description
name	String	The name of subproduct which this meta data relates to in terms of creating a claim.
intro.image	String	The URL for a banner image to be displayed on the meta page, or null if no image.
intro.title	String	A heading to display on the intro page, or null if not headline is defined.
intro.content	String	Any introductory information to be displayed to the user, or null if not defined.
terms_and_conditions.short	String	The short terms and conditions as defined by the insurer.
terms_and_conditions.long	String	The full terms and conditions as defined by the insurer.
attachments.terms_and_conditions	String	The URL to a downloadable version of the terms and conditions (if available), or null.
attachments.schedule_of_benefits	String	The URL to a downloadable version of the schedule of benefits (if available), or null.
attachments.claims_form	String
form_sequence	List	A list of objects. Each object represents a unique identifier for the step and a title that can be displayed to the user.

Note

See How to create a claim for an example of how this can be used.

Submit claim form data

URL	/api/v3/claim/submit/<coverage item slug>/
Methods	GET, POST

Key	Type	Description
coverage item slug	String	The unique coverage item slug which you wish to create a claim for.

This endpoint can be called with either a GET or POST request. If a GET request or a POST request with no JSON payload, then the server will respond with the first form in the sequence of forms. Otherwise a POST request with data will trigger the data validation process. In either case, the server will respond with the following:

{
    "claim_number": "CLAIM_1",
    "description": {
        "image": "",
        "title": "",
        "content": ""
    },
    "form": {},
    "has_errors": false
}

Key	Type	Description
claim_number	String	A unique number given to a customer which represents a specific claim.
description.image	String	A string to be used as a headline for the form, or null if no headline is required.
description.title	String	A URL to an image to displayed along with the form, or null if not image to display.
description.content	String	A HTML string contain additional description to be be displayed along with the form, or null if no description needed.
form	Dict	An object representing the form schema which needs to be completed. See ?? for details about form schemas.
has_errors	Boolean	A boolean flag to indicated if the form has an errors. This will be false if you are requesting the form.

The ‘claim_number’ key in the response object will be empty when you request the first form. On successful submission of the first form, this value will contains the newly created claims number for the claim being completed. You should submit this claim number in all future submissions so that the claims data is associated with the correct claim.

The insurer might also provide additional information to be displayed along with each form that is to be presented to the user. This information will appear in the ‘description’ key of the JSON data (if applicable).

Upload attachment

URL	/api/v3/claim/<claim number>/attachment/add/
Methods	POST

Key	Type	Description
claim number	String	The unique claims number that you wish to upload an attachment for.

This endpoint provides a method to upload a document which will be attached to a specific claim, based upon the claim number in the URL. The upload process is perform asynchronously to the claim form submission process, but the result will be needed in the claim form submission.

When caling this endpoint you will need to create JSON payload where the document data is encodes as a Base64 encoded string along with other meta data.

{
    "data": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...",
    "name": "medical report"
}

Key	Type	Description
data	String	A Base64 encoded string of the document data. This should take the standard format of data:mimetype;base64,encoded_file_data.
name	String	The fileupload input name, or other name to associate with the uploaded document.

Upon successful upload of a document, the server will respond with a unique file reference, which can then be used to access the document, thumbnails and also reference when submitting a form which requires documents to be submitted.

{
    "file_reference": "eyJjbGFpbV91dWlkIjoiQ0xBSU1TMDIyOTgzMDMi...",
}

Key	Type	Description
file_reference	String	A unique reference number for the uploaded attachement. You will need this value to access the attachment, as well as when submitting forms that require attachments.

Get attachment

URL	/api/v3/claim/<claim number>/attachment/get/<file reference>/
Methods	GET

Key	Type	Description
claim number	String	The unique claims number that you wish to upload an attachment for.
file reference	String	A file reference for a specific uploaded attachment for the specified claim

Calling this endpoint with a valid file reference will return you with a response that contains the document data.

Get attachment thumbnail

URL	/api/v3/claim/<claim number>/attachment/thumbnail/<file reference>/
Methods	GET

Key	Type	Description
claim number	String	The unique claims number that you wish to upload an attachment for.
file reference	String	A file reference for a specific uploaded attachment for the specified claim

Confirm claim creation

URL	/api/v3/claim/<claim number>/confirm/
Methods	GET, POST

Key	Type	Description
claim number	String	The unique claims number that you wish to review and confirm.

Calling this endpoint with a GET request or a POST request without a JSON payload will result in the current claim form data being returned in a readonly format, along with a form which the user should complete and submit to confirm they wish to submit the claim details.

{
    "submitted_data": {
        "form 1": {
            "First name": "John",
            "Last name": "Doe"
        },
        "form 2": {
            "Beneficiary's Name": "Jane Doe"
        }
    },
    "form": {},
}

Key	Type	Description
submitted_data	Dict	An object which contains a list of attributes, each represent a form in the sequence of forms that were submitted. Each of these attributes will itself be an object contains a key value for each input the user has provided.
form	Dict	An object representing the form confirmation form schema which needs to be completed. See ?? for details about form schemas

Making a POST request with the submission form data will trigger the server to validate the confirmation form, and then start the processing of the claim details and notifying the insurer.

If the validation of the confirmation form fails, then the readonly version of the data along with the confirmation form and a success key will be return e.g.

{
    "submitted_data": {
        "form 1": {
            "First name": "John",
            "Last name": "Doe"
        },
        "form 2": {
            "Beneficiary's Name": "Jane Doe"
        }
    },
    "form": {},
    "success": false
}

Key	Type	Description
submitted_data	Dict	An object which contains a list of attributes, each represent a form in the sequence of forms that were submitted. Each of these attributes will itself be an object contains a key value for each input the user has provided.
form	Dict	An object representing the form confirmation form schema which needs to be completed. See ?? for details about form schemas
success	Boolean	A boolean value to indicate if the confirmation form was validated successfully.

If validation was success and the claim is being processed then the server will respond with the following:

{
    "success": true,
    "description": {
        "title": "Claim submitted succesfully",
        "image": "http://www.democrance.com/success.jpg",
        "content": "Thank you for your claim submission.  It is currently being processed and one of our customer service agents will be in touch."
    }
}

Key	Type	Description
success	Boolean	A boolean value to indicate if the confirmation form was validated successfully.
description.title	String	An optional title to be displayed when the claim has been submitted successfully.
description.image	String	An optional URL to an image to be displayed when the claim has been submitted successfully.
description.content	String	An optional piece of text to be displayed when the claim has been submitted successfully.

How to create a claim

Claims can be created, but completing all the forms as defined by the subproduct.

The first step to creating a claim should be to call the claims meta data endpoint (see Claim meta data). This will provide you with information about the claims process for the subproduct, including if there is a intro page that should be display along with the name and number of each step in the claim process.

After displaying the meta data and displaying any information required, you should the first request to the submit claim form data endpoint (see Submit claim form data). This initial call should be either a GET or an empty POST request, and will return you the first form to complete.

Once you have completed the form, submit the data back to the server for validation.

If the form is valid, the server will respond with either the next form in the claims process (if there is one), or indicate that there are no more forms to complete. At this point you should offer the customer a chance to review the details submitted, before confirming the claim.

If the form data was not valid, the server will respond with the form data you submitted along with error messages for reason that it failed validation. At this point correct the errors and resubmit the form.

Continue Claim

URL	/api/v3/claim/continue/<signed claim number>/
Methods	GET

Key	Type	Description
signed claim number	String	A signed claim number which needs to be accessed

Customers would need to have access to the claim which they wish to continue and modify. This endpoint verifies the token and in the background also sets up the request session so that the customer can access the claim seamlessly.

Errors

This endpoint will raise a 403 error code if you attempt to access it with an invalid token. In addition, this endpoint will raise a 404 error code if the claim id submitted doesn’t exist on the platform, or the claim is not marked with a status which allows continuation of the claim.