The Claims API from Root Insurance — 31 operation(s) for claims.
openapi: 3.1.0
info:
version: 1.0.1
title: Root Applications Claims API
description: Root is an end-to-end digital insurance platform that enables you to launch new products and digital engagement channels fast.
termsOfService: https://rootplatform.com/about
contact:
name: Root support team
url: https://rootplatform.com/contact
email: support@root.co.za
servers:
- url: https://sandbox.uk.rootplatform.com/v1/insurance
description: United Kingdom multi-tenant - sandbox
- url: https://api.uk.rootplatform.com/v1/insurance
description: United Kingdom multi-tenant - production
- url: https://sandbox.rootplatform.com/v1/insurance
description: South Africa multi-tenant - sandbox
- url: https://api.rootplatform.com/v1/insurance
description: South Africa multi-tenant - production
security:
- basicAuth: []
tags:
- name: Claims
paths:
/claims:
post:
operationId: create-claim
summary: Create a claim
description: Creates a new claim. The claim can optionally be linked to a policy, member, or covered item. A claimant can be specified with contact details.
tags:
- Claims
x-additional-tags:
- Create
parameters:
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
requestBody:
content:
application/json:
schema:
type: object
properties:
policy_id:
type:
- string
- 'null'
description: Must be a UUID. The identifier of the [policy](ref:policy) on which the claim is being made.
member_id:
type:
- string
- 'null'
description: Must be a UUID. The identifier of the member for this claim. Only used for group scheme policies.
covered_item_id:
type:
- string
- 'null'
description: Must be a UUID. The identifier of the covered item that this claim is against. Required if the policy supports covered items.
assigned_to_user_id:
type:
- string
- 'null'
description: Must be a UUID. The identifier of the user to assign this claim to.
incident_type:
type:
- string
- 'null'
description: A description of the incident type.
incident_cause:
type:
- string
- 'null'
description: A description of the cause of the incident.
incident_date:
type:
- string
- 'null'
format: date-time
description: The date on which the incident occurred.
app_data:
type:
- object
- 'null'
description: An object containing additional custom data for the claim.
additionalProperties: true
claimant:
type: object
description: Object containing claimant's details. At least one of `email` or `cellphone` must be provided.
properties:
first_name:
type: string
description: The first name of the claimant.
last_name:
type: string
description: The last name of the claimant.
email:
type: string
description: The claimant's email address. Required if `cellphone` is not provided.
cellphone:
oneOf:
- $ref: '#/components/schemas/cellphone'
- $ref: '#/components/schemas/cellphone-string'
description: The claimant's cellphone number. Required if `email` is not provided.
id_number:
type: string
description: The ID number of the claimant.
relationship:
type: string
description: The relationship of the claimant to the policyholder.
required:
- first_name
- last_name
requested_amount:
type: integer
description: The requested payout amount (in cents) for the claim.
example:
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
member_id: 673b8081-9668-4136-97cc-6ae0debda083
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
incident_type: Theft
incident_cause: Device stolen during burglary
incident_date: '2017-10-16T10:12:02.872Z'
app_data:
key1: value 1
key2: value 2
claimant:
first_name: Erlich
last_name: Aviato
email: erlich@aviato.com
cellphone: 0821234567
requested_amount: 13000000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
claim_number: D33B754ADA8F
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:12:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
policyholder_id: 00000000-0000-0000-0000-000000000004
member_id: 673b8081-9668-4136-97cc-6ae0debda083
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
claim_status: open
approval_status: pending
currency: ZAR
app_data:
key1: value 1
key2: value 2
claimant:
first_name: Erlich
last_name: Aviato
email: erlich@aviato.com
cellphone: 0821234567
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
get:
operationId: fetch-claims
summary: List all claims
description: Returns a paginated list of claims for the organization. Use the query parameters to filter claims by status, policy, policyholder, and more. Use the `include` parameter to include related objects in the response.
tags:
- Claims
x-additional-tags:
- Retrieve
parameters:
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
- name: claim_status
in: query
description: Filter by claim status. Accepts multiple values.
required: false
schema:
type: array
items:
type: string
enum:
- open
- in_review
- acknowledged
- pending_payout
- paid_out
- closed
style: form
explode: false
example: open,in_review
- name: approval_status
in: query
description: Filter by approval status. Accepts multiple values.
required: false
schema:
type: array
items:
type: string
enum:
- pending
- approved
- repudiated
- no_claim
- goodwill
style: form
explode: false
example: pending,approved
- name: search
in: query
description: Search claims by claim number, claimant name, or other searchable fields.
required: false
schema:
type: string
example: D33B754
- name: policyholder_id
in: query
description: Must be a UUID. Filter claims by policyholder ID.
required: false
schema:
type: string
example: 00000000-0000-0000-0000-000000000004
- name: product_module_id
in: query
description: Must be a UUID. Filter claims by product module ID.
required: false
schema:
type: string
example: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
- name: policy_id
in: query
description: Must be a UUID. Filter claims by policy ID.
required: false
schema:
type: string
example: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
- name: created_by
in: query
description: Must be a UUID. Filter claims by the ID of the user or API key that created them.
required: false
schema:
type: string
example: 00000000-0000-0000-0000-000000000001
- name: created_by_type
in: query
description: Filter claims by the type of entity that created them.
required: false
schema:
type: string
enum:
- user
- api_key
example: user
- name: assigned_to
in: query
description: Must be a UUID. Filter claims by the user they are assigned to.
required: false
schema:
type: string
example: 00000000-0000-0000-0000-000000000001
- name: user_group_id
in: query
description: Must be a UUID. Filter claims by user group ID.
required: false
schema:
type: string
example: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
example: policy,policyholder
responses:
'200':
description: Success
headers:
X-Total-Count:
description: The total number of claims matching the query.
schema:
type: integer
example: 42
content:
application/json:
schema:
$ref: '#/components/schemas/claims'
example:
- claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
claim_number: D33B754ADA8F
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
policyholder_id: 00000000-0000-0000-0000-000000000004
member_id: 673b8081-9668-4136-97cc-6ae0debda083
claim_status: open
approval_status: pending
claimant:
first_name: Erlich
last_name: Aviato
email: erlich@aviato.com
currency: ZAR
app_data:
key1: value 1
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
- claim_id: cf5f074e-e09f-4d85-bc2d-07cfcae63f30
claim_number: CF5F074EDA8F
created_at: '2017-10-14T11:09:55.332Z'
updated_at: '2017-10-14T12:00:00.000Z'
policy_id: 76096ff5-f4ed-47e2-8ac0-de16ba095508
policyholder_id: 00000000-0000-0000-0000-000000000005
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
claim_status: closed
approval_status: approved
currency: ZAR
requested_amount: 2000000
granted_amount: 1870000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}:
get:
operationId: retrieve-a-claim
summary: Retrieve a claim
tags:
- Claims
x-additional-tags:
- Retrieve
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
claim_number: D33B754ADA8F
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
policyholder_id: 00000000-0000-0000-0000-000000000004
member_id: 673b8081-9668-4136-97cc-6ae0debda083
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
claim_status: open
approval_status: pending
currency: ZAR
app_data:
key1: value 1
key2: value 2
claimant:
first_name: Erlich
last_name: Aviato
email: erlich@aviato.com
requested_amount: 13000000
granted_amount: 9400000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
patch:
operationId: updating-a-claim
summary: Update a claim
tags:
- Claims
x-additional-tags:
- Manage
parameters:
- name: claim_id
in: path
description: The unique identifier of the [claim](ref:claim)
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
requestBody:
content:
application/json:
schema:
type: object
properties:
incident_type:
type: string
description: A description of the incident type.
incident_cause:
type: string
description: A description of the cause of the incident.
incident_date:
type: string
format: date-time
description: The date on the which the incident occurred.
app_data:
type:
- object
- 'null'
description: '`null` is allowed. An object containing additional custom data for the claim.'
additionalProperties: true
requested_amount:
type: integer
description: The requested payout amount (in cents) for the claim.
example:
incident_type: Theft
incident_cause: Device stolen during burglary
incident_date: '2017-10-16T10:12:02.872Z'
app_data:
key3: value3
requested_amount: 13000000
example:
incident_type: Theft
incident_cause: Device stolen during burglary
incident_date: '2017-10-16T10:12:02.872Z'
app_data:
key3: value3
requested_amount: 13000000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2017-10-16T10:12:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
member_id: 673b8081-9668-4136-97cc-6ae0debda083
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
claim_status: open
approval_status: pending
app_data:
key3: value 3
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}/acknowledge-approved:
post:
operationId: acknowledge-approved
summary: Acknowledge approval
description: Acknowledges a claim approval decision, transitioning the claim to pending payout.
tags:
- Claims
x-additional-tags:
- Supervisor decision
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: A reason for acknowledging the approval.
example:
reason: Claim meets approval criteria.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
policyholder_id: 00000000-0000-0000-0000-000000000004
claim_status: pending_payout
approval_status: approved
claim_number: D33B754ADA8F
currency: ZAR
claimant:
email: erlich@aviato.com
first_name: Erlich
last_name: Aviato
relationship: main_member
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}/acknowledge-goodwill:
post:
operationId: acknowledge-goodwill
summary: Acknowledge goodwill
description: Acknowledges a goodwill claim decision, transitioning the claim to pending payout.
tags:
- Claims
x-additional-tags:
- Supervisor decision
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: A reason for acknowledging the goodwill decision.
example:
reason: Claim meets goodwill criteria.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
policyholder_id: 00000000-0000-0000-0000-000000000004
claim_status: pending_payout
approval_status: goodwill
claim_number: D33B754ADA8F
currency: ZAR
claimant:
email: erlich@aviato.com
first_name: Erlich
last_name: Aviato
relationship: main_member
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}/acknowledge-no-claim:
post:
operationId: acknowledge-no-claim
summary: Acknowledge no claim
description: Acknowledges a no-claim decision, finalizing the claim as no-claim.
tags:
- Claims
x-additional-tags:
- Supervisor decision
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: A reason for acknowledging the no-claim decision.
example:
reason: Claim is inside the waiting period.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
claim_number: D33B754ADA8F
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
policyholder_id: 00000000-0000-0000-0000-000000000004
claim_status: acknowledged
approval_status: no_claim
rejection_reason: Claim is within waiting period
currency: ZAR
claimant:
email: erlich@aviato.com
first_name: Erlich
last_name: Aviato
relationship: main_member
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}/acknowledge-repudiated:
post:
operationId: acknowledge-repudiated
summary: Acknowledge repudiation
description: Acknowledges a claim repudiation decision, finalizing the claim as repudiated.
tags:
- Claims
x-additional-tags:
- Supervisor decision
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: A reason for acknowledging the repudiation.
example:
reason: Claim is not covered under the terms and conditions of the policy.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
covered_item_id: 9dc39b57-cdc7-48f9-a303-d7c4f0421a0c
policyholder_id: 00000000-0000-0000-0000-000000000004
claim_status: acknowledged
approval_status: repudiated
claim_number: D33B754ADA8F
currency: ZAR
claimant:
email: erlich@aviato.com
first_name: Erlich
last_name: Aviato
relationship: main_member
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}/approve:
post:
operationId: approve-claim
summary: Approve claim
description: Approves a claim and optionally specifies payees for the payout. Multiple payees can be specified to split the payout amount.
tags:
- Claims
x-additional-tags:
- Assessor decision
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policy`, `policyholder`, `user_group`.'
required: false
schema:
type: array
items:
type: string
enum:
- policy
- policyholder
- user_group
style: form
explode: false
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: A reason for the claim approval decision.
assigned_to_user_id:
type: string
description: Must be a UUID. The identifier of the user to assign this claim to.
payee:
type: array
description: An array of payee objects specifying who should receive the payout.
items:
type: object
required:
- id
- amount
- type
properties:
id:
type: string
description: Must be a UUID. The ID of the beneficiary or policyholder to be paid out.
amount:
type: integer
description: The amount in cents to be paid to the beneficiary or policyholder.
type:
type: string
description: The type of payee.
enum:
- policyholder
- beneficiary
example:
reason: Claim meets the approval criteria.
payee:
- id: 00000000-0000-0000-0000-000000000004
amount: 13000000
type: policyholder
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim'
example:
claim_id: d3d13c48-4dc3-4816-8d01-de3215878225
claim_number: D33B754ADA8F
created_at: '2017-10-16T10:12:02.872Z'
updated_at: '2017-10-16T10:15:02.872Z'
policy_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
policyholder_id: 00000000-0000-0000-0000-000000000004
claim_status: in_review
approval_status: approved
currency: ZAR
claimant:
email: erlich@aviato.com
first_name: Erlich
last_name: Aviato
relationship: main_member
requested_amount: 13000000
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/claims/{claim_id}/attachments:
get:
operationId: retrieve-claim-attachments
summary: List claim attachments
description: Returns a paginated list of attachments for a claim.
tags:
- Claims
x-additional-tags:
- Attachments & notes
parameters:
- name: claim_id
in: path
description: Must be a UUID. The unique identifier of the [claim](ref:claim).
required: true
schema:
type: string
example: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `embedding`.'
required: false
schema:
type: array
items:
type: string
enum:
- embedding
style: form
explode: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/attachments'
example:
attachment_id: 1dc7b3c6-a921-11ed-bad6-736a4495dd42
file_name: report.pdf
file_type: application/pdf
file_url: http://yoururlhere/report.pdf
description: Police Report
created_at: '2022-01-31T11:25:23.427Z'
requested_by:
type: user
id: 00000000-0000-0000-0000-000000000001
post:
operationId: claim-create-attachment
summary: Create an attachment
tags:
- Claims
x-additional-tags:
- Attachments & notes
parameters:
- name: claim_id
in: path
description: The unique identifier of the [claim](ref:claim).
# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/root/refs/heads/main/openapi/root-claims-api-openapi.yml