Policy transactions

The system APIs support the following policy transactions:

  • Submission
  • Issuance
  • Renewal
  • Cancellation
  • Policy change
  • Reinstatement
  • Rewrite
  • Rewrite new account

Transactions not in this list are not supported at this time.

When using the system APIs, policy transactions are conducted through the Policy and Job APIs. The Policy API provides endpoints for initiating policy transactions on existing policies. The Job API provides endpoints for modifying, quoting, and completing policy transactions, as well as for creating new policies (submissions). The LOB-specific aspects of policy transactions are encapsulated in the Job API.

Note: The base configuration of the system APIs does not include LOB-specific APIs. Clients must generate LOB-specific APIs using Advanced Product Designer (APD). Once generated, the LOB-specific API endpoints are available through the Job API. For details, see Generate LOB-specific APIs.

Conceptually, a policy transaction entails four basic steps:

  1. Initiate the policy transaction through a business action POST.
    • This step creates a new job element, on which subsequent actions will be applied.
    • The new job is in Draft state, and thus can be modified.
  2. Modify the job as needed.
    • Depending on the policy transaction type, a number of calls might be required to apply all necessary data to the job.
  3. Quote the job.
    • This step changes the job from Draft to Quoted state.
    • Jobs in Quoted state cannot be modified. To further modify a quoted job, it must be changed to Draft state, in which case the process then reverts to step 2.
  4. Complete the policy transaction by finalizing the job.
    • A quoted job can be accepted (bound) or declined.

Initiating the policy transaction

To initiate a policy transaction, a caller submits a business action POST to an appropriate endpoint. The following table lists the policy transaction type with its relevant endpoint:

Policy transaction Endpoint
Submission
/job/v1/submissions
Issuance
/policy/v1/policies/{policyId}/issue
Renewal
/policy/v1/policies/{policyId}/renew
Cancellation
/policy/v1/policies/{policyId}/cancel
Policy change
/policy/v1/policies/{policyId}/change
Reinstatement
/policy/v1/policies/{policyId}/reinstate
Rewrite
/policy/v1/policies/{policyId}/rewrite
Rewrite new account
/policy/v1/policies/{policyId}/rewrite-account

All policy transactions other than submissions are initiated from an existing policy element through a Policy API call. The submission policy transaction is initiated using the Job API. In either case, the call returns a response payload that contains a JSON object for a new job element that is accessible through the Job API. Subsequent actions for the policy transaction are executed on this job element.

The following example depicts portions of a response payload returned by a call to initiate a submission policy transaction for a personal auto line:

{
    "data": {
        "attributes": {
            "account": {
                "displayName": "0015863842",
                "id": "pc:401",
                "type": "Account",
                "uri": "/account/v1/accounts/pc:401"
            },
            . . .
            "id": "pc:601",
            . . .
            "jobStatus": {
                "code": "Draft",
                "name": "Draft"
            },
            "jobType": {
                "code": "Submission",
                "name": "Submission"
            },
            . . .
            "product": {
                "displayName": "Personal Auto",
                "id": "PersonalAuto"
            },
            . . .
        },
        . . .
        }
    }
}
  • The id property contains the ID of the new job element, in this case pc:601.
  • The account.id property is the ID for the account holder. It is important to not mistake account.id for id.
  • The jobStatus property indicates that the job is in Draft state.
  • The jobType property shows that the job is for a submission policy transaction.

Subsequent actions for this policy transaction are executed on the /job/v1/jobs/pc:601 element.

Modifying the job

As stated previously, initiating a policy transaction produces a job element that is accessible through the Job API (/job/v1/jobs/{jobId}). All subsequent work involved in processing a policy transaction occurs on this job element.

Depending on the policy transaction type, it might be necessary to modify the job by submitting additional data. For example, after initiating a submission policy transaction for a personal auto line, a caller must modify the job by adding vehicles and drivers and applying coverages.

Quoting the job

For any policy transaction, the associated job must be quoted before it can be completed. To generate a quote, a caller submits a business action POST to /job/v1/jobs/{jobId}/quote. This action changes the job to Quoted state. If subsequent modifications are deemed necessary, then the job must be reverted to Draft state by submitting a business action POST to /job/v1/jobs/{jobId}/make-draft. After modifications are applied, the job must be quoted again.

Completing the policy transaction

To complete the policy transaction, the job must be accepted (bound) or rejected.

For accepted policy transactions, in most cases the transaction can be completed by submitting a business action POST to the /job/v1/jobs/{jobId}/bind-and-issue endpoint. This action binds the transaction to the policy.

A policy transaction can be rejected for a number of reasons. If the insurer rejects the transaction, then the job can be rescinded through a business action POST to the /job/v1/jobs/{jobId}/decline. If the policy transaction contains faulty data, then it can be discarded through a business action POST to the /job/v1/jobs/{jobId}/withdrawn endpoint.

Transaction outcome Condition Job status Endpoint
Accepted The account holder and insurer agree to the quote. The policy is bound and issued. Bound /job/v1/jobs/{jobId}/bind-and-issue
Rejected The insurer declines to offer a policy to the account holder. Declined /job/v1/jobs/{jobId}/decline
Rejected The quote contains erroneous data. Withdrawn /job/v1/jobs/{jobId}/withdrawn

Furthermore, some policy transaction types can be completed by being placed in Pending status.

The specific actions available to complete a policy transaction depend on the transaction type. For details, see subsequent sections for each policy transaction type.

LOB-specific endpoints

Generally speaking, an LOB defines an insurance policy, which provides coverages (risk protection) for coverables (risk exposures, such as tangible assets). Additionally, an LOB could define other policy features such as modifiers, exclusions, or pre-qualification questions for underwriting.

After generating LOB-specific APIs using Advanced Product Designer (APD), the LOB-related endpoints are contained in the Job API. In processing a policy transaction, a caller will add, revise, or remove data related to the LOB.

The following sections provide general guidance on the data structures that can appear in LOB endpoints.

Products

Every job has at least one product. The available products can be accessed through the /job/v1/jobs/{jobId}/lines collection. Each product can be found at /job/v1/jobs/{jobId}/lines/{productId}. Here, productId is a placeholder for a specific product.

For example, on a job for a personal auto line policy, the personal auto line product is accessed through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine endpoint.

Coverables

Coverables refer to any risk exposures that can be covered by the LOB or product. Coverables are accessible as collections on LOB endpoints. For example, one of the coverables for the PersonalAutoLine LOB is vehicle. Each PersonalAutoLine typically has a collection of one or more vehicles. Coverables can also be nested under other coverables. For example, another one of the coverables for PersonalAutoLine is driver. For each vehicle on a PersonalAutoLine, there can be a collection of drivers for that vehicle.

The basic pattern for accessing coverables is as follows:

  • /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}
  • /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/{coverableType}/{coverableId}

Here, coverableType is a placeholder for a collection of some type of coverable, and coverableId refers to a specific coverable.

For example, in a personal auto line, vehicles and drivers are coverables. In the Jobs API, vehicles can be accessed through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine/vehicles collection. Drivers associated with a covered vehicle are can be accessed through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/drivers collection.

Also, the Job API provides a locations coverable type that is associated with the job directly, rather than the LOB. This collection can be used to define coverables in certain LOBs, such as for commercial property.

Coverages

A coverage is protection from a specific risk. Coverages are attached to coverables. There are two basic types of coverages: property and liability. A property coverage is a coverage for a tangible asset belonging to the insured, such as a vehicle. A liability coverage protects the insured, such as covering a driver for damage done to another vehicle.

The available coverages for a product can be accessed through the /job/v1/jobs/{jobId}/lines/{productId}/coverages collection. Each coverage can be found at /job/v1/jobs/{jobId}/lines/{productId}/coverages/{coverageId}. Depending on the LOB, coverages could be nested. For example, a location (a coverable) could have a collection of buildings (child coverables), and a coverage would be applied to each building. For property coverages, the basic pattern is /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/coverages. For liability coverages, the policy line itself is a coverable, and represents the named insureds. The pattern is /job/v1/jobs/{jobId}/lines/{productId}/coverages.

For example, the personal auto line has both property (vehicle) and liability (driver) coverages. The vehicle coverages can be accessed through the /job/v1/jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages endpoint. The driver coverages cover liability, and thus can be found on the line itself: /job/v1/jobs/{jobId}/line/PersonalAutoLine/coverages.

Modifiers

Modifiers are factors that are applied as part of a rating algorithm. For example, the personal auto line could have an "Anti-Lock Breaks Discount" modifier for vehicles that provides a discount on the premium if the vehicle has anti-lock breaks. Modifiers can be associated with coverables or with the LOB itself.

  • /job/v1/jobs/{jobId}/lines/{productId}/modifiers
  • /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/modifiers

For example, the personal auto line could have an "Anti-Lock Breaks Discount" modifier for vehicles that provides a discount on the premium if the vehicle has anti-lock breaks.

Exposures, exclusions, or conditions

An LOB might provide additional exposures, exclusions, or conditions. Exposures can refer to liability coverables, such as a driver in an auto policy. Exclusions define causes of loss that are explicitly not covered by the policy, so that the insurer has no exposure to claims in those areas. Conditions define contractual obligations of the insurance policy that are neither a coverage nor an exclusion.

Exposures, exclusions, or conditions can be accessed at the LOB level.

For example, a workers compensation line could make workplace exclusions accessible through a /job/v1/jobs/{jobId}/lines/WorkersCompLine/excluded-workplaces endpoint. Depending on the LOB, exclusions could be defined on a coverable, in which case the pattern would be /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/{excludedType}/{excludedId}.

Pre-qualification questions for underwriting

In PolicyCenter, prequalifiction is accomplished through a series of questions answered during the submission process that can reveal possible underwriting issues. Answers to pre-qualification questions can be used to raise underwriting issues or block binding of the submission.

Pre-qualification could involve posing queries that are general to all products as well as specific to product, location, or coverable. As such, depending on the LOB, pre-qualification questions could be accessed through the following endpoints:

  • /job/v1/jobs/{jobId}/questions
  • /job/v1/jobs/{jobId}/locations/{locationId}/questions
  • /job/v1/jobs/{jobId}/lines/{productId}/questions
  • /job/v1/jobs/{jobId}/lines/{productId}/locations/{locationId}/questions
  • /job/v1/jobs/{jobId}/lines/{productId}/{coverableType}/{coverableId}/questions

To illustrate, in a personal auto line, a GET request to /job/v1/jobs/{jobId}/questions could return the following:

{
  "data": {
    "attributes": {
      "answers": {
        "q1": {
          "question": {
            "displayName": "Have you been convicted for a moving traffic violation within the past 3 years?",
            "id": "q1"
          },
          "questionType": {
            "code": "Boolean",
            "name": "Boolean"
          }
        },
        "q2": {
          "question": {
            "displayName": "Has any policy or coverage been declined, canceled, or non-renewed during the prior 3 years?",
            "id": "q2"
          },
          "questionType": {
            "code": "Boolean",
            "name": "Boolean"
          }
        },
        "q3": {
          "question": {
            "displayName": "Has your license ever been canceled, suspended or revoked?",
            "id": "q3"
          },
          "questionType": {
            "code": "Choice",
            "name": "Choice"
          }
        },
        "q4": {
          "question": {
            "displayName": "Are you currently insured?",
            "id": "q4"
          },
          "questionType": {
            "code": "Boolean",
            "name": "Boolean"
          }
        }
      }
    },
    "checksum": "*",
    "links": "*"
  }
}