Searching for active and archived claims
A caller application can search for one or more claims that are not associated with the
caller, that are archived, or otherwise do not appear in the GET /claims
results. Use the POST /claim/v1/search/claims-v2
endpoint to return a summary
of claim properties.
The naming convention of the endpoint POST /claim/v1/search/claims-v2
differentiates it from the original search endpoint, POST
/claim/v1/search/claims
. The original search endpoint is still viable, but
/claim/v1/search/claims-v2
provides additional request parameters and a
more detailed response payload, which can include archived cases.
Archived claims or claims in the process of being retrieved from archive never appear in GET
/claims
results. To search for archived claims, you must use
/claims/search-v2
, and set the appropriate fields to search for archived
claims.
For more information about data archiving, see Guidewire Data Archiving.
Note that a caller can search for a claim using /search/claims-v2
but may
not have access to the claim itself. If the caller does not have authorization to view the
claim, they can view the claim summary through POST /search/claims-v2
but
cannot view the claim through GET /claims/{claimId}
.
Request payload for a claim search
The request object for a POST /claim/v1/search/claims-v2
call must include a
body. The body must specify search parameters using the following syntax:
{
"data": {
"attributes": {
"archivedSearch": booleanValue,
"claimNumber": "stringValue",
"companyName": "stringValue",
"firstName": "stringValue",
"lastName": "stringValue",
"nameSearchType": {
"code": " ClaimSearchNameSearchTypeCode ",
},
"policyNumber": "stringValue",
"taxId": "stringValue"
}
}
}
You must provide one of the following fields for a minimum request payload:
The companyName
field and the firstName/lastName
fields
cannot be included in the same request payload.
claimNumber
companyName
nameSearchType
(optional)
firstName
lastName
nameSearchType
(optional)
policyNumber
taxID
nameSearchType
(optional)
For example, the following payload will search for all claims associated with policy number 54-123456:
POST /claim/v1/search/claims-v2
{
"data": {
"attributes": {
"policyNumber": "54-123456"
}
}
}
The following payload will search for all claims where there is a claimant who has a first name of "Ray" and a last name of "Newton":
{
"data": {
"attributes": {
"firstName": "Ray",
"lastName": "Newton"
}
}
}
Searching for archived claims
To search for archived claims, add the field archivedSearch
and set the
field to true. Request payloads that do not include the archivedSearch
field (or that set archivedSearch
to false) automatically search only for
active claims.
{
"status": 400,
"errorCode": "com.guidewire.pl.modules.rest.framework.v1.exceptions.OperationNotCurrentlyAllowedException",
"userMessage": "The operation is not currently allowed for this resource"
}
Searching by name and tax ID
When the payload includes either the firstName
, lastName
, companyName
, or taxID
, the default behavior is to search
for claims where there is a claimant with that first, last, company name, or tax ID.
You can also use the nameSearchType
parameter to execute searches where
the named person is either the insured, an additional insured, or has any role
on the claim. To do this, provide one of the following codes for the
ClaimSearchNameSearchType
code:
addinsured
(additional insured)any
(any role on the claim, including the roles beyond additional insured, claimant, and insured)claimant
(this is the default behavior)insured
For example, the following payload will search for all claims where the insured has a first
name of "Ray" and a last name of "Newton". The nameSearchType
uses a field
from the ClaimSearchNameSearchType
code:
POST /claim/v1/search/claims-v2
{
"data": {
"attributes": {
"firstName": "Ray",
"lastName": "Newton",
"nameSearchType": {
"code": "insured"
}
}
}
}
The following payload searches for all the archived claims where the insured has the company name of Wright Construction:
{
"data": {
"attributes": {
"archivedSearch": true,
"companyName": "Wright Construction",
}
}
}
Response payload for an empty claim search
The system APIs do not require you to provide any search parameters, but ClaimCenter will not execute a claim search with no search parameters. If you attempt to execute a claim search without search parameters, either from the user interface or through a system API, ClaimCenter returns the following error message:
Please specify Claim #, Policy #, any Contact field, Assigned To Group, Assigned To User,
Created By, Cat #, VIN or License Plate
Note that this message is intended primarily for user interface claim searches, which is
why it makes reference to fields not available to the
/claim/v1/search/claims-v2
endpoint, such as Assigned To
Group, Assigned To User, and Created
By.
Response payload for a claim search
The /claim/v1/claims
and
/claim/v1/claims/{claimId}
endpoints return a claim or a collection of
claims. The claim/v1/search/claims-v2
endpoint returns a collection in the
ClaimSearchResultWrapper. Consequently, the endpoint returns a payloads with a slightly
different structure.
The following table identifies the primary differences.
Information | Claim payload example | ClaimSearchResultWrapper payload example |
---|---|---|
Claim owner |
|
|
Claim ID |
|
|
Insured |
|
|
Claimants |
|
|
You can use query parameters to refine the response payload to exclude default fields and include non-default fields. For more information, see Refining response payloads.
Depending on whether the search was for archived or active claims, the response payload will vary.
The following sections identify the differences between archived and active claim search results.
Active claim search results
In the following example, a policy holder searched for all claims associated with Bill Kinman:
adjusterName
states the name of the claim’s assigned userassignedGroup
provides the group assigned to the claimclaimID
claimNumber
- A list of the
claimants
- The
flagged
field stating if the adjuster provided a unique flag statement for the claim futurePayments
are the payments scheduled to be sentinsuredName
lossDate
of the claim- The total amount
paid
policyNumber
of the claimremainingReserves
left on the claimstatus
of the claim, stating whether it is open or closed
{
"count": 1,
"data": [
{
"attributes": {
"adjusterName": "Andy Applegate",
"assignedGroup": "Auto1 - TeamA",
"claimId": "cc:SO",
"claimNumber": "235-53-425891",
"claimants": [
"Bill Kinman"
],
"flagged": true,
"futurePayments": {
"amount": "0.00",
"currency": "usd"
},
"insuredName": "Bill Kinman",
"lossDate": "2021-02-28T00:00:00.000Z",
"paid": {
"amount": "0.00",
"currency": "usd"
},
"policyNumber": "4775949863-02",
"remainingReserves": {
"amount": "0.00",
"currency": "usd"
},
"status": {
"code": "open",
"name": "Open"
}
}
},
Archived claim search results
Archived claim search results produce similar results to the active claim search, but also include archive-related fields. These archive-related fields include the following:
- The
archiveState
of the claim stating whether the claim is archived or is returning to an active claim state - Whether the claim was
archived
or not (always true) - The
archivedAdjuster
which states the adjuster that performed the archive - The
claimInfoID
stating the identification number of theclaimInfo
object that allows the archived claim to be retrieved
Differences between search versions
The following table from outlines the differences in search functions between the
claim/v1/search/claims-v2
endpoint and the
claim/v1/search/claims
endpoint.
Search function | claim/v1/search/claims-v2 |
|
Search for archived claims | ✓ | |
Search by tax ID | ✓ | |
Search by business name | ✓ | |
Search for claims regardless of association to user | ✓ | ✓ |