Working with Benefits

📒 Table of contents

Overview

In this guide, you will learn how to set a benefit offer when updating an employment.

Before you get started

Before you begin, make sure that you have already created an employment, as benefits can only be added through updates to an existing employment.

How to work with benefits

When updating an employment, it's possible to add the benefits under the contract_details field.

Locked Benefits

In certain countries, regulations stipulate that once an employer defines an offer for the first employee, the offer becomes locked for all subsequent employments.

In such cases, each benefit Group for subsequent employment has a default value and only one option available, which is the one that was selected in the first employment.

Opt-out from benefits

In some countries, employers are not required to offer certain benefits. In such cases, there may be an option to indicate that no benefit will be offered to employees. In countries with multiple groups, this selection can be made on a per-group basis.

Single-Question vs Multi-Questions

Depending on the country, employers may choose either one benefit tier or make a selection from multiple groups.

Single-Question

Refers to a scenario (country) where the employer selects only one tier from one list of options.

This field just requires a string value. In the JSON Schema, it’s an inputType: "radio" with the various options described.

bash
1$ curl --location --request PATCH 'https://gateway.remote-sandbox.com/v1/employments/9fb23136-bb7c-488a-b5dc-37d3b7c9033b' \
2     --header …
3     --data-raw '{
4    "contract_details": {
5        …
6        "benefits": "Basic (US Life Health…)",
7        …
8    }
9}'

Multi-Questions

Refers to a scenario (country) where the employer selects one tier for each question/group (like Pension, Health Insurance, Meal Cards, etc).

This field is an object with multiple strings. In the JSON Schema it’s an inputType: "fieldset" with multiple radio fields inside.

bash
1$ curl --location --request PATCH 'https://gateway.remote-sandbox.com/v1/employments/9fb23136-bb7c-488a-b5dc-37d3b7c9033b' \
2     --header …
3     --data-raw '{
4    "contract_details": {
5        …
6        "benefits": {
7          "employee_assistance_program": "no",
8          "health": "Plus - Employee Only (Canada Life...)",
9          "retirement": "Standard Retirement (Canada Life...)"
10        }
11        …
12    }
13}'

Understanding the JSON Schema structure

Looking up the benefits schema

It's possible to find the schema for a benefit by checking for the JSON schema of its respective country. You can do this by making a request to our show form schema endpoint, passing the country code (CAN for example) and contract_details as the form. In the returned schema, one of the properties is called benefits. You can find more information in our documentation.

This benefits field comes with extra information that you can use to enhance the UI of the field in your Form. Let’s take as an example Canada.

By the end, you’ll be able to transform your UI Form using json-schema-form…

…from this (native) example

…into this (enhanced) example

Benefits terminology

To better help you understand the benefits structure, here’s a full JSON Schema example:

Dummy example JSON Schema (click to expand)
🌐
Benefits are dynamic and can change often. All the JSON Schema examples are dummy responses and their values are not a match to reality. The structure is the important part.
json
1{
2  "additionalProperties": false,
3  "properties": {
4    "employee_assistance_program": {
5      "oneOf": [
6        {
7          "const": "Assistance Programs (Lifeworks - Employee Assistance)",
8          "title": "Assistance Programs - $2.74",
9          "x-jsf-presentation": {
10            "description": "Psychologic, Legal and financial counselling. Up to 5 sessions per issue through phone or video call.",
11            "meta": {
12              "providerName": "Lifeworks",
13              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-eap",
14              "displayCost": "$2.74",
15              "tierName": "Assistance Programs"
16            }
17          }
18        },
19        {
20          "const": "no",
21          "title": "I don't want to offer this benefit."
22        }
23      ],
24      "title": "Employee Assistance Program",
25      "type": "string",
26      "x-jsf-presentation": {
27        "inputType": "radio"
28      }
29    },
30    "health": {
31      "oneOf": [
32        {
33          "const": "Basic - Employee Only (Canada Life - Basic Health Employee Only; Canada Life - Basic Dental Employee Only; Canada Life - Basic Vision; Canada Life - Basic Life; Canada Life - Basic AD&D)",
34          "title": "Basic - Employee Only - $80.25/mo",
35          "x-jsf-presentation": {
36            "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (25K CAD (Canada Life Health).",
37            "meta": {
38              "providerName": "Canada Life",
39              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-basic-single",
40              "displayCost": "$80.25/mo",
41              "tierName": "Basic"
42            }
43          }
44        },
45        {
46          "const": "Basic - Family (Canada Life - Basic Health Family; Canada Life - Basic Dental Family; Canada Life - Basic Vision; Canada Life - Basic Life; Canada Life - Basic AD&D)",
47          "title": "Basic - Family - $117.25/mo",
48          "x-jsf-presentation": {
49            "meta": {
50              "providerName": "Canada Life",
51              "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (25K CAD (Canada Life Health).",
52              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-basic-family",
53              "displayCost": "$117.25/mo",
54              "tierName": "Basic"
55            }
56          }
57        },
58        {
59          "const": "Standard - Employee Only (Canada Life - Standard Health Employee Only; Canada Life - Standard Dental Employee Only; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability)",
60          "title": "Standard - Employee Only - $130.00/mo + variable costs",
61          "x-jsf-presentation": {
62            "meta": {
63              "providerName": "Canada Life",
64              "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (1x annual Salary), Dependant and Spouse Life, long and short term disability (66.7% weekly earnings - maximums apply).",
65              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-standard-single",
66              "displayCost": "$130.00/mo + variable costs",
67              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
68              "tierName": "Standard"
69            }
70          }
71        },
72        {
73          "const": "Standard - Family (Canada Life - Standard Health Family; Canada Life - Standard Dental Family; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability; Canada Life - Standard Dependent Life)",
74          "title": "Standard - Family - $243.00/mo + variable costs",
75          "x-jsf-presentation": {
76            "meta": {
77              "providerName": "Canada Life",
78              "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (1x annual Salary), Dependent and Spouse Life, long and short term disability (66.7% weekly earnings - maximums apply).",
79              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-standard-family",
80              "displayCost": "$243.00/mo + variable costs",
81              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
82              "tierName": "Standard"
83            }
84          }
85        },
86        {
87          "const": "Plus - Employee Only (Canada Life - Plus Health Employee Only; Canada Life - Plus Dental Employee Only; Canada Life - Plus Vision; Canada Life - Plus Life; Canada Life - Plus AD&D; Canada Life - Plus Short Term Disability; Canada Life - Plus Long Term Disability)",
88          "title": "Plus - Employee Only - $188.00/mo + variable costs",
89          "x-jsf-presentation": {
90            "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (2x annual Salary), Dependent and Spouse Life, long and short term disability (70% weekly earnings - maximums apply).",
91            "meta": {
92              "providerName": "Canada Life",
93              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-plus-single",
94              "displayCost": "$188.00/mo + variable costs",
95              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
96              "tierName": "Plus"
97            }
98          }
99        },
100        {
101          "const": "Plus - Family (Canada Life - Plus Health Family; Canada Life - Plus Dental Family; Canada Life - Plus Vision; Canada Life - Plus Life; Canada Life - Plus AD&D; Canada Life - Plus Short Term Disability; Canada Life - Plus Long Term Disability; Canada Life - Plus Dependent Life)",
102          "title": "Plus - Family - $353.00/mo + variable costs",
103          "x-jsf-presentation": {
104            "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (2x annual Salary), Dependent and Spouse Life, long and short term disability (70% weekly earnings - maximums apply).",
105            "meta": {
106              "providerName": "Canada Life",
107              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-plus-family",
108              "displayCost": "$353.00/mo + variable costs",
109              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
110              "tierName": "Plus"
111            }
112          }
113        },
114        {
115          "const": "Premium - Employee Only (Canada Life - Premium Health Employee Only; Canada Life - Premium Dental Employee Only; Canada Life - Premium Vision; Canada Life - Premium Life; Canada Life - Premium AD&D; Canada Life - Premium Short Term Disability; Canada Life - Premium Long Term Disability)",
116          "title": "Premium - Employee Only - $203.00/mo + variable costs",
117          "x-jsf-presentation": {
118            "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (3x annual Salary), Dependent and Spouse Life, long and short term disability (75% weekly earnings - maximums apply).",
119            "meta": {
120              "providerName": "Canada Life",
121              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-premium-single",
122              "displayCost": "$203.00/mo + variable costs",
123              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
124              "tierName": "Premium"
125            }
126          }
127        },
128        {
129          "const": "Premium - Family (Canada Life - Premium Health Family; Canada Life - Premium Dental Family; Canada Life - Premium Vision; Canada Life - Premium Life; Canada Life - Premium AD&D; Canada Life - Premium Short Term Disability; Canada Life - Premium Long Term Disability; Canada Life - Premium Dependent Life)",
130          "title": "Premium - Family - $381.00/mo + variable costs",
131          "x-jsf-presentation": {
132            "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (3x annual Salary), Dependent and Spouse Life, long and short term disability (75% weekly earnings - maximums apply).",
133            "meta": {
134              "providerName": "Canada Life",
135              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-premium-family",
136              "displayCost": "$381.00/mo + variable costs",
137              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
138              "tierName": "Premium"
139            }
140          }
141        },
142        {
143          "const": "no",
144          "title": "I don't want to offer this benefit."
145        }
146      ],
147      "title": "Health",
148      "type": "string",
149      "x-jsf-presentation": {
150        "inputType": "radio",
151        "meta": {
152          "subGroups": [
153            {
154              "id": "individual",
155              "label": "Individual",
156              "optionValues": [
157                "Premium - Employee Only (Canada Life - Premium Health Employee Only; Canada Life - Premium Dental Employee Only; Canada Life - Premium Vision; Canada Life - Premium Life; Canada Life - Premium AD&D; Canada Life - Premium Short Term Disability; Canada Life - Premium Long Term Disability)",
158                "Plus - Employee Only (Canada Life - Plus Health Employee Only; Canada Life - Plus Dental Employee Only; Canada Life - Plus Vision; Canada Life - Plus Life; Canada Life - Plus AD&D; Canada Life - Plus Short Term Disability; Canada Life - Plus Long Term Disability)",
159                "Standard - Employee Only (Canada Life - Standard Health Employee Only; Canada Life - Standard Dental Employee Only; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability)",
160                "Basic - Employee Only (Canada Life - Basic Health Employee Only; Canada Life - Basic Dental Employee Only; Canada Life - Basic Vision; Canada Life - Basic Life; Canada Life - Basic AD&D)",
161                "no"
162              ]
163            },
164            {
165              "id": "family",
166              "label": "Family",
167              "optionValues": [
168                "Premium - Family (Canada Life - Premium Health Family; Canada Life - Premium Dental Family; Canada Life - Premium Vision; Canada Life - Premium Life; Canada Life - Premium AD&D; Canada Life - Premium Short Term Disability; Canada Life - Premium Long Term Disability; Canada Life - Premium Dependent Life)",
169                "Plus - Family (Canada Life - Plus Health Family; Canada Life - Plus Dental Family; Canada Life - Plus Vision; Canada Life - Plus Life; Canada Life - Plus AD&D; Canada Life - Plus Short Term Disability; Canada Life - Plus Long Term Disability; Canada Life - Plus Dependent Life)",
170                "Standard - Family (Canada Life - Standard Health Family; Canada Life - Standard Dental Family; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability; Canada Life - Standard Dependent Life)",
171                "Basic - Family (Canada Life - Basic Health Family; Canada Life - Basic Dental Family; Canada Life - Basic Vision; Canada Life - Basic Life; Canada Life - Basic AD&D)",
172                "no"
173              ]
174            }
175          ]
176        }
177      }
178    },
179    "retirement": {
180      "oneOf": [
181        {
182          "const": "Basic Retirement (Canada Life - Basic Retirement)",
183          "title": "Basic Retirement - 0% match",
184          "x-jsf-presentation": {
185            "description": "You won't match the employee's contribution, but the employee will still be enrolled in the basic retirement plan.",
186            "meta": {
187              "providerName": "Canada Life",
188              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-retirement-basic",
189              "displayCost": "0% match",
190              "tierName": "Basic Retirement"
191            }
192          }
193        },
194        {
195          "const": "Standard Retirement (Canada Life - Standard Retirement)",
196          "title": "Standard Retirement - 3% match",
197          "x-jsf-presentation": {
198            "description": "You match the employee's contribution into the plan dollar for dollar, up to 3% of the employee's salary.",
199            "meta": {
200              "providerName": "Canada Life",
201              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-retirement-standard",
202              "displayCost": "3% match",
203              "tierName": "Standard Retirement"
204            }
205          }
206        },
207        {
208          "const": "Plus Retirement (Canada Life - Plus Retirement)",
209          "title": "Plus Retirement - 4% match",
210          "x-jsf-presentation": {
211            "description": "You match the employee's contribution into the plan dollar for dollar, up to 4% of the employee's salary.",
212            "meta": {
213              "providerName": "Canada Life",
214              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-retirement-plus",
215              "displayCost": "4% match",
216              "tierName": "Plus Retirement"
217            }
218          }
219        },
220        {
221          "const": "Premium Retirement (Canada Life - Premium Retirement)",
222          "title": "Premium Retirement - 5% match",
223          "x-jsf-presentation": {
224            "description": "You match the employee's contribution into the plan dollar for dollar, up to 5% of the employee's salary.",
225            "meta": {
226              "providerName": "Canada Life",
227              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-retirement-premium",
228              "displayCost": "5% match",
229              "tierName": "Premium Retirement"
230            }
231          }
232        },
233        {
234          "const": "no",
235          "title": "I don't want to offer this benefit."
236        }
237      ],
238      "title": "Retirement",
239      "type": "string",
240      "x-jsf-presentation": {
241        "inputType": "radio"
242      }
243    }
244  },
245  "required": ["employee_assistance_program", "health", "retirement"],
246  "title": "Benefits",
247  "type": "object",
248  "x-jsf-order": ["employee_assistance_program", "health", "retirement"],
249  "x-jsf-presentation": {
250    "description": "Remote offers its employees supplemental, comprehensive coverage with Remote Health, provided in partnership with Canada Life and Lifeworks. This is to supplement the basic coverage. ",
251    "extra": "The package you have selected will apply to any current and future employees in Canada.",
252    "inputType": "fieldset"
253  }
254}

Terminology

  • Group: A set of related Tiers we can offer. (eg Health, Retirement, etc)
  • Tier: Each option available for a given Group (eg The Health example above has 5 options - Basic_Individual, Basic_Family, Standard_Individual, Standard_Family, Plus_Individual, Plus_Family, and No)
  • Subgroups: How the options can be organized, (e.g. In the JSON Schema above, the Health Group can be organized into “Individual” or “Family”)

Groups

A set of related tiers we can offer (eg Health, Retirement, etc).

Multi-Question

The employer can select one tier for each group (question).

json
1{
2  "type": "object",
3  "title": "Benefits",
4  "properties": {
5    "<Group1>": {
6      "title": "Group name eg 'Health'",
7      "oneOf": ["Tier_1", "Tier_2", "Tier_n"],
8      "type": "string",
9      "x-jsf-presentation": {
10        "inputType": "radio",
11        "meta": {
12          "subGroups": ["SubGroups_A", "SubGroups_B"]
13        }
14      }
15    },
16    "<GroupN1>": {},
17    "<GroupN2>": {}
18  },
19  "x-jsf-presentation": {
20    "inputType": "fieldset"
21  }
22}

Single-Question

The employer can select only one tier from one list of options.

json
1{
2  "type": "string",
3  "title": "{Group name eg 'Health'}",
4  "oneOf": Tier[],
5  "x-jsf-presentation": {
6    "inputType": "radio",
7    "meta": {
8      "subGroups": SubGroups[]
9    }
10  }
11}

Tiers

A Tier is each option available for a country (Single-Question) or for a group (Multi-Questions).

Each Tier is declared in oneOf and has the following structure:

  • "const" - String - The id/value stored in the DB
  • "title" - String - The representative label of this Tier.
  • "x-jsf-presentation"
    • description - String - Tier explanation. Might contain HTML.
    • meta - Object? - Extra details for you to use in your UI Field.
      • "detailsUrl" - String? - URL to page containing all the details of this benefit tier.
      • "displayCost" - String - The cost of this benefit tier
      • "displayCostDisclaimer" - String? - If the cost is not fixed, this sentence explains what additional costs it might include.
      • "providerName" - String? - The name of the benefit provider
      • "tierName" - String - The name of the benefit Tier

Tier Example

json
1"benefits": {
2  "properties": {
3    "health": {
4      "oneOf": [
5        {
6          "const": "Standard - Employee Only (Canada Life - Standard Health Employee Only; Canada Life - Standard Dental Employee Only; Canada Life - Standard Vision; Canada Life - Standard Life; Canada Life - Standard AD&D; Canada Life - Standard Short Term Disability; Canada Life - Standard Long Term Disability)",
7          "title": "Standard - Employee Only - $130.00/mo + variable costs",
8          "type": "string",
9          "x-jsf-presentation": {
10            "description": "Medical Insurance, Drug Prescriptions, Dental Insurance, Vision Insurance, Life Insurance and AD&D Insurance (1x annual Salary), Dependant and Spouse Life, long and short term disability (66.7% weekly earnings - maximums apply).",
11            "inputType": "radio",
12            "meta": {
13              "detailsUrl": "https://remote.com/benefits-guide/employee-benefits-canada-health-standard-single",
14              "displayCost": "$130.00/mo + variable costs",
15              "displayCostDisclaimer": "Some plans in this benefit package include premium costs based on the employee salary. These costs are not included in the listed monthly estimate.",
16              "providerName": "Canada Life",
17              "tierName": "Standard"
18            }
19          }
20        },
21        { ... another tier ... }
22        { ... another tier ... }
23      ]
24    }
25  }
26}

As said in the previous section, the employer might be allowed to opt-out of benefits. In that case, an option with const: "no" will be available. This tier does not include meta keyword, so you’ll only have the default title.

Subgroups

Some groups have tiers that can be organized into subgroups. For example, the group “Health” has multiple tiers that can either fit the subgroup “Individual” or “Family”.

These subgroups are documented under the Group ["x-jsf-presentation"].meta. Each one has the following keys:

  • "id" - String - The subgroup id
  • "label" - String - The visual label
  • "optionValues": Array - Strings matching the value (const) of each tier

Subgroups Example

json
1{
2  "health": {
3    "oneOf": [...]
4    "title": "Health",
5    "type": "string",
6    "x-jsf-presentation": {
7      "inputType": "radio",
8      "meta": {
9        "subGroups": [
10          {
11            "id": "individual",
12            "label": "Individual",
13            "optionValues": [
14              "Standard - Employee Only (Canada Life - Standa...",
15              "Basic - Employee Only (Canada Life - Basic Health Employee...",
16              "no"
17            ]
18          },
19          {
20            "id": "family",
21            "label": "Family",
22            "optionValues": [
23              "Standard - Family (Canada Life - Standard Heal...",
24              "Basic - Family (Canada Life - Basic Health...",
25              "no"
26            ]
27          }
28        ]
29      }
30    }
31  }
32}

Extending the UI Field (Frontend with json-schema-form)

🚧
⚠️ You must have at least version 0.4.0-beta.0 of json-schema-form Related: [json-schema-form] Usage at Remote

Check the codesandbox demo that uses React with Formik. Look for the component FancyBenefitComponent and how it is integrated into createHeadlessForm().