Best Practices

How to use the InsuranceNow v5 API to get the best results when implementing your own portal application. The guidelines in this section are based on the experiences and discoveries of both Guidewire and customer developers.

Correct API usage

These are the correct ways to use the InsuranceNow v5 API.
Call the correct endpoint
The v5 API often provides multiple endpoints that provide similar, but not identical, results. For example you could choose either
get coreapi/v5/policies/{systemid}/full
or
GET /coreapi/v5/policies/{systemid}/InsuredPolicyDetails
Both endpoints can return policy details, but the first returns many more details and takes longer to return a response. Decide which endpoint makes the most sense for your situation. In this example, do you need all the data or only a subset? Is it possible to make one call rather than many to get the data you need? We have seen situations where customers call multiple endpoints for a business scenario that could be achieved by calling the correct, single endpoint.
Invoke API calls only when you need to retrieve the data
Do not preemptively invoke endpoints to get all the data at once. A given user is likely not looking at all data at once, and by the time they do look, the data could be stale. Instead, invoke the appropriate endpoints to get only the data being requested by your user. For example, when a user is viewing a policy or claim, they might not need to look at the details of all documents and attachments at the same time. Retrieve those documents only if the user wants to see them.
Request custom endpoints
If you routinely need to call two or more endpoints to obtain the needed dataset, consider requesting (or implementing) a new endpoint. Reach out to your primary Guidewire contact and ask them to make a request on your behalf for an API that accomplishes your needs. If you cannot wait for us to develop a new API (typically in a future release), consider creating your own custom endpoint by following the guidance we provide in Custom API Development.

User interface considerations

Sometimes, user interface design plays a major role in how and how many API endpoints you need to invoke. And of course user interface design can heavily influence the user experience. For example, if you design a page to display a vast collection of data, that page will take longer to render as the app waits for return data. Designing your user interface to focus on a subset of data might enable you to present a better user experience with faster response. Consider showing only the most recent, most relevant, or most important information in any one element of your user interface, segmenting the data into useful chunks. One way to achieve this design is to divide your application into multiple pages, tabs, or other independent modules.

If your API call takes a long time to return data, consider displaying a helpful message in your user interface to reassure the user that something is happening. For example, whenever the response causes a delay of more than five seconds, display a message or an animated icon so that the user doesn't assume that the application has frozen or crashed.

Use lazy loading when applicable

Use the following techniques to reduce the load caused by large numbers of API endpoint calls:

  • Slow down calls to the API to retrieve data that need not be revealed.
  • Make those calls on an as-needed basis, as we explained in Correct API usage.
  • Avoid making an excessive number of calls. A large number of near-simultaneous calls has the potential to bring down the system.
  • Do not use custom endpoints in a legacy API release. Many customers have endpoints that were copied or updated from InsuranceNow legacy endpoints, and they continue to use them because they remain available. Move to v5 endpoints as soon as practical. If you do not find the endpoint you need, reach out to your main Guidewire contact for advice on how you can to achieve the desired result.
    Important: Custom legacy endpoints will cease to function after Dec-2026.

Architecture considerations

The v5 API is designed to be invoked directly by InsuranceNow portal applications via the web browsers of individual users. Some customer implementations have instead funneled all API invocations through a middle tier. This design has the side effect of showing all API invocations coming from a single IP address, sometimes in huge bursts, having the potential to be identified as a malicious attack. This side effect can in turn trigger defensive security mechanisms such as API rejection and rate limiting.

Therefore, we advise that you reach out to your primary Guidewire contact for guidance prior to embarking on designing a custom application. We have the necessary experience to help you avoid pitfalls related to various ways of designing an application. In addition, we appreciate being advised of your plans to roll out custom applications, and in particular being aware of your go-live dates.

To cache or not to cache

Some of our customers needlessly call the same endpoints over and over again. Before you repeat an endpoint call, analyze whether you need to refresh the data you already retrieved. If not, consider caching or state management. For example, create a Redux store in your application to avoid multiple (and sometimes expensive) API invocation.

When implementing a new portal application, determine early in the design phase the user experience versus the potential work needed to implement that experience. As part of this design phase, also consider the type of data that you want to cache, because the decision will affect your implementation.

During your portal application design phase, consider what data elements you will need to retrieve from the InsuranceNow core application to support your user interface and business logic (if any). Ideally, try to keep all business logic on the server side because doing so enables this logic to be maintained within the InsuranceNow framework within a specific product configuration. If the business logic you require is common to all products, consider adding the logic to a common service handler that you call as part of all business product services.
Important: Keep all business logic out of portal applications unless you can find no other solution. Putting business logic into a portal app makes maintenance more difficult because of dependencies between your app and InsuranceNow core. Disregarding this advice likely will require you either to release your portal apps and InsuranceNow core in tandem, or to add logic to detect and switch your portal app behavior to align with the core version. We strongly advise against the latter solution.
Also during the design phase, categorize the data you want to retrieve into two main types:
  • Data you need to retrieve for information only.
  • Data you need to retrieve and update.
Data elements that are for information only are generally good candidates for caching. For example, drop-down selection lists generally contain static values, particularly those that come from the /coderef/*.xml files and those in product list.xml files. The endpoints related to these two types of select list data include the following endpoint groups:
  • CodeRefs
  • Products
  • claimProducts
The CodeRefs group has endpoints that enable you to retrieve the list data for a specific coderef for a single coderef.xml file or from the entire list of coderefs for the system. Similarly, the Products group has endpoints that enable you to retrieve either the data for a single product list.xml file or from the full set of list.xml files. Depending on the technology you are using to implement your portal application, and if your design shows that you often will need to call specific coderefs or product lists, these endpoints are very good candidates for caching.

For example, assuming you are using React. When you load your application, you could use the browser localStorage to cache the results of the response for these endpoints for use later in the user session. Then, as the user moves from page to page, pages previously visited can use this cached data without additional calls to the server.

API performance considerations

API performance can vary based on a number of factors. For example, simple APIs that operate on a small resource (such as Task) run much faster that those that operate on a large resource (such as Application).

There can be a big difference between API request size and API response size. The request and request objects must be marshaled and unmarshaled, the response structure and values must be validated against the corresponding schema, and sensitive data must be appropriately masked. Therefore, on larger resources such as Application or AccountInquiry, consider using endpoints that support PATCH methods for those resources that support it. A PATCH method enables you to, among other operations, update a sub-model of the resource rather than repeatedly retrieving the entire resource model.

Example
PATCH /applications/15
{
  'id': 'ApplicationId123',
  'insured': {
    'id': 'InsuredId123',
    'preferredDeliveryMethod': 'Email'
  }
}
This example shows how you can pass a minimal request body to update just the insured's preferred delivery method. A more realistic example might update an entire sub-model of risk, coverage, or driver on a page that shows all three entities.
Similarly, if you have designed your application in a modular way, you can access resources such as Application using endpoints that are designed to retrieve specific sub-models. For example, to retrieve just the details on a specific coverage on the Application resource:
GET /applications/{systemId}/lines/{lineCd}/coverages/{coverageCd}

Be aware that using endpoints that support a PATCH method or APIs that access a sub-resource or sub-model of a resource might require you to use a different framework from the one you would typically use for a portal application. A dynamic, asynchronous design using a framework such as React could work well with this model. By splitting a page into different sections, each section could call a sub-resource retrieval endpoint to get just the data relevant to that section. For example, a section might retrieve just Coverage details rather than the entire Application. As the user navigates to another section, you can use a PATCH method or update just the Coverage elements.