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:

  1. Initiate the policy transaction.
    • This creates a new Job element whose status is "Draft".
  2. Modify the job as needed.
    • The status remains "Draft".
  3. Quote the job.
    1. The rating engine or rating service generates a quote for the job.
    2. The status advances to "Quoted".
    3. 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.
  4. Complete the job.
    1. This can be done by binding the job or by withdrawing or canceling the job.
    2. 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:

  1. Initiate the issuance job from the policy.
  2. Modify the job as needed. This could involve specifying information that was not available when the policy was bound.
  3. Quote the issuance job.
  4. 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 Policy and 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.

Note: This example assumes you have generated the LOB-specific endpoints for the base configuration Personal Auto line of business. It will not work in PolicyCenter if you have not yet generated LOB-specific endpoints for the base configuration Personal Auto line of business. For more information on how to do this, see the Cloud API Developer Guide.

The composite request does the following:

  1. Creates a new account.
  2. Create a Personal Auto submission for the account.
  3. Answers the question "Is the applicant currently insured" with "No - New Driver" (newdriver).
  4. Adds a line-level optional coverage (PALossOfUseCov).
  5. Adds a vehicle.
  6. Adds an optional coverage (PARentalCov) to the vehicle, and specifies the 20 dollars/day for 60 days (60/20) coverage term.
  7. Specifies contact information that is required for quoting (such as date of birth and number of accidents).
  8. Specifies vehicle driver information (percent of time the contact driver the vehicle).
  9. Sets the Anti-Lock Breaks Discount modifier to true.
  10. 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"
    }
  ]
}