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 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
    • This must be specified as a string in the form YYYY-MM-DD.
  • 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.

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 The base configuration Personal Auto product.

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 action of both parties agreeing to the policy and making it a legally binding contract.
  • Issuing refers to 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 and issues job pc:4040.

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 only bound. 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:

  • 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:

  • 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:

  • 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, pre-qualification status and underwriter approval does 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 conflict occurs when a job has a transaction date later than another policy transaction, but an effective date earlier than that other policy transaction. 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