Form patterns

For the insured, the physical representation of an insurance policy is a collection of policy forms. Policy forms define aspects of the policy such as coverages, exposures, exclusions, and government regulations. The forms themselves are not stored in PolicyCenter; they’re stored in an external documentation management system and are typically accessed through integration with an external forms printing service. PolicyCenter stores form patterns, a set of information used to identify each form.

For detailed information on forms, see the Application Guide.

For more information on external forms printing service integration, see Plugins, Prebuilt Integrations, and SOAP APIs.

Form patterns information

Cloud API uses the /admin/v1/form-patterns endpoint to work with all aspects of a form pattern. With this endpoint and its child endpoints you can retrieve and update form pattern basic information, products, transaction types, jurisdiction availability and replacements, and policy change behavior.

Retrieving form patterns

Use the following endpoints to retrieve form patterns:

GET /admin/v1/form-patterns
GET /admin/v1/form-patterns/{policyFormPatternId}

Note:

The information retrieved by these endpoints includes everything located on all tabs of the Form Pattern screen in the user interface except jurisdiction availability. See “Form patterns lookups” below for information on retrieving jurisdiction availability. See Application Guide for user interface information.

The following retrieves all available form patterns:

Command

GET /admin/v1/form-patterns

Response

{
     "data": [
        {
            "attributes": {
                "code": "DecSheet",
                "customFormInference": true,
                "edition": "0100",
                "endorsementNumbered": false,
                "formNumber": "PA 00DS",
                "id": "pc:101",
                "inferenceTime": {
                    "code": "bind",
                    "name": "Bind Time"
                },
                "jobTypes": [
                    {
                        "code": "PolicyChange",
                        "name": "Policy Change"
                    },
                    {
                        "code": "Renewal",
                        "name": "Renewal"
                    },
                    {
                        "code": "Rewrite",
                        "name": "Rewrite"
                    },
                    {
                        "code": "Submission",
                        "name": "Submission"
                    }
                ],
                "name": "Dec Sheet",
                "policyLine": {
                    "displayName": "Personal Auto Line",
                    "id": "PersonalAutoLine"
                },
                "priority": 0,
                "products": [
                    {
                        "displayName": "Personal Auto",
                        "id": "PersonalAuto"
                    }
                ],
                "reissueOnChange": true,
                "removalEndorsement": false
            },
        …
        },
        {
            "attributes": {
                "code": "FormCPP01",
                "edition": "00 00",
                "endorsementNumbered": true,
                "formNumber": "CPP 01",
                "genericFormInference": {
                    "code": "GenericAlwaysAddedForm",
                    "displayName": "No additional criteria"
                },
                "id": "pc:102",
                "inferenceTime": {
                    "code": "quote",
                    "name": "Quote Time"
                },
                "jobTypes": [
                    {
                        "code": "PolicyChange",
                        "name": "Policy Change"
                    },
                    {
                        "code": "Renewal",
                        "name": "Renewal"
                    },
                    {
                        "code": "Rewrite",
                        "name": "Rewrite"
                    },
                    {
                        "code": "Submission",
                        "name": "Submission"
                    }
                ],
                "name": "Commercial Package Policy Definition",
                "priority": 1,
                "products": [],
                "reissueOnChange": false,
                "removalEndorsement": false
            },
            …

Creating form patterns

You can create a new form pattern with the following endpoint:

POST /admin/v1/form-patterns

The following properties are required in the request:

Parameter	Type	Description
`code`	string	The form pattern code. This value must be globally unique. PolicyCenter uses this value to link the form to a form pattern. This value cannot contain spaces.
`edition`	string	The form edition. PolicyCenter uses this value, in conjunction with the `formNumber` field, to indicate that two or more patterns are different editions of the same form. Similar to `formNumber`, this is an arbitrary string, but typically it is the edition used by the issuance system. Note: If you add a new edition, you must also update the availability dates of the old and new patterns. Merely setting the edition is not sufficient.
`endorsementNumbered`	Boolean	True if this form must have an endorsement number assigned to it at inference time. The endorsement number indicates the order in which the form is added to the policy. The insurer decides whether the form requires an endorsement number. Some insurers require an endorsement number for forms added after issuing the policy. For example, a form added in a policy change could require an endorsement number.
`formNumber`	string	The form number. This is an arbitrary string, but it typically is the form number used by the issuance system. This field is the form label that shows in the PolicyCenter user interface.
`genericFormInference`	string	The string must be the name of a class that implements the `gw.forms.GenericFormInference` interface. Depending on the value, other fields could be required. See Form inference below for more details. Note: This property is not required if you’re using a custom inference class. See Form inference below for details.
`inferenceTime`	`FormInferenceTime` Typekey	Forms cannot be assigned directly to policies. They are applied automatically at a specified stage of the policy creation process, such as when the policy is quoted or bound. This field specifies the stage at which the form is applied to the policy.
`jobTypes`	Typekey from the `FormPatternJobs` typefilter on the `Jobs` typelist	An array of job types that use this form pattern.
`name`	string	A human-readable description of the form pattern.
`products`	array of Product code ids	The products to which this form pattern applies.

The following example creates a new form pattern for the PersonalAuto product that gets applied to a policy when a submission or policy change is quoted:

Command

POST /admin/v1/form-patterns

Request

{
  "data": {
    "attributes": {
      "code": "Code001",
      "edition": "0001",
      "endorsementNumbered": true,
      "formNumber": "Test001",
      "genericFormInference": {
        "code": "GenericRemovalAndReplacementEndorsementForm"
      },
      "inferenceTime": {
        "code": "quote"
      },
      "jobTypes": [
        {
          "code": "PolicyChange"
        },
        {
          "code": "Submission"
        }
      ],
      "name": "Test Form 001",
      "products": [
        {
          "id": "PersonalAuto"
        }
      ]
    }
  }
}

Updating form patterns

You can use the following endpoints to update and delete form patterns:

PATCH /admin/v1/form-patterns/{policyFormPatternId}
DELETE /admin/v1/form-patterns/{policyFormPatternId}

The following example changes the job type to Renewal on form pattern pc:910:

Command

PATCH /admin/v1/form-patterns/pc:910

Request

{
  "data": {
    "attributes": {
      "jobTypes": [
        {
          "code": "Renewal"
        }
      ]
    }
  }
}

Note that in this example the Renewal job type is not added to existing job types for this form; all existing job types on form pattern pc:910 are replaced with the value specified in the PATCH request. This is due to the fact that PATCH on an array in Cloud API is destructive, not additive. When you PATCH an array, the new content replaces the previous content. If you want to add to an array, the PATCH request must contain all current members of the array as well as the member being added.

To delete the form pattern in the preceding example, use the following command:

DELETE /admin/v1/form-patterns/pc:910

Note: DELETE works only in development mode. The command will throw an exception if you try to delete a form pattern when the server is in production mode.

Form inference

When you create a new form pattern, you can use custom form inference or generic form inference. This section describes using generic form inference. To use custom form inference, see "Adding a custom inference class for form patterns" in the Application Guide and "Configuring custom form inference" in the Application Guide for more information.

If you use generic form inference, you must include a value for the genericFormInference property. The code is a string that contains the name of a class that implements the gw.forms.GenericFormInference interface.

Depending on the value of the genericFormInference property, there could be properties required for form pattern creation in addition to those specified in the table above. The following table lists the additional required properties for each base configuration generic form inference condition.

`genericFormInference` value	Additional required properties
GenericAdditionalInsuredForm	`policyLine`
GenericAdditionalInterestForm	`policyLine`
GenericAlwaysAddedEveryJobForm	none
GenericAlwaysAddedForm	none
GenericClauseNonExistenceForm	`clause` `policyLine`
GenericClauseSelectionForm	`clause` `policyLine`
GenericCovTermSelectionForm	`clause` `policyLine` `selectedCovTerm`
GenericCoverableTypeKeyForm	`coverableType` `coverableTypeKey` `coverableTypeKeyExistsOnAll` `coverableTypeList` `policyLine`
GenericRemovalAndReplacementEndorsementForm	none
GenericRemovalEndorsementForm	none

You might have a form that requires inference logic beyond what you can specify with the base configuration classes. In this case, you can either configure a new generic forms inference class or specify a custom form inference class. The custom form inference class overrides the base configuration settings.

Form patterns lookups

PolicyCenter automatically generates the list of forms for a policy by using forms inference logic and configuration settings. For example, if a user submits a new auto policy, the forms to print when issuing the policy can be inferred by the coverages, vehicles, and other fields. Included in this logic is a lookup of the jurisdiction and availability.

Forms can be designated as being explicitly available or unavailable in certain jurisdictions. With Cloud API, you can retrieve, add, and update jurisdiction availability information through the form patterns lookups endpoints.

Note: The information accessed by these endpoints corresponds to the information in the Availability table under the Jurisdictions tab in the user interface.

Retrieving jurisdiction availability

The list of jurisdiction availability for each form pattern is accessed through the form pattern lookups endpoints:

GET /admin/v1/form-patterns/{policyFormPatternId}/lookups
GET /admin/v1/form-patterns/{policyFormPatternId}/lookups/{lookupId}

Here is an example of retrieving the jurisdiction availability for form pattern pc:102:

Command

GET /admin/v1/form-patterns/pc:102/lookups

Response

{
    "data": [
        {
            "attributes": {
                "availability": {
                    "code": "Unavailable",
                    "name": "Unavailable"
                },
                "id": "pc:909",
                "jurisdiction": {
                    "code": "OK",
                    "name": "Oklahoma"
                },
                "startEffectiveDate": "1989-12-01T08:00:00.000Z"
            },
        …
        },
        {
            "attributes": {
                "availability": {
                    "code": "Available",
                    "name": "Available"
                },
                "id": "pc:910",
                "jurisdiction": {
                    "code": "MT",
                    "name": "Montana"
                },
                "startEffectiveDate": "1989-12-01T08:00:00.000Z"
            },
            …
        }

Adding jurisdiction availability

You can add jurisdiction availability information to a form pattern with the following endpoint:

POST /admin/v1/policy-form-patterns/{policyFormPatternId}/lookups

The following example makes form pc:910 unavailable in the Florida jurisdiction as of July 26, 2024:

Command

POST /admin/v1/form-patterns/pc:910/lookups

Request

{
    "data": {
        "attributes": {
            "availability": {
                "code": "Unavailable"
            },
            "startEffectiveDate": "20240726",
            "jurisdiction": {
                "code": "FL"
            }
        }
    }
}

Updating jurisdiction availability

You can update and delete a form pattern jurisdiction availability with the following endpoints:

PATCH /admin/v1/form-patterns/{policyFormPatternId}/lookups/{lookupId}
DELETE /admin/v1/form-patterns/{policyFormPatternId}/lookups/{lookupId}

The following example changes the availability of the jurisdiction with ID pc:90001 on form pattern pc:910 to Available:

Command

PATCH /admin/v1/form-patterns/pc:910/lookups/pc:90001

Request

{
    "data": {
        "attributes": {
            "availability": {
                "code": "Available"
            }
        }
    }
}

The following command deletes jurisdiction availability pc:90001 from form pattern pc:910:

DELETE /admin/v1/form-patterns/pc:910/lookups/pc:90001

Form patterns with lookups

You can use request inclusion to create a form pattern with lookups. Here is an example:

Command

POST /admin/v1/form-patterns

Request

{
  "data": {
    "attributes": {
      "code": "Code002",
      "edition": "0001",
      "endorsementNumbered": true,
      "formNumber": "Test002",
      "genericFormInference": {
        "code": "GenericAlwaysAddedForm"
      },
      "inferenceTime": {
        "code": "quote"
      },
      "jobTypes": [
        {
          "code": "PolicyChange"
        },
        {
          "code": "Submission"
        }
      ],
      "name": "Test Form 002",
      "products": [
        {
          "id": "PersonalAuto"
        }
      ]
    }
  },
    "included": {
        "FormPatternLookup": [
            {
                "attributes": {
                    "availability": {
                        "code": "Available"
                    },
                    "endEffectiveDate": "2024-01-01",
                    "jurisdiction": {
                        "code": "CA"
                    },
                    "startEffectiveDate": "2022-01-01"
                },
                "method": "post",
                "uri": "/admin/v1/form-patterns/this/lookups"
            }
        ]
    }
}

Policy and job forms

You can retrieve a list of all the forms associated with a particular job or policy. Because forms are inferred, you can’t directly add a form to a job or a policy, nor can you update it or delete it from the policy.

Use the following endpoints to retrieve a list of forms for a job or a policy:

GET /job/v1/jobs/{jobId}/forms
GET /policy/v1/policies/{policyId}/forms

These endpoints do not return an actual representation of the forms. Instead they return identifying information that indicates the physical forms that the issuance system creates.

Note: When you retrieve a list of forms on a policy, the list can change between quoting and binding. The list may be different because the information to accurately infer some forms is available only at binding or issuance.