Using the InsuranceNow V5 API

The InsuranceNow API V5 enables the development of InsuranceNow portals. The InsuranceNow API V5 provides an interface to create quotes and applications, process payments, route quotes to agents, manage policies, and submit claims.

These REST API endpoints are available within the system through an interactive API interface. The interactive API uses the Swagger OpenAPI specification to provide a way to view the API endpoints and execute API requests.

InsuranceNow accepts API endpoints with the following format:

https://host:port/coreapi/version/endpoint

Here is an example API Request:

curl -X GET "https://xx.xx.xxx.xxx:xxxxx/coreapi/v5/customers?postalCode=95119" -H "accept: application/json" 
      -H "authorization: Basic YWRtaW46OTk5OQ=="

Before InsuranceNow executes API requests, it validates the callers authentication and authorization to execute the request.

REST API Concepts

The API uses the Representational State Transfer (REST) architecture to issue requests and receive responses from the server.

Resources

Resources and sub-resources identify the objects that can be created, retrieved, and updated by the RESTful API. When using the API, data objects such as a quote, application, or customer are resources. Data objects such as a coverage or driver on a specific policy are considered sub-resources./applications/{systemId} is an example of a resource and /applications/{systemId}/drivers/{driverNumber} is an example of a sub-resource. Using sub-resources is useful when you need access to certain details such as the list of coverages on a specific risk.

Methods

The API uses GET, PATCH, PUT, POST, and DELETE methods to create, read, update, and delete resources. Some methods are safe and some are idempotent. Safe methods do not modify resources. An idempotent method can be called multiple times and the result on the resource is the same. Methods that are safe are also idempotent.

GET: The GET method retrieves a specified resource or sub-resource for the endpoint it acts on. This method is safe and idempotent. The GET method does not change the resource that it retrieves and duplicate GET requests have no impact on the resource either.
PATCH: The PATCH method updates one or more field in a resource and updates the _revision. The body of the request only needs to include the fields to update. When you submit a PATCH request, the server compares the _revision of the resource you are updating with the _revision on the server prior to accepting the request. This method is not safe but it is idempotent.
Note: Some fields associated with a resource, such as id, cannot be changed by the PATCH method.

PUT: The PUT method replaces the specified resource or sub-resource and updates the _revision. The _revision prevents concurrent updates to the same revision. When you submit a PUT request, the server compares the _revision of the resource you are updating with the _revision on the server prior to accepting the request. This method is not safe but it is idempotent.
Note: Some fields associated with a resource, such as id, cannot be changed by the PUT method.
POST: The POST method creates a new resource. This method is not safe and it is not idempotent as a new resource is created each time you submit a POST method. The POST method returns the URL to the new resource in the Location header and the _revision in the body of the response. The URL of the resource includes the systemId which identifies the new resource.

DELETE: The DELETE method deletes a specified resources or sub-resource. This method is idempotent. If you submit the same request more than once, no action is taken as the resource would no longer be available. However, you may receive an error message as the result of trying to delete a resource more than once.

Full endpoints

For certain resources, the API provides an endpoint that interacts with the entire payload of that resource and an endpoint that interacts with the resource without including all of its sub-resources. API endpoints that end with /full interact with the entire resource which includes the sub-resources. For example, PUT /applications/{systemId} requires less payload than PUT /applications/{systemId}/full. The payload for PUT /applications/{systemId}/full needs to include content about sub-resources such as locations and lines.

Links

The body of the API response can include one or more _links sections. These links provide direct access to other related items you might want to access. For example, when you get the full application response there are many sets of links available in the response. The coverages section of the full application response includes links to the coverage, its parent, and the associated list of coverage items:

...
          "coverages": [
            {
              ...
              "_links": [
                {
                  "rel": "self",
                  "href": "/coreapi/v5/applications/883/lines/Homeowners/risks/1/coverages/CovA"
                },
                {
                  "rel": "parent",
                  "href": "/coreapi/v5/applications/883/lines/Homeowners/risks/1"
                },
                {
                  "rel": "coverageItems",
                  "href": "/coreapi/v5/applications/883/lines/Homeowners/risks/1/coverages/CovA/coverageItems"
                }
              ]