The Applications API from Root Insurance — 16 operation(s) for applications.
openapi: 3.1.0
info:
version: 1.0.1
title: Root Applications 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: Applications
paths:
/applications:
post:
operationId: create-application
summary: Create an application
description: '**Note:** Additional custom fields may be required depending on how the [application hook](https://docs.rootplatform.com/docs/application-hook) is configured for the product module.'
tags:
- Applications
x-additional-tags:
- Create
parameters: []
requestBody:
content:
application/json:
schema:
type: object
required:
- quote_package_id
- policyholder_id
- billing_day
properties:
quote_package_id:
type: string
description: Must be a UUID. Unique identifier of quote package retrieved in [quote generation](ref:getting-a-quote-2).
policyholder_id:
type: string
description: Must be a UUID. Unique identifier of the [policyholder](ref:policyholder) that is applying.
billing_day:
type: integer
description: The day of month on which the policy to write will be billed on. Should be between 1 and 31. If it falls on a day that does not exist in the month (for example, 31 in February) the policy to be written will be billed on the last day of that month. Setting this value to 31 will ensure that the policy to be written will be billed on the last day of every month.
minimum: 1
maximum: 31
monthly_premium:
type:
- number
- 'null'
description: '`null` is allowed. The monthly premium amount in cents. Minimum value is 0.'
minimum: 0
type:
type: string
description: The type of the application. One of `requote` or `new_policy`.
enum:
- requote
- new_policy
user_group_id:
type:
- string
- 'null'
description: '`null` is allowed. Must be a UUID. The unique identifier of the user group to assign this application to.'
additionalProperties: true
example:
quote_package_id: f4551b91-3e3e-4acc-915b-82e1b163cef8
policyholder_id: 00000000-0000-0000-0000-000000000009
billing_day: 1
serial_number: '1234567890'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application'
get:
operationId: fetch-applications
summary: List all applications
tags:
- Applications
x-additional-tags:
- Retrieve
parameters:
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
- name: search
in: query
description: A space seperated list of matching words to search for. e.g. "richard@aviato.com"
required: false
schema:
type: string
example: richard@aviato.com
- name: status
in: query
description: A comma seperated list of statuses. eg. "pending,issued"
required: false
schema:
type: string
example: pending
- name: created_by
in: query
description: A valid UUID of the user that created the application.
required: false
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
- name: user_group_id
in: query
description: A valid UUID of the user group that created the application.
required: false
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
- name: created_by_type
in: query
description: A semi-colon seperated list of the requestee types. e.g. api_key, user, legacy_api_key, legacy_user_api_key, system, product_module or embed_jwt
required: false
schema:
type: string
- name: include
in: query
description: An optional semicolon-separated list of underlying objects to include, e.g. `?include=policy;policyholder`. Valid options are 'policy', 'policyholder' and 'quote_package'
required: false
schema:
type: string
example: policyholder
- name: product_module_id
in: query
description: A valid UUID of the product module to filter applications by.
required: false
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/applications'
/applications/{application_id}:
get:
operationId: retrieve-an-application
summary: Retrieve an application
tags:
- Applications
x-additional-tags:
- Retrieve
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 40fb4335-55b2-4f20-951a-cc41097cb213
- name: include
in: query
description: An optional semicolon-separated list of underlying objects to include, e.g. `?include=policy;policyholder`. Valid options are 'policy', 'policyholder' and 'quote_package'
required: false
schema:
type: string
example: policyholder
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application'
example:
application_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
policyholder_id: bf3ab7ce-064d-43b7-811d-0ecd9aca3daf
package_name: Theft + comprehensive
sum_assured: 1199900
monthly_premium: 50000
base_premium: 14999
billing_day: 1
module:
type: root_gadgets
make: Apple
model: iPhone 6S 64GB LTE
serial_number: '1234567890'
created_at: '2017-10-12T15:47:34.281Z'
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
put:
operationId: requote-application
summary: Requote an application
description: Note that additional fields may be required based on the product module type being used. See [product modules](doc:product-modules-overview) for more details.
tags:
- Applications
x-additional-tags:
- Retrieve
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
requestBody:
content:
application/json:
schema:
type: object
properties:
quote_package_id:
type: string
description: Must be a UUID. Unique identifier of quote package retrieved in [quote generation](ref:getting-a-quote-2).
monthly_premium:
type:
- number
- 'null'
description: '`null` is allowed. Premium amount, in cents, to write on policy. This can''t be changed, only discounted by changing the `billing_amount`. This must be more than the `base_premium`. Minimum value is 0.'
minimum: 0
policyholder_id:
type: string
description: Must be a UUID. The unique identifier of the [policyholder](ref:policyholder).
billing_day:
type: integer
description: The day of month on which the policy to write will be billed on. Should be between 1 and 31.
minimum: 1
maximum: 31
additionalProperties: true
example:
monthly_premium: 50000
quote_package_id: bf3ab7ce-064d-43b7-811d-0ecd9aca3daf
billing_day: 1
serial_number: '1234567890'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application'
example:
application_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
policyholder_id: bf3ab7ce-064d-43b7-811d-0ecd9aca3daf
package_name: Theft + comprehensive
sum_assured: 1199900
monthly_premium: 50000
base_premium: 14999
billing_day: 1
module:
type: root_gadgets
make: Apple
model: iPhone 6S 64GB LTE
serial_number: '1234567890'
created_at: '2017-10-05T18:28:30.281Z'
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
/applications/{application_id}/alteration-packages:
post:
operationId: create-application-alteration-package
summary: Create an application alteration package
tags:
- Applications
x-additional-tags:
- Alteration packages
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- data
properties:
key:
type: string
description: The identifier of the application alteration hook.
data:
type: object
description: Custom module-specific fields stored against the application alteration package. See [product modules](doc:product-modules-overview) for more details.
additionalProperties: true
example:
key: update_cover_amount
data:
cover_amount: 25000000
spouse_cover: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application-alteration-packages'
example:
- alteration_package_application_id: 2d200d5c-477c-4c90-b305-e8f445f4d8e5
organization_id: 00000000-0000-0000-0000-000000000001
created_at: '2026-01-28T09:17:05.101Z'
created_by:
type: api_key
id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
owner_id: 00000000-0000-0000-0000-000000000001
module:
package_name: Funeral Cover
suggested_premium: 17500
base_premium: 16000
cover_amount: 25000000
monthly_premium: 17500
currency: ZAR
sum_assured: 25000000
billing_frequency: monthly
status: pending
change_description: Updating cover amount before issuing policy
input_data:
cover_amount: 25000000
spouse_cover: true
application_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
alteration_hook_key: update_cover_amount
/applications/{application_id}/alteration-packages/{alteration_package_id}:
get:
operationId: retrieve-application-alteration-package
summary: Retrieve an application alteration package
tags:
- Applications
x-additional-tags:
- Alteration packages
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
- name: alteration_package_id
in: path
description: Must be a UUID. The unique identifier of the application alteration package.
required: true
schema:
type: string
example: 2d200d5c-477c-4c90-b305-e8f445f4d8e5
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application-alteration-package'
example:
alteration_package_application_id: 2d200d5c-477c-4c90-b305-e8f445f4d8e5
organization_id: 00000000-0000-0000-0000-000000000001
created_at: '2026-01-28T09:17:05.101Z'
created_by:
type: api_key
id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
owner_id: 00000000-0000-0000-0000-000000000001
module:
package_name: Funeral Cover
suggested_premium: 17500
base_premium: 16000
cover_amount: 25000000
monthly_premium: 17500
currency: ZAR
sum_assured: 25000000
billing_frequency: monthly
status: pending
change_description: Updating cover amount before issuing policy
input_data:
cover_amount: 25000000
spouse_cover: true
application_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
alteration_hook_key: update_cover_amount
/applications/{application_id}/alteration-packages/{alteration_package_id}/apply:
post:
operationId: apply-application-alteration-package
summary: Apply application alteration package
tags:
- Applications
x-additional-tags:
- Alteration packages
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
- name: alteration_package_id
in: path
description: Must be a UUID. The ID of the application alteration package to apply to the application.
required: true
schema:
type: string
example: 2d200d5c-477c-4c90-b305-e8f445f4d8e5
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application-alteration-package'
example:
alteration_package_application_id: 2d200d5c-477c-4c90-b305-e8f445f4d8e5
organization_id: 00000000-0000-0000-0000-000000000001
created_at: '2026-01-28T09:17:05.101Z'
created_by:
type: api_key
id: 420df14d-b09d-4d89-84a8-8e3118c9ca23
owner_id: 00000000-0000-0000-0000-000000000001
module:
package_name: Funeral Cover
suggested_premium: 17500
base_premium: 16000
cover_amount: 25000000
monthly_premium: 17500
currency: ZAR
sum_assured: 25000000
billing_frequency: monthly
status: applied
change_description: Updating cover amount before issuing policy
input_data:
cover_amount: 25000000
spouse_cover: true
application_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
alteration_hook_key: update_cover_amount
/applications/{application_id}/attachments:
get:
operationId: retrieve-application-attachments
summary: Retrieve application attachments
tags:
- Applications
x-additional-tags:
- Attachments & notes
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
description: An object providing details regarding the file attached.
properties:
attachment_id:
type: string
description: Must be a UUID. Unique identifier of the attachment.
created_at:
type: string
format: date-time
description: The time at which the attachment was created.
file_name:
type: string
description: The name of the file.
file_type:
type: string
description: The MIME type of the file.
file_url:
type: string
description: The URL to download the file.
description:
type: string
description: A description of the attachment.
is_archived:
type: boolean
description: Whether the attachment has been archived.
requested_by:
type: object
description: An object indicating the user or API key that created the attachment.
archived_at:
type:
- string
- 'null'
format: date-time
description: '`null` is allowed. The time at which the attachment was archived.'
labels:
type: array
items:
type: string
description: An array of labels associated with the attachment.
example:
attachment_id: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
created_at: '2017-10-12T15:47:34.281Z'
file_name: doc.pdf
file_type: application/pdf
file_url: https://example.com/1234.pdf
description: Application PDF
is_archived: false
requested_by:
type: user
id: 00000000-0000-0000-0000-000000000001
labels: []
post:
operationId: add-application-attachments
summary: Add application attachment
tags:
- Applications
x-additional-tags:
- Attachments & notes
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
requestBody:
content:
application/json:
schema:
type: object
required:
- file_name
- description
- file_base64
- file_type
properties:
file_name:
type: string
description: The name of the file (filename and extension)
description:
type: string
description: A description of the file
file_base64:
type: string
description: The file contents, base64 encoded
file_type:
type: string
description: The file mime type.
example: application/pdf
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/attachment'
example:
file_name: report.pdf
file_type: application/pdf
file_url: http://yoururlhere/report.pdf
description: Police Report
type: attachment_created
application_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
created_at: '2022-01-31T11:25:23.427Z'
requested_by:
type: user
id: 00000000-0000-0000-0000-000000000001
/applications/{application_id}/attachments/{attachment_id}/archive:
post:
operationId: archive-application-attachment
summary: Archive an attachment
tags:
- Applications
x-additional-tags:
- Attachments & notes
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
- name: attachment_id
in: path
description: Must be a UUID. The unique identifier of the attachment.
required: true
schema:
type: string
example: bf1ada91-eecb-4f47-9bfa-1258bb1e0055
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
description: An event object indicating the attachment was archived.
properties:
type:
type: string
description: The type of event.
application_id:
type: string
description: Must be a UUID. The unique identifier of the application.
file_name:
type: string
description: The name of the archived file.
file_type:
type: string
description: The MIME type of the archived file.
file_url:
type: string
description: The URL of the archived file.
description:
type: string
description: A description of the archived file.
created_at:
type: string
format: date-time
description: The time at which the attachment was archived.
requested_by:
type: object
description: An object indicating the user or API key that archived the attachment.
example:
type: attachment_archived
application_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
file_name: report.pdf
file_type: application/pdf
file_url: https://example.com/report.pdf
description: Police Report
created_at: '2023-02-03T12:00:00.000Z'
requested_by:
type: user
id: 00000000-0000-0000-0000-000000000001
/applications/{application_id}/beneficiaries:
get:
summary: List beneficiaries
operationId: fetch-application-beneficiaries
tags:
- Applications
x-additional-tags:
- Beneficiaries
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/beneficiaries'
put:
operationId: update-application-beneficiaries
summary: Update beneficiaries
description: This endpoint accepts an array of beneficiary objects as the body. The entire array of beneficiaries will be replaced. The number of beneficiaries cannot exceed the max defined in the [general settings](doc:general-settings). The percentages must add up to 100%.
tags:
- Applications
x-additional-tags:
- Beneficiaries
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/beneficiaries-request'
example:
$ref: '#/components/schemas/beneficiaries-request/example'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/application'
example:
application_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
policyholder_id: bf3ab7ce-064d-43b7-811d-0ecd9aca3daf
package_name: Theft + comprehensive
sum_assured: 1199900
monthly_premium: 50000
base_premium: 14999
billing_day: 1
module:
type: root_gadgets
make: Apple
model: iPhone 6S 64GB LTE
serial_number: '1234567890'
created_at: '2017-10-12T15:47:34.281Z'
created_by:
id: 00000000-0000-0000-0000-000000000001
type: user
beneficiaries:
- first_name: Jared
last_name: Dunn
id:
type: id
number: '8704094800082'
country: ZA
percentage: 100
relationship: cousin_or_relative
/applications/{application_id}/notes:
get:
operationId: retrieve-application-notes
summary: Retrieve application notes
tags:
- Applications
x-additional-tags:
- Attachments & notes
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/notes'
post:
operationId: add-application-notes
summary: Add application notes
tags:
- Applications
x-additional-tags:
- Attachments & notes
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
requestBody:
content:
application/json:
schema:
type: object
properties:
text:
type: string
description: The string of text to add as a note
required:
- text
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/note'
/applications/{application_id}/events:
get:
operationId: retrieve-application-events
summary: Retrieve application events
tags:
- Applications
x-additional-tags:
- Retrieve
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
type: string
example: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
description: An event object containing details about an action that occurred on the application. Events include application events, notification events, and user group event logs.
properties:
type:
type: string
description: The type of event.
application_id:
type: string
description: Must be a UUID. The unique identifier of the application.
created_at:
type: string
format: date-time
description: The time at which the event occurred.
requested_by:
type: object
description: An object indicating the user or API key that triggered the event.
example:
- type: application_created
application_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
created_at: '2023-02-03T11:17:49.009Z'
requested_by:
type: api_key
id: b6565862-cc6e-4563-85d3-659894338cda
owner_id: e17f06ce-2a6a-4864-b826-19a83270eab4
- type: attachment_created
application_id: 128ba0c0-3f6a-4f8b-9b40-e2066b02b59e
file_name: report.pdf
file_type: application/pdf
file_url: https://example.com/report.pdf
description: Police Report
created_at: '2023-02-03T12:00:00.000Z'
requested_by:
type: user
id: 00000000-0000-0000-0000-000000000001
/applications/{application_id}/payment-method:
get:
operationId: retrieve-application-payment-method
summary: Retrieve application payment method
tags:
- Applications
x-additional-tags:
- Billing & payments
parameters:
- name: application_id
in: path
description: Must be a UUID. The unique identifier of the [application](ref:application).
required: true
schema:
# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/root/refs/heads/main/openapi/root-applications-api-openapi.yml