Part 4: Amending policies with alteration hooks

Learn how to amend policies using alteration hooks on Root.

Useful documentation

Overview and success criteria

✅ The policy cover amount can be updated which leads to a new premium being calculated and applied to the policy via alteration hooks.
✅ The alteration package can be created and applied via the Root API or Dashboard.
✅ Unit tests are written for the alteration hook.
✅ Schemas have been created to create and apply an alteration on the Root Dashboard.


Watch our explainer videos:

Watch the video Policy Lifecycle: Alterations & MTAs to learn more about configuring alteration hooks on the Root platform:

In this part of the course process, you should now be able to issue a policy and view that policy on the Root Dashboard. In insurance, it’s very common to be able to endorse or amend a policy, and on Root, we use alteration hooks to accomplish that.

To successfully amend and update a policy follow these six steps:

  1. Start by adding the alteration hook to the .root-config file, where the key and name are specified.
  2. Create an alteration validation schema with Joi that abides by the specifications below.
  3. Create an alteration package that includes the updated cover and premium.
  4. Use the apply alteration hook to update the policy.
  5. Write the corresponding schema in the workflows/alteration-hooks/update-cover.json file so that the alteration can be applied from the Root Dashboard. Note that the platform won’t allow you to push your code if this doesn’t correspond to the name given in step 1.
  6. Create unit tests that thoroughly test validation, and pricing and that the expected alteration is being created and applied correctly.

Updating cover with alterations

Business rules

AH1The cover chosen should be amendable and subsequently recalculate the premium associated with the chosen cover amount.
AH2The cover amount (sum insured) must be provided, and it must fall between R10,000.00 and R100,000.00 inclusive.

Input parameters

Field nameTypeRequirementRestrictions
cover_amountintegerRequiredDefined in the business rules.

The scenarios below should have unit tests written for them to show that the logic has been implemented correctly:

  • A payload with valid data passes the validateAlterationPackageRequest
  • A payload with invalid data fails the validateAlterationPackageRequest
  • A 20-year-old Tyrannosaurus Rex with R90,000.00 has its cover changed to R75,000.00 with a resulting premium of R1215.00
  • A 36-year-old Velociraptor with R50,000.00 has its cover changed to R75,000.00 with a resulting premium of R2052.00


If you're doing the Root certification:

Once you’ve worked through the changes above, submit it as a pull request into the main branch on your Github repository. In the PR description, copy and answer the questions below in the last section Part Specific Questions. Message your facilitator to review the PR when ready.


  1. What other ways do you think alteration hooks can be used on policies, considering that it’s just an endpoint to update data on the policy?
  2. What parts were confusing or hard to understand in this part of the course? Could the guides or instructions have been more clear?

You can proceed to the next part without being blocked by the facilitator, but be sure to branch off of this part’s branch to ensure that these workings are in place for the next part. You will be required to ship a new PR for the next Part.