Towers and layers

Create a tower when you want a coinsurance agreement to cover a range of risk in terms of financial limits. The tower can define a single range with a single risk layer, or it can be divided into multiple layers. A policy can have a tower that applies to the entire policy or a tower can be associated with one or more policy sections.

You can use layers to perform the following:
  • Define the range of risk for a coinsurance agreement
  • Set commission override amounts
  • Decline coverage for a range of risk

For more information on the business functionality of towers and layers, see Application Guide.

Query for tower details

Use the following endpoints to query for tower details:
  • GET /jobs/{jobId}/towers
  • GET /jobs/{jobId}/towers/{towerId}
  • GET /jobs/{jobId}/towers/{towerId}/layers
  • GET /jobs/{jobId}/towers/{towerId}/layers/{layerId}
  • GET /jobs/{jobId}/towers/{towerId}/layers/{layerId}/parties
  • GET /jobs/{jobId}/towers/{towerId}/layers/{layerId}/parties/{partyID}
  • GET /jobs/{jobId}/towers/{towerId}/policy-sections
  • GET /jobs/{jobId}/towers/{towerId}/policy-sections/{sectionId}
  • GET /policies/{policyId}/towers/
  • GET /policies/{policyId}/towers/{towerId}
  • GET /policies/{policyId}/towers/{towerId}/layers
  • GET /policies/{policyId}/towers/{towerId}/layers/{layerId}
  • GET /policies/{policyId}/towers/{towerId}/layers/{layerId}/parties
  • GET /policies/{policyId}/towers/{towerId}/layers/{layerId}/parties/{partyId}
  • GET /policies/{policyId}/towers/{towerId}/policy-sections
  • GET /policies/{policyId}/towers/{towerId}/policy-sections/{sectionId}

For example, the following query returns a list of policy sections associated with job pc:Sf-bEIu7Pui2fQz_40mdJ and tower 3:

Command
GET /job/v1/jobs/pc:Sf-bEIu7Pui2fQz_40mdJ/towers/3/policy-sections
Java
Response
{
    "count": 1,
    "data": [
        {
            "attributes": {
                "id": "LI",
                "sectionType": {
                    "code": "LI",
                    "name": "Liability"
                }
            },
            "checksum": "cc195ceeffa633d1a405dd531568d4b5",
            "links": {
                "self": {
                    "href": "/job/v1/jobs/pc:Sf-bEIu7Pui2fQz_40mdJ/towers/3/policy-sections/LI",
                    "methods": [
                        "get"
                    ]
                }
            }
        }
    ],
    "links": {
        "first": {
            "href": "/job/v1/jobs/pc:Sf-bEIu7Pui2fQz_40mdJ/towers/3/policy-sections",
            "methods": [
                "get"
            ]
        },
        "self": {
            "href": "/job/v1/jobs/pc:Sf-bEIu7Pui2fQz_40mdJ/towers/3/policy-sections",
            "methods": [
                "get"
            ]
        }
    }
}
Java

Create a tower with layers

Create a tower for a submission so that you can define the scope of coinsurance agreements and coverage, or to override commission overrides based on the range of coverage. Creating a tower requires multiple calls to different endpoints.
After reading this topic, you'll be able to:
  • Create a tower.
  • Define one or more layers to specify each coverage range.
  • Associate a coinsurance agreement with a layer.

Before you begin

Verify the following before you create a tower:
  • The product must support layers. If you want to enable coinsurance for layers, the product must also support coinsurance. For more information, see the Coinsurance and risk section of Creating Products with APD App.
  • PolicyCenter must include one or more coinsurers in the PolicyCenter database. For more information, see Application Guide.

Step 1: Create a tower

A policy can have more than one tower. You can create a tower with a section or without a section. When you create a tower without a section, the tower applies to any coverages on the policy that are not covered by other coinsurance agreements or risk towers.

For example, suppose a policy has two towers where one tower is associated with the Liability section and the other has no section. The tower associated with the Liability section covers the liability coverages. The tower without a section covers all coverages on the policy that are not part of the Liability section.

Use the following command to create a tower:
  • POST /job/v1/jobs/${jobId}/towers

For example, the following request creates a tower with a section HO for job pc:abcd1234

Command
POST /job/v1/jobs/pc:abcd1234/towers
Java
Request
{
  "data": {
    "attributes": {
      "initialPolicySections": [
        {
          "sectionType": {
            "code": "HO"
          }
        }
      ]
    }
  }
}
Java

Step 2: Add a layer to a tower

A tower has one or more layers. The fields required to add a layer differ based on whether coinsurance is enabled or not.

  • POST /job/v1/jobs/${jobId}/towers/${towerId}/layers
Configure the following properties in the request body:
  • excessAmount. The starting range for the layer.
  • limitAmount. The end range for the layer
  • policyNumberSuffix. A string of up to 8 characters that BillingCenter appends to the policy number on the splinter policy for this agreement.
  • To enable coinsurance, include the following properties:
    • coinsured. Set to true to enable coinsurance.
    • leadersFee. A number that specifies the leader fee percentage.
    • model. The model specifies which party distributes payments to the followers and which party pays claims to the insured. Valid values from the CoinsuranceModel typelist include administer, administerNoClaim, brokerClaim, and brokerNoClaim.
    • ourRole. The role (lead or follow) of the PolicyCenter insured.
    • ourShare. The percentage of risk for the PolicyCenter insured.
  • To decline coverage by the PolicyCenter insurer, set declined to true .

For example, the following request creates a layer on tower 123 with coinsurance enabled:

Command 
POST /job/v1/jobs/pc:abcd1234/towers/123/layers
Java
Request body with coinsurance enabled:
{
  "data": {
    "attributes": {
      "coinsured": true,
      "declined": false,
      "excessAmount": {
        "amount": "100",
        "currency": "usd"
      },
      "leadersFee": "5.5",
      "limitAmount": {
        "amount": "1000",
        "currency": "usd"
      },
      "model": {
        "code": "administer"
      },
      "ourRole": {
        "code": "follow"
      },
      "ourShare": "10",
      "policyNumberSuffix": "testsuf"
    }
  }
}
Java

If you do not want to enable coinsurance, you can instead include something like the following in the request body:

Request body without coinsurance enabled
{
  "data": {
    "attributes": {
      "excessAmount": {
        "amount": "100",
        "currency": "usd"
      },
      "limitAmount": {
        "amount": "1000",
        "currency": "usd"
      },
      "policyNumberSuffix": "testsuf"
    }
  }
Java

Step 3: Add a party to a layer (required for coinsured layers)

If a coinsurance agreement is associated with the layer, use the following command to add a coinsurance party to a layer:
  • POST /job/v1/jobs/{jobId}/towers/{towerId}/layers/{layerId}/parties

For example, the following request adds a party pc:1 to layer 502 in tower 404 for job pc:S2dbzbNWO8Nh_PHfbYCDm:

Command
POST /job/v1/jobs/pc:S2dbzbNWO8Nh_PHfbYCDm/towers/404/layers/502/parties
Java
Request body
{
  "data": {
    "attributes": {
      "coinsuranceRole": {
        "code": "follow"
      },
      "coinsuranceShare": "10",
      "producerCode": {
        "id": "pc:1"
      }
    }
  }
}
Java
Response
{
    "data": {
        "attributes": {
            "coinsuranceRole": {
                "code": "follow",
                "name": "Follow"
            },
            "coinsuranceShare": "10.00",
            "id": "404",
            "organization": {
                "displayName": "Enigma Fire & Casualty",
                "id": "systemTables:1",
                "type": "Organization",
                "uri": "/admin/v1/organizations/systemTables:1"
            },
            "producerCode": {
                "displayName": "Standard Code",
                "id": "pc:1"
            }
        },
        "checksum": "84ac93be2ccd5fef4f1f4e2aee618c28",
        "links": {
            "self": {
                "href": "/job/v1/jobs/pc:S2dbzbNWO8Nh_PHfbYCDm/towers/404/layers/502/parties/404",
                "methods": [
                    "delete",
                    "get",
                    "patch"
                ]
            }
        }
    }
}
Java

Update a tower

After you create a tower, you can perform the following updates:

Associate a section with a tower

Use the following command to add a section to a tower:
  • POST /job/v1/jobs/{jobId}/towers/{towerId}/policy-sections

The request body must include the sectionType code.

For example, the following request adds the property section PP to tower 209 on job pc:SrAlPrMYv14hLu-oNBTzG:

Command 
POST /job/v1/jobs/pc:SrAlPrMYv14hLu-oNBTzG/towers/209/policy-sections
Java
Request body
{

"data": {

        "attributes": {

            "sectionType": {
                "code": "PP"

                }

           }

     }
}
JSON

Remove a section from a tower

Use the following command to remove a section from a tower:
  • DELETE /job/v1/jobs/{jobId}/towers/{towerId}/policy-sections/{sectionId}
For example, the following command deletes policy section MO from tower 209 on job pc:SrAlPrMYv14hLu-oNBTzG: 
DELETE /job/v1/jobs/pc:SrAlPrMYv14hLu-oNBTzG/towers/209/policy-sections/MO
Java
Note: This command fails if deleting the section results in more than one tower or coinsurance agreement with no sections on the policy.

Update a layer

Use the following command to update layer properties:
  • PATCH /job/v1/jobs/{jobId}/towers/{towerId}/layers/{layerId}

For example, the following request updates the excessAmount to 350000 for layer 502 in tower 404 on job pc:S2dbzbNWO8Nh_PHfbYCDm:

Command
PATCH /job/v1/jobs/pc:S2dbzbNWO8Nh_PHfbYCDm/towers/404/layers/502
Java
Request body
{
 "data": {
     "attributes": {
         "coinsured": true,
         "excessAmount": {
             "amount": "350000.00",
             "currency": "usd"
             }
         }
      }
}
Java

Delete a tower

Use the following command to delete a tower from a submission:

  • DELETE /job/v1/jobs/${jobId}/towers/${towerId}

For example, the following command deletes tower 209 from job pc:SrAlPrMYv14hLu-oNBTzG: 
DELETE /job/v1/jobs/pc:SrAlPrMYv14hLu-oNBTzG/towers/209
Java