Submissions
A submission is a policy transaction that creates a new policy. This topic covers how to create submissions through Cloud API.
For details on the business functionality of submissions, see the Application Guide.
Overview of policy transaction management
Work with policy transactions typically involves endpoints from two different APIs:
- The Policy API, which has endpoints to:
- Initiate all types of policy transactions except for submissions
- The Job API, which has endpoints to:
- Initiate submissions
- Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
- Quote jobs
- Bind and issue jobs, or withdraw jobs
- Work with objects owned by jobs, such as activities and underwriting issues
Conceptually, a policy transaction is completed in four steps:
- Initiate the policy transaction.
- This creates a new
Job
element whose status is "Draft".
- This creates a new
- Modify the job as needed.
- The status remains "Draft".
- Quote the job.
- The rating engine or rating service generates a quote for the job.
- The status advances to "Quoted".
- The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous step. In other words, the status reverts to "Draft" and the job must be later requoted.
- Complete the job.
- This can be done by binding the job or by withdrawing or canceling the job.
- The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.
Initiating a submission
Before you can create a new submission, the account that will own the submission must exist. For information on creating accounts, see Creating an account.
Use the following endpoint to create a submission:
- POST
/job/v1/submissions
Minimum creation criteria
At a minimum, the request payload must include the following information:
- The
account
- The
baseState
- This is the jurisdiction of the primary location of the account
- This must be set to a value from the
Jurisdiction
typelist
- The
jobEffectiveDate
- The
producerCode
- The
product
- This specifies the type of policy the submission will create, such as a Personal Auto policy
Retrieving product ids
For submissions, the product
attribute must be set to the ID of the
product.
You can determine the ID through Advanced Product Designer. This value appears in the product's Identifier field.
You can also use the following endpoint from the Product Definition API to retrieve information about all available products, including their product IDs.
- GET
productdefinition/v1/products
Example of POSTing a submission
For example, the following request payload creates a new Personal Auto submission for account pc:401 with a base state of California, a job effective date of August 1, 2022, and a producer code pc:16.
POST /job/v1/submissions
{
"data": {
"attributes": {
"account": {
"id": "pc:401"
},
"baseState": {
"code": "CA"
},
"jobEffectiveDate": "2022-08-01",
"producerCode": {
"id": "pc:16"
},
"product": {
"id": "PersonalAuto"
}
}
}
}
This new job instance has a job type of "Submission" and a status of "Draft". For the purposes of the following examples, assume that the ID of this job is pc:4040.
Modifying the submission
Modifying a submission job is the process of adding the content that is required to accurately reflect the desired policy. For more information on how to modify a policy within the context of a job, see Overview of modifying jobs.
Typically, multiple calls are needed to specify all of the required information. For submissions, you can combine multiple calls into a single request using composite requests. For more information on composite requests, see Composite requests.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy content, and then quotes the submission, see Composite request submission example for Personal Auto.
Risk analysis information
PolicyCenter gathers information that an underwriter can use to process a job, such as a submission. In the user interface, this information is referred to as Risk Analysis information. This includes the following:
- Loss history - This is a list of prior losses that have been incurred by the insured. This information can be edited during a submission or outside of the context of a job. For more information, see Loss history.
- Prior policies - This is a list of policies that the insured has had prior to this policy. They could be policies with the insurer or with other insurers. This information can be edited during a submission or outside of the context of a job. For more information, see Prior policies.
Quoting the submission
To quote a job (such as a submission), use the following endpoint:
- POST
/job/v1/jobs/{jobId}/quote
The request object does not require a request body.
For example, the following request quotes job pc:4040:
POST /job/v1/jobs/pc:4040/quote
<no request body>
If the job lacks all the information required for rating, the call fails. For example, for the base configuration Personal Auto product, a submission will fail if you specify a covered vehicle, but you do not specify a driver for the vehicle.
If the call succeeds, a quote is generated for the job. The status of the job is advanced to "Quoted".
Editing a quoted job
You can make further edits to the job. However, this cannot be done while the job's
status is "Quoted". To make edits, you must call the POST
/job/v1/jobs/{jobId}/make-draft
endpoint, which reverts the job's
status to "Draft".
For example, the following request moves the quoted job pc:4040 back to a draft state:
POST /job/v1/jobs/pc:4040/make-draft
<no request body>
Additional quoting features
Cloud API has access to additional PolicyCenter quoting functionality. This includes:
- Retrieving payment information
- Generating multiple "side-by-side" quotes for a single job
- Overriding rating
For additional information, see Quoting.
Completing the submission
A submission can be completed in one of several ways.
Binding and issuing a submission at the same time
If the insurer and account holder agree upon the quote, the policy can be bound and issued.
- Binding refers to the act of both parties agreeing to the policy and making it a legally binding contract.
- Issuing refers to the act of printing and sending the documents that define the policy.
These actions are typically done at the same time, but they can be done separately.
Use the following endpoint to simultaneously bind and issue a policy:
- POST
/job/v1/jobs/{jobId}/bind-and-issue
The request object does not require a request body.
For example, the following request binds and issues job pc:4040.
POST /job/v1/jobs/pc:4040/bind-and-issue
<no request body>
The submission's status is changed to "Bound".
Binding a submission without issuing
In some situations, an insurer and account holder may agree to bind a policy, even though all information about the policy has not yet been collected. For example, a shipping business who is interested in a commercial auto policy may need to provide the vehicle identification numbers for a fleet of several hundred trucks. This information is needed to issue the policy, but it will take several weeks to provide it. The insurer agrees to bind the policy now, but to not issue the policy until after the vehicle identification numbers have been received.
Use the following endpoint to bind a policy without issuing it:
- POST
/job/v1/jobs/{jobId}/bind-only
The request object does not require a body.
For example, the following request binds job pc:4040 without issuing it.
POST /job/v1/jobs/pc:4040/bind-only
<no request body>
The submission's status is changed to "Bound".
Identifying a policy is bound but not issued
There is no flag on the Policy
entity that directly identifies a
policy is bound but not issued. You can identify a policy is bound but not issued in
the following ways:
- In the PolicyCenter user interface, the policy has an "Issuance Policy" menu item in the Actions menu.
- From Cloud API, any call that returns a policy as the root resource includes an
issue
link in the links section. This includes GET, POST, and PATCH calls.
Issuing a previously bound policy
Issuance refers to the action of issuing a policy that was previously bound but unissued. From a technical standpoint, issuance is a policy transaction.
- Issuance does not involve the original submission job. That job is considered to be concluded when the policy was bound.
- Similar to policy change and renewal:
- Issuance jobs are created from the policy.
- Issuance jobs can modify the policy contents.
- Issuance jobs must be quoted and completed.
To issue a previously bound policy, you must:
- Initiate the issuance job from the policy.
- Modify the job as needed. This could involve specifying information that was not available when the policy was bound.
- Quote the issuance job.
- Complete the issuance job.
Initiate the issuance job
Use the following endpoint to issue a previously bound but unissued policy. Note that this endpoint is in the Policy API and is executed from the policy:
- POST
/policy/v1/policies/{policyId}/issue
The request object requires an empty request body.
For example, the following creates an issuance job for policy pc:919.
POST /job/v1/jobs/pc:919/issue
{
"data": {
"attributes": {
}
}
}
This creates a new job instance whose job type is "Issuance" and whose status is "Draft". For the purposes of the following examples, assume that the ID of this job is pc:8808.
Modify the issuance job as needed
To modify the job, use the Job API endpoints to specify information as if it were part of the original submission.
Quote the issuance job
To quote the issuance job, use the following endpoint:
- POST
/job/v1/jobs/{jobId}/quote
The request object does not require a body.
For example, the following request quotes job pc:8808:
POST /job/v1/jobs/pc:8808/quote
<no request body>
If the quote at issuance is different than the quote when bound, this typically triggers an additional billing request to either charge for or credit the difference.
Complete the issuance job
There is no /issue-only
endpoint. To successfully complete an issuance
job, you must use the /bind-and-issue
endpoint.
For example, the following request binds and issues issuance job pc:8808.
POST /job/v1/jobs/pc:8808/bind-and-issue
<no request body>
You can also withdraw the issuance job. For example, this might be appropriate if the issuance included significantly erroneous information. To withdraw an issuance job, use the following endpoint:
- POST
/job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:4040.
POST /job/v1/jobs/pc:8808/withdraw
<no request body>
Withdrawing and rejecting submissions
There are several ways a submission can end without becoming a policy:
- Withdraw - The submission is abandoned before a final decision is made. (For example, there could be a significant error in the submission.)
- Decline - The submission is rejected by the insurer.
- Not Taken - The submission is rejected by the account holder.
Withdrawing a submission
Use the following endpoint to withdraw a submission:
- POST
/job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:4040.
POST /job/v1/jobs/pc:4040/withdraw
<no request body>
The submission's status is changed to "Withdrawn".
Declining a submission
Use the following endpoint to decline a submission:
- POST
/job/v1/jobs/{jobId}/decline
You must specify a rejectReason
in the request body.
For example, the following request declines job pc:4040.
POST /job/v1/jobs/pc:4040/withdraw
{
"data": {
"attributes": {
"rejectReason": {
"code": "PaymentHistory"
}
}
}
}
The submission's status is changed to "Declined".
Not taking a submission
Use the following endpoint to indicate a submission was not taken:
- POST
/job/v1/jobs/{jobId}/not-take
You must specify a rejectReason
in the request body.
For example, the following request indicates that job pc:4040 was not taken.
POST /job/v1/jobs/pc:4040/not-take
{
"data": {
"attributes": {
"rejectReason": {
"code": "nottaken"
}
}
}
}
The submission's status is changed to "Not taken".
Copying submissions
You can create a new submission by copying an existing submission. The submission can be unbound or bound. You can also create a copy from a bound policy, in which case the submission used to create the policy is the one that is copied.
To copy a submission, use one of the following endpoints:
Endpoint | Source submission |
---|---|
POST /job/v1/jobs/{jobId}/copy-submission |
The specified submission |
POST
/policy/v1/policies/{jobId}/copy-submission |
The submission used to create the specified policy |
The request does not require a body.
The copied submission is always in a draft state, regardless of the status of the source submission. Also, any pre-qualification status or underwriter approvals do not get copied.
For example, the following creates a copy of submission job pc:4100.
POST /job/v1/jobs/pc:4100/copy-submission
<no request body>
Copying a multi-version submission
A job can have multiple versions. For more information on multi-version jobs, see Multi-version quoting.
If a job is multi-versioned, there is always only one selected version. By default,
when you execute a copy-submission on a multi-versioned job, the selected submission
is used as the source submission. You can make a copy of a non-selected version. To
do this, you must include the jobVersion
query parameter in the
call, and you must specify the ID of the desired version.
For example, suppose job pc:4100 has two versions. The IDs for the versions are pc:61 (the selected version) and pc:62.
The following call creates a copy of version pc:61. This is because the call specifies no version, and pc:61 is the selected version.
POST /job/v1/jobs/pc:4100/copy-submission
<no request body>
The following call creates a copy of version pc:62.
POST /job/v1/jobs/pc:4100/copy-submission?jobVersion=pc:62
<no request body>
The jobVersion
query parameter is available only on the Job API
version of /copy-submission
. It is not available on the Policy API
version of /copy-submission
.
Additional features for submissions
PolicyCenter includes several features that can be used to manage multiple types of jobs, including submissions. The following table summarizes these feature.
Feature | Description | More information |
---|---|---|
Contingencies | An object that identifies an issue affecting a job or policy that must be resolved by a particular date. | Contingencies |
Job locks | A lock that indicates that there are associated underwriting issues to review and that the job ought to remain unchanged while the issues are resolved | Job locks |
Job search | A search for all jobs that meet a given set of criteria | Job search |
Multi-version quoting | The ability to create and compare multiple quotes for a single job | Multi-version quoting |
Out-of-sequence conflicts | A conflict that occurs with two jobs for the same policy where job 2 has a transaction date later than job 1, but an effective date earlier than job 1. | Out-of-sequence conflicts |
Rating overrides | The ability to override a specific Cost for a specific quote | Rating overrides |
Underwriting issues | An object attached to a job or policy that tracks an issue that may require underwriter review | Underwriting issues |
Composite request submission example for Personal Auto
The following is an example of a single composite request that creates an account and creates and quotes a Personal Auto submission using the base configuration Personal Auto line of business.
The composite request does the following:
- Creates a new account.
- Create a Personal Auto submission for the account.
- Answers the question "Is the applicant currently insured" with "No - New Driver"
(
newdriver
). - Adds a line-level optional coverage (
PALossOfUseCov
). - Adds a vehicle.
- Adds an optional coverage (
PARentalCov
) to the vehicle, and specifies the 20 dollars/day for 60 days (60/20
) coverage term. - Specifies contact information that is required for quoting (such as date of birth and number of accidents).
- Specifies vehicle driver information (percent of time the contact driver the vehicle).
- Sets the Anti-Lock Breaks Discount modifier to true.
- Quotes the job.
{
"requests": [
{
"method": "post",
"uri": "/account/v1/accounts",
"body": {
"data": {
"attributes": {
"initialAccountHolder": {
"contactSubtype": "Person",
"firstName": "Tamsin",
"lastName": "Tester",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"initialPrimaryLocation": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"producerCodes": [
{
"id": "pc:16"
}
],
"organizationType": {
"code": "other"
}
}
}
},
"vars": [
{
"name": "accountId",
"path": "$.data.attributes.id"
},
{
"name": "driverId",
"path": "$.data.attributes.accountHolder.id"
}
]
},
{
"method": "post",
"uri": "/job/v1/submissions",
"body": {
"data": {
"attributes": {
"account": {
"id": "${accountId}"
},
"baseState": {
"code": "CA"
},
"jobEffectiveDate": "2022-08-01",
"producerCode": {
"id": "pc:16"
},
"product": {
"id": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "jobId",
"path": "$.data.attributes.id"
}
]
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/questions",
"body": {
"data": {
"attributes": {
"answers": {
"PACurrentlyInsured": {
"choiceValue": {
"code": "newdriver"
}
}
}
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/coverages",
"body": {
"data": {
"attributes": {
"pattern": {
"id": "PALossOfUseCov"
}
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles",
"body": {
"data": {
"attributes": {
"make": "Toyota",
"model": "Tercel",
"modelYear": 2010,
"costNew": {
"amount": "33000",
"currency": "usd"
},
"licenseState": {
"code": "CA"
},
"vin": "14HEW8RLGMDSP03AA"
}
}
},
"vars": [
{
"name": "vehicleId",
"path": "$.data.attributes.id"
}
]
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles/${vehicleId}/coverages",
"body": {
"data": {
"attributes": {
"pattern": {
"id": "PARentalCov"
},
"terms": {
"PARental": {
"choiceValue": {
"code": "60/20"
}
}
}
}
}
}
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/contacts/${driverId}",
"body": {
"data": {
"attributes": {
"dateOfBirth": "1980-10-10",
"licenseNumber": "CA7732839",
"licenseState": {
"code": "CA"
},
"numberOfAccidents": {
"code": "0"
},
"numberOfViolations": {
"code": "0"
},
"policyNumberOfAccidents": {
"code": "0"
},
"policyNumberOfViolations": {
"code": "0"
}
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles/${vehicleId}/drivers",
"body": {
"data": {
"attributes": {
"percentageDriven": 100,
"policyDriver": {
"id": "${driverId}"
}
}
}
}
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles/${vehicleId}/modifiers/PAAntiLockBrakes",
"body": {
"data": {
"attributes": {
"booleanModifier": true
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/quote"
}
]
}