Typelist metadata

The `/typelists` endpoints

The Common API contains two /typelist endpoints:

common/v1/typelists - By default, this returns the names and descriptions of all typelists in ClaimCenter.
common/v1/typelists/{typelistName} - By default, this returns the non-retired typecodes in the named typelist.

In the base configuration, these endpoints are available only to callers who have been authenticated.

Including retired typecodes

By default, the common/v1/typelists/{typelistName} endpoint returns only non-retired typecodes. You can include retired typecodes by adding the following query parameter to the call:

?includeRetired=true

Querying with typekey filters

Some typelists have a parent/child relationship. These typelists make use of typekey filters. A typekey filter is a mapping that identifies, for a typecode in one typelist, the valid values in a related typelist. For more information on typekey filters, refer to the Configuration Guide.

For example, the following typelists make use of typekey filters:

ActivityType - The activity's broad type, such as General, Approval, or Assignment Review.
ActivityCategory - An activity's specific category, such as Interview, Reminder, or Approval Denied.

If an activity's ActivityType is set to General, then some ActivityCategory values (such as Interview and Reminder) are valid, whereas others (such as Approval Denied) are not.

The `typekeyFilter` query parameter

When using the /typelists/{typelistName} endpoint, if the typelist is associated with a typekey filter, you can limit the results to only those typecodes that have a given relationship with the typekey filter. You can specify three types of criteria:

/typelists/{typelistName}?typekeyFilter=category:in:typecodeList
- Returns all typekeys whose categories array contains at least one of the listed typecodes
/typelists/{typelistName}?typekeyFilter=category:cn:typecodeList
- Returns all typekeys whose categories array contains all of the listed typecodes
/typelists/{typelistName}?typekeyFilter=category:ni:typecodeList
- Returns all typekeys whose categories array does not contain any of the listed typecodes

The typecode list must be specified as:

relatedTypelist1.Typecode1,relatedTypelist2.Typecode2,...

where:

relatedTypelistX is the name of the Nth related typelist.
TypecodeX is the Nth typecode to use as a filter

Examples

No filter parameter

This call does not use the typekeyFilter query parameter. Therefore, it retrieves all typecodes in the ActivityCategory typelist:

GET /common/v1/typelists/ActivityCategory

Associated with one category

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of General:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general

Associated with any of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of either General or Approval:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general,ActivityType.approval

Associated with all of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of both General and Approval: (Note that, in the base configuration, there are no typecodes that meet this criteria.)

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general,ActivityType.approval

Associated with none of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are not associated with either the ActivityType of General or the ActivityType of Approval:

GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:ni:ActivityType.general,ActivityType.approval

The /business-line-metadata endpoint

In ClaimCenter, the line of business model is a set of typelists that organizes policies, coverages, and covered losses into a single hierarchy. Collectively, these typelists define the valid types of coverages, incidents, and exposures for a given policy and type of loss. For more information on the line of business model, see the Configuration Guide.

A caller application may want to access the metadata for these typelists so that it can determine valid coverage and exposure values for a given claim. This information can be retrieved using the Claim API's /business-line-metadata endpoint. This endpoint returns the entire line of business model in the following format:

policyTypes
- coverageTypes
  - coverageSubtypes
    - exposureType
    - incidentType
    - lossPartyType
- internalPolicyType
- lobCodes
  - lossType
    - lossCauses

For example, the following request executed against the base configuration returns the following edited results.

Command

GET /claim/v1/claims/business-line-metadata

Response

{
    "policyTypes": [
        {
            "code": "BusinessOwners",
            "coverageTypes": [
                {
                    "code": "BOPReceivablesCov",
                    "coverageSubtypes": [
                        {
                            "code": "BOPReceivablesCov",
                            "description": "Accounts Receivable",
                            "exposureType": {
                                "code": "GeneralDamage",
                                ...
                            },
                            "incidentType": {
                                "code": "Incident",
                                ...
                            },
                            "lossPartyType": {
                                "code": "insured",
                                ...
                            },
                            "name": "Accounts Receivable",
                            "priority": -1,
                            "sortOrder": 103
                        }
                    ],
                    ...
                },
                ...
            ],
            "description": "Business Owners",
            "internalPolicyType": {
                "code": "commercial",
                ...
            },
            "lobCodes": [
                {
                    "code": "BOPLine",
                    "description": "BusinessOwners",
                    "lossType": {
                        "code": "GL",
                        "description": "Liability",
                        "lossCauses": [
                            {
                                "code": "animal_bite",
                                ...
                            },
                            ...
                        ],
                        "name": "Liability",
                        "priority": -1,
                        "sortOrder": 1
                    },
                    ...
                }
            ],
            "name": "Businessowners",
            ...
            ## This is the end of the Businessowners policy metadata
        },
        {
            ## This is the start of the policy metadata for the Business Auto policy
            "code": "BusinessAuto",
        ...
        },
        ...
    ]
}

There are no filters defined for this endpoint. Caller applications always receive the entire model. Any required parsing or filtering must be done by the caller application.

Tutorial: Query for typelist metadata

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will query for all typecodes in the ClaimantType typelist. You will then use a typekey filter to query for all claimant types that are related to a claim loss type of PR (which means the claim's policy is a property policy).

Tutorial steps

In Postman, start a new request by clicking the + to the right of the Launchpad tab.
Specify Basic Auth authorization using user su and password gw.
Enter the following call and click Send:
- GET http://localhost:8080/cc/rest/common/v1/typelists/ClaimantType
The response payload contains all non-retired claimant types. Verify that the first three codes in the payload are: insured, householdmember, veh_ins_driver.)
Modify the call by adding the following query parameter to the end, and then click Send:
- ?typekeyFilter=category:cn:LossType.PR
The response payload now contains only claimant types relevant to property claims. Verify that the first three codes in the payload are now: insured, householdmember, propertyowner. (veh_ins_driver no longer appears because it is not a valid claimant type for a property claim.)