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.
Conceptually, a policy transaction entails four basic steps:
- 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.
- 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.
- 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.
- 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 |
|
Issuance |
|
Renewal |
|
Cancellation |
|
Policy change |
|
Reinstatement |
|
Rewrite |
|
Rewrite new 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 casepc:601
. - The
account.id
property is the ID for the account holder. It is important to not mistakeaccount.id
forid
. - 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": "*"
}
}