Authority profile grants

Cloud API provides endpoints to query for, create, and modify and delete grants.

Querying for grants

To retrieve information about grants, use the following endpoints:

  • GET /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}/grants
  • GET /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}/grants/{grantId}
For example, the following request retrieves one of the grants for underwriting authority profile pc:agent1.
GET /admin/v1/uw-authority-profiles/pc:agent1/grants/pc:SdRrdafrc_csBc6qMX2Wp

"data": {
    "attributes": {
        "approveAnyValue": false,
        "comparator": {
            "code": "Monetary_LE",
            "name": "At most (monetary)"
        },
        "id": "pc:SdRrdafrc_csBc6qMX2Wp",
        "issueType": {
            "code": "HOPCondoCovALimit",
            "displayName": "HOP: Condo Coverage A limit value"
        },
        "moneyValue": {
            "amount": "200000",
            "currency": "usd"
        },
        "valueType": "money"
    },
    ...

Creating grants

Use the following endpoint to create a new grant for an existing underwriting authority profile:

  • POST /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}/grants

The issueType field

For every new grant, you must specify the grant's issueType.

There are two ways you can retrieve a list of existing issue types and their codes: through Cloud API and through PolicyCenter.

Retrieving issue type codes from Cloud API

From Cloud API, you can use the following endpoint from the Product Definition API:

  • GET /productdefinition/v1/reference-data/uw-issue-types

The following is a snippet of the output when executing this endpoint from the base configuration. It includes the response for two issue types: UWManagerReviewBlocksQuoteRelease and TSTManualMonetaryAmount.

{
    "data": [
        {
            "attributes": {
                "checkingSet": {
                    "code": "Manual",
                    "name": "Manual"
                },
                "code": "UWManagerReviewBlocksQuoteRelease",
                "comparator": {
                    "code": "None",
                    "name": "None"
                },
                "description": "To be reviewed by underwriting manager, blocking quote release",
                "name": "To be reviewed by underwriting manager, blocking quote release",
                "valueFormatterType": {
                    "code": "Unformatted",
                    "name": "Unformatted"
                }
            },
        },
        {

            "attributes": {
                "checkingSet": {
                    "code": "Manual",
                    "name": "Manual"
                },
                "code": "TSTManualMonetaryAmount",
                "comparator": {
                    "code": "Monetary_LE",
                    "name": "At most (monetary)"
                },
                "description": "Test manually triggered issue with monetary amount format",
                "name": "Test manually triggered issue with monetary amount format",
                "valueFormatterType": {
                    "code": "MonetaryAmount",
                    "name": "MonetaryAmount"
                }
            }
...

Retrieving issue type codes from PolicyCenter

You can also retrieve issue type codes directly from PolicyCenter by exporting metadata about the existing underwriting issues. To do this:

  1. In PolicyCenter, navigate to the Utilities screen on the Administration tab. (You must be logged in as a user who has permission to export admin data.)
  2. In the Export Administrative Data column, select Underwriting Issue Types.
  3. Click Export.

PolicyCenter generates an XML file with metadata about the underwriting issue types. The code for each issue type is defined in the <code> tag. The following is a snippet of the output when exporting this data from the base configuration. It includes the XML for two issue types: UWManagerReviewBlocksQuoteRelease and TSTManualMonetaryAmount:

  <UWIssueType public-id="pc:ScEwfrYMvGZSphmhfSCtk">
    <CheckingSet>Manual</CheckingSet>
    <Code>UWManagerReviewBlocksQuoteRelease</Code>
    <Comparator>None</Comparator>
    <Description>To be reviewed by underwriting manager, blocking quote release</Description>
    <Name>To be reviewed by underwriting manager, blocking quote release</Name>
    <ValueFormatterType>Unformatted</ValueFormatterType>
  </UWIssueType>
  <UWIssueType public-id="pc:S6FIzWqP5JFpEaPvDURH5">
    <CheckingSet>Manual</CheckingSet>
    <Code>TSTManualMonetaryAmount</Code>
    <Comparator>Monetary_LE</Comparator>
    <Description>Test manually triggered issue with monetary amount format</Description>
    <Name>Test manually triggered issue with monetary amount format</Name>
    <ValueFormatterType>MonetaryAmount</ValueFormatterType>
  </UWIssueType>
Note that you cannot have two or more grants in the same authority profile with the same UWIssueType. If you attempt to add a grant whose UWIssueType is used by an existing grant, you will get a validation error. For example, attempting to create a second grant of type ChangedProducerOrg results in this error:
"UWIssueTypes on grants must have unique code values. This underwriting authority profile has 
more than one grant where the UWIssueType code is 'ChangedProducerOrg'."

Additional required fields

There may be an additional required field based on the valueFormatterType of the underwriting issue type. The following table identifies the possible valueFormatterType values and the additional require field, if any.

valueFormatterType Additional required field Example
Age integerValue
"integerValue": "22"
Integer integerValue
"integerValue": "22"
MonetaryAmount moneyValue
"moneyValue": {
  "amount": "200000",
  "currency": "usd"
}
Number decimalValue
"decimalValue": "4"
StateSet stateSetValue
"stateSetValue": {
  "inclusionType": "exclusive",
  "states": ["CA","OR"]
}
Unformatted none

The following sections contain examples of commonly used valueFormatterType values.

Example of an unformatted grant

If an issueType has a valueFormatterType of Unformatted, then there is no required information beyond the issueType.

For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType is ChangedProducerOrg. This issue type is unformatted.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
  "data": {
    "attributes": {
        "issueType": {
            "code": "ChangedProducerOrg"
        }
    }
  }
}

Example of a MonetaryAmount grant

If an issueType has a valueFormatterType of MonetaryAmount, you must include a moneyValue attribute with an amount and currency.

For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType is ClaimTotalIncurred. This issue type is monetary amount, so there is an additional moneyValue attribute that specifies $200,000 USD.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
  "data": {
    "attributes": {
        "issueType": {
            "code": "ClaimTotalIncurred"
        },
        "moneyValue": {
            "amount": "200000",
            "currency": "usd"
        }
    }
  }
}

Example of a Number grant

If an issueType has a valueFormatterType of Number, you must include a decimalValue attribute.

For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType is IncidenceOfClaims. This issue type is decimal, so there is an additional decimalValue attribute that specifies 4.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
  "data": {
    "attributes": {
        "issueType": {
            "code": "IncidenceOfClaims"
        },
        "decimalValue": "4"
    }
  }
}

Example of a StateSet grant

If an issueType has a valueFormatterType of StateSet, you must include a stateSetValue attribute. This field has two child fields:

  • inclusionType, which must be set to one of these values:
    • inclusive (if the value must be within one of the states listed)
    • exclusive (if the value cannot be within one of the state listed)
  • states, which must be a JSON string array of codes from the States typelist

For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType is PAGargeState. This issue type is StateSet, so there is an additional stateSetValue attribute that specifies the garage state cannot be California or Oregon.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
  "data": {
    "attributes": {
        "issueType": {
            "code": "PAGarageState"
        },
        "stateSetValue": {
            "inclusionType": "exclusive",
            "states": ["CA","OR"]
        }
    }
  }
}

Creating authority profiles and grants in a single call

You can create an authority profile and one or more grants for the profile in a single call using request inclusion. For more information on request inclusion, see Request and response inclusion.

For example, the following call creates an authority profile and two grants.

POST /admin/v1/uw-authority-profiles

{
  "data": {
    "attributes": {
        "name": "Agent 3",
        "description": "Profile 3 for agents"
    }
  },
  "included": {
    "UWAuthorityGrant": [
      {
        "attributes": {
          "issueType": {
            "code": "ChangedProducerOrg"
          }
        },
        "method": "post",
        "uri": "/admin/v1/uw-authority-profiles/this/grants"
      },
      {
        "attributes": {
           "issueType": {
              "code": "ClaimTotalIncurred"
            },
            "moneyValue": {
              "amount": "200000",
              "currency": "usd"
            }
        },
        "method": "post",
        "uri": "/admin/v1/uw-authority-profiles/this/grants"
      }      
    ]
  }  
}

Modifying grants

You can use the following endpoints to PATCH or DELETE grants:

  • PATCH /uw-authority-profiles/{uwAuthorityProfileId}/grants/{grantId}
  • DELETE /uw-authority-profiles/{uwAuthorityProfileId}/grants/{grantId}

For example, the following request modifies the moneyValue of grant pc:227:

PATCH /admin/v1/uw-authority-profiles/pc:agent1/grants/pc:227

{
  "data": {
    "attributes": {
        "moneyValue": {
            "amount": "100000",
            "currency": "usd"
        }
    }
  }
}

The following request deletes grant pc:227:

DELETE /admin/v1/uw-authority-profiles/pc:agent1/grants/pc:227

<no request body>