Claims blocks reference
Customise the information that needs to be captured on a claim
Overview
This guide is a reference for the different display and form element block types that can be included in a claims blocks schema. Read more about how claims blocks fit into the broader claims workflow in the claims workflow overview guide. Read more about how claims blocks work and how they are linked to other aspects of the product module build in the claims blocks overview guide.
Block categories
Three categories of blocks can be defined in the claims blocks schema:
- Display blocks- These blocks neither accept nor store any input. They are included in the claim's block states but do not have a value attribute.
- Form element blocks- These blocks render on the claim description form as form inputs. They accept and store input values in block states.
- Disbursement blocks - This is a special category of blocks that facilitate the transfer of monetary and non-monetary compensation to beneficiaries.
Alert
A text block that displays important information to the user. You can specify one of a predefined set of color schemes to customise the alert's meaning or severity.
Properties
| Property | Definition |
|---|---|
"key" | String. The unique identifier of this block. |
"type" | String. The block type. In this case, "alert". |
"markdown" | String. The content that will be parsed as markdown and rendered inside the alert. |
"color" | String. Sets the display color of the alert to indicate severity. One of ["success", "danger", "warning", "info"]. |
Example
{
"block": {
"key": "claim_within_waiting_period",
"type": "alert",
"markdown": "This claim is still within the waiting period.",
"color": "warning"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type. In this case, "alert". |
{
"claim": {
"block_states": {
"claim_within_waiting_period": {
"type":"alert"
}
},
...
}
}Heading
A text block that will render a heading on screen. Useful for grouping input fields under the same category.
Properties
| Property | Definition |
|---|---|
"key" | String. The unique identifier for this block. |
"type" | String. The block type, in this case "heading". |
"title" | String. The text that will be rendered as a heading. |
Example
{
"block": {
"key": "payout_details",
"type": "heading",
"title": "Payout details"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "heading". |
{
"claim": {
"block_states": {
"payout_details": {
"type":"heading"
}
},
...
}
}Markdown
A text block that will parse and render given text content according to the markdown specification.
Properties
| Property | Definition |
|---|---|
"key" | String. The unique identifier for this block |
"type" | String. The block type, in this case "markdown". |
"markdown" | String. The content to be parsed as markdown and rendered. |
Example
{
"block": {
"key": "fsca_information",
"type": "markdown",
"markdown": "For more information see [here](https://www.fsca.co.za/)"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "markdown". |
{
"claim": {
"block_states": {
"fsca_information": {
"type":"markdown"
}
},
...
}
}Divider
A block that will render a horizontal line on screen to separate sections of input fields.
Properties
| Property | Definition |
|---|---|
"key" | String .The unique identifier for this block |
"type" | String. The block type, in this case "divider". |
Example
{
"block": {
"key": "section_divider",
"type": "divider"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "divider". |
{
"claim": {
"block_states": {
"section_divider": {
"type":"divider"
}
},
...
}
}Form element blocks
Checkbox
A boolean block that stores true if checked and false if unchecked. The user interface renders a single checkbox element with a description.
Properties
| Property | Definition |
|---|---|
"key" | String. The unique identifier for this block. |
"type" | String. The block type, in this case "checkbox". |
"title" | String. The text heading that will be displayed above the checkbox element. |
"default_value" | Boolean. The default value of the block before the user enters a value. One of [true, false]. |
Example
{
"block": {
"key": "documents_uploaded",
"type": "checkbox",
"title": "Have the necessary documents been uploaded?",
"default_value": true
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "checkbox". |
"value" | Boolean. The currently stored value value of the block. One of [true, false]. |
{
"claim": {
"block_states": {
"documents_uploaded": {
"type": "checkbox",
"value": true
}
},
...
}
}Radio block
This block renders a list of radio buttons, of which one can be selected. Each option has a key and a value attribute. Both the key and the value of the selected option are persisted to the block state.
For each option, the label displayed next to the corresponding radio button will be the option value, in title case.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "was_third_party_insured",
"type": "radio",
"title": "Was the third party insured?",
"description": "Was the third party vehicle involved in the accident insured?",
"default_value": "No",
"options": [
{
"key": "no",
"value": "No"
},
{
"key": "yes",
"value": "Yes"
},
]
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "radio". |
"option_value" | String. The value of the option currently selected. |
"option_key" | String. The key of the option currently selected. |
{
"claim": {
"block_states": {
"was_third_party_insured": {
"type": "radio",
"option_value": "No",
"option_key": "no"
}
},
...
}
}Dropdown
Renders a dropdown element with a list of options, from which the user can select one option. Each option has a key and a value attribute. Both the key and the value of the selected option are persisted to the block state.
For each option, the label displayed in the dropdown list will be the option value, in title case.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "bank_for_payout",
"type": "dropdown",
"title": "Select bank for payout:",
"options": [
{
"key": "absa",
"value": "ABSA"
},
{
"key": "fnb",
"value": "FNB"
},
{
"key": "capitec",
"value": "Capitec"
},
{
"key": "investec",
"value": "Investec"
},
{
"key": "nedbank",
"value": "Nedbank"
},
{
"key": "standard_bank",
"value": "Standard Bank"
},
],
"default_value": "FNB"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "dropdown". |
"option_value" | String. The value of the option currently selected. |
"option_key" | String. The key of the option currently selected. |
{
"claim": {
"block_states": {
"bank_for_payout": {
"type": "dropdown",
"option_value": "FNB",
"option_key": "fnb"
}
},
...
}
}Input currency
A numeric block designated with a specified currency. Renders an interactive input element that displays the currency symbol and two decimal points. The values are persisted as integers in cents on the block’s state.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "payout_amount",
"type": "input.currency",
"title": "Payout amount",
"isoCode": "ZAR",
"placeholder": 10000000,
"max": 25000000,
"min": 5000000,
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "input.currency". |
"value" | Integer. The current value of the block. |
{
"claim": {
"block_states": {
"payout_amount": {
"type": "input.currency",
"value": 10000000
}
},
...
}
}Input number
A numeric block that accepts an integer or floating point value. The user interface renders an interactive input element that only accepts numeric input.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "number_of_beneficiaries",
"type": "input.number",
"title": "Number of beneficiaries",
"placeholder": 1,
"max": 5,
"min": 1
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "input.number". |
"value" | Integer. The current value of the block. |
{
"claim": {
"block_states": {
"number_of_beneficiaries": {
"type": "input.number",
"value": 1
}
},
...
}
}Input text
A free text element used to capture shorter string fields.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "name_of_account_holder",
"type": "input.text",
"title": "Account holder name",
"description": "The payout will be made to the account holder specified below.",
"placeholder": "Mr John Doe",
"max_length": 25,
"min_length": 5
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "input.text". |
"value" | String. The current value of the block. |
{
"claim": {
"block_states": {
"name_of_account_holder": {
"type": "input.text",
"value": "Mr John Doe"
}
},
...
}
}Input paragraph
This block is used to capture longer text input, for example where a full description of the incident needs to be captured. It renders as a form input into which the user can enter a paragraph of text.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "incident_description",
"type": "input.paragraph",
"title": "Incident description",
"placeholder": "On the date of the incident, the following occurred...",
"max_length": 500,
"min_length": 150
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "input.paragraph". |
"value" | String. The current value of the block. |
{
"claim": {
"block_states": {
"incident_description": {
"type": "input.paragraph",
"value": "On the date of the incident, the following occurred..."
}
},
...
}
}Input time
A block that accepts the time of day in the ISO 8601 time format. On the frontend, this block allows both direct string input and displays a time picker.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "time_of_incident",
"type": "input.time",
"title": "Time of incident",
"placeholder": "12:00",
"default_value": "12:00"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "input.time". |
"value" | String. The block's current value. |
{
"claim": {
"block_states": {
"time_of_incident": {
"type": "input.time",
"value": "12:00"
}
},
...
}
}Input date
A block that accepts a date in the ISO 8601 date format. On the frontend, this block allows both direct string input and displays a date picker.
Properties
Property | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
{
"block": {
"key": "date_of_death",
"type": "input.date",
"title": "Date of death:",
"default_value": "{{ dateNow }}",
"placeholder": "{{ dateNow }}",
"max": "{{ dateNow }}",
"min": "2021-01-01"
}
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "input.date". |
"value" | String. The current value of the block. |
{
"claim": {
"block_states": {
"date_of_death": {
"type": "input.date",
"value": "2021-07-29T13:56:47+02:00"
}
},
...
}
}Group
The block enables grouping nested blocks related to a specific context.
Properties
| Property | Definition |
|---|---|
"key" | String. The unique identifier for this block |
"type" | String. The block type, in this case "group". |
"title" | String. The text that will be rendered as the group's title. |
"blocks" | Array. An array of sub-blocks, each representing an input field within the group. |
"collapsible" | Boolean. Defines whether the group can be collapsed or not. |
Example
{
"block": {
"key": "police_block",
"type": "group",
"title": "Provide the following details:",
"blocks": [
{
"block": {
"key": "police_station",
"type": "input.text",
"title": "Police station reported",
"max_length": 25,
"min_length": 0
}
},
{
"block": {
"key": "investigating_officer",
"type": "input.text",
"title": "Investigating officer information - name and contact number",
"max_length": 25,
"min_length": 0
}
},
{
"block": {
"key": "case_number",
"type": "input.text",
"title": "Case Number",
"max_length": 25,
"min_length": 0
}
}
],
"collapsible": false
},
"show_if": "{{if (ifCondition claim.block_states.claim_type.option_key '===' 'accidental') '||' (ifCondition claim.block_states.claim_type.option_key '===' 'unnatural')}}"
}
State
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "group". |
Note that each nested block saves on the claim record at the same level as the group block.
{
"claim": {
"block_states": {
"police_block": {
"type": "group"
},
"police_station": {
"type": "input.text",
"value": "Tokai"
},
"investigating_officer": {
"type": "input.text",
"value": "PC Wayne"
},
"case_number": {
"type": "input.text",
"value": "ABCDE1234"
},
...
}
}List
A repeatable group of nested blocks. The user can dynamically add or remove items at runtime - useful for capturing line items, expenses, or any data where the number of entries isn't known in advance (e.g. funeral expense breakdown). The entire list (all items and their inner values) PATCHes as a single block_key and is persisted as one entry in the claim's block states.
Properties
| Property | Definition |
|---|---|
"key" | String. The unique identifier for this block. |
"type" | String. The block type, in this case "list". |
"title" | String. The text that will be rendered as the list's title. |
"min_count" | Integer. Minimum number of items that must be present. The list is pre-populated with this many empty items when the claim is opened. Must be >= 0. |
"max_count" optional | Integer. Maximum number of items allowed. When reached, the "Add" button is hidden. Must be >= 1 if specified. |
| `"add_button_label" optional | String. Custom label for the button that appends a new item. Defaults to "Add another". |
"remove_button_label" optional | String. Custom label for the per-item remove link. Defaults to "Remove". |
"blocks" | Array. The inner block template - every item in the list will render these blocks. See "Allowed inner block types" below. |
"request_block_field_mappings" optional | Array. Maps per-item input values onto the fulfillment_data of a fulfillment_request inner block at create time. See "Per-item field mappings" below. |
Allowed inner block types
Any non-container block type can be nested inside a list item: every input type (input.text, input.paragraph, input.number, input.currency, input.date, input.time), the selection types (checkbox, dropdown, radio), the display types (heading, divider, alert, markdown), and the disbursement types (fulfillment_request, payout_request, annuity_request).
list and group blocks cannot be nested inside a list. Lists do not nest, and groups remain banned inside lists.
Example
{
"block": {
"type": "list",
"key": "funeral_expense_items",
"title": "Funeral expense breakdown",
"min_count": 1,
"max_count": 20,
"add_button_label": "Add expense line",
"remove_button_label": "Remove",
"blocks": [
{
"block": {
"type": "input.text",
"key": "description",
"title": "Description",
"placeholder": "e.g. Casket, transport, catering"
},
"required_if": "true"
},
{
"block": {
"type": "input.currency",
"key": "amount",
"title": "Amount"
},
"required_if": "true"
},
{
"block": {
"type": "input.text",
"key": "receipt_reference",
"title": "Receipt reference (optional)",
"placeholder": "Invoice / receipt no."
}
}
]
}
}State
The state for a list is an array of items. Each item is a { <innerKey>: <innerBlockState> } map - the same shape as the top-level state, just nested.
| Property | Definition |
|---|---|
"type" | String. The block type, in this case "list". |
"items" | Array. One entry per item, each containing the inner block states for that item. |
{
"claim": {
"block_states": {
"funeral_expense_items": {
"type": "list",
"items": [
{
"description": { "type": "input.text", "value": "Casket" },
"amount": { "type": "input.currency", "value": 5000000 },
"receipt_reference": { "type": "input.text", "value": "INV-001" }
},
{
"description": { "type": "input.text", "value": "Transport" },
"amount": { "type": "input.currency", "value": 200000 },
"receipt_reference": { "type": "input.text", "value": "" }
}
]
}
},
...
}
}Inner block values are accessed by combining the list key, the item index, and the inner key. For example, the first item's amount is at claim.block_states.funeral_expense_items.items[0].amount.value.
Per-item field mappings
When a list contains a fulfillment_request inner block, each item creates its own fulfillment request independently of sibling items. By default the request is created using the static fulfillment_data declared in the schema, which means every item produces an identical request. To make each item's request reflect the assessor's per-item input, declare request_block_field_mappings on the list block.
Each mapping is a { source_key, target_field } pair:
source_keyis the key of an inner block in the same list item (e.g."description").target_fieldis the field name on the fulfillment type'sfulfillment_datathat should receive that inner block's value (e.g."funeral_item").
At fulfillment-request creation time, the inner block's current value is written into the request's fulfillment_data at the specified target field, overriding any static value the schema declared for that field. Empty or undefined values are skipped, so the static schema value remains as a fallback. The target_field must be a field declared on the fulfillment type in the product module's .root-config.json for the value to surface on the request and in the requests table.
{
"block": {
"type": "list",
"key": "funeral_expense_items",
"title": "Funeral expense breakdown",
"min_count": 1,
"request_block_field_mappings": [
{ "source_key": "description", "target_field": "funeral_item" },
{ "source_key": "amount", "target_field": "funeral_item_amount" }
],
"blocks": [
{ "block": { "type": "input.text", "key": "description", "title": "Description" } },
{ "block": { "type": "input.currency", "key": "amount", "title": "Amount" } },
{
"block": {
"type": "fulfillment_request",
"key": "fulfillment",
"title": "Fulfillment",
"description": "Pays the funeral provider for this line item",
"fulfillment_type_key": "funeral_items",
"fulfillment_data": {}
}
}
]
}
}This mapping mechanism currently applies to fulfillment_request inner blocks only. payout_request and annuity_request inner blocks render and behave correctly inside list items but always use the static schema values when their requests are created.
Lock-on-create
Once a request block inside a list item has been created (i.e. it has a fulfillment_request_id, payout_request_id, or annuity_request_id), the item's source-only input fields (description, amount, etc.) are hidden. Only the request card remains, showing the captured values and the "View request" link. The request is a committed artifact - editing the inputs after creation would mislead the user into thinking the request itself is being updated, which it isn't. The item-level "Remove" button continues to work, and other items in the list are unaffected.
Per-item display conditions
The standard display conditions (show_if, hide_if, disabled_if, required_if) work at both the outer list-card level and on each inner block template:
-
Outer (list-card level): evaluated server-side against
claim.*andblock_states.*paths, identical to any other block. -
Inner (per template block): evaluated client-side with access to per-item context via
{{item.*}}paths. Inner conditionals support two Handlebars patterns:{{#ifEquals item.description.value 'Casket'}}true{{else}}false{{/ifEquals}} {{#if item.amount.value}}true{{else}}false{{/if}}Plus the pre-evaluated literal forms (
"true","false", booleans). Unrecognised Handlebars expressions fall back to the default (visible / enabled / not required) and emit a console warning.
Example: only show the casket_type field on rows where the description is "Casket".
{
"block": {
"type": "list",
"key": "claimed_items",
"title": "Claimed items",
"min_count": 1,
"blocks": [
{ "block": { "type": "input.text", "key": "description", "title": "Description" } },
{
"show_if": "{{#ifEquals item.description.value 'Casket'}}true{{else}}false{{/ifEquals}}",
"block": { "type": "input.text", "key": "casket_type", "title": "Casket type" }
}
]
}
}Display conditions
Display conditions allow you to customise the claims workflow by hiding or disabling certain blocks based on other block states, or based on existing claim, policy or policyholder information. You can also use the required_if parameter to define conditions under which the input for a given block will be mandatory.
All display conditions are optional.
"show_if"
"show_if"Default value: true.
If the value is truthy, the Block will be visible, else it will be hidden. If this condition is specified, "hide_if" will be ignored.
"show_if": "{{ifCondition claim.status '===' 'open'}}"
"show_if": "{{ifCondition claim.block_states.claim_type.option_key '===' 'accidental_death'}}""hide_if"
"hide_if"Default value: false.
If truthy, the Block will be hidden, else it will be visible. If "show_if" is specified, this condition will be ignored.
"hide_if": "{{ifCondition claim.policy.sum_assured '<' 2000000}}""disabled_if"
"disabled_if"Default value: false.
This property is only relevant for form element blocks. If truthy, the block will be disabled, effectively making it read-only. The value of a disabled block can't be changed via the frontend but it can still be changed via the API. A disabled block’s value(s) will still be visible on the dashboard.
"disabled_if": "{{ifCondition claim.policy.module_data.life_benefit '===' 'expired' }}""required_if"
"required_if"Default value: false.
This property is only relevant for form element blocks. If truthy, and the block has no value, the form input will have a red border applied on the frontend, indicating that a value is required. If this property is false, it will have no effect on the styling of the block on the dashboard. This property does not have any effect when retrieving and updating block states over the API.
Note that when a block has "required_if": true, and has a missing value, this will not prevent the claim from progressing. In other words, a claim will still be able to pass through the full process from opening to approval if a required input is missing.
"required_if": "{{ifCondition claim.block_states.has_excess_applicable_check.value '===' true }}"Updated 6 days ago