Creating exposures

The POST /claims/{claimId}/exposures endpoint can be used to create new exposures.

Minimum creation criteria

In order for an exposure to be assignable, the exposure must have the following:

  • A coverage and coverage subtype
  • A claimant
  • An incident

The exposure resource also has a coverage attribute, which identifies the coverage object on the policy. This is not a required attribute. However, there are features in ClaimCenter that require this attribute to be set in order to work properly. For example, deductible handling works only when the exposure is associated with the appropriate coverage object so that ClaimCenter can determine if the coverage has a deductible and if so how much. Therefore, Guidewire recommends always setting the exposure's coverage attribute.

The following JSON skeleton summarizes these components as they appear in a POST /exposures request payload.

{
    "data": {
        "attributes": {
            "primaryCoverage": {
                "code": "..."
            },
            "coverageSubtype": {
                "code": "..."
            },
            "claimant": {
                "id" / "refid" / "policySystemId": "..."
            },
            "...Incident": {
                "id" / "refid": "..."
            },
            "coverage": {
                "id": "..."
            }
        }
    },
    "included": {
        "...Incident": ...
        "ClaimContact": ...
    }
}
Java

Note the following:

  • The coverage and coverage subtype are identified by typecodes from the CoverageType and CoverageSubtype typelists.
  • The claimant can be referenced by any of the following:
    • id, if the claimant already exists on the claim
    • refid, if the claimant is being created in the same payload as the exposure
    • policySystemId, if the claimant is listed on the policy
  • The exposure must reference an incident. The incident type varies based on the coverage.
  • The incident can be referenced by any of the following:
    • id, if the incident already exists on the claim
    • refid, if the incident is being created in the same payload as the exposure
  • The coverage is optional. However, Guidewire recommends always including it as some ClaimCenter features require this to be specified to work as expected.

Building an exposure payload

To build an exposure payload, you must:

  1. Identify the coverage type
  2. Identify the coverage subtype
  3. Create or identify the claimant
  4. Create or identify the incident
  5. Identify the coverage

Note that each item in the previous list does not necessarily map to a single block of code. When it is time to create the exposure, the caller application may already have the required information. Also, the caller application may be able to query ClaimCenter for multiple pieces of information in a single call.

Example creation of an exposure payload

The following sections provide an example of creating the payload for a new exposure. This exposure will be for claim 235-53-373906 in the sample data, which is assigned to Betty Baker. The ID for this claim is demo_sample:8037. The claim's policy has two vehicles: a Honda Civic and a Ford Explorer. The new exposure will be for the Honda Civic using the collision coverage. The claimant is Allen Robertson, an additional insured on the policy.

All of the calls assume the instance of ClaimCenter is on the local machine.

Step 1: Identify the coverage type

If the caller application does not know the coverage type, it can use the GET /claims/{claimId}/policy endpoint to determine the coverages attached to the Honda Civic.

Request to determine the coverage type

GET  http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:8037/policy/vehicle-risk-units?fields=*all
Java

Response payload (snippet)

"RUNumber": 1,
  "coverages": [
    {
      ...
      "coverageType": {
        "code": "PACollisionCov",
        "name": "Collision"
        }
       ...
    }
  ],
  "id": "cc:9",
  "vehicle": {
    ...
    "id": "demo_sample:4",
    "make": "Honda",
    "model": "Civic"
    ...
Java

Exposure request payload (first part)

Based on the previous query, the first part of the POST /exposures request payload looks like this:

{
    "data": {
        "attributes": {
            "primaryCoverage": {
                "code": "PACollisionCov"
            },
            ...
Java

Step 2: Identify the coverage subtype

The set of ClaimCenter coverage types and coverage subtypes change infrequently. To reduce the number of calls, you may want to store the possible coverage types and coverage subtypes locally with the caller application.

Either during development or at the time of exposure creation, the caller application can determine the coverage subtypes for a given coverage by executing the Common API's GET /typelists endpoint. To limit the response to only the coverage subtypes for a given coverage type, the call can filter the CoverageSubtype typelist using the exposure's CoverageType (such as PACollisionCov).

For more information on the Common API's GET /typelists endpoint, see The /typelists endpoints.

Request to determine the coverage subtype

GET  http://localhost:8080/cc/rest/common/v1/typelists/CoverageSubtype
         ?typekeyFilter=category:cn:CoverageType.PACollisionCov
Java

Response payload (snippet)

"description": "Subtype of coverage, filtered by CoverageType",
"name": "CoverageSubtype",
"typeKeys": [
  {
    "code": "PACollisionCov",
    "description": "Collision",
    "name": "Collision",
    "priority": -1
  }
]
Java

Exposure request payload (first two parts)

Based on the previous query, the first and second part of the POST /exposures request payload looks like this:

{
    "data": {
        "attributes": {
            "primaryCoverage": {
                "code": "PACollisionCov"
            },
            "coverageSubtype": {
                "code": "PACollisionCov"
            },
            ...
Java

Step 3: Create or identify the claimant

If the claimant exists on the policy, the payload can identify the claimant by its policySystemId. If necessary, the caller application can query the Policy Administration System for the policySystemId.

If the claimant does not already exist, the caller application can create a new ClaimContact in the POST /exposures request payload and then reference that ClaimContact using a refid. This technique is referred to as request inclusion. For more information, see Request inclusion.

If the claimant exists in ClaimCenter, the payload can identify the claimant by its id. If necessary, the caller application can query ClaimCenter for the id.

Note: If the claimant already exists in ClaimCenter, always reference the existing ClaimContact and use the id field. Do not create an additional ClaimContact through the use of the refid field. Creating the same logical ClaimContact twice results in duplicate data. This can complicate the processing of the claim.

In this example, the claimant has already been copied over to ClaimCenter. Therefore, the payload will identify the claimant by ClaimCenter id.

Request to determine the claimant ID

GET  http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:8037/contacts
Java

Response payload (snippet)

{
  "attributes": {
    ...
    "displayName": "Allen Robertson",
    "id": "cc:32",
    ...
    },
Java

Exposure request payload (first three parts)

Based on the previous query, the first three parts of the POST /exposures request payload looks like this:

{
    "data": {
        "attributes": {
            "primaryCoverage": {
                "code": "PACollisionCov"
            },
            "coverageSubtype": {
                "code": "PACollisionCov"
            },
            "claimant": {
                "id": "cc:32"
            },
            ...
Java

Step 4: Create or identify the incident

An incident is a collection of information that typically represents an item that was lost or damaged. Incidents may reference objects on a policy. (For example, a vehicle incident can reference a vehicle on the policy.) But, incidents never appear on policies. Incidents exist solely in ClaimCenter.

If the incident does not already exist, the caller application can create a new incident in the POST /exposures request payload and then reference that incident using a refid. This technique is referred to as request inclusion. For more information, see Request inclusion. Depending on the incident type, the new incident can reference a child object (a location, injured person, or vehicle). This child object could be on the policy, in ClaimCenter, or also created in the POST /exposures request payload.

If the incident already exists in ClaimCenter, the caller application can reference it by its id.

Note: If the incident already exists in ClaimCenter, always reference the existing incident and use the id field. Do not create an additional incident through the use of the refid field. Creating the same logical incident twice results in duplicate data. This can complicate the processing of the claim.

In this example, the incident does not exist and must be created. But, it will reference a vehicle that is already on the policy. The ID for this vehicle was already retrieved in the first step when the coverage type was identified. The ID is demo_sample:4. There is no need for an additional request to retrieve additional vehicle information.

Exposure request payload (first four parts)

Based on the previous query, the first four parts of the POST /exposures request payload looks like this:

{
    "data": {
        "attributes": {
            "primaryCoverage": {
                "code": "PACollisionCov"
            },
            "coverageSubtype": {
                "code": "PACollisionCov"
            },
            "claimant": {
                "id": "cc:32"
            },
            "vehicleIncident": {
                "refid": "newVehicleIncident"
            },
            ...
        }
    },
    "included": {
        "VehicleIncident": [
            {
              "attributes": {
                "vehicle": {
                  "id": "demo_sample:4"
                }
              },
            "refid": "newVehicleIncident",
            "method": "post",
            "uri": "/claim/v1/claims/demo_sample:8037/vehicle-incidents"
            }
        ]
    }
}
Java

Step 5: Identify the coverage

The coverage is an object on the policy that provides information about the coverage, including coverage terms such as deductibles or limits. When creating an exposure, you are not required to specify the coverage. However, Guidewire recommends always doing so. This is because there are features in ClaimCenter, such as deductible handling, that require this attribute to be set in order to work properly.

The coverage must be referenced by its id. The endpoint used to retrieve a coverage depends on what the coverage is attached to. For example:

  • For coverages attached to the policy itself (which are typically liability coverages), use: GET /claims/{claimId}/policy/coverages/{coverageId}.
  • For coverages attached to a location-based risk unit, use: GET /claims/{claimId}/policy/location-based-risk-units/{locationBasedRiskUnitId}
  • For coverages attached to a vehicle risk unit, use: GET /claims/{claimId}/policy/vehicle-risk-units/{vehicleRiskUnitId}

Request to determine the coverage ID

Suppose that the policy for claim demo_sample:8037 has a single vehicle risk unit whose id is cc:121.

GET  http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:8037/
     policy/vehicle-risk-units/cc:121
Java

Response payload (snippet)

{
    "attributes": {
      "coverages": [
        {
          "coverageType": {
            "code": "PACollisionCov"
          },
          "id": "cc:7007",
...
Java

Exposure request payload (complete)

The complete POST /exposures request payload looks like this:

{
    "data": {
        "attributes": {
            "primaryCoverage": {
                "code": "PACollisionCov"
            },
            "coverageSubtype": {
                "code": "PACollisionCov"
            },
            "claimant": {
                "id": "cc:32"
            },
            "vehicleIncident": {
                "refid": "newVehicleIncident"
            },
            "coverage": {
                "id": "cc:7007"
            }
        }
    },
    "included": {
        "VehicleIncident": [
            {
              "attributes": {
                "vehicle": {
                  "id": "demo_sample:4"
                }
              },
            "refid": "newVehicleIncident",
            "method": "post",
            "uri": "/claim/v1/claims/demo_sample:8037/vehicle-incidents"
            }
        ]
    }
}
Java