Correctly Mapped Coverages

Overview

Refer to our [Breaking] Several Coverages to Become Vehicle-level changelog post for more details about this change to our API behavior. This breaking change went into effect on January 23, 2025.

To prevent this breaking change from affecting your integration, Root maintains the legacy API behavior for requests and responses until the integration has been updated to handle the new behavior. In this case, the breaking change was to our Quote and Policy coverages objects and the strategy by which we assign certain coverages like bodily injury (BI) and property damage (PD). The legacy API behavior scopes these coverages to the policy level in all markets, while the new behavior scopes them to the vehicle level.

Does This Apply to Your Integration?

This guide is only applicable to your integration if Root has notified your team that your integration is configured for the legacy API behavior (where some vehicle-level coverages are mapped at the policy level).

Why Should Your Integration Be Upgraded?

We will need to upgrade your integration to correctly map coverages in order for your integration to support:

• Rating in states released after the breaking change was introduced (January 23, 2025)
  • e.g. Minnesota and Washington
  • While configured for legacy coverage mappings, these states remain unavailable for your integration.
• New API features related to coverages
  • e.g. Coverage-level Pricing Now Available in Quote Responses

How to Upgrade Your Integration

Please reach out to your account manager at any point during the process outlined below if you have any questions or concerns.

1. Update your integration to provide correctly mapped coverages for all Quote requests

   Related API endpoints:

   • Create quote
   • Update quote
   • Patch quote

   Follow the guidelines and examples provided here.

   If you are not providing coverages at all or use our Suggested coverages endpoint without coverage customization, then you may not need to update anything for this step! This step only applies if your integration is passing a customized coverages object during quote creates or updates, since that likely means that your integration is passing us legacy coverage mappings (where some vehicle-level coverages are at the policy level).

   You will need to ensure that your integration is including correctly mapped coverages within the coverages object (if provided) in all requests to our Quote API. Since a particular coverage's scope (policy level or vehicle level) may change per state, we recommend using the Get available coverages or Get available coverages by state endpoint to see the scope for each coverage. The coverages are also listed at the correct scope in the Suggested coverages response.

   Refer to our Coverage Customization guide for a more thorough walkthrough of how to update your integration to support coverage customization dynamically. This will guarantee that your integration will remain flexible enough to handle updates to any coverage rules or options in the future.

2. Update your integration to accept both the updated and legacy coverage mappings within Quote and Policy API responses

   Related API endpoints:

   • Quote
     • Create quote
     • Patch quote
     • Update quote
     • Get quote
     • Finalize quote
   • Policy
     • Get payment information
     • Get policy summary
     • Get policy documents
   
   

   Since your integration is currently configured for the legacy coverage mappings, we return coverages at the legacy scope (some vehicle-level coverages will be at the policy level) within our Quote and Policy API responses. Before we upgrade your integration configuration to correctly map coverages, you must ensure that your integration can handle both the legacy API behavior (where some vehicle-level coverages are mapped at the policy level) and the new API behavior (correctly mapped coverages).

   This only applies to your integration if you are reading the Quote or Policy response and expect the coverages to be scoped with the legacy mappings (e.g. BI at the policy level always).

   We recommend updating your integration to properly handle any coverage at any scope, so it will be dynamic to any difference in coverage scope per state, which is expected behavior with the new coverage mapping strategy. As mentioned above, our Coverage Customization guide provides a thorough walkthrough of how to update your integration to support coverage customization dynamically.

   The goal of this step is to ensure that your integration will be ready for upgrading to the new API behavior (correctly mapped coverages) in the following steps. Therefore, the changes needed will be specific to your integration. Please do not hesitate to contact your account manager and the Root team if you run into any issues while performing this step of the migration.

   To mitigate risk during the migration, we highly recommend testing your changes for some time before continuing to the next step.

3. Notify your account manager when you are ready for Root to upgrade your integration in our test environment

   Once your team is ready to test your integration updates in Root's partner-testing environment, please let your account manager know that you are ready for your integration to be upgraded to correctly mapped coverages. To upgrade your test integration, Root needs to update your integration's configuration on our side. Note that your integration will use the new API behavior immediately once Root updates your configuration.

   Just like before, to mitigate risk, we highly recommend monitoring and thoroughly testing your integration against our test environment for some time before continuing to the next step. If you run into any issues while validating the upgrade, please notify your account manager immediately, and we can downgrade your test integration back to the legacy coverage mappings to restore the legacy API behavior.

4. Notify your account manager when you are ready for Root to upgrade your integration in our production environment

   After your team is confident that your integration is able to handle correctly mapped coverages in Root's test environment, let your account manager know when you are ready for your integration to be upgraded to correctly mapped coverage in Root's production environment. As with our test environment, Root just needs to update your integration's configuration on our side, which will go into effect immediately when we do so.

   Again, if you run into any issues while validating the upgrade, please notify your account manager immediately, and we can downgrade your production integration back to the legacy coverage mappings to restore the legacy API behavior.