Guidewire ClaimCenter™

for Guidewire Cloud

Cloud API Consumer Guide

Release: 2022.09
© 2023 Guidewire Software, Inc.
For information about Guidewire trademarks, visit [Link]
Guidewire Proprietary & Confidential — DO NOT DISTRIBUTE

Product Name: Guidewire ClaimCenter for Guidewire Cloud

Product Release: 2022.09
Document Name: Cloud API Consumer Guide
Document Revision: 19-March-2023
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Contents
Support.......................................................................................................................................................... 13

Part 1
Basic REST operations
1 Introduction to Cloud API................................................................................................................................ 17
List of APIs in Cloud API.................................................................................................................................... 17
Version numbers for major and minor releases....................................................................................... 18
Viewing API definitions.................................................................................................................................... 19
Swagger UI............................................................................................................................................... 19
The API definition endpoints and Postman.............................................................................................. 20
The Guidewire API References site...........................................................................................................23
REST API fundamentals.................................................................................................................................... 23
Cloud API calls.......................................................................................................................................... 23
Resources................................................................................................................................................. 24
Endpoints................................................................................................................................................. 25
Requests and responses........................................................................................................................... 28
Testing requests and responses............................................................................................................... 29
2 GETs.................................................................................................................................................................. 31
Overview of GETs............................................................................................................................................. 31
Standard payload structures............................................................................................................................ 31
Viewing schemas...................................................................................................................................... 33
View a response schema in Swagger UI................................................................................................... 33
Sending GETs.................................................................................................................................................... 33
Send a GET using Postman....................................................................................................................... 33
Tutorial: Send a basic Postman request................................................................................................... 34
Payload structure for a basic response............................................................................................................ 34
Structure of a basic response................................................................................................................... 34
The count property.................................................................................................................................. 35
The data section....................................................................................................................................... 35
The attributes section.............................................................................................................................. 35
The checksum field................................................................................................................................... 37
The links subsection (for an element)...................................................................................................... 37
The collection-level links section.............................................................................................................. 38
Payload structure for a response with included resources.............................................................................. 38
Tutorial: Send a Postman request with included resources..................................................................... 39
Structure of a response with included resources..................................................................................... 39
The related section (for a resource)......................................................................................................... 40
The included section (for a response)...................................................................................................... 41
Including either a collection or a specific resource.................................................................................. 41
Determining which resources can be included........................................................................................ 42
3 Query parameters............................................................................................................................................43
Overview of query parameters........................................................................................................................ 43
Viewing query parameter definitions.......................................................................................................44
The fields query parameter.............................................................................................................................. 44

Contents 3
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Tutorial: Send a GET with the fields parameter........................................................................................46

The filter query parameter............................................................................................................................... 47
Endpoints with default filters................................................................................................................... 49
Tutorial: Send a GET with the filter parameters....................................................................................... 49
The sort query parameter................................................................................................................................ 49
Tutorial: Send a GET with the sort query parameter................................................................................51
The pagination query parameters.................................................................................................................... 51
pageSize limits the number of resources per page.................................................................................. 51
The self link returns a single resource in a page.......................................................................................52
pageOffset pages through resources........................................................................................................52
includeTotal retrieves the total number of resources.............................................................................. 53
Tutorial: Send a GET with the pageSize and totalCount parameters........................................................ 54
Query parameters for included resources........................................................................................................54
Specifying query parameters that apply to an included resource............................................................54
Summary of query parameters for included resources............................................................................ 55
Tutorial: Send a GET with query parameters for included resources....................................................... 56
4 POSTs............................................................................................................................................................... 59
Overview of POSTs........................................................................................................................................... 59
Standardizing payload structures..................................................................................................................... 60
Viewing request schemas......................................................................................................................... 61
View a request schema in Swagger UI......................................................................................................61
Designing a request payload............................................................................................................................ 61
Request payload structure....................................................................................................................... 61
Determining the minimum creation criteria............................................................................................ 62
Specifying scalar values............................................................................................................................ 62
Specifying compound values.................................................................................................................... 63
Setting values and objects to null.............................................................................................................64
Sending POSTs.................................................................................................................................................. 64
Send a POST using Postman..................................................................................................................... 64
Tutorial: Create a new note that specifies required fields only................................................................65
Tutorial: Create a new note that specifies optional fields........................................................................ 65
Responses to a POST........................................................................................................................................ 66
Postman behavior with redirects..................................................................................................................... 67
Business action POSTs...................................................................................................................................... 67
Improving POST performance.......................................................................................................................... 68
5 PATCHes........................................................................................................................................................... 69
Overview of PATCHes....................................................................................................................................... 69
The PATCH payload structure........................................................................................................................... 69
Designing a request payload.................................................................................................................... 70
PATCHes and arrays.......................................................................................................................................... 70
Sending PATCHes.............................................................................................................................................. 70
Send a PATCH using Postman................................................................................................................... 70
Tutorial: PATCH an activity........................................................................................................................ 71
Responses to a PATCH...................................................................................................................................... 72
PATCHes and lost updates................................................................................................................................ 72
Postman behavior with redirects..................................................................................................................... 72
6 DELETEs............................................................................................................................................................ 73
Overview of DELETEs........................................................................................................................................ 73
Tutorial: DELETE a note............................................................................................................................ 73
DELETEs and lost updates.................................................................................................................................74
7 Request headers.............................................................................................................................................. 75

4 Contents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

HTTP headers................................................................................................................................................... 75
Overview of Cloud API headers................................................................................................................ 75
Send a request with a Cloud API header using Postman..........................................................................77
Language and locale......................................................................................................................................... 77
Routing related calls in clustered environments.............................................................................................. 79
Preventing duplicate database transactions.................................................................................................... 80
Warming up an endpoint................................................................................................................................. 80
Handling a call with unknown elements.......................................................................................................... 81
Validating response payloads against additional constraints........................................................................... 81

Part 2
Optimizing calls
8 Reducing the number of calls.......................................................................................................................... 85
Features that execute multiple requests at once............................................................................................. 85
Comparing features that execute multiple requests................................................................................ 85
Determining which feature to use............................................................................................................86
9 Composite requests......................................................................................................................................... 87
Constructing composite requests.....................................................................................................................87
The requests section................................................................................................................................ 88
Using variables to share information across subrequests........................................................................ 89
Responses to the subrequests..................................................................................................................90
The selections section.............................................................................................................................. 92
Composite request limitations................................................................................................................. 94
Composite request examples................................................................................................................... 95
Administering composite requests...................................................................................................................95
Error handling...........................................................................................................................................95
Logging..................................................................................................................................................... 96
Configuring the maximum number of subrequests................................................................................. 96
Complete composite request syntax................................................................................................................ 97
10 Request inclusion.............................................................................................................................................99
Syntax for simple parent/child relationships.................................................................................................... 99
Syntax for named relationships...................................................................................................................... 101
Additional request inclusion behaviors.......................................................................................................... 102
11 Batch requests............................................................................................................................................... 105
Batch request syntax...................................................................................................................................... 105
Optional subrequest attributes.............................................................................................................. 106
Batch request examples................................................................................................................................. 106
Simple batch requests............................................................................................................................ 106
Batch requests with query parameters.................................................................................................. 107
Batch requests with request payloads................................................................................................... 107
Batch requests with distinct operations................................................................................................. 108
Administering batch requests........................................................................................................................ 108
Specifying subrequest headers.............................................................................................................. 108
Specifying onFail behavior......................................................................................................................109
Configuring the maximum number of subrequests............................................................................... 109
12 Lost updates and checksums......................................................................................................................... 111
Lost updates................................................................................................................................................... 111
Checksums..................................................................................................................................................... 112
Checksums for PATCHes and business action POSTs...................................................................................... 113
Tutorial: PATCH an activity using checksums.......................................................................................... 113

Contents 5
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Tutorial: Assign an activity using checksums.......................................................................................... 114

Checksums for DELETEs..................................................................................................................................115
Send a checksum in a request header using Postman........................................................................... 115
Tutorial: DELETE a note using checksums...............................................................................................115
13 Asynchronous calls........................................................................................................................................ 117
Overview of asynchronous calls..................................................................................................................... 117
Determining when the call has been processed.................................................................................... 118
Retrieving the response using /requests/{asyncRequestId}...................................................................120
Retrieving the response from /requests/{asyncRequestId}/response................................................... 121
Sending a request asynchronously................................................................................................................. 121
Tutorial: Send a request asynchronously................................................................................................122
Retrieving the response to the original request.............................................................................................123
Response information in the /requests response.................................................................................. 123
Response information using the /response endpoint............................................................................ 123
Tutorial: Retrieve information about an asynchronous request.............................................................124
Waiting for a response synchronously........................................................................................................... 124
Tutorial: Send a request asynchronously with a wait time.....................................................................125
Asynchronous request administration........................................................................................................... 126

Part 3
Business flows: FNOL and adjudication
14 Executing FNOL.............................................................................................................................................. 129
The FNOL process in ClaimCenter.................................................................................................................. 129
Draft claims and open claims................................................................................................................. 129
Verified and unverified policies.............................................................................................................. 130
The FNOL process in Cloud API...................................................................................................................... 130
The Cloud API FNOL process.................................................................................................................. 130
FNOL use cases by policy state............................................................................................................... 131
Composite request limitations with claims............................................................................................ 132
Canceling claims..................................................................................................................................... 133
Claim modes........................................................................................................................................... 133
The Test Util API............................................................................................................................................. 133
Viewing Test Util API information...........................................................................................................133
Set the ClaimCenter environment in Studio........................................................................................... 133
View the Test Util API in Swagger UI...................................................................................................... 134
Creating test policy data.........................................................................................................................134
Tutorial: Creating a policy using the Test Util API................................................................................... 137
Creating test data for related objects.....................................................................................................138
POSTing a minimal draft claim....................................................................................................................... 138
Tutorial: POSTing a minimal draft claim for personal auto.....................................................................138
PATCHing a draft claim....................................................................................................................................139
Tutorial: PATCHing a draft claim for personal auto................................................................................. 139
POSTing a typical draft claim.......................................................................................................................... 140
Tutorial: POSTing a typical draft claim for personal auto....................................................................... 140
Creating claims with unverified policies......................................................................................................... 141
Minimum criteria for an unverified policy and claim............................................................................. 142
Contacts on an unverified policy............................................................................................................ 143
Locations on an unverified policy........................................................................................................... 144
Risk units on an unverified policy........................................................................................................... 144
Coverages on unverified policies............................................................................................................ 145

6 Contents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

PATCH an unverified policy..................................................................................................................... 148

Retrieving information about an unverified policy.................................................................................148
Submitting a draft claim................................................................................................................................. 149
Minimum criteria for submitting a claim with an unverified policy....................................................... 149
Tutorial: Submitting a draft claim........................................................................................................... 150
Canceling a draft claim................................................................................................................................... 151
Sample payload addendum............................................................................................................................151
Sample policy payload............................................................................................................................ 151
Sample draft claim payload.................................................................................................................... 153
Sample composite claim payload........................................................................................................... 154
Sample composite first-and-final........................................................................................................... 160
15 Claims.............................................................................................................................................................165
Querying for claims associated with you........................................................................................................165
Querying for a claim by claim ID.................................................................................................................... 166
Searching for active and archived claims....................................................................................................... 167
Request payload for a claim search........................................................................................................ 168
Response payload for a claim search..................................................................................................... 170
Retrieving policy information......................................................................................................................... 171
Summary of the policy endpoints.......................................................................................................... 172
Assigning claims............................................................................................................................................. 173
Validating claims.............................................................................................................................................174
ClaimCenter validation levels................................................................................................................. 174
Validating a claim through the Cloud API............................................................................................... 175
Retrieving claims from archive....................................................................................................................... 177
16 ClaimContacts................................................................................................................................................ 179
Overview of ClaimContacts in ClaimCenter....................................................................................................179
Overview of ClaimContacts in Cloud API........................................................................................................ 180
Modifying ClaimContact roles........................................................................................................................ 183
Setting reserved roles.............................................................................................................................183
Setting non-reserved roles..................................................................................................................... 184
Identifying the ClaimContact..........................................................................................................................186
Creating a new ClaimContact and specifying its role............................................................................. 186
Specifying a role for a ClaimContact that is already on the claim.......................................................... 186
Specifying a role for a contact that is on the policy............................................................................... 187
ClaimContact role constraints........................................................................................................................ 187
17 Incidents........................................................................................................................................................ 191
Overview of incidents in ClaimCenter............................................................................................................ 191
Overview of incidents in Cloud API................................................................................................................ 192
Fixed property incidents.................................................................................................................................193
Managing fixed property incidents........................................................................................................ 194
Managing dwelling incidents..................................................................................................................194
Managing other structure incidents.......................................................................................................195
General incidents........................................................................................................................................... 196
Injury incidents...............................................................................................................................................197
Living expenses incidents............................................................................................................................... 197
Mobile property incidents..............................................................................................................................198
Baggage incidents...................................................................................................................................198
Property contents incidents................................................................................................................... 200
Vehicle incidents.................................................................................................................................... 201
Trip incidents.................................................................................................................................................. 202
Overview of trip incidents...................................................................................................................... 202

Contents 7
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Managing trip incidents......................................................................................................................... 202

Managing trip accommodations............................................................................................................ 203
Managing trip segments.........................................................................................................................203
18 Exposures....................................................................................................................................................... 205
Overview of exposures in ClaimCenter.......................................................................................................... 205
Creating exposures......................................................................................................................................... 207
Minimum creation criteria..................................................................................................................... 207
Building an exposure payload................................................................................................................ 208
Step 1: Identify the coverage type......................................................................................................... 208
Step 2: Identify the coverage subtype....................................................................................................209
Step 3: Create or identify the claimant.................................................................................................. 210
Step 4: Create or identify the incident................................................................................................... 210
Step 5: Identify the coverage................................................................................................................. 211
Querying for and modifying exposures.......................................................................................................... 212
Assigning exposures....................................................................................................................................... 212
Additional exposure endpoints...................................................................................................................... 214
Deleting draft exposures........................................................................................................................ 214
Validating exposures.............................................................................................................................. 214
Closing exposures................................................................................................................................... 215
19 Service requests.............................................................................................................................................217
Overview of service requests in ClaimCenter.................................................................................................217
Service request kinds............................................................................................................................. 217
The service request lifecycle.................................................................................................................. 218
Invoices for service request....................................................................................................................220
Overview of service requests in the Cloud API.............................................................................................. 220
Service request APIs and vendor portals................................................................................................220
Required service request data model.................................................................................................... 220
Service request numbers........................................................................................................................221
Support for each service request kind................................................................................................... 221
Composite request limitations with service requests............................................................................ 222
Querying for service requests........................................................................................................................ 222
Creating service requests............................................................................................................................... 222
Minimum creation criteria..................................................................................................................... 222
Modifying existing service requests............................................................................................................... 224
PATCHing service requests......................................................................................................................224
Assigning service requests to users........................................................................................................ 225
Advancing a service request in its lifecycle.................................................................................................... 226
Submitting, accepting, and declining service requests.......................................................................... 227
Completing and canceling service requests........................................................................................... 228
Service request quotes................................................................................................................................... 229
Service request invoices................................................................................................................................. 231
Querying for invoices............................................................................................................................. 231
Creating invoices for service requests.................................................................................................... 231
Approving service request invoices........................................................................................................ 232
Marking invoices as paid........................................................................................................................ 232
Withdrawing service request invoices....................................................................................................233

Part 4
Business flows: Financials
20 Reserves......................................................................................................................................................... 237

8 Contents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Overview of reserves in ClaimCenter............................................................................................................. 237

Querying for reserves..................................................................................................................................... 238
Creating reserves............................................................................................................................................240
Example of creating reserves................................................................................................................. 241
Example of adding to reserves............................................................................................................... 242
Acknowledging reserve transactions..............................................................................................................242
21 Creating checks.............................................................................................................................................. 245
Overview of checks in ClaimCenter................................................................................................................ 245
Payments................................................................................................................................................ 245
Checks.................................................................................................................................................... 245
Check sets...............................................................................................................................................246
Querying for check sets and checks............................................................................................................... 246
POSTing checks...............................................................................................................................................248
Check creation in ClaimCenter............................................................................................................... 248
Check creation through Cloud API..........................................................................................................248
Example of creating a minimal check set............................................................................................... 249
Recurrences....................................................................................................................................................250
Recurrences in ClaimCenter................................................................................................................... 251
Recurrences in Cloud API....................................................................................................................... 251
Sending checks every X months on the Nth day.................................................................................... 251
Sending checks every X months on the Nth dayOfWeek....................................................................... 252
Sending checks every X weeks on dayOfWeek....................................................................................... 252
Deductible handling....................................................................................................................................... 253
Deductible handling in ClaimCenter.......................................................................................................253
Deductible handling in Cloud API........................................................................................................... 253
Underpaying and overpaying deductibles.............................................................................................. 254
PATCHing checks............................................................................................................................................. 255
DELETEing checks........................................................................................................................................... 255
22 Managing the check life cycle....................................................................................................................... 257
The check life cycle prior to submission......................................................................................................... 257
Advancing a check to submission through Cloud API.............................................................................258
The check life cycle after submission............................................................................................................. 258
Advancing a check beyond submission through Cloud API.................................................................... 259
Acknowledging payment transactions........................................................................................................... 260
23 Recoveries and recovery reserves................................................................................................................. 263
Querying for recoveries and recovery reserves............................................................................................. 264
Creating recoveries and recovery reserves.................................................................................................... 265
Creating a recovery reserve....................................................................................................................265
Creating a recovery reserve set.............................................................................................................. 266
Acknowledging a recovery reserve.........................................................................................................267
Creating a recovery................................................................................................................................ 267
24 Multicurrency................................................................................................................................................ 269
Multicurrency overview................................................................................................................................. 269
Multicurrency in ClaimCenter................................................................................................................ 269
Multicurrency in Cloud API.....................................................................................................................269
Retrieving multicurrency information............................................................................................................ 270
Multicurrency reserves.......................................................................................................................... 270
Multicurrency checks............................................................................................................................. 271
POSTing multicurrency information............................................................................................................... 272
POSTing a reserve with multiple currencies........................................................................................... 272
POSTing a reserve with a custom exchange rate....................................................................................272

Contents 9
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

POSTing a check set with multiple currencies........................................................................................ 273

POSTing a check set with a custom exchange rate................................................................................. 274
Specifying multicurrency line items....................................................................................................... 275
Additional exchange rate schema fields................................................................................................. 277

Part 5
Business flows: Framework APIs
25 Activities........................................................................................................................................................ 281
Querying for activities.................................................................................................................................... 281
Creating activities........................................................................................................................................... 281
Assigning activities......................................................................................................................................... 283
Assignment options................................................................................................................................ 283
Assignment examples.............................................................................................................................283
Retrieving recommended assignees.......................................................................................................284
Closing activities............................................................................................................................................. 285
Additional activity functionality..................................................................................................................... 287
26 Documents..................................................................................................................................................... 289
Overview of documents................................................................................................................................. 289
Querying for document information.............................................................................................................. 290
Querying for document metadata..........................................................................................................290
Querying for document content.............................................................................................................290
POSTing documents....................................................................................................................................... 291
POSTing documents using Postman....................................................................................................... 292
PATCHing documents..................................................................................................................................... 293
DELETEing documents.................................................................................................................................... 294
27 Notes.............................................................................................................................................................. 295
Querying for notes......................................................................................................................................... 295
Creating claim notes.......................................................................................................................................295
Additional notes functionality........................................................................................................................ 297
28 Users and groups........................................................................................................................................... 299
Users.............................................................................................................................................................. 299
Querying for user information............................................................................................................... 299
Creating users.........................................................................................................................................300
Updating users....................................................................................................................................... 301
Deleting users.........................................................................................................................................301
Groups............................................................................................................................................................ 302
Querying for groups............................................................................................................................... 302
Creating groups...................................................................................................................................... 302
Assigning users to groups....................................................................................................................... 303
Updating groups..................................................................................................................................... 305
Deleting groups...................................................................................................................................... 305
Queues........................................................................................................................................................... 305
Working with queues............................................................................................................................. 306
User roles....................................................................................................................................................... 307
Querying for user roles...........................................................................................................................307
Creating user roles................................................................................................................................. 308
Updating user roles................................................................................................................................ 310
Authority limit profiles................................................................................................................................... 310
Retrieving information about authority limit profiles............................................................................ 311
Creating authority limit profiles............................................................................................................. 312

10 Contents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Adding limits to the profile.....................................................................................................................313

Updating authority limit profiles............................................................................................................ 314
29 Typelist metadata.......................................................................................................................................... 317
The /typelists endpoints.................................................................................................................................317
Querying with typekey filters......................................................................................................................... 317
Tutorial: Query for typelist metadata............................................................................................................. 319
30 Batch processes............................................................................................................................................. 321
Overview of batch processes......................................................................................................................... 321
Querying for batch process information........................................................................................................ 322
Managing batch processes............................................................................................................................. 323
Starting a batch process......................................................................................................................... 323
Starting a batch process with arguments............................................................................................... 324
Stopping a batch process....................................................................................................................... 325
31 Database consistency checks........................................................................................................................ 327
Overview of database consistency checks (DBCCs)........................................................................................327
Running DBCCs............................................................................................................................................... 328
Running a previously run DBCC.............................................................................................................. 329
Querying for DBCC run information............................................................................................................... 330

Contents 11
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

12 Contents
Support

For assistance, visit the Guidewire Community.

Guidewire customers
[Link]
Guidewire partners
[Link]
part 1

Basic REST operations

The following topics discuss how caller applications can execute fundamental REST operations on Cloud API, and the
Guidewire-specific enhancements to these operations. This includes how to:
• Construct GET requests to query for data
• Use query parameters to refine response payloads
• Construct POST requests to create new data
• Construct PATCH requests to modify existing data
• Construct DELETE requests to remove data

Basic REST operations 15

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

16 Basic REST operations

chapter 1

Introduction to Cloud API

InsuranceSuite Cloud API for ClaimCenter is a set of RESTful system APIs that caller applications can use to request
data from or initiate action within an ClaimCenter. Cloud API is built on top of the Guidewire REST API framework
using the Swagger 2.0 Specification. The APIs in Cloud API are also referred to as the system APIs.
This topic provides an overview of the APIs available in Cloud API and how you can view them.
If you are coding a consumer application and have limited experience with REST APIs, the “REST API fundamentals”
on page 23 section provides a brief overview of how REST APIs work in Cloud API.

List of APIs in Cloud API

Cloud API for ClaimCenter consists of the following APIs:

API Name Description Path

Admin API for administration objects, such as users and groups /admin/v1
API List API for listing the available APIs /apis
Async API for retrieving responses to asynchronously processed /async/v1
calls
Claim API for claims and claim-specific objects /claim/v1
Common API for common InsuranceSuite platform objects, such as /common/v1
activities and notes
Composite API for composite requests /composite/v1
System Tools API for batch processes and database consistency checks /systemtools/v1
Test Util API for testing during development /test-util/v1
(Available only when enabled)

Note: The /apis endpoint returns all REST APIs for ClaimCenter. This includes some APIs that are not part of
Cloud API, such as /system/v0/database and /system/v0/maintenance. The only APIs that are part of
Cloud API are the ones listed in the previous table. These are the only APIs that have access to Cloud API
features, such as request inclusion and authentication.
Cloud API for ContactManager consists of the following APIs:

API Name Description Path

Admin API for administration objects, such as users and groups /admin/v1

Introduction to Cloud API 17

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

API Name Description Path

API List API for listing the available APIs /apis
Async API for retrieving responses to asynchronously processed /async/v1
calls
Common API for common InsuranceSuite platform objects, such as /common/v1
activities and notes
Contact API for contacts /contact/v1

Note: The /apis endpoint returns all REST APIs for ContactManager. This includes some APIs that are not
part of Cloud API, such as /system/v0/database and /system/v0/maintenance. The only APIs that are part
of Cloud API are the ones listed in the previous table. These are the only APIs that have access to Cloud API
features, such as request inclusion and authentication.
You can use the API path to view metadata about the API. This is discussed in detail in the following section.

Version numbers for major and minor releases

The following section defines what a minor release is. Minor releases are not expected to have "breaking changes".
The types of changes that do and do not fall into the definition of "breaking change" are described in the Schema
Backwards Compatibility Contract. To access a copy of this contract, consult your Guidewire representative.

Release numbers
Every release of Cloud API has a three-digit version number. The first digit is the version's major release number. The
second digit is the version's minor release number. For example, suppose the latest release of Cloud API has a version
number of 1.5.0. This release is major release 1 and minor release 5.
The release number can be seen in the API definition. For example, in Swagger UI, when you view an API, the version
number appears in a gray bubble next to the API name. (Note that individual APIs do not have distinct version
numbers. The version numbers that appear in the API definition are for the entire Cloud API release.)
For every API, the major release number is also part of the endpoint path. It is the number that appears after the "/v".
For example, the first major release of the Admin API has a path of /admin/v1. If there was a theoretical ninth major
release of the Admin API, its path would be /admin/v9.

Minor and major releases

In future releases, Cloud API functionality is expected to change. To define and control these changes, Guidewire
defines the scope of change that can be added to each release.
• In a minor version release, the functionality is either identical to the previous release or additive.
• In a major version release, the functionality has changed from the previous release.
A given release of ClaimCenter can have multiple major versions of Cloud API. For example, suppose that in a given
year there were the following releases:
• The January release is the first new major release.
• The April release is identical or additive to the previous release.
• The July release is identical or additive to the previous release.
• The October release includes changes to existing functionality.
In this case, the January, April, and July releases would all include a single major release of the APIs whose endpoint
included "/v1". The October release would include two major versions: the "/v1" major release (whose changes were
identical or additive to the previous release) and a new "/v2" major release. This is summarized in the following table.

Release Month Version # Compared to the previous release, this Major versions in this release
release...
January 1.0.0 ...is identical or additive /admin/v1

18 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Release Month Version # Compared to the previous release, this Major versions in this release
release...
April 1.0.1 ...is identical or additive /admin/v1
July 1.0.2 ...is identical or additive /admin/v1
October 1.0.3 and 2.0.0 ...includes changes to existing functionality /admin/v1 (identical or additive to July's release),
and /admin/v2 (containing the changed
functionality)

Viewing API definitions

An API definition is a technical description of the behavior of an API. The API definition typically includes the
following:
• The endpoints in the API
• The schemas used by each endpoint, which dictate how resources in the payload are structured
• The fields available in each resource
• The properties that apply to each field
There are several different ways you can view API definitions for Cloud API. This includes:
• Swagger UI
• Calling the /[Link] endpoint (or the /[Link]) through a request tool
• The Guidewire API references site

Swagger UI
Swagger UI is an open source tool that presents API definitions as interactive web pages. For information on Swagger
UI, refer to the Swagger web site: [Link]
Swagger UI is automatically bundled with ClaimCenter.
Swagger UI can be helpful when viewing schema information. Swagger UI presents this information hierarchically.
Child schemas are indented with respect to parent schemas, and individual nodes of the hierarchy can be expanded and
collapsed. Searching through a complex schema is relatively straight-forward in Swagger UI.
However, Swagger UI strips out some of the metadata that is present in the source files. For example, Guidewire-
proprietary tags are not rendered in Swagger UI. When you need access to all the metadata for an API, it may be better
to call the /[Link] endpoint directly.
Swagger UI also requires access to a running instance of ClaimCenter. If you do not have access to a running instance,
you may want to use the Guidewire API References site.
Note: Swagger UI also has the capability to send requests to a working endpoint and observe responses.
However, Guidewire recommends using Swagger UI only to view API definitions. The APIs in Cloud API are
significantly robust. When sending requests using Swagger UI, the performance time for getting responses can
be unacceptably long. Also, if you attempt to send calls from Swagger UI and log into the ClaimCenter user
interface on the same machine, the two systems may attempt to share the same session, and either or both may
stop working. For more information on recommended request tools, see “Requests and responses” on page
28.

View definitions using Swagger UI

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “List of APIs in Cloud API” on page 17.)
2. Start ClaimCenter.
3. In a web browser, enter the URL for Swagger UI. This loads the Swagger UI tool.

Introduction to Cloud API 19

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The format of the URL is <applicationURL>/resources/swagger-ui/

• For example, for a local instance of ClaimCenter, use: [Link]
ui/
4. In the text field at the top of the Swagger UI interface, enter the URL that points to the desired API's
[Link] file. Then, click Explore.
• The format of the URL is <applicationURL>/rest<APIpath>/[Link].
• For example, to view the common API, enter: <applicationURL>/rest/common/v1/[Link]

Results
The following screenshot shows the top of the Swagger UI display of the Common API.

Information in Swagger UI
The Cloud API version number at the top in a gray bubble after the API name. (Note that individual APIs do not have
distinct version numbers. The version numbers that appear in Swagger UI are for the entire Cloud API release.)
Every endpoint in the API appears in a list. For each API, the following information is shown by default:
• The endpoint's operation (such as GET)
• The endpoint's path (such as /activities)
• An endpoint summary (such as "Returns a list of activities assigned to the current user")
If you click the operation button, additional information about the endpoint appears. This includes:
• A more detailed endpoint description
• A list of query parameters supported by the endpoint
• A hierarchical list of resources and schemas used by the endpoint (This appears in the Responses section on the
Model tab.)

The API definition endpoints and Postman

In some situations, it is useful to view the raw API definition information. In Cloud API, every API includes two
endpoints that return the API definition: /[Link] and /[Link].

20 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• /[Link] returns the API definition using the OpenAPI 3.0 specification, often referred to as "OpenAPI 3.0"
• /[Link] returns the API definition using the Swagger 2.0 specification, often referred to as "Swagger 2.0"
Note: Cloud API is built using the Swagger 2.0 Specification. However, the definition for each API can be
returned in either the Swagger 2.0 specification (using the /[Link] endpoint) or the OpenAPI 3.0
specification (using the /[Link] endpoint).
The API definition endpoints can be helpful when you want to view all metadata about an endpoint, including metadata
that other tools such as Swagger UI might strip out. However, the API definition endpoints present information in a
"raw" format. There is no use of color, font, or placement to help separate information. Schema hierarchies are not as
readable as in Swagger UI. When you need to review a schema hierarchy in detail, it may be easier to use Swagger UI.
Retrieving API definitions for these endpoints requires access to a running instance of ClaimCenter. If you do not have
access to a running instance, you may want to use the Guidewire API References site.
From a metadata perspective, the OpenAPI 3.0 specification is richer than the Swagger 2.0 specification. So whenever
either endpoint is an option, Guidewire recommends using the /[Link] endpoint. For example, Guidewire-
proprietary tags (such as x-gw-typelist) are listed in the /[Link] response, but not in the /[Link]
response. However, some tools used to render API metadata may not be robust enough to process information using the
OpenAPI 3.0 specification. The /[Link] endpoint is available for these types of circumstances.
In the base configuration, the API definition endpoints are available to any caller, including unauthenticated callers.

Postman
You can call the API definition endpoints using a request tool. Request tools are not automatically bundled with
InsuranceSuite applications. You must download and install them on your own.
Postman is a request tool that Guidewire recommends. This tool has the ability to:
• Save API calls, including headers and payloads
• Save collections of calls
• Automatically create a collection of calls for a schema's paths by importing the Swagger schema file
• Share collections with other developers on your team
For more information and to download the tool, see [Link]

View definitions using Postman

Before you begin
Install Postman. For more information and to download the tool, see [Link]

About this task

This task does not involve authentication information. This is because every type of caller can request API metadata,
including unauthenticated callers.

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “List of APIs in Cloud API” on page 17.)
2. Start ClaimCenter.
3. Start Postman.
4. In Postman, start a new request by clicking the + tab to the right of the Launchpad tab.
5. Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
6. In the Enter request URL field, enter the following URL: <applicationURL>/rest<APIpath>/[Link] (or
<applicationURL>/rest<APIpath>/[Link]). For example, to view the Common API on a local instance
of ClaimCenter, enter the following:

Introduction to Cloud API 21

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• [Link] (OR [Link]

[Link])
7. Click the Send button to the right of the request field.

Results
The API information appears in the results pane. For example, the following is the first part of the results when calling
the previously referenced [Link] endpoint:

{
"components": {
"parameters": {
"activityId": {
"description": "The REST identifier for the activity, as returned via previous requests that return a
list of activities\n",
"in": "path",
"name": "activityId",
"required": true,
"schema": {
"type": "string"
}
},
...

Information in the output of API definition endpoints

The output of the API definition endpoints is "raw" JSON.
• General information about the API can be found in the info section.
• The list of endpoints can be found in the paths section.
◦ If an endpoint path has multiple operations, the endpoint path is listed only once. Each operation appears under
it.
◦ For example, in the Common API, the /activities/{activityId} path has listings for GET and PATCH.
• Summaries and descriptions appear inline with the thing they summarize or describe.

Additional options for the /[Link] endpoints

If you are using the /[Link] endpoints, the following query parameters provide additional ways to manage the
response. (Note that the /[Link] endpoints do not support the following query parameters.)
Alternate options for rendering schemas
These query parameters change the way in which schema metadata is rendered.
• filterByUser - Whether to filter endpoints and schema properties by the authorization of this user.
◦ Defaults to false
• prettyPrint - Whether to "pretty print" the returned schema, making it larger but more human readable.
◦ Defaults to false.
For example, the following HTTP request retrieves the metadata for the Admin API. It also enables filterByUser and
prettyPrint.

[Link]

Converting schema metadata into SDKs

Some tools, such as openapi-generator, provide the ability to consume a Swagger schema and output a Software
Development Kit (SDK). The following query parameter changes the way in which an SDK is rendered.
• enablePolymorphism - Whether to use the discriminator/oneOf pattern to output schemas in cases where the valid
set of fields can vary based on some attribute of the data such as the country or subtype.
◦ Defaults to true.
◦ When set to false, the schema contains the superset of all valid fields. For example, address schemas will
contain all fields for all countries, rather than have separate schemas for different countries.

22 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ Setting this to false may make the schema output more consumable by tools that do not support that part of the
OpenAPI schema.
For example, the following HTTP request retrieves the metadata for the Admin API. It also disables polymorphism.
[Link]
(For more information on openapi-generator, see [Link]

The Guidewire API References site

Guidewire Documentation hosts copies of the API references at the following URL:
[Link]
This link automatically directs you to the API references of the latest release. From here, you can navigate to the API
reference for a specific product and then to a specific API (such as the Admin API).
The API reference information on the Guidewire API References site is based on the output of the /[Link]
endpoint. This endpoint returns the API definition using the OpenAPI 3.0 specification.
The Guidewire API References site is useful when you want to view the API definitions and you do not have
immediate access to a working instance of ClaimCenter.

View definitions using the API References site

Procedure
1. In a web browser, enter the URL [Link] The site automatically redirects you
to the API definitions for the latest version of the product.
2. Click the API Reference link under the name of the product, such as ClaimCenter.
3. In the left-hand pane, click the name of the desired API.

Information on the API References site

The API reference information on the Guidewire API References site is based on the output of the /[Link]
endpoint. This endpoint returns the API definition using the OpenAPI 3.0 specification.
Every endpoint in the API appears in the left-hand pane. To view information about a specific endpoint, click the
endpoint name. This causes information about the endpoint to be shown in the center pane.
The middle pane shows general information about the endpoint, such as:
• The endpoint's operation (such as GET)
• The endpoint's path (such as /activities)
• An endpoint summary (such as "Returns a list of activities assigned to the current user")
The right pane shows Response samples. You can expand the [Link] note to see the fields on the parent resource.
If there is an included node, you can expand it to see the child resources for the endpoint.

REST API fundamentals

This topic discusses the fundamental concepts of REST APIs and how those concepts are used in Cloud API. This
topic is intended primarily for developers with minimal experience using REST APIs.

Cloud API calls

InsuranceSuite Cloud API is a set of RESTful system APIs that caller applications can use to request data from or
initiate action within an InsuranceSuite application. These APIs can be used by browser-based applications and
service-to-service applications. This documentation uses the term caller application to generically refer to any
application or service calling Cloud API.

Introduction to Cloud API 23

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Making Cloud API calls

The following diagram provides a high-level overview of the interaction between the caller application and the Cloud
API.

1. The caller application constructs a request object. The request object consists of:
• A header, which can contain authentication information and other metadata.
• A payload, when necessary.
2. The caller application sends the request to Cloud API using an HTTP command.
• The command calls a specific endpoint.
• The command may include query parameters that further identify the data that is desired.
• The request object is sent with the command.
3. Cloud API processes the request.
• This activity uses all of the InsuranceSuite application logic, such as validation logic and pre-update rules.
• The request is restricted by authorization controls within Cloud API.
4. Cloud API responds with an HTTP response code (such as 200 for success) and a response object. The response
object consists of:
• A header
• A payload, when necessary.
Cloud API and InsuranceSuite logic
In the software industry, some RESTful APIs are configured to interact directly with the database. Cloud API is not
configured to behave this way. Cloud API interacts with operational data only through the layer of the application's
business logic. Therefore, Cloud API always leverages the existing business logic of the application.
For example:
• Suppose an internal user does not have permission to create an activity. If the internal user attempts to create an
activity through Cloud API, the attempt results in an insufficient permissions error.
• Suppose there is a validation rule that requires an activity's due date to be set in the future. If an external system
attempts to create an activity with a due date in the past, the attempt results in a validation error.
• Suppose there is a pre-update rule that creates an approval activity whenever a document is marked as "Final". If an
external system creates a "Final" document through Cloud API, the pre-update rule will create an approval activity.

Resources
The primary mechanism for passing information between the caller application and ClaimCenter is the resource. A
resource is an instance of data that you can create, modify, delete, or query for. Resources are defined in JSON schema
files.
Every resource has a type. The type defines the Guidewire data model entities that the resource maps to. For example,
Activity resources map to the Activity data model entity. In most cases, each resource maps to a single data model

24 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

entity. However, there are some resources which map to multiple data model entities. For example, the ClaimContact
resource maps to three data model entities in ClaimCenter: ClaimContact, Contact, and ClaimContactRole.
Resources contain a set of fields. Each field stores information about the resource. Depending on the context, fields are
also referred to as properties or attributes.
Resources are exchanged in the payloads of the request and response objects. The payload is a block of JSON-
formatted text that contains fields from the relevant resources and their values. The following is a portion of the
response payload for an Activity resource.

"attributes": {
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
},
"dueDate": "2020-11-16T08:00:00.000Z",
"id": "xc:20",
"priority": {
"code": "urgent",
"name": "Urgent"
"subject": "Contact claimant"
}

Note that a field can store:

• A scalar value, such as the subject field.
• A set of values, such as the assignedUser field. This is referred to as an inline object.
• An array of objects. (There is no example of this in Activity. If there were, the field name would be followed by
square braces ([ and ]) delimiting the array. Each array member would be listed in curly braces ({ and }).
Every resource can be uniquely defined by its resource ID. This value maps to the data model entity's PublicID field.
The activity in the previous example is activity xc:20.
A single resource is called an element. For example, /contact/xc:203 is an element. (In some REST API literature,
this is also referred to as a singleton.)
A set of resources is called a collection. For example, /contact/xc:203/addresses (the addresses associated with
contact xc:203) is a collection.

Endpoints
Every API consists of a set of endpoints. An endpoint is a command that a caller application can use to request data
from or trigger action in ClaimCenter. For example, the /common/v1/activities endpoint can be used to either
request data about ClaimCenter activities or trigger actions related to ClaimCenter activities. When referenced in
documentation, endpoints start with a slash (/), such as the /activities endpoint. Endpoints are defined in Swagger
schema files.
In Cloud API, the endpoint path (the full name of the endpoint) includes the API and the version. For convenience
sake, the documentation often refers to endpoints using only the last part of the endpoint path. For example, the /rest/
common/v1/activities endpoint is often referred to simply as "the /activities endpoint".

Endpoints in Cloud API have four fundamental components: root resources, child resources, methods, and paths.

Root resources
Every endpoint has a root resource. The root resource is the resource which the endpoint creates, updates, deletes, or
queries for. Every call to an endpoint makes use of the root resource.
For example, the root resource for the /common/v1/activities endpoint is Activity. This endpoint is used to
potentially create, update, delete, or queries for activities.

Introduction to Cloud API 25

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Child resources
Most endpoints also include child resources. A child resource is a resource related to the root resource. Child resources
improve the usability of an endpoint by providing access to information related to the root resource. For example, the /
common/v1/activities endpoint has one child resource - Notes. This means you could use the endpoint to:

• Query for a specific activity (and only the activity)

• Query for a specific activity and its related notes
Every call to an endpoint must make use of the root resource. The use of child resources is optional.

Inline and included resources

Child resources can be declared either as inline resources or included resources.
• An inline resource is a resource that appears in the attributes section of the payload inline with the other root
resource fields, such as an Activity resource's assignedUser field. These resources may be included in a response
by default and can be controlled through the fields query parameters.
• An included resource is a resource that appears in the included section at the bottom of the payload, such as an
Activity resource's Notes. These resources are not included in a response by default and must be controlled
through the included query parameters.
For more information on inline and included resources, see “GETs” on page 31.

Methods
A method is a type of action a caller application can take on a resource through an endpoint. Methods are also referred
to as verbs or operations. Cloud API supports the following subset of HTTP methods:
• GET - Used to request resources.
• POST - Used to create resources. Also used to execute business actions, such as quoting a submission or
submitting a claim.
• PATCH - Used to update resources.
• DELETE - Used to delete resources.
Every endpoint supports one or more of these methods. For example, in the Common API:
• The notes/{noteId} endpoint supports GET, PATCH, and DELETE.
• The /activities endpoint supports only the GET operation.
The HTTP methods are designed for CRUD operations (Create, Read, Update, Delete). Some business processes in
InsuranceSuite applications are available to Cloud API but do not readily map to any of these operations, such as
assigning objects, closing objects, or approving objects. As a general rule, the custom actions that trigger these
processes use the POST method.

Operation mapping to elements and collections

In general:
• You can GET either an element or a collection.
• You POST a collection to create an element.
• You POST to a custom action (to execute a business action).
• You PATCH an element.
• You DELETE an element.
For example:

Method On endpoint... Does the following...

GET /activities Returns all activities assigned to the current user
GET /activities/{activityId} Returns the details for the specified activity

26 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Method On endpoint... Does the following...

POST /activities/{activityId}/notes Adds a new note to the specified activity
POST /activities/{activityId}/assign Assigns the activity
PATCH /activities/{activityId} Updates information on the specified activity
DELETE /notes/{NoteId} Deletes the specified note

Contrasting endpoints and methods

Technically speaking, when an endpoint supports multiple methods, it is still a single endpoint. However, in casual
discussion, each method is sometimes referred to as a separate endpoint. For example, consider the following:
• GET /common/v1/activities
• POST /common/v1/activities
This is a single endpoint (/common/v1/activities) that supports two methods (GET and POST). However, in a
casual sense, it is sometimes referred to as two endpoints (the GET /activities endpoint and the POST /activities
endpoint).

The PUT method

Within REST API architecture, there are two methods that modify existing resources - PATCH and PUT. PATCH is
used to modify a portion of an existing resource (while leaving other aspects of it unmodified). PUT is used to replace
the entire contents of an existing resource with new data. Cloud API supports the PATCH operation, but not the PUT
operation. This is because nearly every method that modifies an InsuranceSuite object modifies only a portion of it
while keeping the rest of the object untouched. This behavior maps to PATCH, but not to PUT.

Paths
Every endpoint has a path. The path is the portion of the URL used by caller applications to identify the specific
endpoint.
For Cloud API, every path consist of the following pattern:

rest/<APIname>/<APImajorVersion>/<endpointName>

For example, consider the path: rest/common/v1/activities:

• common is the name of the API to which the endpoint belongs.
• v1 is the major version number of the API
• activities is the endpoint name
The major version number provides information about the backwards compatibility of the endpoint. For more
information, see “Version numbers for major and minor releases” on page 18.
A path can also contain a reference to a specific resource. For example, the path /activities/xc:20/notes refers to
the notes for activity xc:20. When a path includes a reference to a specific resource, the generic path name is specified
using {typeId}, where type is the resource type. For example, the generic path for /activities/xc:20/notes is /
activities/{activityID}/notes. A reference to a specific resource in a path is known as a path parameter.

For most endpoints, the endpoint name is the same as the resource name, with the following conventions and caveats:
• If the endpoint's root resource is an element, the endpoint name ends in a singular noun (such as /activity) or a
resource reference (such as /activity/{activityId}).
• If the endpoint's root resource is a collection, the endpoint name ends in a plural noun (such as /activities).
• If the endpoint executes a business action, the endpoint name ends in a verb (such as /{activityId}/assign).
• The endpoint name is often close to, but not identical to, the resource name.
◦ Endpoint names use lower case, whereas resource names use mixed case (for example, the root resource for
the /activity endpoint is Activity)

Introduction to Cloud API 27

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ Endpoint names use hyphens to separate words, whereas resource names do not (for example, the root resource
for the /fixed-property-incidents endpoint is FixedPropertyIncident)
◦ In some cases, the endpoint name may differ from the root resource name (for example, the root resource for
the /contacts endpoint is ClaimContact)

Requests and responses

Requests
A request is a call from a caller application to an endpoint to either query for data or initiate action.
Requests are made using URLs. Request URLs have the following components:

[Link]
\__________________/\______________________________/\___________________/
application URL endpoint path query parameters

• Application URL - The URL to the InsuranceSuite application.

◦ This value is required.
• Endpoint path - The path to the specific endpoint that the request is requesting.
◦ This value is required.
◦ Endpoint paths end either with a resource name (such as .../activities) or the ID of a specific element (such
as .../activities/xc:207 in the example above). The ID of a specific element is also referred to as a path
parameter.
• Query parameters - This is a set of query parameters that further defines the data that is desired in the response.
For most endpoints, query parameters are optional.
◦ For example, when you add ?fields=assignedGroup, you are specifying that the only field you want returned
in the response is the assignedGroup field.
Some requests require a payload. The payload is a block of JSON-formatted text that contains information about one or
more resources associated with the operation. Typically:
• GETs and DELETEs do not require request payloads.
◦ For a GET, you only need to identify the resource you want information about, and this is done in the URL.
◦ For a DELETE, you only need to identify the element to delete, and this is done in the URL.
• POSTs and PATCHes do require request payloads.
◦ For a POST, you must specify data about the element to create.
◦ For a PATCH, you must specify the data about the element that must be updated.

Responses
A response is the set of information returned by an API endpoint for a request to the caller application.
Some responses include a payload. The payload contains information about one or more resources that are returned by
the operation. For example, for a request to get all open activities assigned to a given user, the response includes a
payload with information about the open activities. For more information about the payload structure, see “GETs” on
page 31.
The outcome of the operation is specified as an HTTP status code, also referred to as a response code. These codes are
three-digit numbers. The general meanings of these codes are defined in the following table:

Status code Category Meaning

1xx Information Used for transfer protocol-level information
2xx Success The server accepted the client request successfully.
(The code 200 indicates a successful GET or PATCH. 201 indicates a successful POST. 204 indicates
a successful DELETE.)

28 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Status code Category Meaning

3xx Redirection The client must take some additional action in order to complete its request.
4xx Errors (client-side) An error condition occurred on the client side of the HTTP request and response.
5xx Faults (server-side) An error condition occurred on the server side of the HTTP request and response.

Testing requests and responses

Developers who work with Cloud API typically use a tool that can send requests and get responses within an
acceptable amount of time. Guidewire recommends Postman. This tool has the ability to:
• Save API calls, including headers and payloads
• Save collections of calls
• Automatically create a collection of calls for a schema's paths by importing the Swagger schema file
• Share collections with other developers on your team
For more information and to download the tool, see [Link]
Note: Swagger UI also has the capability to send requests to a working endpoint and observe responses.
However, Guidewire recommends using Swagger UI only to view API definitions. The APIs in Cloud API are
significantly robust. When sending requests using Swagger UI, the performance time for getting responses can
be unacceptably long. Also, if you attempt to send calls from Swagger UI and log into the ClaimCenter user
interface on the same machine, the two systems may attempt to share the same session, and either or both may
stop working. For more information on recommended request tools, see “Requests and responses” on page 28.

Tutorial: Set up your Postman environment

The Cloud API documentation contains a set of tutorials that guide you through examples of how to send requests and
review the responses. All of these tutorials assume the following base environment:
• A default instance of ClaimCenter installed on your machine that contains only the Demo sample data set.
• An instance of Postman.
This tutorial walks you through the process of setting up this environment.
If your instance of ClaimCenter is installed on a different machine, you will need to adjust the endpoint URLs provided
in the tutorials. Also, if you create data in addition to the Demo sample data, then your responses may differ from the
ones described in the tutorials.

Tutorial steps
1. Install Postman. (For more information, refer to [Link]
2. Start ClaimCenter and load the Demo sample data set.
You can test your environment by sending your first Postman request.
1. Open Postman.
2. Start a new request by clicking the + to the right of the Launchpad tab.
3. Every request in Postman requires some form of authorization:
a. Click the Authorization tab.
b. For the Type drop-down list, select Basic Auth.
c. In the Username field, enter aapplegate.
d. In the Password field, enter gw.
4. Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
5. In the Enter request URL field, enter the following URL: [Link]
activities
6. Click the Send button to the right of the request field.

Introduction to Cloud API 29

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Checking your work

Once a response has been received, its payload is shown in the lower portion of the Postman interface. If your
environment has been set up correctly, the first few lines of the response payload are:

{
"count": 25,
"data": [
{
"attributes": {
"activityPattern": "contact_claimant",
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
},
...

Troubleshooting: No response
Requests can be sent only to running applications. All of the tutorials in this documentation require that ClaimCenter is
running. If you send a request when the application is not running, you will see an error similar to the following:
Could not get any response

There was an error connecting to [Link]

Troubleshooting: NotFoundException
Unless it is stated otherwise, all of the tutorials use basic authentication and the aapplegate user. If you encounter a
NotFoundException such as the following example, this could be caused by not providing correct authentication
information for this user.

"status": 404,
"errorCode": "[Link]",
"userMessage": "No resource was found at path /common/v1/activities"

30 Introduction to Cloud API

chapter 2

GETs

This topic discusses how the GET method queries for data and the structure of the response payload. For information
on how you can add query parameters to a GET URL to refine the response, see “Query parameters” on page 43.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: Send a basic Postman request” on page 34
• “Tutorial: Send a Postman request with included resources” on page 39

Overview of GETs
A GET is an HTTP method that is used to retrieve data from an InsuranceSuite application.
There are two types of GETs:
• A collection GET is a GET that returns a collection of one or more resources. Collection GETs have paths that end
in a plural noun, such as GET /activities/xc:1227/notes.
• An element GET is a GET that returns a single, specific resource. Element GETs have paths that end in the ID of
the specific resource. For example, GET /activities/xc:1227.
When a GET is successful, the response includes:
• An HTTP response indicating success.
• A response payload that contains the data that was queried for.
When you configure a caller application to send a GET, the construction of the API call is fairly straight-forward. The
call may require query parameters, but GETs do not require a request payload. The majority of the work lies in parsing
the response payload. The remainder of this topic discusses how response payloads are structured and how developers
can learn about response payload formats.

Standard payload structures

The endpoints in Cloud API have standard structures for both request payloads and response payloads. The structures
are defined by data envelopes, and by request and response schemas.
Standard information common to all endpoints
A data envelope is a wrapper that wraps JSON sent to or returned from a REST API. To maintain a standard payload
structure, Cloud API uses two data envelopes: DataEnvelope and DataListEnvelope.
DataEnvelope standardizes the format of information for a single element. It specifies a data property with the
following child properties:
GETs 31
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• checksum
• id
• links (for a single element)
• method
• refid
• related
• type
• uri

The format of a payload for a single element has the following structure:

{
"data": {
"checksum": ...,
"id": ...,
"links": ...,
"method": ...,
"refid": ...,
"related": ...,
"type": ...,
"uri": ...
}
}
}

DataListEnvelope standardizes the format of information for collections. It specifies the following properties, which
are siblings to the data section:
• count
• links (for a collection)
• total
The format of a payload for a collection has the following structure:

{
"count" ...,
"data": [
{ properties_for_element_1 },
{ properties_for_element_2 },
...
],
"links": ...,
"total": ...
}

Every property does not appear in every payload. There are different reasons why a property may not appear in a given
payload. For example:
• Some properties, such as refid, apply only to requests and do not appear in response payloads.
• Some properties, such as count, apply only to responses and do not appear in request payloads.
• Some properties, such as related, do not appear by default and appear only when the request includes certain
query parameters.

Standard information specific to a given endpoint

DataEnvelope and DataListEnvelope provide a standard format for information that is applicable to all request and
response payloads. But, different endpoints interact with different types of resources. For each endpoint, some portion
of the payload must provide information about a specific type of resource.
To address this, Cloud API also uses request schemas and response schemas. A request schema is a schema that is used
to define the valid structure of a request payload for a specific set of endpoints. Similarly, a response schema is a
schema that is used to define the valid structure of a response payload for a specific set of endpoints.
Request and response schemas are hierarchical. For example, for responses, the GET /activity/{activityId}
endpoint uses the ActivityResponse schema. This schema has two child schemas: ActivityData and
ActivityResponseInclusions.

32 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Request and response schemas extend DataEnvelope or DataListEnvelope. This ensures that information relevant to
all endpoints appears in payloads in a standard way.
Request and response schemas also define an attributes property for the payload. This property is associated with a
schema that includes resource-specific information for the payload. For example, the GET /activity/{activityId}
endpoint specifies an attributes property in the ActivityData child schema. This property is associated with the
Activity schema, which contains activity-specific fields, such as activityPattern and activityType. As a result,
response payloads for the GET /activity/{activityId} endpoint have this structure:

{
"data": {
"checksum": ...,
"attributes" : {
"activityPattern": ... ,
"activityType": ...,
...},
"id": ...,
"links": ...,
"method": ...,
"refid": ...,
"related": ...,
"type": ...,
"uri": ...
}
}
}

Viewing schemas
You can use API definition tools, such as Swagger UI, to review information about the schemas for a given endpoint
and how they structure the data.

View a response schema in Swagger UI

Procedure
1. Start ClaimCenter.
2. In a web browser, navigate to the Swagger UI for the appropriate API.
• For more information, see “View definitions using Swagger UI” on page 19.
3. Click the operation button for the appropriate endpoint. Swagger UI shows details about that endpoint underneath
the endpoint name.
• For example, to view the response schema for GET /activities/{activityID}, click the GET button for
that endpoint.
4. Scroll down to the Responses section. The Model tab shows the hierarchy of schemas for this endpoint, and the
contents defined by each schema.

Sending GETs
You can use a request tool, such as Postman, to ensure GETs are well-formed and to review the structure of the
response payloads. For more information, see “Requests and responses” on page 28.

Send a GET using Postman

Procedure
1. Start ClaimCenter and Postman.
2. Start a new request by clicking the + to the right of the Launchpad tab.
3. Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
4. In the Enter request URL field, enter the URL for the server and the endpoint.

GETs 33
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• For example, to do a GET /activities on an instance of ClaimCenter on your machine, enter: http://
localhost:8080/cc/rest/common/v1/activities
5. On the Authorization tab, provide sufficient authorization information to execute the request. For example, to set
up basic authentication for aapplegate:
a) Click the Authorization tab.
b) For the Type drop-down list, select Basic Auth.
c) In the Username field, enter aapplegate.
d) In the Password field, enter gw.
6. Click the Send button to the right of the request field.

Tutorial: Send a basic Postman request

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” on page 29.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following call and click Send: GET [Link]
activities

Checking your work

Once a response has been received, its payload is shown in the lower portion of the Postman interface. The first few
lines of the response payload are:

{
"count": 25,
"data": [
{
"attributes": {
"activityPattern": "contact_claimant",
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
},

Payload structure for a basic response

The following sections describe the response payload for a basic response. For the purpose of this discussion, a basic
response is a response that contains information about a specific element or collection, but does not contain any
included resources. Included resources are discussed in “Payload structure for a response with included resources” on
page 38.

Structure of a basic response

The high-level structure of a basic response is shown below. The first and last properties (count and collection-level
links) are used only for collection payloads. All other properties are used for both element and collection payloads.

(Note: JSON does not support comments. However, to clarify the code, pseudo-comments have been added. Each
pseudo-comment is preceded by a hashtag (#).)

{
"count": N, # Number of resources in collection*
"data": [ # List of resources
{ # Resource 1 begins here
"attributes": { # Resource 1 name/value pairs

34 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"propertyName": "propertyValue",
... },
"checksum": "val", # Resource 1 checksum value
"links": { ... } # Resource 1 links
}, # Resource 1 ends here
{ # Resource 2 begins here
"attributes": { # Resource 2 name/value pairs
"propertyName": "propertyValue",
... },
"checksum": "val", # Resource 2 checksum value
"links": { ... } # Resource 2 links
}, # Resource 2 ends here
... ], # Resources 3 to N
"links": { ... } # Collection-level links*
}
# *-used only for collection responses

The count property

The count property identifies the number of elements returned in the payload. It is used only in responses that contain
collections.

The data section

The data section contains information about the resources returned by the endpoint. For each resource, the following
subsections appear by default:
• attributes - A set of name/value pairs for the fields of each resource.
• checksum - A checksum value for each resource.
• links - HTTP links that can be used to take action on each resource.
If an endpoint returns a single element, the data section has a single set of attributes, checksum, and links. If an
endpoint returns a collection, the data section has one set of attributes, checksum, and links for each resource.

The attributes section

The attributes subsection lists the fields returned for a resource, and the values for those fields. For example:

"attributes": {
"activityPattern": "check_coverage",
"activityType": {
"code": "general",
"name": "General"
},
...
},

Each resource has a default set of fields that are returned. This is typically a subset of all the fields that could be
returned. You can override the default set of fields returned using the fields query parameter. For more information,
see “The fields query parameter” on page 44.

Simple values
When a field is a scalar, its value is listed after the colon. For example:

"subject": "Verify which coverage is appropriate"

ID properties
Every resource has an id field. This has the same value as the Public ID of the object in ClaimCenter. This is typically
one of the fields returned by default. For example:

"id": "xc:20",

This value is also used in an endpoint that names a specific element, such as:

GET /activities/xc:20/notes

GETs 35
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Date and datetime values

Date and datetime values appear in payloads as a string with the following format:
• Datetime: YYYY-MM-DDThh:mm:[Link]
• Date: YYYY-MM-DD
where:
• YYYY is the year
• MM is the month
• DD is the day
• For datetime values:
◦ T is a literal value that separates the date portion and the time portion
◦ hh is the hour
◦ mm is the minute
◦ ss is the second
◦ fff is the second fraction
◦ Z is a literal value that means "zero hour offset". It is also known as "Zulu time" (UTC)
For example:
"dueDate": "2020-03-23T07:00:00.000Z",

Inlined resources
Some response payloads contain inlined resources. An inlined resource is a resource that is not the root resource, but
some of its fields are listed in the attributes section by default along with fields from the root resource. Inlined
resources follow the format:

"inlinedResourceName": {
"inlinedResourceField1": value,
"inlinedResourceField2": value,
...
},

Inlined resources are declared in the response schema. Similar to scalar values, you can control which inlined resources
and inlined resource fields are returned in a response by using the fields query parameter. For more information, see
“The fields query parameter” on page 44.
Broadly speaking, there are four types of inlined resources: typelists, monetary amount values, simple references, and
complex references.
Typelists are listed with a code field and a name field. They use the TypeCodeReferences schema. For example:

"priority": {
"code": "urgent",
"name": "Urgent"
},

Monetary amount values are complex values with a currency field and an amount field. For example:

"transactionAmount": {
"amount": "500.00",
"currency": "usd"

(Note that in Cloud API, the datatype is referred to as MonetaryAmount. But in ClaimCenter, these values are actually
stored using the CurrencyAmount datatype.)
Simple references are references to a related object that use the SimpleReferences schema. This schema includes
only the following fields: displayName, id, refId, type, and uri. By default, most endpoints return only
displayName and id.

36 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For example, in the following snippet, assignedGroup and assignedUser are simple references:

"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
},

Complex references are references to a related object that uses a schema more complex than the SimpleReferences
schema. For example, when a contact's primary address is added to a response payload, it uses the Address schema,
which includes a larger number of fields.

Fields with null values are omitted

Response payloads contain only fields whose values are non-NULL. Fields with NULL values are omitted from the
response payload.
If a given field is expected in a response payload but it is missing, this is often because the value was NULL.

The checksum field

The checksum field lists a value that identifies the "version" of a resource. Whenever a resource is modified at the
database level, it is assigned a new checksum value. Processes that modify data can use checksums to verify that a
resource has not been modified by some other process in between the time the resource was read and the time the
resource is to be modified.
For more information, see “Lost updates and checksums” on page 111.

The links subsection (for an element)

The links subsection of the data section lists a set of paths which identify actions that can be taken on the specific
element, if any. Each link has a name, an href property, and a list of methods. Caller applications can use these links to
construct HTTP requests for additional actions to take on that resource.
Note: The links subsection of the data section is one of the way in which Cloud API enforces the Hypermedia
as the Engine of Application State (HATEOAS) constraint.
For example, suppose that a given caller application gets activity xc:20. This application has sufficient permission to
assign this activity and to view the notes associated with this activity. The following would appear in the links section
for activity xc:20:

"links": {
"assign": {
"href": "/common/v1/activities/xc:20/assign",
"methods": [
"post"
]

},
"notes": {
"href": "/common/v1/activities/xc:20/notes",
"methods": [
"get",
"post"
]
},
"self": {
"href": "/common/v1/activities/xc:20",
"methods": [
"get"
]
}
}

The self link is a link to the resource itself. The self link is useful when a caller application receives a list of
resources and wants to navigate to a specific resource in the list.

GETs 37
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For a given object, links that execute business actions appear only if the action makes sense given the state of the
object, and only if the caller has sufficient permission to execute the action. For example, the link to close an activity
will not appear if the activity is already closed. Similarly, the link to assign an activity will not appear if the caller lacks
permission to assign activities.

The collection-level links section

If a response contains a collection, there is a links section at the end of the payload. This section is a sibling of the
data section. It contains links that are relevant to the entire collection, such as the prev and next links that let you
page through a large set of resources.
Note: The links section at the end of a collection-level payload is one of the way in which Cloud API enforces
the Hypermedia as the Engine of Application State (HATEOAS) constraint.

Payload structure for a response with included resources

Some endpoints support the ability to query for a given type of resource and for related resource types. For example,
the default behavior of the GET /activities endpoint is to return only activity resources. However, you can use the
include query parameter to include any notes related to the returned activities in the response payload. These types of
resources are referred to as included resources. The technique of adding included resources to a GET is sometimes
referred to as response inclusion or read inclusion.
The syntax for adding included resources is:

<endpointPath>?include=<resourceName>

where:
• <endpointPath> is the default path, such as /common/v1/activities
• <resourceName> is the name of the related resource, such as notes
For example GET /activities?include=notes returns all activities assigned to the current user, and all notes
associated with those activities.
You can include multiple resource types in a single query. To do this, identify the resources in a comma-delimited list.
For example, GET /claims?include=exposures,activities returns all claims assigned to the current user, and all
exposures and activities associated with those claims.
When you execute a call with include, the response payload contains information about the primary resources and the
included resources. However, most of the information about the included resources do not appear inline with the
primary resources. Rather:
• Every primary resource has a related section. This section lists the ids (and types) of included resources related to
that resource. However, each related section does not include any other details about those resources.
• Details about the included resources appear at the end of the payload in a section called included.
The ids of included objects appear in both the related section and the included section. You can use these ids to
match a primary resource with details about its included resources.

Contrasting included resources and inlined resources

A response payload can contain two types of resources that have a relationship to the root resources: inlined resource
and included resources. The following table contrasts the two types of resources.

Resource How many related resources Where do their fields When do they appear?
type for each primary resource? appear?
Inlined Typically one. (For example, Entirely in the attributes If the query does not use the fields query
resource every activity has only one section of the root resource parameter, then each inlined resource appears only if
related assignedUser.) it is one of the default attributes.

38 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

If the query does use the fields query parameter,

then each inlined resource does or does not appear
based on whether it is specified in that query
parameter.
Included One to many. (For example, ids appear in the related When the query parameter includes the ?
resource every activity can have section of the root resource. include=resourceName query parameter
several related notes.) The remaining attributes
appear in the included
section at the bottom of the
payload.

Tutorial: Send a Postman request with included resources

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” on page 29.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. You can use a GET to retrieve a resource and a set of related resources. For example, in a single GET you can
retrieve a claim and all of its contacts. The following GET retrieves Claim 235-53-365870 (Public ID
demo_sample:1) and its contacts. Enter this URL in Postman and click Send:
GET [Link]
Note the following in the response payload:
• The data section starts at line 2. It includes information about the claim.
• The included section starts at or around line 363. It includes an array of contacts for this claim.
3. You can use a GET to retrieve a resource and a single related resource. For example, in a single GET you can
retrieve a claim and its main contact. The following GET retrieves Claim 235-53-365870 (Public ID
demo_sample:1) and its main contact. Enter this URL in Postman and click Send:
GET [Link]
Note the following in the response payload:
• The data section starts at line 2. It includes information about the claim. At or around line 91, there is
information about the claim's main contact. However, the only meaningful information is the main contact's
display name and ID.
• The included section starts at or around line 339. It includes a single contact for this claim. In this section,
there is detailed information about the contact beyond just the display name and ID.

Structure of a response with included resources

The high-level structure of a response with included resources is shown below. Information that pertains specifically to
included resources appears in bold. (Note: JSON does not support comments. However, to clarify the code, pseudo-
comments have been added. Each pseudo-comment is preceded by a hashtag (#).)

{
"count": N, # Number of resources is payload
"data": [ # Details for each resource
{ # Resource 1 begins here
"attributes": { # Resource 1 name/value pairs
"propertyName": "propertyValue",
... },
"checksum": "val", # Resource 1 checksum value
"links": { # Links relevant to Resource 1
... },
"related": { # List of resources related to R1
"resourceType": { # Related resource type
"count": NN, # Number of related resources for R1
"data": [
{ # First resource related to R1 starts

GETs 39
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"id": "relatedResourceID",
"type": "resourceType"
}, # First resource related to R1 ends
... # Other resources related to R1
] } }
}, # Resource 1 ends here
{ # Resource 2 begins here
"attributes": { # Recourse 2 name/value pairs
"propertyName": "propertyValue",
... },
"checksum": "val", # Resource 2 checksum value
"links": { # Links relevant to Resource 2
... },
"related": { # List of resources related to R2
"resourceType": { # Related resource type
"count": NN, # Number of related resources for R2
"data": [
{ # First resource related to R2 starts
"id": "relatedResourceID",
"type": "resourceType"
}, # First resource related to R2 ends
... # Other resources related to R2
] } }
}, # Resource 2 ends here
... ], # Resources 3 to N
"links": { # Links relevant to collection
...
},
"included": { # List of related resources
"resourceType": [ # First related resource type
{
"attributes": { # Related resource 1 start
... # Related resource 1 name/value pairs
"id": " relatedResourceID ",
... },
"checksum": "0", # Related resource 1 checksum value
"links": { ... } # Links relevant to Related resource 1
},
... # Related resources 2 to end
] }
}

The related section (for a resource)

For every resource, there is an additional related section that identifies:
• The number of included resources, and
• The ids of the included resources
For example, the following code snippet is from the response for a query for all activities and related notes. Activity
xc:44 has one included note, whose id is xc:55.

{
"attributes": {
...
"id": "xc:44",
...
"subject": "Check coverage"
},
"checksum": "2",
"links": {
...
},
"related": {
"notes": {
"count": 1,
"data": [
{
"id": "xc:55",
"type": "Note"
}
]
}
}
},

If a GET uses the included query parameter, but no related resources exist, the related section still appears. But, the
count is 0 and the data section is empty. For example:

"related": {
"notes": {
"count": 0,

40 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"data": []
}
}

If a GET omits the included query parameter, the related section is omitted from the response payload.

The included section (for a response)

For every response, there is an included section that appears at the end of the response payload. It lists details about
every included resource for the primary resources.
For example, the following code snippet is from the included section from the previous example.

"included": {
"Note": [
{
"attributes": {
"author": {
"displayName": "Betty Baker",
"id": "demo_sample:8"
},
"bodySummary": "Main contact is on vacation 03/20",
"confidential": false,
"createdDate": "2020-03-30T23:11:33.346Z",
"id": "xc:55",
"relatedTo": {
"displayName": "235-53-373871",
"id": "demo_sample:8002",
"type": "Claim"
},
"subject": "Main contact is on vacation 03/20",
"topic": {
"code": "general",
"name": "General"
},
"updateTime": "2020-03-30T23:12:08.892Z"
},
"checksum": "0",
"links": {
"self": {
"href": "/common/v1/notes/xc:55",
"methods": [
"get",
"patch"
]
}
}
}
]
},

Recall that activity xc:44 has one included note. The included note's id is xc:55. The note shown in the included
section is the note related to activity xc:44.

Including either a collection or a specific resource

For a given endpoint, some of the include options return a collection of resources for each primary resource. Other
include options return a single resource for each primary resource.

An example of the first case is GET /claims/{claimId}?include=contacts. This call returns the claim with the
given Claim ID and all ClaimContacts related to that claim. There are theoretically several related resources
(ClaimContacts) for each primary resource (the claim with the given Claim ID).
An example of the second case is GET /claims/{claimId}?include=mainContact. This call returns the claim with
the given Claim ID and the ClaimContact who is designated as the main contact. There is only a single related resource
(the main ClaimContact) for each primary resource (the claim with the given Claim ID).
You can also specify multiple include options, as in GET /claims/{claimId}?include=contacts,mainContact. In
this case, for each claim, the related section specifies the IDs of all related contacts and it also explicitly identifies the
ID of the main contact.
As a general rule, if an include option is named using a plural, it returns a set of resources for each primary resource.
If an include option is named using a singular, it returns a single resource for each primary resource.

GETs 41
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Determining which resources can be included

For each endpoint, you can determine the resources that can be included by referring to the API definition for the
endpoint. There will be a data envelope in the model whose name ends with ...Inclusions. This data envelope lists
all the resources that can be included when querying for that type of resource.
For example, in the Common API, the model for GET /activities references an ActivityResponseInclusions
element. This element has a single child element - Note. This means that the only type of element you can include on
an activity query is notes.
If you attempt to include a resource type that a given endpoint does not support for inclusion, the API returns a 400
error code and message. For example, the following is the message if you attempt to do a GET /activities?
include=users:

"userMessage": "Bad value for the 'include' query parameter - The requested
inclusions '[users]' are not valid for this resource. The valid options are [notes]."

42 GETs
chapter 3

Query parameters

This topic discusses how to use query parameters to refine a request to customize the response payload. This is most
often done with GETs. But, query parameters can also be used with POSTs and PATCHes to refine the responses to
those methods.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: Send a GET with the fields parameter” on page 46
• “Tutorial: Send a GET with the filter parameters” on page 49
• “Tutorial: Send a GET with the sort query parameter” on page 51
• “Tutorial: Send a GET with the pageSize and totalCount parameters” on page 54
• “Tutorial: Send a GET with query parameters for included resources” on page 56

Overview of query parameters

When you execute a Cloud API call using only the endpoint (as in GET /activities), the response payload has a
default response. You may want to refine the default by:
• Specifying a custom set of properties
• Filtering out resources that do not meet a given criteria
• Sorting the resources
• Modify how pagination behaves, which can include:
◦ Limiting the number of resources returned in each payload
◦ Advancing to the next set of resources
◦ Retrieving a count of the total number of resources that meet the query's criteria
You can refine the response using query parameters. A query parameter is an expression added to the HTTP request
that modifies the default response.
Query parameters are specified at the end of the URL after a question mark (?). The general syntax is:

<URL>?<queryParameterExpressionList>

For example:
• GET /common/v1/activities?fields=*all
• GET /common/v1/activities?filter=escalated:eq:false

Query parameters 43
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Specifying multiple query parameters

A Cloud API call can include multiple query parameter expressions. Separate each query parameter expression using
an ampersand (&). For example:
• GET /common/v1/activities?fields=*all&filter=escalated:eq:false

Included resources
You can use the include query parameter to include resources related to the primary resources of the response. You
can also use query parameters to specify a custom set of properties for included resources, filter out included resources
that do not meet a given criteria, sort the included resources, and so on. For more information, see “Query parameters
for included resources” on page 54.

Some query parameters are not supported for all fields

If you attempt to use a query parameter on a field that does not support that parameter, Cloud API returns a 400 Bad
Request error and an error message. For example, if you execute: GET /common/v1/activities?
sort=escalationDate, Cloud API provides an error message similar to the following:

"message": "The sort column 'escalationDate' is not a valid option. The valid
sort options are [assignedUser, dueDate, escalated, priority, status, subject],
optionally prefixed with '-' to indicate a descending sort."

Viewing query parameter definitions

For every endpoint, the API definition provides descriptions of the query parameters supported by that endpoint.

Query parameters in Swagger UI

In Swagger UI, the query parameters information is hidden by default. To show the descriptions, click the endpoint's
operation button (such as the GET button for GET /activities). The query parameter descriptions appear under the
endpoint.
Parameter definitions
The Parameters section describes each query parameter.
Supported parameters
The Responses section include a Model tab. This tab provides information about the fields that support particular query
parameters. For example, you can sort results on some fields, but not all of them. The fields that support sorting appear
in the model with the text "sortable": true.

The fields query parameter

Every endpoint returns a default set of fields. You can override this default set using the fields query parameter. This
is useful when you need properties not returned by default, or when you want to avoid getting properties that are not
necessary.
You can also use the fields query parameter for related resources added through the include parameter. For more
information, see “Query parameters for included resources” on page 54.
The fields parameter can be set to one or more of the following values:
• *all - Return all fields
Note: *all is not recommended for production environments. For more information, see the following
section on "Returning all fields".
• *default - Return the default fields (typically used in conjunction with an additional field list)
• fieldList - Return one or more fields specified as a comma-delimited list

44 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The "detail list" and "summary list" of fields

For endpoints that return a single element, the default fields to return are defined in a detail list. Similarly, for
endpoints that return a collection, the default fields to return are defined in a summary list.
For example, the following list compares the detail list fields for a claim resource (for example, the default fields for
the /claims/{claimId} endpoint) and the summary list fields returned for a claim collection (for example, the default
fields for the /claims endpoint). Fields included in the detail list only are in bold:
• Detail list: assignedGroup, assignedUser, assignmentStatus, claimNumber, description, faultRating,
flagged, id, incidentOnly, insured, jurisdiction, lobCode, lossCause, lossDate, lossLocation, lossType,
mainContact, policyAddresses, policyNumber, reportedByType, reportedDate, reporter, segment, state,
strategy, validationLevel
• Summary list: assignedGroup, assignedUser, assignmentStatus, claimNumber, faultRating, flagged, id,
incidentOnly, insured, jurisdiction, lobCode, lossCause, lossDate, lossType, mainContact,
policyNumber, reportedByType, reportedDate, reporter, segment, state, strategy, validationLevel

The fields parameter has three options related to these default sets:
• *detail - Return the fields in the "detail list"
• *summary - Return the fields in the "summary list"
• *default - Return the default list. If the endpoint returns a single element, the default is the "detail list". If the
endpoint returns a collection, the default is the "summary list"

Returning the default properties plus additional specific properties

Some API calls need a set of fields that is not exactly equivalent to either the detail list or the summary list. These calls
can name specific fields, either on their own or in addition to a default list of fields. They can also specify all fields.
To return the default fields of an endpoint with an additional set of fields, use:

fields=*default,fieldList

where fieldList is a comma-delimited list of fields.

For example, the following query returns all default fields for activity xc:20 as well as the description and the start
date.
GET /activities/xc:20?fields=*default,description,startDate

Returning a specific set of properties

To return a specific set of fields, use:

fields=fieldList

where fieldList is a comma-delimited list of fields.

For example, the following query returns only the description and the start date for activity xc:20:
GET /activities/xc:20?fields=description,startDate

Returning a specific set of properties on inlined resources

Some response payloads include inlined resources in the attributes section. For example, the following is a portion
of the response for a GET /activities. This payload contains two inline resources, assignedGroup and
assignedUser.

"attributes": {
"activityPattern": "contact_claimant",
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",

Query parameters 45
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"id": "demo_sample:1"
},
"closeDate": "2020-04-06T07:00:00.000Z",
"dueDate": "2020-04-06T07:00:00.000Z",
"escalated": false,
"id": "cc:20",
...
}

You can use the fields query parameter to specify an inlined resource. When you do, all default fields for that
resource are returned. For example, you could specify that you want a GET /activities to return only the
assignedGroup and assignedUser fields (and all of their default subfields) using the following:

GET /activities?fields=assignedGroup,assignedUser
This would return:

"attributes": {
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
}
}

You can also specify specific subfields using the following syntax:
fields=[Link]

For example, you could specify that you want a GET /activities to return only the ids of the assigned user and
group using the following:
GET /activities?fields=[Link],[Link]
This would return:

"attributes": {
"assignedGroup": {
"id": "demo_sample:31"
},
"assignedUser": {
"id": "demo_sample:1"
}
}

Returning all fields

To return all of the fields that an endpoint is configured to return, use:

fields=*all

For example, the following query returns all the possible fields for activity xc:20.
GET /activities/xc:20?fields=*all
Note that the *all query parameter returns all fields that the caller is authorized to view. If there are fields on a
resource that a caller is not authorized to view, they are excluded from queries using the *all query parameter.
*all is not recommended for production environments as it may return fields that are not included in default responses
because they require additional resources to calculate. Instead, use the *default filter with any specific fields that do
not appear in the default detail or summary list.

Tutorial: Send a GET with the fields parameter

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” on page 29.

46 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following and click Send:
GET [Link]
3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
4. Enter the following and click Send:
GET [Link]
Checking your work
Compare the two payloads. Note that the first response payload includes the default fields for activities, whereas the
second response payload includes only the two fields specified in the fields query parameter.

The filter query parameter

You can narrow which resources are returned using the filter keyword followed by one or more criteria. The criteria
are specified using the following syntax:

filter=field:op:value

where:
• field is the name of a filterable field
• op is one of the comparison operators from the following table
• value is the value to compare

op value Meaning Example using the GET /activities endpoint Returns activities where...
eq Equal to ?filter=escalated:eq:true ...the escalated field equals true
ne Not equal to ?filter=escalated:ne:true ...the escalated field equals false
lt Less than ?filter=dueDate:lt: ...the due date is less than (before) May 11,
2020-05-11T07::00::00.000Z 2020.
gt Greater than ?filter=dueDate:gt: ...the due date is greater than (after) May
2020-05-11T07::00::00.000Z 11, 2020.
le Less than or equal ?filter=dueDate:le: ...the due date is less than or equal to (on
2020-05-11T07::00::00.000Z or before) May 11, 2020.
ge Greater than or equal ?filter=dueDate:ge: ...the due date is greater than or equal to
2020-05-11T07::00::00.000Z (on or after) May 11, 2020.
in In ?filter=priority:in:urgent,high ...the priority is either urgent or high
ni Not in ?filter=priority:ni:urgent,high ...the priority is neither urgent nor high
sw Starts with ?filter=subject:sw:Contact ...the subject starts with the string "Contact
%20claimant claimant"
cn Contains ?filter=subject:cn:Contact ...the subject contains the string "Contact
%20claimant claimant"

The query parameter is passed as part of a URL. Therefore, special conventions must be used for certain types of
characters to ensure the URL can be parsed correctly.
• Specify strings without surrounding quotes.
• If a string has a space in it, use the URL encoding for a space (%20). (For example, "subject starts with 'Contact
claimant'" is specified as filter=subject:sw:Contact%20claimant)
• If a string has a colon (:) in it, use two colons (::) in the URL. The first colon acts as an escape character. (For
example, "subject starts with 'Urgent: Information needed'" is specified as ?filter=subject:sw:Urgent::
%20Information%20needed)

Query parameters 47
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• Specify Booleans as either true or false. (For example, "escalated is true" is specified as ?
filter=escalated:eq:true)
• Date and datetime fields must be specified as an ISO-8601 datetime value. All datetime fields can accept either date
values or datetime values. For datetime values, the colons in the value must be expressed as "::". For example, "due
date is less than 2020-04-03T15:00:00.000Z" is specified as ?filter=dueDate:lt:
2020-05-11T07::00::00.000Z.
• Specify null values as null. For example, "all activities whose escalation date is null" is specified as ?
filter=escalationDate:eq:null.

References to typekey fields automatically resolve to the field's code. For example, to filter on activities whose priority
is set to urgent, use: GET /activities?filter=priority:eq:urgent.
You can also use the filter query for related resources added through the include parameter. For more information, see
“Query parameters for included resources” on page 54.

Determining which values you can filter on

For a given endpoint, you can identify the attributes that are filterable by reviewing the schema definition. If a field is
filterable, then the schema definition of the field includes the text: "filterable": true.
For example, the following is the schema description from Swagger UI for two fields returned by the Common API's /
activities endpoint.

escalated boolean
readOnly: true
x-gw-extensions: OrderedMap { "filterable": true, "sortable": true }
escalationDate string($date-time)
x-gw-nullable: true

Note that the escalated field includes the "filterable": true expression, but the escalationDate field does not.
This means that you can filter on escalated, but not escalationDate.

Filtering on multiple values

You can include multiple filter criteria. To do this, each criteria requires its own filter expression. Separate the
expressions with an ampersand (&). The syntax is:

filter=field:op:value&filter=field:op:value

When multiple criteria are specified, the criteria are ANDed together. Resources must meet all criteria to be included in
the response. For example, the following GET returns only high priority activities that have not been escalated.
GET /activities?filter=priority:eq:high&filter=escalated:eq:false
The filter query parameter cannot be used to construct OR criteria.

When querying for a specific root resource, do not filter on the id property
When writing a call to GET a single root resource, use an endpoint that returns a single element, such as:
GET /activities/xc:20
Do not attempt to retrieve the resource by using an endpoint that returns a collection and filtering on the id property, as
in:
GET /activities?filter=id:eq:xc::20
Typically, the latter approach does not work because collection endpoints do not have filterable id properties.
This restriction applies to the root resource only. There may be situations where you need to retrieve a root resource
and one or more child resources. When retrieving the child resources, it may be possible and appropriate to filter on the
child resource's id.

48 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Endpoints with default filters

Default filters
The following endpoint has a default filter:
• GET /claim/v1/claims - By default, it filters out claims that are closed, archived, or not assigned to the caller.

Overriding default filters

You can use the filter query parameter to override default filters. There are several ways to do this.
• You can retrieve unfiltered results by specifying filter=*none.
◦ For example, GET /activities?filter=*none returns all claims (that you have authorization to view),
regardless of who they are assigned to.
• You can override the default filter by specifying your own filter.
◦ For example, GET /claims?filter=state:eq:draft returns all draft claims. (Draft claims have not yet been
assigned and therefore are not assigned to you.)
If you want the response payload to reflect both the default filter and a custom filter, you must specify both filters
explicitly.

Tutorial: Send a GET with the filter parameters

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” on page 29.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Specify Basic Auth authorization using user aapplegate and password gw.
4. Enter the following and click Send:
GET [Link]
5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
6. Enter the following and click Send:
GET [Link]

Checking your work

Compare the two payloads. Note that the first response payload includes all activities, whereas the second response
payload contains only the activities with a high priority.

The sort query parameter

For endpoints that return collections, you can sort the elements in the collection. To do this, use:

sort=propertiesList

where propertiesList is a comma-delimited list of properties that support sorting for that endpoint.
For example, the following query returns all activities and sorts them by due date:
GET /activities?sort=dueDate
You can specify multiple sort properties. Resources are sorted based on the first property. Any resources with the same
value for the first property are then sorted by the second property, and so on. For example, the following query returns
all activities assigned to the current caller and sorts them first by escalation status and then by due date:

Query parameters 49
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

GET /activities?sort=escalated,dueDate
You can also use the sort query for related resources added through the include parameter. For more information, see
“Query parameters for included resources” on page 54.

Sort orders
The default sort order is ascending. To specify a descending sort, prefix the property name with a hyphen (-). For
example, the following queries return all activities assigned to the current caller, sorted by due date. The first query
sorts them in ascending order. The second sorts them in descending order.
GET /activities?sort=dueDate
GET /activities?sort=-dueDate

Determining which values you can sort on

For a given endpoint, you can identify the attributes that are sortable by reviewing the endpoint Model in Swagger UI.
If a field is sortable, then the schema description of the field includes the text: "sortable": true.
For example, the following is the schema description for two fields returned by the Common API's /activities
endpoint.

escalated boolean
readOnly: true
x-gw-extensions: OrderedMap { "filterable": true, "sortable": true }
escalationDate string($date-time)
x-gw-nullable: true

Note that the escalated field includes the "sortable": true expression, but the escalationDate field does not.
This means that you can sort on escalated, but not escalationDate.

Overriding default sorts

Some collections have default sorts. For example, by default, Activities collections are sorted by priority and then
by subject.
Default sorts in the base configuration are defined in shared_core-[Link]. Custom default sorts
(which could either be overrides of base configuration sort orders or sort orders for custom endpoints) are defined in
shared_ext-[Link]. Both of these [Link] files started with a resources section. Some of the
collection resources have a defaultSort property which defines the sort order. For example, the following is the
portion of shared_core-[Link] where the default sort order for Activities is defined.

resources:
...
Activities:
resource: [Link]
defaultSort:
- priority
- subject

In the defaultSort section, every field is preceded by a hyphen and a space (- ). This first hyphen does not indicate
descending order. If a field has a default descending order, then the field name is preceded by a second hyphen and
surrounded by quotation marks. For example, a default sort on priority in descending order would appear as - "-
priority".

As discussed in the previous section, you can use the sort query parameter to override the default sort for a collection.
You can also remove the default sort order by specifying ?sort=*none. When you do this, results are sorted based on
their id value. This may improve performance when you are retrieving a large amount of information from an endpoint
with a default sort order and the column that the sort is based on is not indexed.
For example:
• GET /common/v1/activities returns activities using the default sort (priority and then subject).
• GET /common/v1/activities?sort=priority returns activities sorted by priority only.

50 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• GET /common/v1/activities?sort=*none returns activities sorted only by id.

Tutorial: Send a GET with the sort query parameter

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” on page 29.
In this tutorial, you will execute two requests to GET activities. The first does not sort the responses. The second does.
To make it easier to compare the order of activities, each request retrieves only the ID and due date of each activity.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Specify Basic Auth authorization using user aapplegate and password gw.
4. Enter the following and click Send:
GET [Link]
5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
6. Enter the following and click Send:
GET [Link]

Checking your results

Compare the two payloads. In the first response payload, the activities are not sorted. In the second response payload,
the activities are sorted by due date.

The pagination query parameters

Some endpoints return collections. However, the entire collection is typically not returned in a single call. Instead, only
the first N resources are returned in the first payload. Each set of N resources is called a page. A caller can use
"previous" and "next" links to access the previous or next page of N resources. The practice of separating a list of
resources into pages is referred to as pagination.
Every endpoint that returns a collection has default pagination behaviors. Each payload contains one page of resources.
There are several query parameters that refine these behaviors. This includes:
• pageSize - limits the number of resources returned per page
• pageOffset - specifies which page of resources to return
• includeTotal - ensures the response includes a count of the entire number of resources that meet the request's
criteria

pageSize limits the number of resources per page

For endpoints that return collections, you can use the pageSize parameter to limit the number of resources in each
page. This can be useful when a query may return more resources than what is practical for performance and parsing.
The syntax for pageSize is:

pageSize=n

where n is the maximum number of resources per page. For example:

GET /activities?pageSize=20
Every resource type has a default pageSize. This value is used when the query does not specify a pageSize. You can
specify a pageSize less than or greater than the default pageSize.
Also, every resource has a maximum pageSize, and you cannot execute a query with a pageSize larger than the
maximum.

Query parameters 51
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For example, suppose a given user has 125 activities, and the activities resource has a default pageSize of 25 and
maximum pageSize of 100.
• GET /activities returns the first 25 activities (using the default pageSize value).
• GET /activities?pageSize=10 returns the first 10 activities.
• GET /activities?pageSize=30 returns the first 30 activities.
• GET /activities?pagesize=120 returns an error because the value for pageSize exceeds the maximum for the
resource.
The pageSize values for a resource defaults to defaultPageSize=25 and maxPageSize=100. Individual resources may
override these values in the API's [Link] file. (For example, in [Link], the
ActivityPatterns resource overrides the default values and uses defaultPageSize=100 and maxPageSize=500.)

You can also use the pageSize query for related resources added through the include parameter. For more
information, see “Query parameters for included resources” on page 54.

The self link returns a single resource in a page

When a response payload contains a collection, every element in the collection is listed in the data section of the
payload. For every element, there is a links section that contains endpoints relevant to that element. One of the links is
the self link. For example:

{
"attributes": {
...
"id": "cc:32",
... },
...
"links": {
...
"self": {
"href": "/common/v1/activities/cc:32",
"methods": [
"get",
"patch"
]
}
}
}

The href property of the self link is an endpoint to that specific element. When necessary, you can use this link to
construct a call to act on that element.

pageOffset pages through resources

Whenever a response payload includes some but not all of the available resources, the payload also include a
collection-level links section at the bottom. These links provide operations and endpoints you can use to act on a
specific page of resources. (In the following descriptions, N is the pageSize of the query.)
• The first link is an endpoint to the first page (the first N elements).
◦ This appears for all collections.
• The prev link is an endpoint to the previous page (the N elements before the current set of elements).
◦ This appears if there are elements earlier than the elements in the payload.
• The next link is an endpoint to the next page (the N elements after the current set of elements).
◦ This appears if there are elements later than the elements in the payload.
• The self link is an endpoint to the current page (the current set of elements).
◦ This always appears (for elements and for collections).
For example, suppose there are 25 activities assigned to the current owner. The response payloads have a pageSize of
5, and a specific payload has the second set of activities (activities 6 through 10). The collection-level links for this
payload would be:

"links": {
"first": {

52 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"href": "/common/v1/activities?pageSize=5&fields=id",
"methods": [
"get"
]
},
"next": {
"href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=10",
"methods": [
"get"
]
},
"prev": {
"href": "/common/v1/activities?pageSize=5&fields=id",
"methods": [
"get"
]
},
"self": {
"href": "/common/v1/activities?pageSize=5&fields=id&pageOffset=5",
"methods": [
"get"
]
}
}

To access a collection that starts with a specific resource, Cloud API uses a pageOffset parameter. This parameter is
used in the prev and next links for a collection. The pageOffset index starts with 0, so a theoretical pageOffset=0
would start with the first element and pageOffset=5 skips the first 5 elements and starts with the sixth.
There can be some complexity involved in determining how to construct a link with the correct pageOffset value.
Therefore, Guidewire recommends that you use the prev and next provided in response payloads and avoid
constructing pageOffset queries of your own.

includeTotal retrieves the total number of resources

When querying for data, you can get the total number of resources that meet the criteria. To get this number, use the
following syntax:

includeTotal=true

When you submit this query parameter, the payload includes an additional total value that specifies the total. For
example:

"total": 72

When the includeTotal query parameter is used, the response payload contains two counting values:
• count - The number of resources returned in this page.
• total - The total number of resources that meet the query's criteria.
If the total number of resources that meet the criteria is less than or equal to the pageSize, then count and total are
the same. If the total number of resources that meet the criteria is greater than the pageSize, then count is less than
total. count can never be greater than total.

For performance reasons, Guidewire will count the total number of items up to 1000 only. When the total value is
stated as 1000, the actual count could be 1000 or some number greater than 1000.
Note: If the number of resources to total is sufficiently large, using the includeTotal parameter can affect
performance. Guidewire recommends you use this parameter only when there is a need for it, and only when
the number of resources to total is unlikely to affect performance.
In some situations, you may be interested in retrieving only the total number of resources that meet a given criteria,
without needing any information from any specific resource. However, a GET cannot return only an included total. If
there are resources that meet the criteria, it must return the first N set of resources and at least one field for each
resource. For calls that are sent to retrieve only the total number of resources, Guidewire recommends using a call with
query parameters that return the smallest amount of resource information, such as GET ...?
includeTotal=true&fields=id&pageSize=1.

Query parameters 53
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

You can also use the includeTotal query for related resources added through the include parameter. For more
information, see “Query parameters for included resources” on page 54.

Tutorial: Send a GET with the pageSize and totalCount parameters

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” on page 29.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Specify Basic Auth authorization using user aapplegate and password gw.
4. Enter the following and click Send:
GET [Link]
5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
6. Enter the following and click Send:
GET [Link]

Checking your work

Compare the two payloads. In the first payload, the count of activities included in the payload is 25. Also, there is no
count for the total number of activities the endpoint could return. In the second payload, the count of activities included
in the payload is 10. Also, the count for the total number of activities the endpoint could return is 30. (This appears at
the end of the payload.)

Query parameters for included resources

Some endpoints support the ability to query for a given type of resource and for resource types related to that type. For
example, by default, the GET /activities endpoint returns only activity resources. However, you can use the
include query parameter to include any notes related to the returned activities in the response payload. These types of
resources are referred to as included resources. The technique of adding included resources to a GET is sometimes
referred to as response inclusion or read inclusion.
The syntax for adding included resources is:

?include=<resourceName>

For example GET /activities?include=notes returns all activities assigned to the current caller, and all notes
associated with those activities.
For more information on the default behavior of include, see “Payload structure for a response with included
resources” on page 38.
Most query parameters that can be used on primary resources can also be used on included resources.

Specifying query parameters that apply to an included resource

The general pattern for query expressions on included resources is to specify the included resource name somewhere in
the expression's value. For example, the following call gets all activities assigned to the current user and any related
notes. The number of notes returned is limited to 5.
GET /activities?include=notes&pageSize=notes:5

54 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Included resources and primary resources

Query expressions for included resources are independent of query expressions for primary resources. There could be a
query expression for primary resources only, for included resources only, or for both. For example, the following three
queries all return activities and their related notes. But, the impact of the pageSize parameter varies.
• GET /activities?pageSize=7&include=notes
◦ The response is limited to 7 activities.
◦ There is no limit on notes.
• GET /activities?include=notes&pageSize=notes:5
◦ There is no limit on activities.
◦ The response is limited to 5 notes per activity.
• GET /activities?pageSize=7&include=notes&pageSize=notes:5
◦ The response is limited to 7 activities.
◦ The response is limited to 5 notes per activity.

Included resources and other included resources

Query expressions for each included resource are also independent of query expressions for other included resources. If
a given GET includes multiple included resources and you want to apply a given query expression to all included
resources, you must specify the query expression for each included resource.
For example, suppose you want to GET all claims. But you want the response payload to include only the main contact
and reporter, and you want only the id, primary phone, and work phone for these contacts. To get this response, you
must send the following:

GET /claims?include=mainContact,reporter
&fields=mainContact,reporter
&fields=mainContact:id,primaryPhone,workPhone
&fields=reporter:id,primaryPhone,workPhone

Note that, in this example, the logic to restrict the returned fields to only id, primary phone, and work phone needs to
be specified for each included resource.

Summary of query parameters for included resources

The filter parameter
You can filter out included resources that do not meet a given criteria.
• Syntax: filter=resource:field:op:value
• Example:
GET claim/v1/claims/demo_sample:1?
include=activities&
filter=activities:escalated:eq:true

• Returns: Claim demo_sample:1 and its included activities that have been escalated

The fields parameter

You can specify which fields you want returned in the included resources.
• Syntax: fields=resource:field_list
• Example:
GET claim/v1/claims/demo_sample:1?
include=activities&
fields=activities:id,dueDate

• Returns: Claim demo_sample:1 and its included activities. For the activities, return only id and dueDate.

Query parameters 55
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The sort parameter

You can sort the included resources. This sorting is reflected in both the payload's related sections and the included
section.
• Syntax: sort=resource:properties_list
• Example:
GET claim/v1/claims/demo_sample:1?
include=activities&
sort=activities:dueDate

• Returns: Claim demo_sample:1 and its included activities, sorted by their due date.

The pageSize parameter

You can specify a maximum number of included resources per root resource. Also, when you use pageSize on
included resources, there are no prev and next links at the included resource level.
• Syntax: pageSize=resource:n
• Example:
GET claim/v1/claims/demo_sample:1?
include=activities&
pageSize=activities:5

• Returns: Claim demo_sample:1 and up to 5 of its included activities.

The includeTotal parameter

You can include the total number of included resources.
• Syntax: includeTotal=resource:true
• Example:
GET claim/v1/claims/demo_sample:1?
include=activities&
includeTotal=activities:true

• Returns: Claim demo_sample:1, its included activities, and the total number of included activities for
demo_sample:1.

Tutorial: Send a GET with query parameters for included resources

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” on page 29.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following and click Send:
GET [Link]
3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
4. Enter the following and click Send:
GET [Link]
fields=id,claimNumber&include=activities&filter=activities:escalated:eq:true

Checking your results

Compare the two payloads. Note the following differences:
In the first payload:

56 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• For claims, the default claim fields are returned.

• For activities, all activities are returned.
In the second payload:
• For claims, only the id and claimNumber fields are returned.
• For activities, only the escalated activities are returned.

Query parameters 57
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

58 Query parameters
chapter 4

POSTs

This topic discusses the POST method and how to construct a request payload for creating a single resource. For
information on how to create request payloads that specify multiple resources, see “Reducing the number of calls” on
page 85.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: Create a new note that specifies required fields only” on page 65
• “Tutorial: Create a new note that specifies optional fields” on page 65

Overview of POSTs
A POST is a REST API method that creates a resource in ClaimCenter. The POST method is also used to execute
specific business processes, such as assigning an activity.
A POST consists of the POST method and the endpoint, such as POST /activities/{activityId}/notes, and a
request payload. The request payload contains data about the resource to create.
The response to a POST includes an HTTP code indicating success or failure. It also includes a response payload. The
contents of the response payload is determined by the endpoint's schema.
• For an endpoint used to create data, the response payload may contain data from the request payload. It may also
contain data generated by ClaimCenter, such as ids and timestamps.
• For an endpoint used to execute a business action, the response payload is a resource related to the business action.
It could be the resource on which the action was executed. For example, when assigning an activity, the response
payload contains the assigned activity. It could also be a resource generated by the business action. For example,
when canceling a policy the response payload contains a JobResponse.
When a developer is configuring a caller application to POST information using Cloud API, they will need to
determine the correct structure for the request payload. They may also need to parse information out of the response
payload. The remainder of this topic discusses how request payloads for resources are structured and how developers
can learn about request payload formats.
POSTs are also used to execute business actions. For these types of POSTs, request payloads may be unnecessary,
optional, or required. For example:
• A POST that marks an activity as complete does not require a request payload.
◦ You can optionally provide a request payload to add a note to the completed activity.
• A POST that assigns an activity requires a request payload. The payload specifies how to assign the activity.

POSTs 59
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Standardizing payload structures

Communication between caller applications and Cloud API is easier to manage when the information in the payloads
follows a standard structure. Cloud API has standard structures for both request payloads and response payloads. The
structures are defined by data envelopes, and by request and response schemas.

Standardizing information common to all endpoints

A data envelope is a wrapper that wraps JSON sent to or returned from Cloud API. To maintain a standard payload
structure, Cloud API uses two data envelopes: DataEnvelope and DataListEnvelope.
DataEnvelope is used to standardize the format of information for a single element. It specifies a data property with
the following properties: checksum, id, links (for a single element), method, refid, related, type and uri. At a
high level, the format of a payload for a single element looks like:

{
"data": {
"checksum": ...,
"id": ...,
"links": ...,
"method": ...,
"refid": ...,
"related": ...,
"type": ...,
"uri": ...
}
}
}

DataListEnvelope is used to standardize the format of information for collections. It specifies the following
properties, which are siblings to the data section: count, links (for a collection), and total. At a high level, the
format of a payload for a single element looks like:

{
"count" ...,
"data": [
{ properties_for_element_1 },
{ properties_for_element_2 },
...
],
"links": ...,
"total": ...
}

Every property does not appear in every payload. There are different reasons why a property may not appear in a given
payload. For example:
• Some properties, such as refid, apply only to requests and do not appear in response payloads.
• Some properties, such as count, apply only to responses and do not appear in request payloads.
• Some properties, such as related, do not appear by default and appear only when the request includes certain
query parameters.

Standardizing information specific to a given endpoint

DataEnvelope and DataListEnvelope provide a standard format for information that is applicable to all request and
response payloads. But, different endpoints interact with different types of resources. For each endpoint, some portion
of the payload must provide information about a specific type of resource.
To address this, Cloud API also uses request schemas and response schemas. A request schema is a schema that is used
to define the valid structure of a request payload for a specific set of endpoints. Similarly, a response schema is a
schema that is used to define the valid structure of a response payload for a specific set of endpoints.
Request and response schemas are hierarchical. For example, for responses, the GET /activity/{activityId}
endpoint uses the ActivityResponse schema. This schema has two child schemas: ActivityData and
ActivityResponseInclusions.

Request and response schemas extend DataEnvelope or DataListEnvelope. This ensures that information relevant to
all endpoints appears in payloads in a standard way.

60 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Request and response schemas also define an attributes property for the payload. This property is associated with a
schema that includes resource-specific information for the payload. For example, the GET /activity/{activityId}
endpoint specifies an attributes property in the ActivityData child schema. This property is associated with the
Activity schema, which contains activity-specific fields, such as activityPattern and activityType. As a result,
response payloads for the GET /activity/{activityId} endpoint have this structure:

{
"data": {
"checksum": ...,
"attributes" : {
"activityPattern": ... ,
"activityType": ...,
...},
"id": ...,
"links": ...,
"method": ...,
"refid": ...,
"related": ...,
"type": ...,
"uri": ...
}
}
}

Viewing request schemas

You can use Swagger UI to review the structure of a request payload for a given endpoint. This includes the hierarchy
of schemas and the type of information in each schema. The information appears in the description of the endpoint's
body parameter on the Model tabs.

View a request schema in Swagger UI

Procedure
1. Start ClaimCenter.
2. In a web browser, navigate to the Swagger UI for the appropriate API.
• For more information, see “View definitions using Swagger UI” on page 19.
3. Click the method button for the appropriate endpoint. Swagger UI shows details about that endpoint underneath
the endpoint name.
• For example, to view the request schema for POST /activities/{activityID}/notes, click the POST
button for that endpoint.
4. Scroll down to the Body entry in the Parameters section. The Model tab shows the hierarchy of data envelopes for
this endpoint, and the contents of each data envelope.

Designing a request payload

Request payload structure
The basic structure for a request payload that creates a single resource is:

{
"data": {
"attributes": {
<field/value pairs are specified here>
}
}
}

For example, this request payload could be used to create a note:

{
"data": {
"attributes": {

POSTs 61
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"subject": "Main contact vacation",

"body": "Rodney is on vacation in June. Direct urgent questions to Sarah Jackson.",
"confidential": false,
"topic": {
"code": "general"
}
}
}
}

In some situations, you can create an object using an "empty body" (a body that specifies no values). An object created
in this way will contain only default values. In these situations, the payload has an empty attributes section:

{
"data": {
"attributes": {
}
}
}

Determining the minimum creation criteria

For most types of business objects, there are a set of fields that you must specify when creating that type of object. For
example:
• To create an activity, the only required field is activityPattern.
• To create a document, the required fields are name, status, and type.
• To create a note, the only required field is body.
It is typically not possible to determine the minimum required fields from the API definition. This is because the
minimum required fields are often enforced not by Cloud API but rather by ClaimCenter. The easiest way to determine
the minimum required fields is to refer to this documentation. For example:
• The minimum required fields for activities are documented in “Activities” on page 281.
• The minimum required fields for activities are documented in “Documents” on page 289.
• The minimum required fields for activities are documented in “Notes” on page 295.
The documentation also provides examples for how to create various types of business objects and information on any
requirements or behaviors unique to that type of object.

Specifying scalar values

Scalar values follow these patterns:

Field value type Pattern Example Notes

String "fieldName" : "value" "firstName" : "Ray", ids are considered strings.
"id": "demo_date:12"
Integer "fieldName" : value "numDaysInRatedTerm": 180 Unlike the other scalar value types,
integer, Boolean, and null values are
expressed without quotation marks.
Decimal "fieldName" : "value" "speed": "60.0"
Date "fieldName" : "value" "dateReported": Expressed using the format
"2020-04-09"
YYYY-MM-DD
Datetime "fieldName" : "value" "createdDate": Expressed using the format
"2020-04-09T18:24:57.
YYYY-MM-DDT
256Z"
hh:mm:[Link]
where T and Z are literal values.

62 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Field value type Pattern Example Notes

Boolean "fieldName" : value "confidential": false Unlike the other scalar value types,
integer, Boolean, and null values are
expressed without quotation marks.

For scalars, the formats for values are the same for request payloads and response payloads. For a given field, you can
use its format in a response payload as a model for how to build a request payload.

ids
ID values are assigned by ClaimCenter. Therefore, you cannot specify an id for an object that is being created.
However, you can specify ids when identifying an existing object that the new object is related to.

Specifying compound values

InsuranceSuite includes several datatypes where multiple values are stored as a unit. This includes the following:
• Typekey (containing a code and a name)
• MonetaryAmount and CurrencyAmount (containing a currency and an amount)
• SpatialPoint (containing a longitude coordinate and a latitude coordinate)
For example, an activity's assignmentStatus property is a typekey. Thus, the response payload for an activity's
assignment status has two sub-fields (code and name):
"assignmentStatus": {
"code": "assigned",
"name": "Assigned"
}

Typekeys
Typekeys use the following format:

"field": {
"code": "value"
}

For example:

"priority": {
"code": "urgent"
}

Typekeys also have a name field, which is included in responses. But, the name field is not required. If you include it in
a request schema, it is ignored.

Monetary amounts
Monetary amounts use the following format:

"field": {
"amount": "amountValue",
"currency": "currencyCode"
}

For example:

"transactionAmount": {
"amount": "500.00",
"currency": "usd"
}

(Note that in Cloud API, the datatype is referred to as MonetaryAmount. But in ClaimCenter, these values are actually
stored using the CurrencyAmount datatype.)

POSTs 63
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Spatial points
Spatial points use the following format:

"field": {
"longitude": "coordinateValue",
"latitude": "coordinateValue"
}

For example:

"coordinates": {
"longitude": "-122.26842",
"latitude": "37.55496"
}

Setting values and objects to null

To set the value of a field to null, use the following syntax:

Field value type Pattern Example Notes

Field whose value is to "fieldName" : null "middleName": null You can set any scalar value to null.
be set to null Express it without quotation marks.

To set the value of an object to null, specify the null at the object field level. For example, a user can optionally have a
home phone number. The following explicitly states that the home phone number is null:

"homePhone": null

To set a typekey to null, specify the null at the typekey field level. (Do not specify the null at the code level.) For
example, the following sets a document's language field to null:

"language": null

To set a monetary amount, currency amount, or spatial point to null, specify the null at the field level. (Do not specify
the null at the amount, currency, longitude, or latitude level.) For example, the following sets a transactionAmount
field to null:

"transactionAmount": null

Sending POSTs
You use a request tool, such as Postman, to ensure POSTs are well-formed and to review the structure of the response
payloads. For more information, see “Requests and responses” on page 28.

Send a POST using Postman

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify the appropriate authorization information.
3. Under the Untitled Request label, make sure that POST is selected.
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to create a new note for activity cc:2 on an instance of ClaimCenter on your machine, enter:
[Link]
5. Specify the request payload.
a) In the first row of tabs (the one that starts with Params), click Body.

64 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

b) In the row of radio buttons, select raw.

c) At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d) Paste the request payload into the text field underneath the radio buttons.
6. Click Send. The response payload appears below the request payload.

Tutorial: Create a new note that specifies required fields only

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” on page 29.
In this tutorial, you will create a note whose subject is "API tutorial note 1" for an existing activity. The other fields
will not be specified and will be assigned default values by the application (such as not being confidential and having a
subject of "General").

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following call and click Send:
GET [Link]
3. Identify the id of the first activity in the payload. This value is referenced below as <activityId>.
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
POST [Link]
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note 1"
}
}
}

7. Click Send. The response payload appears below the request payload.

Checking your work

1. View the new note in ClaimCenter.
a. In the response payload, note the claim number of the claim this note is related to. (It is the value of the
[Link] field.)
b. Log on to ClaimCenter as aapplegate.
c. On the Claim tab, click the drop-down arrow. Enter the claim number in the Claim # field and press Enter.
d. In the left-hand sidebar, click Notes.
The API tutorial note should be listed as one of the notes.

Tutorial: Create a new note that specifies optional fields

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” on page 29.
In this tutorial, you will create a note whose subject is "API tutorial note 2" for an existing activity. You will also
specify values for two optional fields: confidential (set to true) and subject (set to "Litigation").

POSTs 65
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following call and click Send:
GET [Link]
3. Identify the id of the first activity in the payload. This value is referenced below as <activityId>.
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
POST [Link]
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note 2",
"confidential": true,
"topic": {
"code": "litigation"
}
}
}
}

7. Click Send. The response payload appears below the request payload.

Checking your work

1. View the new note in ClaimCenter.
a. In the response payload, note the claim number of the claim this note is related to. (It is the value of the
[Link] field.)
b. Log on to ClaimCenter as aapplegate.
c. On the Claim tab, click the drop-down arrow. Enter the claim number in the Claim # field and press Enter.
d. In the left-hand sidebar, click Notes.
The API tutorial note should be listed as one of the notes. This note is confidential and it has the category specified in
the request payload.

Responses to a POST
Every successful POST generates a response object with a response payload. This payload may contain values
generated by ClaimCenter during resource creation that are needed by the caller application For example:
• The resource's Public id (which is also the Cloud API id value)
• Generated human-readable id values, such as the claim number
• Values generated by a business flow, such as:
◦ The user and group that the resource was assigned to
◦ Activities generated to process the resource
Similarly to request schemas, response schemas follow certain patterns around using data envelopes to wrap the
resource schema. In many instances, the request and response schemas will match.

Fields with null values are omitted

Similar to GETs, the response payloads for POSTs contain only fields whose values are non-null. Fields with null
values are omitted from the response payload.

66 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

If a given field is expected in a response payload but it is missing, this is often because the value was null.

POSTs and query parameters

You can use the fields query parameter with a POST to control the fields that appear in the response payload. For
example, the following creates a note for activity xc:20 based on the request payload. The response payload has the
default fields.
POST /activities/xc:20/notes
The following also creates a note for activity xc:20 based on the request payload. But, the response payload includes
only the id field.
POST /activities/xc:20/notes?fields=id

Postman behavior with redirects

Some servers automatically redirect incoming calls to different URLs. For example, a call that uses a non-secure URL
(one starting with [Link] may get automatically redirected to a secure URL (one starting with [Link]
When Postman executes a POST or PATCH and is redirected to a new URL, Postman automatically changes the
operation to a GET. This changes the outcome of the operation, as a GET will only retrieve data. This behavior can
cause confusion during development, as the developer using Postman may not realize the POST or PATCH is being
turned into a GET, or they may not realize why Postman is making the change.
You can avoid this behavior by ensuring that you use URLs in Postman that avoid any redirect behavior from the
server. Alternately, you can disable the Postman behavior by disabling the "Automatically follow redirects" setting in
File > Settings.

Business action POSTs

True REST APIs focus exclusively on the CRUD methods (Create, Read, Update, Delete). Like other REST APIs,
Cloud API exposes these CRUD methods through endpoints that support the POST, GET, PATCH, and DELETE
methods.
However, in some circumstances, Cloud API needs to trigger a business process that does not readily map to a single
Create, Read, Update, or Delete operation. For example, Cloud API exposes the ability to assign an activity. This
action modifies the value of the activity's assignedUser and assignedGroup fields. But, the assigned user and group
can be determined by assignment logic internal to ClaimCenter. Assignment could vary based on the activity itself, on
the current workload of each group, or on whether a given user is on vacation or not. Activity assignment cannot be
executed through a PATCH because the caller application cannot always determine how to set the assignedUser and
assignedGroup fields.

In standard REST architecture, there is no operation for this type of business action. Therefore, Cloud API has adopted
the following conventions:
• Endpoints that execute business actions use the POST method.
• Endpoints that execute business actions have paths the end in verbs (such as "assign" or "complete").
Examples of endpoints that execute business actions include:
• POST /common/v1/activities/{activityId}/assign, which assigns the corresponding activity
• POST /common/v1/activities/{activityId}/complete, which marks the corresponding activity as complete
• POST /claim/v1/claims/{claimId}/cancel, which cancels the corresponding draft claim
• POST /claim/v1/claims/{claimId}/submit, which submits the corresponding draft claim, thereby promoting it
to an open claim

POSTs 67
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Business action POSTs and request payloads

All POST endpoints that create resources (such as POST /common/v1/activities/{activityId}/notes, which
creates a note for the given activity) require a request payload. For some endpoints, the payload can be empty. But, a
request payload is always required.
For POST endpoints that execute business actions, payload requirements can vary.
• Some business action POSTs require a payload. (For example, activities/{activityId}/assign requires a
payload that specifies the assignment criteria.)
• Some business action POSTs can optionally have a payload. (For example, activities/{activityId}/complete
does not require a payload. But you can specify one if you want to attach a note to the activity while you complete
it.)
• Some business action POSTs may not permit any payload.
To determine whether a business action POST requires, allows, or forbids a request payload, refer to the relevant
section of this documentation.

Business action POSTs and lost updates

When a business process spans multiple calls, the first call is typically either a GET that retrieves data, or a POST that
creates data. If the business process involves a POST that executes a business action, this POST typically comes after
the first call, and it typically acts on a resource that was queried for or created in a previous call.
It is possible for some other process to modify the data after the initial GET/POST, but before the subsequent business
action POST. This can cause a lost update. Within Cloud API, a lost update is a modification made to a resource that
unintentionally overwrites changes made by some other process.
You can prevent lost updates using checksums. For more information, see “Lost updates and checksums” on page 111.

Improving POST performance

The first time a caller application makes a call to a Cloud API endpoint, the call may take longer to process than
normal. This is because the Guidewire server may need to execute tasks for the first call that it does not need to re-
execute for subsequent tasks, such as:
• Loading Java and Gosu classes
• Parsing and loading configuration files that are lazy-loaded on the first reference
• Loading data from the database or other sources into local caches
• Initializing database connections
A caller application can avoid having this slow processing time occur during a genuine business call by "warming up"
the endpoint. This involves sending a dummy "warm-up request" to trigger these initial tasks. The warm-up request
helps subsequent requests execute more rapidly. The best way to accomplish this is with a POST that contains the GW-
DoNotCommit header. The POST triggers the initial endpoint tasks, and the header identifies that data modifications
made by the request are to be discarded and not committed.
For more information, see “Warming up an endpoint” on page 80.

68 POSTs
chapter 5

PATCHes

This topic discusses the PATCH method, which modifies existing data.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: PATCH an activity” on page 71

Overview of PATCHes
A PATCH is a REST API method that modifies an existing resource in ClaimCenter.
A PATCH consists of the PATCH method and the endpoint, such as PATCH /activities/{activityId}, and a
request payload. The request payload contains the data to modify in the specified resource.
The response to a PATCH includes an HTTP code indicating success or failure. It also includes a response payload.
The default response for a PATCH consists of a predetermined set of fields and resources. This may or may not include
the data that the PATCH modified.
When a developer is configuring a consumer application to PATCH information to Cloud API, they will need to
determine the correct structure for the request payload. They may also need to parse information out of the response
payload.

The PUT operation

Within REST API architecture, there are two operations that modify existing resources - PATCH and PUT. PATCH is
used to modify a portion of an existing resource (while leaving other aspects of it unmodified). PUT is used to replace
the entire contents of an existing resource with new data. Cloud API supports the PATCH operation, but not the PUT
operation. This is because nearly every operation that modifies an InsuranceSuite object modifies only a portion of it
while keeping the rest of the object untouched. This behavior maps to PATCH, but not to PUT.

The PATCH payload structure

Communication between consumer applications and Cloud API is easier to manage when the information in the
payloads follows a standard structure. Cloud API has standard structures for both request payloads and response
payloads. The structures are defined by data envelopes, and by request and response schemas. POSTs and PATCHes
use data envelopes, request schemas, and response schemas in the same way. For more information, see “Standardizing
payload structures” on page 60.

PATCHes 69
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Designing a request payload

Designing a request payload for a PATCH is almost the same as designing a request payload for a POST. The only
differences are:
• Fields that are marked as requiredForCreate are required for POSTs but not for PATCHes.
• Fields that are marked as createOnly are allowed in POSTs but not in PATCHes.
For more information on designing request payloads for POSTs, see “Designing a request payload” on page 61.

PATCHes and arrays

You can include arrays in a PATCH request payload. For most arrays in Cloud API, PATCHing an array does not add
the PATCH members to the members already existing in the array. Instead, the PATCH replaces the existing members
with the PATCH members.
For example, in the Claim API, the Claim resource has a witnesses array. This is an array of ClaimContacts who are
witnesses to the loss. The following PATCH payload will set the witnesses array to a single witness, the ClaimContact
whose id is cc:1306. If there were witnesses in this array before the PATCH, those witnesses will be removed and the
only witness will be ClaimContact cc:1306.

{
"data": {
"attributes": {
"witnesses": [
{
"contact": {
"id": "cc:1306"
}
}
]
}
}
}

If you want a PATCH to be additive to an array, you must first determine the existing members of the array, and then
specify an array in the PATCH with the existing members as well as the ones you wish to add.

Sending PATCHes
You can use a request tool, such as Postman, to ensure PATCHes are well-formed and to review the structure of the
response payloads. For more information on Postman, see “Requests and responses” on page 28.

Send a PATCH using Postman

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify Basic Auth authorization using user aapplegate and password gw.
3. Under the Untitled Request label, make sure that PATCH is selected.
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to patch activity cc:2 on an instance of ClaimCenter on your machine, enter: http://
localhost:8080/cc/rest/common/v1/activities/cc:2
5. Specify the request payload.
• In the first row of tabs (the one that starts with Params), click Body.
• In the row of radio buttons, select raw.
• At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
• Paste the request payload into the text field underneath the radio buttons.

70 PATCHes
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

6. Click Send. The response payload appears below the request payload.

Tutorial: PATCH an activity

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” on page 29.
In this tutorial, you will find an open activity from the sample data. You will then update the activity's subject and
priority.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Get police report" activity for Andy Applegate, which can be PATCHed because it
is an open activity on an open claim. Query for that activity by entering the following call and clicking Send:
a. GET [Link]
%20report
3. For the activity in the response payload that is assigned to Andy/Alice Applegate, note the following information:
a. Activity ID
b. Priority
c. Subject
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
a. PATCH [Link]
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons. Note that the subject has an additional
"!" at the end.
{
"data": {
"attributes": {
"subject" : "Get police report!",
"priority": {
"code": "low"
}
}
}
}

7. Click Send. The response payload appears below the request payload.

Checking your work

1. View the modified activity in ClaimCenter.
a. Log on to ClaimCenter as the user aapplegate. Andy's landing page is the Activities screen, which shows
the open activities assigned to him. It defaults to showing "My activities today". change the drop-down list
at the top of the Activities screen to "All open".
b. Click the Priority column to sort the activities in ascending priority order.
The PATCHed activity (whose priority is now Low) should be at or near the top of the list. The patched activity will
have a subject ending with an "!".

PATCHes 71
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Responses to a PATCH
Every successful PATCH generates a response object with a response payload. Depending on the default fields returned
and whether any query parameters have been specified, the response payload may or may not contain the values
modified by the PATCH.
Similarly to request schemas, response schemas follow certain patterns around using data envelopes to wrap the
resource schema. In many instances, the request and response schemas will match.

Fields with null values are omitted

Similar to GETs and POSTs, the response payloads for PATCHes contain only fields whose values are non-null. Fields
with null values are omitted from the response payload.
If a given field is expected in a response payload but it is missing, this is often because the value was null.

PATCHes and query parameters

You can use the fields query parameter with a PATCH to control the fields that appear in the response payload. For
example, the following PATCHes a note for activity xc:20 based on the request payload. The response payload has the
default fields.
PATCH /activities/xc:20/notes
The following also PATCHes a note for activity xc:20 based on the request payload. But, the response payload includes
only the id field.
POST /activities/xc:20/notes?fields=id

PATCHes and lost updates

When a business process spans multiple calls, the first call is typically either a GET that retrieves data, or a POST that
creates data. If the business process involves a PATCH, this PATCH typically comes after the first call, and it typically
acts on a resource that was queried for or created in a previous call.
It is possible for some other process to modify the data after the initial GET/POST, but before the subsequent PATCH.
This can cause a lost update. A lost update is a modification made to a resource that unintentionally overwrites changes
made by some other process.
You can prevent lost updates using checksums. For more information, see “Lost updates and checksums” on page 111.

Postman behavior with redirects

Some servers automatically redirect incoming calls to different URLs. For example, a call that uses a non-secure URL
(one starting with [Link] may get automatically redirected to a secure URL (one starting with [Link]
When Postman executes a POST or PATCH and is redirected to a new URL, Postman automatically changes the
operation to a GET. This changes the outcome of the operation, as a GET will only retrieve data. This behavior can
cause confusion during development, as the developer using Postman may not realize the POST or PATCH is being
turned into a GET, or they may not realize why Postman is making the change.
You can avoid this behavior by ensuring that you use URLs in Postman that avoid any redirect behavior from the
server.

72 PATCHes
chapter 6

DELETEs

This topic provides an overview of DELETEs, which are used to delete resources.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• Tutorial: “Tutorial: DELETE a note” on page 73

Overview of DELETEs
Within the context of APIs that are fully REST-compliant, a DELETE is an endpoint operation that deletes a resource.
This typically involves removing the resource from the underlying database.
Within the context of Cloud API, a DELETE is a Cloud API method that "removes" an existing resource from
ClaimCenter. What it means to "remove" the resource depends on the resource type. The DELETE operation federates
to the ClaimCenter code that matches the functionality most closely tied to deletion. That code could theoretically:
• Delete the corresponding data model instance from the operational database.
• Mark the corresponding data model instance as retired.
• Modify the corresponding data model instance and other related instances to indicate the data is no longer active or
available.
Unlike GET, POST, and PATCH, there are only a small number of endpoints in the base configuration that support
DELETE. This is because, in most cases, ClaimCenter does not support the removal of data. Several business objects
can be approved, canceled, completed, closed, declined, rejected, retired, skipped, or withdrawn. But only a few can be
deleted.
A DELETE call consists of the DELETE method and the endpoint, such as DELETE /notes/{noteId}. Similar to
GETs, DELETEs are not permitted to have a request payload.
The response to a DELETE includes an HTTP code indicating success or failure. DELETE responses do not have a
response payload.

Tutorial: DELETE a note

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” on page 29.
In this tutorial, you will send calls as Elizabeth Lee (user name elee). In the base configuration, Elizabeth Lee is a
manager who has permission to delete notes. As Elizabeth Lee, you will create a note and query for it. You will then
delete the note and attempt to query for it a second time.
DELETEs 73
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following call and click Send:
GET [Link]
3. Identify the id of the first activity in the payload. This value is referenced below as <activityId>.
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab tab.
a. On the Authorization tab, select Basic Auth using user elee and password gw.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST [Link]
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted"
}
}
}

7. Click Send. In the response payload, identify the note's id.

8. Open a third request tab and right-clicking the second tab and selecting Duplicate Tab tab.
a. Because it is a duplicate of the second tab, this tab also uses user elee.
9. Change the operation to DELETE, enter the following URL, but do not click Send yet:
a. DELETE [Link]
10. DELETEs cannot specifies request bodies. On the third tab, navigate to the Body tab and select the none radio
button.
11. Click Send. (The response to a successful DELETE is "204 - No content".)

Checking your work

Resend the request on the third tab. This request returns a "No resource was found" error because it is attempting to
DELETE a note that has already been DELETEd.

DELETEs and lost updates

When a business process spans multiple calls, the first call is typically either a GET that retrieves data, or a POST that
creates data. If the business process involves a DELETE, this DELETE typically comes after the first call, and it
typically acts on a resource that was queried for or created in a previous call.
It is possible for some other process to modify the data after the initial GET/POST, but before the subsequent
DELETE. This can cause a lost update. Within Cloud API, a lost update is a modification made to a resource that
unintentionally overwrites changes made by some other process.
You can prevent lost updates using checksums. For more information, see “Lost updates and checksums” on page 111.

74 DELETEs
chapter 7

Request headers

This topic describes how you can modify call behavior using the Guidewire-proprietary headers supported by Cloud
API.

HTTP headers
Request and response objects are used by REST APIs to send information between application. These objects contain
HTTP headers. An HTTP header is a name/value pair included with a request or response object that provides
metadata about the request or response. An HTTP header can specify information such as:
• The format used in the request object (such as whether it is JSON or XML)
• The format to use in the response object
• Session and connection information
• Authorization information

Overview of Cloud API headers

Cloud API supports standard HTTP headers, such as Authorization and Content-Type.
Cloud API also supports the following Guidewire-proprietary headers and Guidewire-proprietary values for standard
headers. Every Guidewire-proprietary header is optional.

Header Datatype Description

GW-Checksum String This can prevent lost updates.
When specified, if the call would result in a database
commit, then Cloud API allows the commit only if the
checksum in the header matches the checksum value
from ClaimCenter.
For more information, see “Lost updates and
checksums” on page 111.
GW-DBTransaction-ID String of up to 128 This can prevent duplicate requests.
characters When specified, this is used as the database transaction
ID for this request. Cloud API allows the commit only if the
header's value has not be submitted by any prior request.
The value is stored in the ClaimCenter database and must
be globally unique across all clients, APIs, and web
services.

Request headers 75
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Header Datatype Description

For more information, see “Preventing duplicate
database transactions” on page 80.
GW-DoNotCommit Boolean This can be used to warm up endpoints.
Typically, a caller application specifies this on a dummy
POST that is sent prior to any genuine business requests.
The POST triggers "warm up" activities for the endpoint,
such as the loading of Java and Gosu classes. But the
header prevents any data from being committed. This
request can improve the performance of subsequent
requests to that endpoint.
For more information, see “Warming up an endpoint”
on page 80.
GW-IncludeSchemaProperty Boolean This can modify the format of a JSON payload.
When this is set to true, if the operation returns JSON
with a defined schema, the $GW-Schema property is
added to the root JSON object of the response with the
fully-qualified name of the JSON Schema definition for
that object. The default is false.
GW-Language String This sets the language for the response.
For more information, see “Language and locale” on
page 77.
GW-Locale String This sets the locale for the response.
For more information, see “Language and locale” on
page 77.
GW-UnknownPropertyHandling One of these string values: This specifies the behavior for handling request payloads
• log with unknown properties. The default behavior is
reject.
• reject
• ignore For more information, see “Handling a call with
unknown elements” on page 81.
GW-UnknownQueryParamHandling One of these string values: This specifies the behavior for handling URLs with
• log unknown query parameters. The default behavior is
reject.
• reject
• ignore For more information, see “Handling a call with
unknown elements” on page 81.
GW-User-Context String This provides information about the represented user
when a service makes a service-for-user or service-for-
service call.
For more information, see the Cloud API Developer Guide.

GW-ValidateResponseHandling Boolean This requests that the server performs additional

validation of REST API responses against constraints such
as maxLength that are declared in the schema. Disabled
by default, but may be useful in some contexts for testing
or debugging of custom endpoints.
For more information, see “Validating response
payloads against additional constraints” on page 81.
x-gwre-session String This controls how related calls are routed on instances of
ClaimCenter running in a cluster.

76 Request headers
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Header Datatype Description

(Note: This header is not exclusive to Cloud API and
therefore does not follow the convention of using "GW-"
at the start of header names.)
For more information, see “Routing related calls in
clustered environments” on page 79.
Prefer String This gives the caller the ability to specify a wait time.
(Note: This is a standard HTTP header. Cloud API supports
the following standard values for this header: respond-
async and respond-async, wait=T. It also supports
one Guidewire-specific value, respond-async, wait-
ms=T.)
For more information, see “Asynchronous calls” on page
117.
X-Correlation-ID String This permits a customer to trace a request from its initial
reception through all of the subsequent applications that
were invoked to handle that request.
The actual traceability ID present in the MDC and logs
(and returned in the response) is dependent on the
implementation of the TraceabilityIDPlugin plugin.
The default implementation uses this value, if specified, or
a generated UID. However, another implementation may
always generate a unique ID and log the relationship
between these incoming values and the generated UID.
This header can be repeated, but the resulting string will
just be the comma separated values.
(Note: This header predates the REST API Framework and
was created prior to the convention of using "GW-" at the
start of header names.)

Send a request with a Cloud API header using Postman

About this task
You can include Cloud API headers in calls executed from Postman.

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify authorization as appropriate.
3. Add the header and header value.
• In the first row of tabs (the one that starts with Params), click Headers.
• Scroll to the bottom of the existing key/value list.
• In the blank row at the bottom of the key/value list, enter the header name in KEY column and its value in the
VALUE column.
4. Enter the request operation and URL.
5. Click Send.

Language and locale

When you send a request to Cloud API, the default behavior is to present data in the response using the default
language and locale specified in ClaimCenter. These defaults are specified in [Link] using the following
application configuration parameters:

Request headers 77
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• DefaultApplicationLanguage
• DefaultApplicationLocale
For more information on how InsuranceSuite applications support globalization, see the Globalization Guide.
If ClaimCenter supports multiple languages and locales, Cloud API requests can use request headers to specify a
language and locale for the response. There are different ways the language and locale of the response can be
interpreted:
• The Guidewire-specific GW-Language and GW-Locale headers
◦ This is the recommended method
• The preferred language of an authenticated user
• The standard HTTP Accept-Language header

GW headers
Cloud API has two Guidewire-specific headers you can use to specify language and locale: GW-Language and GW-
Locale. These headers give you the ability to explicitly state the desired language and locale for a call.

To specify a language using Guidewire-specific headers, include the following header with the request:
• Key: GW-Language
• Value: (an ISO 639-1 code designating the language)
For example, to set the language to Japanese, the request must contain a GW-Language/ja header.
To specify a locale using GW headers, include the following header with the request:
• Key: GW-Locale
• Value: (an ISO 639-1 code followed by an underscore followed by an ISO 3166-1 alpha-2 locale code)
For example, to set the locale to Japanese, the request must contain a GW-Locale/ja_JP header.
If you want to specify a language and locale, Guidewire recommends using these headers. They are the most explicit
declaration of the intent of the call.

The preferred language of the authenticated caller

If the caller is authenticated and has a preferred language and the call does not specify a GW-Language or GW-Locale
header, then the caller's preferred language is used.
Note that this only applies to calls where the caller is authenticated. It does not apply to calls where authentication does
not occur, such as calls to the /[Link] and /[Link] endpoints.

The Accept-Language header

The Accept-Language header is a standard HTTP header that specifies a preferred language (but not a preferred
locale). This header is automatically added by most browsers. However, how it is set depends on the browser. The
header can also be set by non-browser calls.
If the request does not contain either a GW-Language header or GW-Locale header, and the caller is not an authenticated
user with a preferred language, then the Accept-Language header is used.

How are the response language and locale determined?

What is specified What is language set to? What is locale set to?
Both GW-Language and GW- The GW-Language header value. The GW-Locale header value.
Locale
Only GW-Language The GW-Language header value. The caller's preferred locale, if any.
Otherwise, the ClaimCenter default locale.
Only GW-Locale The caller's preferred language, if any. Otherwise, The GW-Locale header value.
the ClaimCenter default language.

78 Request headers
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

What is specified What is language set to? What is locale set to?
Neither GW-Language nor The caller's preferred language, if any. Otherwise, The caller's preferred locale, if any.
GW-Locale the Accept-Language header, if any. Otherwise, Otherwise, the ClaimCenter default locale.
the ClaimCenter default language.

Routing related calls in clustered environments

To improve performance and reliability, you can install multiple ClaimCenter servers in a configuration known as a
cluster. A ClaimCenter cluster distributes client connections among multiple ClaimCenter servers, reducing the load on
any one server. If one server fails, the other servers seamlessly handle its traffic. For more information on clusters, refer
to the Administration Guide.
When ClaimCenter is running in a cluster, it is possible for related Cloud API calls to be routed to different nodes. This
can cause problems, such as Concurrent Data Change Exceptions. Typically, multiple related Cloud API calls need to
be routed to the same node.
There are two ways that you can ensure a series of related Cloud API calls are routed to the same instance: session IDs
(which is the default behavior) and cookies.

Using session IDs

Within the context of Cloud API calls in a clustered environment, a session ID is an arbitrary string generated by the
caller application to identify related API calls. The ID is passed in the header of each request. Every request that uses a
given session ID will be routed to the same node in the cluster. The header key for a session ID is x-gwre-session.
For example, suppose that a caller application makes the following calls to ClaimCenter cluster:
1. A POST to create an activity.
2. A PATCH to update the activity.
3. A POST to create a note on the activity.
All three calls include the following header:

x-gwre-session: 09d0fbf0-243c-4337-a582-725df8d33e39

Because all three calls specify the same session ID, all three calls will be routed to the same node.
Session IDs is the default behavior of the Guidewire Cloud Platform. If you wish to use this option, you do not need to
make any special request to Guidewire Cloud Operations.

Using cookies
Within the context of Cloud API calls in a clustered environment, a cookie is an arbitrary string generated by
Guidewire Cloud Platform that can be used to identify subsequent related API calls.
If a request header does not contain an x-gwre-session header key, the Guidewire Cloud Platform generates a cookie
and returns it in the response header with a Set-Cookie header key. Subsequent calls can include this cookie in the
request header using the Cookie header key. Every request that uses a given cookie will be routed to the same node in
the cluster that generated the cookie.
For example, suppose that a caller application makes the following calls to ClaimCenter cluster:
1. A POST to create an activity
• The request header contains no x-gwre-session header key.
• The response header contains the following: Set-Cookie: gwre=ccd37ca0-f8d3-4a8e-
b278-83274d82b355; Path=/
2. A PATCH to update the activity.
• The request header contains the following: Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355
3. A POST to create a note on the activity

Request headers 79
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The request header contains the following: Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355

Because the second and third call specify the cookie returned by the first call, the second and third call are routed to the
same node that processed the first call.
Cookies are not the default behavior of the Guidewire Cloud Platform. If you wish to use this option, you must request
this from Guidewire Cloud Operations.

Comparing session IDs and cookies

Under most circumstances, it may be easier to use session IDs.
• Session IDs are generated by the caller application.
• Session IDs do not require the caller application to identify information in a response header and then manage the
storage that information for later use.
• Session IDs are the default behavior for Guidewire Cloud Platform.
If you wish to use cookies, you must request this from Guidewire Cloud Operations.

Preventing duplicate database transactions

In some circumstances, when a caller application is making a request that involves a commit to the database, the
application may want to ensure that the request is processed only once. The caller application can do this using the GW-
DBTransaction-ID header.

The GW-DBTransaction-ID header identifies a transaction ID (a string of up to 128 characters). When submitted with a
Cloud API call, Cloud API attempts to insert the value into the database's TransactionID table.
• If the value does not already exist in the table, the insert is successful. Cloud API assumes the transaction has not
already been committed, and the call is processed as normal.
• If the value does exist in the table, the insert fails. Cloud API assumes the transaction has already been committed,
and the call is rejected. Cloud API returns a 400 status code with an
[Link] error.

For the call to succeed, the transaction ID specified in the header must be globally unique across all clients, APIs, and
web services.
The GW-DBTransaction-ID header has the following limitations:
• It only works with Cloud API calls that commit data to the database.
• It only works when Cloud API commits a single time only. (Cloud API calls that commit multiple times are rare.)
• It only works if the commit is either the only side effect of the call, or if the commit happens before any other side
effects, such as the sending of notifications to external systems.
Duplicate requests do not return identical responses. The first request will succeed, but subsequent requests will fail. It
is the responsibility of the caller application to decide how or if to handle this situation.

Warming up an endpoint
The first time a caller application makes a call to a Cloud API endpoint, the call may take longer to process than
normal. This is because the Guidewire server may need to execute tasks for the first call that it does not need to re-
execute for subsequent tasks, such as:
• Loading Java and Gosu classes
• Parsing and loading configuration files that are lazy-loaded on the first reference
• Loading data from the database or other sources into local caches
• Initializing database connections
A caller application may want to avoid having this slow processing time occur during a genuine business call.
Therefore, the caller application may want to "warm up" the endpoint. This involves sending a dummy "warm-up
request" to trigger these initial tasks. The warm-up request helps subsequent requests execute more rapidly.

80 Request headers
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Warm-up requests are not supposed to create or modify data. Theoretically, a caller application could use a GET as a
warm-up request. However, GETs do not trigger as wide a range of start-up tasks as POSTs. The better option is to
send a POST that does not commit any changes to the database. The best way to accomplish this is with a POST that
contains the GW-DoNotCommit header. This header identifies that data modifications made by the request are to be
discarded and not committed.

Best practices for warming up endpoints

Every endpoint makes use of different resources. Therefore, to warm up multiple endpoints, you need multiple
requests. In general, the most effective warm-up request is a composite request with a large number of subrequests that
POST to each endpoint you want to warm up.
For example, this could be a composite request where you create an unverified policy, and then a claim for that policy.
This would include POSTs to other child objects as well, such as contacts, incidents, exposures, and service requests.
When executing a GW-DoNotCommit request, the response code will be the same as normal, such as 200 or 201, even
though no data is committed. Caller applications need to be careful to ensure that there are no other undesired side
effects from the warm-up request, such as integration points that might inadvertently send the dummy data
downstream.

Handling a call with unknown elements

A Cloud API call may include a payload that includes a property that is not defined in the associated schema. By
default, Cloud API rejects unknown properties. You can override the default behavior by including the GW-
UnknownPropertyHandling header. The header must be set to one of the following string values:

• ignore - Ignore all unknown properties. Do not log any messages or return any validation errors.
• log - Log a service-side info message, but then process the call, ignoring any unknown properties.
• reject - Do not process the call. Return a validation error specifying there are unknown properties.
Similarly, a Cloud API call may include a URL with a query parameter that is not defined in the associated schema. By
default, Cloud API rejects calls with unknown query parameters. You can override the default behavior by including
the GW-UnknownQueryParamHandling header. The header must be set to one of the following string values:
• ignore - Ignore all unknown query parameters. Do not log any messages or return any validation errors.
• log - Log a service-side info message, but then process the call, ignoring any unknown query parameters.
• reject - Do not process the call. Return a validation error specifying there are unknown query parameters.

Validating response payloads against additional constraints

Serialization of the HTTP response is one of the final steps in handling a request. Both the response body and response
headers need to be serialized, with the response body written to the HttpServletResponse output stream and the
response headers turned into strings that the servlet container is responsible for writing to the response. Cloud API
supports serialization of a number of different Java object types that can be returned directly from an API handler
method, set as the value of the body of a response object, or added as the value of a header on the response object.
There are several types of response objects whose serialized format is JSON. This includes JsonObject, JsonWrapper,
and TransformResult. By default, a JsonObject or JsonWrapper is validated only against the declared response
schema to ensure that all properties on the object are declared in the schema and have the correct data type.
TransformResult objects are "implicitly validated", given that the mapping file that produces them must conform to
the associated JSON schema.
It is possible to request that the framework also validate a JsonObject, JsonWrapper, or TransformResult against
additional constraints defined in the schema, such as minLength, the set of required fields, or any custom validators
that have been defined. These additional validations are not done by default because they can potentially be an
unnecessary expense in a production situation where the assumption is that the endpoint has been implemented
correctly and will only return valid data. It is also possible that the constraints defined in the schema are intended to
only apply to inputs, and that the response may violate some of them.

Request headers 81
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

You can use the GW-ValidateResponseHandling header to have Cloud API validate its responses against the declared
schema. To do this, include the header and set its value to true.

82 Request headers
part 2

Optimizing calls

The following topics discuss how caller applications can optimize Cloud API calls. This may involve reducing the
number of calls needed to complete an operation, or improving call performance. This includes how to:
• Reduce the number of calls needed to accomplish a business flow using:
◦ Composite requests
◦ Request inclusion
◦ Batch requests
• Prevent lost updates using checksums
• Execute calls asynchronously

Optimizing calls 83
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

84 Optimizing calls
chapter 8

Reducing the number of calls

Good integration design typically involves writing integration points so that the number of calls between services is as
small as possible. Cloud API includes multiple features that let caller applications execute multiple requests in a single
call. This topic provides an overview of these features.

Features that execute multiple requests at once

Cloud API has several features that let caller applications execute multiple requests in a single call.
Composite requests are requests which consist of multiple sibling subrequests, with no parent request. Each
subrequest is executed transactionally in the order it appears. If a given subrequest that attempts to commit data fails,
the entire composite request fails. Information can be passed from one subrequest to another.
For details about composite requests, see “Composite requests” on page 87.
Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:
• A single parent request that creates or modifies a resource
• One or more child requests that create or modify resources related to the parent resource
If either the parent request or any child request fails, the entire request fails.
For details about request inclusion, see “Request inclusion” on page 99.
Batch requests are requests which consist of multiple sibling subrequests, with no parent request. Each subrequest is
executed non-transactionally in the order it appears. If a given subrequest fails, other subrequests in the batch might
still be attempted. Also, there is no mechanism for passing information from one subrequest to another. Each
subrequest is essentially independent from the others.
For details about batch requests, see “Batch requests” on page 105.

Comparing features that execute multiple requests

Composite requests Request inclusion Batch requests
Architecture of the call Sibling subrequests (with no A parent request with one or Sibling subrequests (with
parent request) more child requests no parent request)
The endpoint to call The Composite API's / The endpoint that creates or The relevant API's /batch
composite endpoint modifies the parent object endpoint
(though not all endpoints
support request inclusion)

Reducing the number of calls 85

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Composite requests Request inclusion Batch requests

Behavior when one subrequest that The entire request fails The entire request fails Other subrequests may still
attempts to commit data fails be attempted
Passing information between Through the use of Through the use of refids Not supported
subrequests variables
Allows GET subrequests? Yes No Yes
Allows DELETE subrequests? Yes No Yes
Allows business action POST Yes No Yes
subrequests (such as /assign)?
Allows the creation or modification of Yes No Yes
two unrelated objects?

Determining which feature to use

There is no simple algorithm for determining the appropriate feature to use. In some situations, it may be possible to
use multiple features, but it is easier to write the code using one particular feature.
At a high level, composite requests are typically the most robust option. If there is a choice of which feature to use, it
may be best or easiest to use composite requests.
The following guidelines may also help you determine the best feature to use:
• Use composite requests or request inclusion if:
◦ All subrequests must succeed or fail as a unit.
◦ Information must be passed from one subrequest to another.
◦ The subrequests must use endpoints from different APIs.
• Use composite requests or batch requests if:
◦ At least some of the subrequests are GETs, DELETEs, or business action POSTs
There also may be some situations where a given technique is required. For example, unverified policies can only be
created through composite requests.

86 Reducing the number of calls

chapter 9

Composite requests

From a Cloud API perspective, a composite request is a set of requests that are executed in a single InsuranceSuite
bundle (which corresponds to a single database transaction).
• A composite request can include one or more subrequests that create or modify data. Either all of the subrequests
succeed, or none of them are executed. Each subrequest is a separate unit of work.
• A composite request can also include one or more subselections that query for data.
Subrequests and subresponses are executed serially, in the order they are specified in the composite request payload.
ClaimCenter then gathers the response to each subrequest and subselection and returns them in a single response
payload. The responses to each subrequest and subselection appear in the same order as the original composite request.
Composite requests can make use of variables. This allows data created by the execution of one subrequest to be used
by later subrequests.
Composite requests can be submitted asynchronously. For more information, see “Asynchronous calls” on page 117.
Composite requests are limited to a maximum number of subrequests. For more information, see “Configuring the
maximum number of subrequests” on page 96.

Constructing composite requests

The /composite endpoint
To create a composite request, use the /composite endpoint in the Composite API. This is different than batches.
Every API has its own /batch endpoint. But in all of Cloud API, there is only one /composite endpoint, and it is in
the Composite API.
The syntax for the composite request call is:

POST <applicationURL>/rest/composite/v1/composite

Sections of a composite request

A composite request can have up to two sections:
• A requests section, which contains the subrequests that commit data.
• A selections section, which contains the subselections that query for data. These are executed after the
subrequests, and only if all the subrequests commit data successfully.

Composite requests 87
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

At a high level, the syntax for these sections is as follows:

{
"requests": [
{
<subrequest 1>
},
{
<subrequest 2>
},
...
],
"selections": [
{
<subselection 1>
},
{
<subselection 2>
},
...
]
}

The requests section

In the requests section, the only supported operations are POST, PATCH, and DELETE. This includes both POSTs that
create data and POSTs that execute business actions (such as POST /assign).
The basic syntax for the requests section is shown below.

{
"requests": [
{
"method": "<post/patch/delete>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
"<field1>": "<value1>",
"<field2>": "<value2>",
...
}
}
}
},
{
<next subrequest>
},
...
{
<final subrequest>
}
]
}

For example, the following simple composite request creates two notes for activity xc:202.

POST <applicationURL>/rest/composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/common/v1/activities/xc:202/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
},
{
"method": "post",
"uri": "/common/v1/activities/xc:202/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #2."
}
}
}
}

88 Composite requests
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

]
}

For the complete syntax that includes all composite request features, see “Complete composite request syntax” on page
97.

Using variables to share information across subrequests

Information from one subrequest can be used in later subrequests. You can do this through the use of composite
variables.

Declaring variables
Composite variables are declared in a subrequest's vars section. Each variable has a name and path. The name is an
arbitrary string. The path specifies what to set the variable to. It is set to a JSON path expression that identifies a value
in the subrequest's response payload.
For example, suppose a subrequest that creates an activity has the following:

"vars": [
{
"name": "newActivityId",
"path": "$.[Link]"
}
]

This creates a variable named newActivityId, which is set to the value of the data section's attributes section's id
field (which would typically be the id of the newly created activity).

Referencing variables
To reference a variable, use the following syntax:

${<varName>}

You can use variables anywhere in the body of a subrequest. The most common uses for variable values are:
• In an attributes field
• Within the path of a uri
• As part of a query parameter
For example, suppose there is a subrequest that creates an activity, and it is followed by a subrequest that creates a
note. The first subrequest creates a newActivityId variable as shown previously. The uri for the second subrequest is:

"uri": "/common/v1/activities/${newActivityId}/notes"

This would create the new note as a child of the first subrequest's activity.
The following is the complete code for the previous examples.

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/claims/cc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"vars": [
{
"name": "newActivityId",
"path": "$.[Link]"
}
]
},
{

Composite requests 89
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
}
]
}

Responses to the subrequests

The response to a composite request contains a responses section. This section contains one subresponse for each
subrequest. Every subresponse has three sections:
• A body section, which by default contains the default response data defined in the corresponding endpoint.
• A headers section, which contains any custom headers.
• A status field, which indicates the subresponse's status code.
For example, the following is the responses section and the first subresponse for a composite request whose first
subrequest created an activity:

"responses": [
{
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1",
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
},
...
},
"checksum": "0",
"links": {
"assign": {
"href": "/common/v1/activities/cc:403/assign",
"methods": [
"post"
]
},
...
}
}
},
"headers": {
"GW-Checksum": "0",
"Location": "/common/v1/activities/xc:403"
},
"status": 201
},

Fields whose values are generated when data is committed

The individual subresponses to each subrequest specify data that has technically not been committed yet. However,
some fields contain values that are not generated until the data is committed.
When a subresponse includes a value that is generated as part of the commit, Cloud API makes effort to match the data
that will be committed as closely as possible. For example, the composite request reserves id values so that these ids
can be provided in subresponses and committed to the database.
But, there are some fields for which Cloud API cannot match the value. For example, the values for createTime and
updateTime cannot be determined prior to the commit. Fields of this type are always omitted from a subrequest's
subresponse. But, they can be retrieved through a subselection.

90 Composite requests
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Suppressing subresponse details

In some cases, a given object may be modified by multiple subrequests. This makes the intermediate subresponses
unnecessary, and those subresponses can increase the size of the composite response unnecessarily and make the
composite response harder to parse.
You can simplify the composite response by suppressing the amount of information returned for one or more
subrequests. To do this, include the following with each relevant subrequest:

"includeResponse": false

For example:

{
"requests": [
{
"method": "post",
"uri": "/common/v1/activities/xc:202/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
},
"includeResponse": false
},
...

The composite response still includes a subresponse for the subrequest. But instead of providing the endpoint's default
response, the subresponse appears as:

{
"responseIncluded": false
},

The responseIncluded field defaults to true. If you want a detailed response for a given subrequest, simply omit the
responseIncluded reference.

Using query parameters in subrequests

For a POST or PATCH subrequest, you can also refine which fields are returned. To do this, use the fields query
parameter. The syntax for this is:

{
"requests": [
{
"method": "<post/patch>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
"<field1>": "<value1>",
"<field2>": "<value2>",
...
}
}
},
"parameters" : {
"fields" : "<value>"
}
},
...
]
}

For example, the following code snippet creates an activity. For the subresponse, it specifies to include only the
activity's id and the assigned user.

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/claims/cc:34/activities",
"body": {

Composite requests 91
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"parameters" : {
"fields" : "id,assignedUser"
}
},
...

For a given API, you can see a complete list of all query parameters that can be used in composite requests by
executing a GET /[Link] call. If a query parameter is available to composite requests, the OpenAPI output will
include the following line: "x-gw-allowForCompositeApi": true.

The selections section

The selections section contains subselections that query for data. These are executed after the subselections in the
requests section, and only if all the subrequests commit data successfully.
The basic syntax for the selections section is shown below. You do not need to specify a method for each subselection,
as the only valid method in the selections section is GET.

"selections": [
{
"uri": "<pathForFirstSubselection>"
},
{
"uri": "<pathForSecondSubselection>"
},
....
]

For example, the following code creates a new activity and a note for that activity. It then queries for the newly created
activity.

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/claims/cc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"vars": [
{
"name": "newActivityId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
}
],
"selections": [
{
"uri": "/common/v1/activities/${newActivityId}"
}
]
}

For the complete syntax that includes all composite request features, see “Complete composite request syntax” on page
97.

92 Composite requests
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Using query parameters in the selections section

You can use certain query parameters for each subselection. This includes:
• fields
• filter
• includeTotal
• pageOffset
• pageSize
• sort

Each subselection is independent from the others. You can use different query parameters for each subselection, and
you can have some subselections with query parameters and others without query parameters.
The syntax for adding query parameters to a subselection is as follows:

"selections": [
{
"uri": "<pathForFirstQuery>",
"parameters" : {
"fields" : "<value>",
"filter" : [<value>],
"includeTotal" : <value>,
"pageOffset" : <value>,
"pageSize" : <value>,
"sort" : [<value>]
}
},
....
]

Note the following:

• fields is specified as a single string of one or more fields, delimited by commas. The entire string is surrounded by
quotes.
◦ For example, "assignedUser,dueDate,priority,subject"
• filter and sort are stringified arrays consisting of one or more expressions. Each individual expression is
surrounded by quotes. The list of expressions is then surrounded by [ and ].
◦ For example: ["dueDate:gt:2022-12-20","status:in:open,complete"]
• includeTotal , pageOffset, and pageSize are either Boolean or integer values, and therefore do not use quotes.
For example, when querying for activities, to return only the assigned user, due date, priority and subject fields:

{
"uri": "/common/v1/activities",
"parameters" : {
"fields" : "assignedUser,dueDate,priority,subject"
}

To return only open and complete activities with due dates after 2022-12-20:

{
"uri": "/common/v1/activities",
"parameters" : {
"filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"] }

To return activities based on multiple criteria:

{
"uri": "/common/v1/activities",
"parameters" : {
"fields" : "assignedUser,dueDate,priority,subject",
"filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"],
"includeTotal" : true,
"pageSize" : 5,
"sort" : ["dueDate"]
}

Composite requests 93
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For a given API, you can see a complete list of all query parameters that can be used in composite requests by
executing a GET /[Link] call. If a query parameter is available to composite requests, the OpenAPI output will
include the following line: "x-gw-allowForCompositeApi": true.

Composite requests that execute only queries

You can create a composite request that does not create or modify data and instead only queries for data. To do this,
create a composite request with only a selections section and no requests section. In this case, the GETs in the
selections section are always executed.

Responses to the selections subrequests

When a composite request contains a selections section, the response also contains a selections section. This
section has the same structure as the responses section. It contains one subresponse for each subselection. Every
subresponse has three sections:
• A body section, which by default contains the default response data defined in the corresponding endpoint.
• A headers section, which contains any custom headers.
• A status field, which indicates the subresponse's status code.

Composite request limitations

Composite requests have the following general limitations:
• The number of subrequests and subselections in a single composite request must be less than or equal to the value
of the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. (In the base configuration, this
is set to 100.)
• The subrequests can make use of other endpoints that are part of Cloud API. However, they cannot make use of
endpoints outside of Cloud API, such as custom endpoints created by an insurer.
• You cannot use request inclusion in composite requests.
◦ For more information on request inclusion, see “Request inclusion” on page 99.
• You cannot include a subrequest that uses a content type other than application/json.
◦ For example, you cannot work with document resources in composite requests, as documents use multipart/
form-data.
• There is no mechanism for iterating over a set of things.
◦ For example, you cannot start with a list of elements and include related resources for each item in that list.
There may be some business requirements where you are required to use a composite request. For example, when
creating a new claim with an unverified policy, you must create the policy and claim in a composite request.
There are also specific business requirements where you cannot use a composite request. For example:
• You cannot have a single composite request operate on more than one claim.
• For service requests that are Quote Only, Quote and Service, or Service Only, you can create and submit a service
request in a single composite request. But you cannot advance these types of service requests to any other stage in
its life cycle (such as in progress, declined, or canceled at the vendor’s or insurer’s request) in the same composite
request.
• Within a composite request, the only financial object you can create or modify is final non-recurring check sets.
You otherwise cannot create or modify financial objects. This includes reserve sets and reserve transactions,
recurring check sets and payment transactions, and the check life cycle endpoints (such as POST /mark-issued).
However, within a composite request, you can GET information on financial objects.
Many of the examples in the previous list pertain to situations where there must be an intermediate data commit, which
composite requests do not allow by design. However, the previous list is not intended to be exhaustive. Refer to the
section of the documentation that discusses each business requirement for more information on requirements or
limitations related to composite requests.

94 Composite requests
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Composite request examples

This documentation includes examples of composite requests for common business tasks. This includes the following:
• Creating a new claim with an unverified policy: “Sample composite claim payload” on page 154
• Creating, closing, and paying out a claim: “Sample composite first-and-final” on page 160

Administering composite requests

Composite requests have special functionality for:
• Error handling
• Logging
• Configuration of the maximum number of subrequests

Error handling
If any of the subrequests in the requests section fail, Cloud API does the following:
• Does not commit any of the data
• Does not execute any GETs in the selections section
• Returns a 400 error
Cloud API also returns a response.
• The response begins with the following: "requestFailed": true. This is to make it easy to identify that the
composite request did not commit data.
• For the initial subrequests that did not fail (if any), the response is returned.
◦ This is either the response as specified by the associated endpoint (and any query parameters), or the
"responseIncluded": false text.
◦ The standard response can be useful for debugging purposes, as you can see the state of objects that succeeded
before the subrequest that failed.
• For the subrequest that failed, the error message is returned.
• For the subrequests after the failed subrequest, the text "skipped": true is returned.
• If a selections section was included, the text "skipped": true is returned for each subselection.
For example, the following is the response for a composite request with five subrequests and a set of queries. All
subrequests have responseIncluded set to false. The third subrequest failed because the dueDate attribute was
incorrectly spelled as ueDate.

{
"requestFailed": true,
"responses": [
{
"responseIncluded": false
},
{
"responseIncluded": false
},
{
"requestError": {
"details": [
{
"message": "Schema definition '[Link].v1.common_ext-
1.0#/definitions/Note' does not define any property
named 'ueDate'",
"properties": {
"lineNumber": 1,
"parameterLocation": "body",
"parameterName": "body"
}
}
],
"developerMessage": "The request parameters or body had issues.
See the details elements for exact details of the problems.",
"errorCode": "[Link]",
"status": 400,

Composite requests 95
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"userMessage": "The request parameters or body had issues"

},
"status": 400
},
{
"skipped": true
},
{
"skipped": true
}
],
"selections": [
{
"skipped": true
}
]
}

If there is an error in the selections section only, the subrequests in the requests section will execute, the data will
be committed, and the composite request will return with a 200 response code, indicating success. Cloud API also
attempts to execute each subselection as best as possible.

Logging
Cloud API logs information about composite requests at both the composite request level and the subrequest/
subselection level. This information appears in the logs under the CompositeSubRequest marker, which is a child of
the normal RestRequest marker.
Each subrequest and subselection log message details information for that subrequest/subselection, such as the actual
path, the HTTP method, and the apiFqn. The same log parameter names and conventions are used for both the parent
request logging and the subrequest logging, such as whether a given value is logged with an empty string or whether it
is omitted. However:
• Some parameters are always omitted at the subrequest level because they only make sense for the parent request.
• Some additional composite-specific parameters are added.
For example, suppose you executed the previous composite request example in which a composite request creates two
notes for activity xc:202. The corresponding log entries could appear as follows. Note that the first message is for the
parent request and the next two messages are for the two subrequests:

server-id-207 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13

14:40:30,803 INFO <RestService[ [Link] ]> Operation started
{path="/composite/v1/composite", from="[0:0:0:0:0:0:0:1]", method="POST",
query="", startTime=1227026673066900, message="", eventType="START",
serverID="server-id-207"}

server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13

14:40:30,894 INFO <CompositeSubRequest[ RestRequest ]> Operation status
{path="/common/v1/activities/xc:202/notes", query="", method="POST",
pathTemplate="/common/v1/activities/{activityId}/notes",
apiFqn="[Link].v1.common_ext-1.0", status=201, error="", userMessage="",
devMessage="", elapsedTimeMs=53, message="Composite API subrequest
succeeded", eventType="STATUS", serverID="server-id-207"}

server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13

14:40:30,899 INFO <CompositeSubRequest[ RestRequest ]> Operation status
{path="/common/v1/activities/xc:202/notes", query="", method="POST",
pathTemplate="/common/v1/activities/{activityId}/notes",
apiFqn="[Link].v1.common_ext-1.0", status=201, error="", userMessage="",
devMessage="", elapsedTimeMs=4, message="Composite API subrequest
succeeded", eventType="STATUS", serverID="server-id-207"}

Each subrequest or subselection always generates a log statement, whether the subrequest succeeded, failed, or was
skipped due to prior failures. A separate log statement is also added specifically for the commit of the composite
request, whether the composite request commit succeeded, failed, or was skipped.

Configuring the maximum number of subrequests

Composite requests are limited to a maximum number of subrequests and subselections. The maximum is specified by
the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. In the base configuration, this
parameter is set to 100. Composite requests with more than the maximum number fail with a BadInputException.
(The maximum applies to the sum of the number of subrequests and the number of subselections.)

96 Composite requests
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The greater the number of subrequests in a composite request, the greater the chances that there will be a compromise
in performance. A composite request with the maximum number of subrequests could result in a slow response,
depending on what the maximum is and what those subrequests are doing.
You can increase the maximum number of subrequests to a value greater than 100. However, composite requests with a
significantly large number of subrequests could have negative consequences, such as:
• The request consuming a significant amount of service resources. This could include both memory and database
resources.
• The request taking so long to complete that it times out before a response can be provided to the caller.
Consequently, Guidewire recommends setting the maximum number of subrequests to the lowest value that is needed.
If there is a legitimate business need to raise the maximum above 100, Guidewire recommends the limit be raised only
as much as is absolutely necessary.
Also, be aware that composite requests are subject to any application server limitations around the maximum size of a
request body. Thus, it is possible for a composite request to be too large to process, even if the number of subrequests is
at or below the allowed maximum.

Complete composite request syntax

The following is the complete syntax for a composite request:

{
"requests": [
{
"method": "<post/patch/delete>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
"<field1>": "<value1>",
"<field2>": "<value2>",
...
}
}
},
"parameters" : {
"fields" : "<value>"
},
"vars": [
{
"name": "<name>",
"path": "<path-starting-with-$>"
},
<next variable>,
...
],
"includeResponse": false
},
{
<next subrequest>
},
...
{
<final subrequest>
}
],
"selections": [
{
"uri": "<pathForFirstQuery>",
"parameters" : {
"fields" : "<value>",
"filter" : [<value>],
"includeTotal" : <value>,
"pageOffset" : <value>,
"pageSize" : <value>,
"sort" : [<value>]
}
},
{
<next subselection>
},
...
{
<final subselection>
}

Composite requests 97
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

]
}

98 Composite requests
chapter 10

Request inclusion

Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:
• A single parent request that creates or modifies a resource
• One or more child requests that create or modify resources related to the parent resource
If either the parent request or any child request fails, the entire request fails.
The parent resource is often referred to as the root resource. The root resource is specified in the payload's data
section. The related resources are specified in the payload's included section.
For example, a caller can use a single POST /claims to create a new claim, a set of ClaimContacts for that claim, a set
of incidents for that claim, and a set of exposures for that claim.
In order to use request inclusion, the following must be true:
• There must be a POST or PATCH endpoint for the root resource.
• This endpoint must have the child resource as part of its included section.
• There must also be a POST or PATCH endpoint for the child resource.
The syntax for request inclusion varies slightly, depending on whether the relationship between the root resource and
the included resource is a "simple parent/child relationship", or a "named relationship".

Syntax for simple parent/child relationships

In most cases, the relationship between the root resource and an included resource is a simple parent/child relationship.
Examples of this include:
• An activity and its notes
• A claim and its incidents
When using request inclusion for simple parent/child relationships, the JSON has the following structure:

{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"method": "post",

Request inclusion 99
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"uri": "/../this/..."
}
]
}
}

The data section

The data section includes information about the root resource, such as its attributes. (For PATCHes, the data
section could also include a checksum value for the root resource.)

The included section

The included section consists of one or more subsections of included resources. Each subsection starts with the
resource type name. Then, one or more resources of that type can be specified. For each resource, you must specify:
• The resource's attributes
• The method and uri to create or modify the resource.

The method and uri fields

Request inclusion involves a single call to a single endpoint. But internally, Cloud API uses multiple endpoints to
execute the call. For every included resource, you must specify the operation and uri relevant to that resource.
For example, suppose you are writing a POST /claims call to create a claim and a note. The note is the included
resource. The included section would contain code similar to this:

"included": {
"Note": [
{
"attributes": {
...
},
"method": "post",
"uri": "/claim/v1/claims/this/notes"
}
]
}

This specifies that in order to create the note, use the POST /claim/v1/claims/{claimId}/notes endpoint.
The uri must start with the API name, such as "/claim/v1".
The uri must also specify the id of the root resource. When the root resource and the included resources are being
created at the same time, the root resource does not yet have an id. Therefore, the keyword this is used in the uri to
represent the root resource's id.

Example of request inclusion for simple parent/child relationships

The following payload is an example of creating a claim and a note for the claim. The payload assumes there is an
existing policy whose number is "FNOL-POLICY". For more information on creating policies, see “Executing FNOL”
on page 129.

POST [Link]

{
"data" : {
"attributes": {
"lossDate": "2020-02-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY"
}
},
"included": {
"Note": [
{
"attributes": {
"subject": "Initial phone call",
"body": "Initial phone call with claimant"
},
"method": "post",
"uri": "/claim/v1/claims/this/notes"
}
]

100 Request inclusion

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

Syntax for named relationships

In some cases, the relationship between the root resource and an included resource is more than just a parent/child
relationship. It is a "named relationship" in which the relationship has a special designation or label.
For example, every claim has a "reporter". This is the ClaimContact who first reported the claim to the insurer. A claim
can have any number of child ClaimContacts, but only one of those ClaimContacts can be labeled as the reporter.
When using request inclusion for named relationships, the JSON has the following structure. The lines that are not
required for simple parent/child relationships but are required for named relationships appear in bold:

{
"data" : {
"attributes": {
"<relationshipField>": "<arbitraryRefId>"
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"refid": "<arbitraryRefId>",
"method": "post",
"uri": "/../this/..."
}
]
}
}

The data section

The data section includes information about the root resource, such as its attributes. (For PATCHes, the data
section could also include a checksum value for the root resource.)
The data section also includes the field that names the relationship with the child resource. This field is set to some
reference ID. The value of this reference ID is arbitrary. It can be any value, as long as the value also appears with the
child resource in the included section.

The included section

The included section consists of one or more subsections of included resources. Each subsection starts with the
resource type name. Then, one or more resources of that type can be specified. For each resource, you must specify:
• The resource's attributes
• The method and uri to create or modify the resource.

The refid field

Each included resource must include a refid field. This field must be set to the same arbitrary reference ID used in
the data section. The system APIs use refids to identify which child resource in the included section has the named
relationship with the root resource.

The method and uri fields

Request inclusion involves a single call to a single endpoint, but the system APIs internally use multiple endpoints to
execute the call. For every included resource, you must specify the operation and uri relevant to that resource.
For example, suppose you are writing a POST /claims call to create a claim and a ClaimContact who is the "reporter".
The ClaimContact is the included resource. The included section would contain code similar to this:

"included": {
"ClaimContact": [
{

Request inclusion 101

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"attributes": {
...
},
"refid": "...",
"method": "post",
"uri": "/claim/v1/claims/this/contacts"
}
]
}

This specifies that in order to create the ClaimContact, use the POST /claim/v1/claims/{claimId}/contacts
endpoint.
The uri must start with the API name, such as "/claim/v1".
The uri must specify the ID of the root resource. When the root resource and the included resources are being created at
the same time, the root resource does not yet have an ID. Therefore, the keyword this is used in the uri to represent
the root resource's ID.
The uri must specify the ID of the root resource. When the root resource and the included resources are being created at
the same time, the root resource does not yet have an ID. Therefore, the keyword this is used in the uri to represent
the root resource's ID.

Example of request inclusion for named relationships

The following payload is an example of creating a claim and a ClaimContact for the claim whose relationship is
"reporter". The payload assumes there is an existing policy whose number is "FNOL-POLICY". For more information
on creating policies, see “Executing FNOL” on page 129.

POST [Link]

{
"data" : {
"attributes": {
"lossDate": "2020-02-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY",
"reporter": {
"refid": "robertFarley"
}
}
},
"included": {
"ClaimContact": [
{
"attributes": {
"firstName": "Robert",
"lastName": "Farley",
"contactSubtype": "Person"
},
"refid": "robertFarley",
"method": "post",
"uri": "/claim/v1/claims/this/contacts"
}
]
}
}

Additional request inclusion behaviors

PATCHing and POSTing in a single request
When you execute a POST with request inclusion, the operation for each included resource must also be POST.
When you execute a PATCH with request inclusion, the operation for an included resource could be either POST or
PATCH.
• If you want to modify an existing resource and create a new related resource, the included resource's operation is
POST.
• If you want to modify an existing resource and modify an existing related resource, the included resource's
operation is PATCH.

102 Request inclusion

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Requests succeed or fail as a unit

When a POST or PATCH uses request inclusion, it is possible that there could be a failure either of the operation on the
root resource or the operation on any of the included resources. If any operation fails, the entire request fails and none
of the objects are POSTed or PATCHed.

Included resources cannot reference resources other than the root resource
When using request inclusion, each included resource must specify its own operation and uri. The uri is expected to
reference the root resource using the keyword this. This ensures that when the included resource is POSTed or
PATCHed, the included resource is related to the root resource.
For example, suppose a POST is creating a claim and a note. The uri for the exposure would have a value such as "/
claim/v1/claims/this/notes".

From a syntax perspective, you could attempt to attach an included resource not to the root resource, but rather to some
other existing resource. For example, instead of referencing the root resource, the uri for the note could reference an
existing claim, such as "/claim/v1/claims/cc:200/notes". This uri says "create a note and attach it not to the root
resource of this POST, but rather to the existing claim cc:200".
Cloud API will not allow this. Any attempt to POST or PATCH an included resource to something other than the root
resource will cause the operation to fail.

Request inclusion 103

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

104 Request inclusion

chapter 11

Batch requests

From a Cloud API perspective, a batch request is a set of requests that are executed in a non-transactional sequence.
Each call within the batch request is referred to as a subrequest. The object that contains all of the subrequests is
referred to as the main request.
Subrequests are executed serially, in the order they are specified in the request payload. ClaimCenter then gathers the
responses to each subrequest and returns them in a single response payload. Once again, the subresponses appear in the
same order as the corresponding subrequests.
When the response to a batch request contains a response code of 200, it means the batch request itself was well-
formed. However, each individual subrequest may have succeeded or failed.
Batch requests are limited to a maximum number of subrequests. The maximum is specified by the
MaximumAllowedNumberOfBatchSubRequests configuration parameter. In the base configuration, this parameter is set
to 100. Batch requests with more than the maximum number of subrequests fail with a BadInputException. For more
information on modifying the maximum number of subrequests, see “Configuring the maximum number of
subrequests” on page 109.

Batch request syntax

Batch request call syntax
The syntax for the batch request call is:

POST <applicationURL>/rest/<apiWithVersion>/batch

For example, if you were executing a Claim API batch from an instance of ClaimCenter on your local machine, the call
would be:

POST [Link]

Batch request payload syntax

The basic syntax for a batch request payload is:

{
"requests": [
{
"method": "<method>",
"path": "<path>",
"query": "<queryParameters>",
"data":
{

Batch requests 105

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"attributes": {
"<field1>": "<value1>",
"<field2>": "<value2>",
...
}
}
},
{
"method": "<method>",
"path": "<path>",
"query": "<queryParameters>",
"data":
{
"attributes": {
"<field1>": "<value1>",
"<field2>": "<value2>",
...
}
}
},
...
]
}

where:
• <method> is the method in lower case, such as "get", "post", "patch", or "delete".
• <path> is the endpoint path.
◦ This path starts as if it was immediately following the API path (including the major version, such as "/v1").
For example, suppose the path for a command when executed in isolation is: [Link]
rest/claim/v1/claims/cc:22/activities/cc:55. The path within a batch is: /claims/cc:22/
activities/cc:55
• <queryParmaters> is an optional string of query parameters. Start this string without an initial "?".
• <field1/<value> are the field and value pairs of the request body.
The following sections provide examples of how to use this syntax.

Optional subrequest attributes

A subrequest can optionally have query parameters that refine the corresponding subresponse payload.
By default, each subrequest inherits the information in the headers of the main request object. The one exception to this
is the GW-Checksum header. This header is not inherited because it is unlikely that a single checksum value will
correspond to multiple sub-requests. You can optionally specify header values for an individual subrequest, which will
override the corresponding values in the main request header.
If a subrequest fails, the default is to continue processing the remaining subrequests. For each subrequest, you can
optionally specify that if the subrequest fails, ClaimCenter must skip the remaining subrequests.
For a complete list of options and further information on how they work, refer to the batch_pl-[Link] file.

Batch request examples

The following topics provide examples of different types of batch requests.

Simple batch requests

The most simple batch request consist of default GET subrequests. This involves no query parameters and no request
payloads.
For this example, the response will consist of three subresponses. Each subresponse will consist of the default fields for
each claim.

{
"requests": [
{
"method": "get",
"path": "/claims/demo_sample:1"
},

106 Batch requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"method": "get",
"path": "/claims/demo_sample:2"
},
{
"method": "get",
"path": "/claims/demo_sample:3"
}
]
}

Batch requests with query parameters

The following is an example of a batch request with multiple GET subrequests. This example includes query
parameters for some of the GETs. As shown in the example, it is possible for some subrequests to use query parameters
while others do not. The subrequests that use query parameters can use different query parameters.
The response will consist of three subresponses. The fields in each subresponse will vary based on the query
parameters.

{
"requests": [
{
"method": "get",
"path": "/claims/demo_sample:1",
"query": "sort=lossDate"
},
{
"method": "get",
"path": "/claims/demo_sample:2",
"query": "fields=*all"
},
{
"method": "get",
"path": "/claims/demo_sample:3"
}
]
}

Batch requests with request payloads

The following is an example of a batch request with multiple POST subrequests. This example includes request
payloads for each subrequest.
In this example, two notes are POSTed to different activities. But it would also be possible to POST each note to the
same activity.

{
"requests": [
{
"method": "post",
"path": "/activities/xc:11/notes",
"data":
{
"attributes": {
"body": "Batch note 1"
}
}
},
{
"method": "post",
"path": "/activities/xc:73/notes",
"data":
{
"attributes": {
"body": "Batch note 2"
}
}
}
]
}

Batch requests 107

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Batch requests with distinct operations

Every subrequest in a batch request is distinct from the other subrequests. There is no requirement for any subrequest
to share any attribute with any other subrequest. Thus, the following is an example of a batch request with multiple
subrequests where each subrequest uses a different operation.

{
"requests": [
{
"method": "post",
"path": "/activities/xc:21/notes"
"body": {
"data": {
"attributes": {
"body": "Batch activity 1",
"subject": "Batch activity 1",
"topic": {
"code": "general",
"name": "General"
}
}
}
}
},
{
"method": "patch",
"path": "/notes/xc:22",
"body": {
"data": {
"attributes": {
"body": "PATCHed note body"
}
}
},
},
{
"method": "delete",
"path": "/notes/xc:23"
},
{
"method": "get",
"path": "/activities/xc:24/notes",
"query": "sort=subject&fields=id,subject"
}
]
}

Administering batch requests

Batch requests have special functionality for:
• Specifying subrequest headers
• Specifying behavior when a subrequest fails
• Configuration of the maximum number of subrequests

Specifying subrequest headers

The following is an example of a batch request where each subrequest has a header that overrides the main request
header.

{
"requests": [
{
"method": "delete",
"path": "/activities/xc:55",
"headers": [
{
"name": "GW-Checksum",
"value": "2"
}
]
},
{
"method": "delete",
"path": "/activities/xc:57",
"headers": [
{

108 Batch requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"name": "GW-Checksum",
"value": "4"
}
]
}
]
}

Specifying onFail behavior

The following is an example of a batch request that uses onFail to specify that if any of the subrequests fail, the
remaining subrequests need to be skipped.

{
"requests": [
{
"method": "patch",
"path": "/activities/xc:93",
"body": {
"data": {
"attributes": {
"subject": "PATCH body 1"
}
}
},
"onFail": "abort"
},
{
"method": "patch",
"path": "/activities/xc:94",
"body": {
"data": {
"attributes": {
"subject": "PATCH body 2"
}
}
},
"onFail": "abort"
},
{
"method": "patch",
"path": "/activities/xc:95",
"body": {
"data": {
"attributes": {
"subject": "PATCH body 3"
}
}
}
}
]
}

Configuring the maximum number of subrequests

Batch requests are limited to a maximum number of subrequests. The maximum is specified by the
MaximumAllowedNumberOfBatchSubRequests configuration parameter. In the base configuration, this parameter is set
to 100. Batch requests with more than the maximum number of subrequests fail with a BadInputException.
The greater the number of subrequests in a batch request, the greater the chances that there will be a compromise in
performance. A batch request with the maximum number of subrequests could result in a slow response, depending on
what the maximum is and what those subrequests are doing.
You can increase the maximum number of subrequests to a value greater than 100. However, batch requests with a
significantly large number of subrequests could have negative consequences, such as:
• The request consuming a significant amount of service resources. This could include both memory and database
resources.
• The request taking so long to complete that it times out before a response can be provided to the caller.
Consequently, Guidewire recommends setting the maximum number of subrequests to the lowest value that is needed.
If there is a legitimate business need to raise the maximum above 100, Guidewire recommends the limit be raised only
as much as is absolutely necessary.

Batch requests 109

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Also, be aware that batch requests are subject to any application server limitations around the maximum size of a
request body. Thus, it is possible for a batch request to be too large to process, even if the number of subrequests is at
or below the allowed maximum.

110 Batch requests

chapter 12

Lost updates and checksums

This topic defines lost updates and discusses how you can prevent them through the use of checksums.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: PATCH an activity using checksums” on page 113
• “Tutorial: Assign an activity using checksums” on page 114
• “Tutorial: DELETE a note using checksums” on page 115

Lost updates
Business processes often span multiple Cloud API calls. When this occurs, the first call is typically either a GET that
retrieves data or a POST that creates data. A later call may attempt to modify the resource queried for or created in the
initial GET or POST.
Some other process could modify the resource between the GET/POST and the subsequent attempt to modify it. For
example, suppose:
1. A caller application GETs activity xc:20. The activity's subject is "Contact additional insured" and the priority is
Normal.
2. An internal user manually changes the subject of activity xc:20 to "Contact primary insured" and sets the priority
to Urgent.
3. The caller application PATCHes activity xc:20 and sets the priority to Low.
The caller application's PATCH overwrites some of the changes made by the internal user. This could be a problem for
several reasons:
• The caller application's change may be based on the data it initially retrieved. The caller application may not have
initiated the change if it had known the subject or priority had later been changed by someone else.
• The internal user may not be aware that some of their changes were effectively discarded.
• The activity may now be in an inconsistent state (such as having a subject that is normally used for urgent activities
and a priority of Low).
This type of modification is referred to as a lost update. Within Cloud API, a lost update is a modification made to a
resource that unintentionally overwrites changes made by some other process. You can prevent lost updates through the
use of checksums.

Lost updates and checksums 111

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Checksums
A checksum is a string value that identifies the "version" of a particular resource. Cloud API calculates checksums as
needed based on information about the underlying entities in the ClaimCenter database.
When a process modifies data, either through user action, Cloud API, or some other process, Cloud API calculates a
different checksum for the resource. You can prevent lost updates by checking a resource's checksum before you
modify the resource to see if it matches a previously retrieved checksum.
By default, checksums are provided in the response payloads of all GETs, POSTs, and PATCHes.
Checksums can be included in:
• Request payloads, which is appropriate for:
◦ PATCHes
◦ Business action POSTs that allow request payloads (such as POST /{activityID}/assign)
• Request object headers for:
◦ DELETEs
◦ Business action POSTs that do not allow request payloads
When you submit a request with a checksum, ClaimCenter calculates the checksum and compares that value to the
submitted checksum value.
• If the values match, ClaimCenter determines the resource has not been changed since the caller application last
acquired the data. The request is executed.
• If the values do not match, ClaimCenter determines the resource has been changed since the caller application last
acquired the data. The request is not executed, and ClaimCenter returns an error similar to the following:
{
"message": "The supplied checksum '1' does not match the current checksum '2' for the resource with uri '/
common/v1/notes/xc:101'",
"properties": {
"uri": "/common/v1/notes/xc:101",
"currentChecksum": "2",
"suppliedChecksum": "1"
}
}

Generating checksums
Checksums are always string values generated by Guidewire based on all the values in the database for the associated
entity. Checksums are typically complex string values, such as c689ec1403a489ed7bc3ca6e8ce4f73e.
An resource's checksum is modified when any field in the associated entity changes, whether that field is exposed to
Cloud API or not. For example, the Activity entity has a field named EmailTemplate which stores the id of any email
template associated with the activity. This field is not exposed in Cloud API. However, if this field is changed for a
given activity, either through the user interface or by some other process, this will increment the Activity resource's
checksum.
In some cases, checksums are set to simple integer values, such as 1, and a change to the entity simply increments the
integer value by 1. However, when a checksum is an integer, there is no guarantee that the next checksum will be the
integer value incremented by one. Guidewire recommends against caller applications attempting to predict what the
next checksum value will be. Limit checksums in Cloud API requests to only the checksums returned in previous
responses.

Resources that map to multiple data model entities

Most resources correspond to a single data model entity. For example, the properties in the Activity resource map to a
single data model entity - the Activity data model entity.
However, there are resources that combine fields from multiple data model entities. For example, the User resource has
fields that map to the User data model entity (such as externalUser), the Credential data model entity (such as
username), and the UserContact data mode entity (such as cellphone).

112 Lost updates and checksums

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

In the base configuration, when a resource maps to multiple data model entities, a change to any one of the underlying
entities increments the resource's checksum. Custom resources that map to multiple data model entities can also be
configured to have the checksum reflect changes to any of the underlying data model entities. For more information,
see the Cloud API Developer Guide.

Checksums for PATCHes and business action POSTs

For operations that have a request payload, checksums can be specified in the request payload. This applies to
PATCHes and to most POSTs that execute business actions. (If a business action POST does not allow a request
payload, you can still specify a checksum. But, you must do this in the request header. For more information, see
“Checksums for DELETEs” on page 115.)
The checksum property is a child of the data property and a sibling of the attributes property. It uses the following
syntax:

"checksum": "<value>"

For example, the following payload is for a PATCH to an activity. The payload specifies a new attribute value (setting
priority to urgent) and a checksum value (7a0d9677f11e246bbe3c124889219c50).

{
"data": {
"attributes": {
"priority": {
"code": "urgent"
}
},
"checksum": "7a0d9677f11e246bbe3c124889219c50"
}
}

Checksums can be specified on the root resource and on any included resource. Specifying a checksum for any one
resource does not require you to specify checksums for the others. For example:
• You could specify a checksum for only the root resource.
• You could specify a checksum for only one of the included resources.
• You could specify a checksum for the root resource and some of the included resources, but not all of the included
resources.

Tutorial: PATCH an activity using checksums

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” on page 29.
In this tutorial, you will attempt to PATCH an activity twice. Both PATCHes will include a checksum value. The first
PATCH will succeed, and the second will fail.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Get police report" activity, which can be PATCHed because it is an open activity
on an open claim. Query for that activity by entering the following call and clicking Send:
a. GET [Link]
%20report
3. Note the ID, subject, and checksum of the first activity returned in the response payload. (These values are
referred to in later steps as "<ActivityID>", "<originalSubject>", and "<originalChecksum>".)
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
a. PATCH [Link]

Lost updates and checksums 113

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

6. Specify the request payload.

a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons. For subject, specify the original subject
with an additional "-1".
{
"data": {
"attributes": {
"subject" : "<originalSubject>-1"
},
"checksum": "<originalChecksum>"
}
}

7. Click Send. The checksum value in the payload matches the checksum value for the activity stored in
ClaimCenter. So, the PATCH should be successful and the response payload should appear below the request
payload.
8. Click Send a second time. Now, the checksum value in the payload does not match the checksum value for the
activity calculated by ClaimCenter. So, the second PATCH is unsuccessful and an error message appears.

Tutorial: Assign an activity using checksums

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” on page 29.
In this tutorial, you will attempt to execute a business action (assigning an activity) twice. Both attempts will include a
checksum value. The first attempt will succeed, and the second will fail.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Get police report" activity, which can be PATCHed because it is an open activity
on an open claim. Query for that activity by entering the following call and clicking Send:
a. GET [Link]
%20report
3. Note the ID and checksum of the first activity returned in the response payload. (These values are referred to in
later steps as "<ActivityID>", and "<originalChecksum>".)
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST [Link]
6. The POST /{activityId}/assign endpoint requires a request payload that specifies how the assignment is to
be done. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons. For subject, specify the original subject
with an additional "-1".
{
"data": {
"attributes": {
"autoAssign": true
},
"checksum": "<originalChecksum>"
}
}

114 Lost updates and checksums

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

7. Click Send. The checksum value in the payload matches the checksum value for the activity stored in
ClaimCenter. So, the POST /assign should be successful and the response payload should appear below the
request payload.
8. Click Send a second time. Now, the checksum value in the payload does not match the checksum value for the
activity calculated by ClaimCenter. (The successful POST /assign from the previous step will have modified the
checksum value.) So, the second POST /assign is unsuccessful and an error message appears.

Checksums for DELETEs

For operations that do not permit a request payload, checksums can be specified in the request header. This applies to
DELETEs and a small number of business action POSTs that do not permit request payloads.
The header key for a checksum is GW-Checksum. A checksum specified in the header applies only to the root resource.

Send a checksum in a request header using Postman

About this task
You can send checksums in request headers executed from Postman.

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify authorization as appropriate.
3. Add the checksum to the header.
• In the first row of tabs (the one that starts with Params), click Headers.
• Scroll to the bottom of the existing key/value list.
• In the blank row at the bottom of the key/value list, enter the following:
◦ KEY: GW-Checksum
◦ VALUE: <checksum value>
4. Enter the request operation and URL.
5. Click Send.

Results
The response appears below the request. Depending on the checksum value provided, the response will either include a
success code or an error message.

Tutorial: DELETE a note using checksums

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” on page 29.
In this tutorial, you will send calls as Elizabeth Lee (user name elee). In the base configuration, Elizabeth Lee is a
manager who has permission to delete notes. As Elizabeth Lee, you will create a note. You will then attempt to
DELETE the note twice. Both DELETEs will include a checksum value. The first DELETE will fail, and the second
will succeed.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following call and click Send:
GET [Link]
3. Identify the id of the first activity in the payload. This value is referenced below as <activityId>.

Lost updates and checksums 115

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab tab.
a. On the Authorization tab, select Basic Auth using user elee and password gw.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST [Link]
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted with a checksum"
}
}
}

7. Click Send. In the response payload, identify the note's id.

8. Open a third request tab and right-clicking the second tab and selecting Duplicate Tab tab.
a. Because it is a duplicate of the second tab, this tab also uses user elee.
9. Change the operation to DELETE, enter the following URL, but do not click Send yet:
a. DELETE [Link]
10. DELETEs cannot specifies request bodies. On the third tab, navigate to the Body tab and select the none radio
button.
11. Add the checksum to the header
a. In the first row of tabs (the one that starts with Params), click Headers.
b. Scroll to the bottom of the existing key/value list.
c. In the blank row at the bottom of the key/value list, enter the following:
• KEY: GW-Checksum
• VALUE: 99
12. Click Send. The checksum value in the header does not match the checksum value for the note calculated by
ClaimCenter. So, the DELETE is unsuccessful and an error message appears.
13. Change the checksum value so that it matches the one from the POST payload.
14. Click Send a second time. Now, the checksum value in the header matches the checksum value for the note
calculated by ClaimCenter. So, the DELETE is successful. (The response to a successful DELETE is "204 - No
content".)

116 Lost updates and checksums

chapter 13

Asynchronous calls

REST calls made to Cloud API are typically synchronous. The caller application submits a call and then waits for the
reply. However, for some types of calls, waiting for a reply may be problematic. For example:
• The call may take long enough to process that the API Gateway times out.
• The call may take long enough to process that the client-side toolkit used to make the call times out.
• A synchronous call may consume too many client-side resources.
To address these situations, calls can also be made asynchronously. The caller application submits the request at one
point in time. At a later point in time, the caller application retrieves the response.
This topic discusses how to execute Cloud API calls asynchronously.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: Send a request asynchronously” on page 122
• “Tutorial: Retrieve information about an asynchronous request” on page 124
• “Tutorial: Send a request asynchronously with a wait time” on page 125

Overview of asynchronous calls

Synchronous calls
By default, calls made to Cloud API are synchronous. The caller application submits the request and waits for a
response. This is depicted in the following diagram.

1. The caller application sends a request to Cloud API. In the diagram, the request is a POST for a resource named
someResource. The request has a set of request headers and may have a payload.
Asynchronous calls 117
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

2. Cloud API processes the request synchronously.

3. Assuming the request is successful, Cloud API provides the response. The response also has a set of response
headers and may have a payload.

Asynchronous calls
For some calls, it can be problematic to wait for a synchronous response. For example, quoting a large commercial
policy may take several minutes, and the API Gateway may time out before the quote can be completed and returned to
the caller.
To address these situations, you can execute a Cloud API call asynchronously. Broadly speaking, there are three phases
to an asynchronous call. In practice, this could occur with fewer than or more than three calls.

Submitting the call

For an asynchronous call, the request is almost identical to a synchronous call. The only difference is that the request
object includes an additional Prefer request header indicating the desire for an asynchronous response.
If the call is well-formed, Cloud API provides an initial response.
• The status of the response is "202 Accepted", indicating that the request has been accepted.
• The response body is empty.
• The response includes a GW-Async-Location header. The header's value is a path for an Async API endpoint that
the caller can use to retrieve information about the original request.
This is depicted in the following diagram.

1. The caller application sends a request to Cloud API. The request object includes a request header indicating to
process the call asynchronously.
2. Cloud API accepts the request. But it does not immediately process it.
3. Cloud API provides a response. The response includes a header with an Async API /requests path that can be
used to retrieve:
a. Information about the initial request.
b. The response to the initial request, once it is available.

Determining when the call has been processed

After the call has been submitted, the caller application uses the Async API /requests path from the initial response to
retrieve information about the original request. This path takes the form of /async/v1/requests/<asyncRequestId>.
The response to the /requests call always includes the following information:

118 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The requestMethod and requestPath of the original request

• The status of the original request, which can be set to:
◦ Accepted - The request is still waiting to be processed.
◦ InProgress - The request is being processed, but processing is not yet complete.
◦ Complete - The request has been processed.
• The startTime of the original request
If the original request has been completed, then the following information is also included:
• The completionTime of the original request
• The responseStatus and responseHeaders
• If the response's format is application/json, then the response itself is included in the responseBodyJson field

Example response for a call that has not been completed

The following is a portion of the /requests response for a asynchronous call that has not yet been completed.

{
"data": {
"attributes": {
"requestMethod": "POST",
"requestPath": "/admin/v1/users",
"responseStatus": 202,
"startTime": "2022-07-12T16:53:12.365Z",
"status": {
"code": "Accepted",
"name": "Accepted"
}
}
}
}

Example response for a call that is complete

The following is a portion of the /requests response for a asynchronous call that is complete.

{
"data": {
"attributes": {
"completionTime": "2022-07-12T16:53:16.073Z",
"requestMethod": "POST",
"requestPath": "/admin/v1/users",
"responseBodyJson": {
"data": {
"attributes": {
...
"username": "asyncUser99",
"vacationStatus": {
"code": "atwork",
"name": "At work"
}
},
"checksum": "321dff263827cbbd772c26676398d8ae",
"links": {
...
}
}
},
"responseHeaders": {
"Cache-Control": [
"must-revalidate",
"post-check=0",
"pre-check=0",
"max-age=0",
"no-store",
"no-cache"
],
"Content-Type": [
"application/json;charset=UTF-8"
],
"GW-Checksum": [
"321dff263827cbbd772c26676398d8ae"
],
"Location": [
"/admin/v1/users/pc:ScaA3kB5cImBkuh7bxjNn"
],
"X-Correlation-ID": [
"d516344d-5769-4964-adb7-79eaca41e4a2"

Asynchronous calls 119

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

],
...
},
"responseStatus": 201,
"startTime": "2022-07-12T16:53:12.365Z",
"status": {
"code": "Complete",
"name": "Complete"
}
}
...
}
}

Polling until the original request is complete

The caller application can poll Cloud API periodically until it receives a response whose status is Complete. This is
depicted in the following diagram.

1. The caller application sends a GET /async/v1/requests/{asyncRequestId} request to Cloud API. The path
comes from the header of the initial response.
2. The Cloud API response includes information about the original request. If the status is Accepted or In Progress,
the caller application must re-submit the GET after an appropriate interval.
When the response includes a status of Complete, the caller can retrieve the response to the original request. There are
multiple ways that it can be retrieved.

Retrieving the response using /requests/{asyncRequestId}

The /requests endpoint returns an AsyncRequest resource. This resource includes a responseBodyJson attribute. If
the original request has a status of Complete, and if the response's type is application/json, then this attribute
contains the response payload for the initial request.
This is depicted in the following diagram.

120 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

4. The caller application sends a GET /async/v1/requests/{asyncRequestId} request to Cloud API. The
acyncRequestId comes from the header of the initial response.

5. The Cloud API response includes information about the original request. When the status is Complete, the response
includes the original request's response if the response type is application/json.
Note that the GET /async/v1/requests/{asyncRequestId} request could return a response of Complete the first
time it is submitted or on a subsequent try.

Retrieving the response from /requests/{asyncRequestId}/response

There is also a /requests/{asyncRequestId}/response endpoint. For completed requests, this endpoint returns the
original response as if the call had been executed synchronously. This endpoint is useful when:
• The response type is something other than application/json, and therefore is not included in the GET /
async/v1/requests/{asyncRequestId} response.
• The caller application wants the work with the response as it would normally appear, as opposed to having to
extract it from within the responseBodyJson attribute of a larger data envelope.
This is depicted in the following diagram.

6. The caller application sends a GET /async/v1/requests/{asyncRequestId}/response request to Cloud API.

7. The Cloud API response includes the original response, as if the request had been executed synchronously.
When the original call is complete, the response to GET /async/v1/requests/{asyncRequestId}/response has the
same status code, response body (if any), and response headers as if the caller were getting a synchronous response to
the original request.
For example, if the original request was a POST that created a new activity, the GET request to retrieve the response
might return a 201 response code and have a Location header. If the original request failed because of a validation
error, the GET request to retrieve the response might have a 400 status code and a response body with details of the
errors.

Sending a request asynchronously

To send a request asynchronously, include the following header with the request:
• Key: Prefer
• Value: respond-async
The caller application can also specify an amount of time it is willing to wait for a response. If the call can be
processed within the specified time, Cloud API returns the results as if the call had been executed synchronously. For
more information, see “Waiting for a response synchronously” on page 124.

Asynchronous calls 121

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Validating the call

If no wait time has been specified, Cloud API executes some validation before accepting the call. This includes the
following:
• Verifying the path is valid
• Verifying the input is well-formed with respect to the schema
• Verifying the user is authenticated
If any of these validations fail, then the response to the call will be an error.
It is possible for the initial call to get a "202 Accepted" response, even when it has a validation error. This can happen
in the following situations:
• The call has a validation error other than one of the reasons in the previous list. For example, the call could by
trying to create a group and the id for the supervisor does not map to any user.
• The server waits a maximum of 5 seconds for the validation to be completed. If the server is under heavy load and
the asynchronous request is queued, or if the validation takes an unusually long time, the server returns a 202
Accepted response without completing the validation.

Response to the call

In most cases, if the call passes initial validation, Cloud API returns the following:
• A "202 Accepted" response.
• A response object with an empty body and a set of response headers, including a GW-Async-Location header.
The GW-Async-Location header contains the Async API /requests path that the caller application must use to
determine the status of the original call (such as whether the call has been processed) and to access the results. The
value for this header uses the following syntax:

/async/v1/requests/<asyncRequestId>

The <asyncRequestId> is a random value that provides secure access to the results of the original call. Because this
value provides access to application data, Guidewire recommends keeping it secure.
There are some situations where the response will not be "202 Accepted":
• If the wait preference is used and the request completes faster than the requested wait time, the response will be
synchronous. For information on specifying a wait preference, see “Waiting for a response synchronously” on page
124.
• If the application is overloaded and unable to process or queue the request, it will return a 503 response.

Tutorial: Send a request asynchronously

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” on page 29.
In this tutorial, you will submit a request asynchronously to create a new user. (The work needed to create a user is
minimal, and one would not normally need to execute this type of request asynchronously. User is used here to
simplify the tutorial. User requires no parent entity, has only one required field, and has the same behavior across all
InsuranceSuite applications.)

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user su and password gw.
2. Enter the following call, but do not click Send yet:
a. POST [Link]
3. Specify the request payload.

122 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data": {
"attributes": {
"username": "asyncUser"
}
}
}

4. Add the asynchronous request to the header.

a. In the first row of tabs, click Headers.
b. Scroll to the bottom of the existing key/value list.
c. In the blank row at the bottom of the key/value list, enter the following:
i. KEY: Prefer
ii. VALUE: respond-async
5. Click Send.

Results
The response should be "202 Accepted". To view the value for GW-Async-Location header, click the Headers tab in
the response object pane. (This Headers tab is in a row of tabs that starts with Body and Cookies.) This value is used in
the next tutorial.

Retrieving the response to the original request

There are multiple ways to retrieve the response to the initial request.

Response information in the /requests response

The response to the initial call includes a GW-Async-Location header. This header uses the following syntax:

/async/v1/requests/<asyncRequestId>

You can execute a GET on this endpoint to retrieve information about the original request.

The response status

The response includes a status field, which has one of the following values:
• Accepted - The request is still waiting to be processed.
• In Progress - The request is being processed, but processing is not yet complete.
• Complete - The request has been processed.
The response also includes a responseBodyJson attribute. If the original request has been processed and if the original
request's response type is application/json, then the responseBodyJson attribute contains the response payload for
the initial request.

Response information using the /response endpoint

There is also a /requests/{asyncRequestId}/response endpoint. Calls to this endpoint use the following syntax:

/async/v1/requests/<asyncRequestId>/response

If the original request is complete, this endpoint returns the response to the original request as if the call had been
executed synchronously. This endpoint is useful when:

Asynchronous calls 123

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The response type is something other than application/json, and therefore is not included in the /requests
response.
• The caller application wants to work with the response as it would normally appear, as opposed to having to extract
it from within the responseBodyJson attribute of a larger data envelope.
Note that there are two situations in which this endpoint could return a 400 error:
• The original request does not yet have a status of Complete. Its status is either still Accepted or In Progress.
• The original request has a status of Complete, and the response to the original request is a 400 error.

Tutorial: Retrieve information about an asynchronous request

This tutorial assumes you have submitted an asynchronous request to create a user and you have the GW-Async-
Location value from the response. For more information, see “Tutorial: Send a request asynchronously” on page 122.

In this tutorial, you will retrieve information about the asynchronous request using both the /requests and /response
endpoints.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab
a. On the Authorization tab, select Basic Auth using user su and password gw.
2. Enter the following call, but do not click Send yet:
a. GET [Link] where <Async-Location> is the value of
the GW-Async-Location response header from the initial asynchronous request.
3. Ensure that, for this request, you do not have Prefer/respond-async header specified in your request.
(Although you can submit the /requests call asynchronously, you typically would not want to.)
4. Click Send.
5. Send a second request that uses the /response endpoint to retrieve only the response.
a. Right-click the current tab and choose Duplicate Tab.
b. In the new tab, add "/response" to the end of the existing URL.
6. Click Send.

Results
On the first tab, the response object contains information about the response to the original request. Typically, user
creation occurs very rapidly, and the original request should already be processed. If so:
• The completionTime is specified.
• The responseBodyJson attribute contains the response to the original request. In this case, it is information about
the newly created user.
• The responseStatus is 201.
• The status has a code of Complete.
On the second tab, the response object contains the same information that would have been returned if the initial
request were submitted synchronously.

Waiting for a response synchronously

When sending an asynchronous call, a caller application can specify an amount of time it is willing to wait for a
response.
• If the call can be processed within the specified time, Cloud API returns the results as if the call had been executed
synchronously.
• If the call cannot be processed within the specified time, Cloud API returns a "202 Accepted" response and a GW-
Async-Location header. As is the case with regular asynchronous calls, the caller application must retrieve the
results with a second call

124 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

You can specify the wait time in seconds or milliseconds.

Specifying wait time in seconds

To specify a wait time in seconds, specify the asynchronous header as:
• KEY: Prefer
• VALUE: respond-async, wait=T
where T is the number of seconds the caller application is willing to wait.

Specifying wait time in milliseconds

To specify a wait time in milliseconds, specify the asynchronous header as:
• KEY: Prefer
• VALUE: respond-async, wait-ms=T
where T is the number of milliseconds the caller application is willing to wait.

Specifying a 0 wait time

You can force a call to always execute asynchronously and without any initial validation. To do this, specify wait=0 or
wait-ms=0.

Tutorial: Send a request asynchronously with a wait time

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” on page 29.
In this tutorial, you will submit two requests asynchronously to create a new user. Both will specify a wait time.

Tutorial steps
1. In Postman, start a new request by:
a. Clicking the + to the right of the Launchpad tab
b. Specifying Basic Auth authorization using user su and password gw.
2. Enter the following call, but do not click Send yet:
a. POST [Link]
3. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data": {
"attributes": {
"username": "asyncUserNoWait"
}
}
}

4. Add the asynchronous request to the header.

a. In the first row of tabs, click Headers.
b. Scroll to the bottom of the existing key/value list.
c. In the blank row at the bottom of the key/value list, enter the following:
i. KEY: Prefer
ii. VALUE: respond-async, wait=1
5. Create a second tab by duplicating the first tab. To do this, right-click the tab and select Duplicate Tab.

Asynchronous calls 125

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

6. Modify the second tab so that it executes with a wait time.

a. In the request body, change the username value to asyncUserWithWait.
b. Change the Prefer header so its wait time is "wait-ms=1" instead of "wait=1":
i. KEY: Prefer
ii. VALUE: respond-async, wait-ms=1
7. On both tabs, click Send.

Results
The first tab executes an asynchronous call with a wait time of 1 second. The application is able to complete the call
within this time, so the response is provided. (The status is "201 Created" and the response to the original call is
provided.)
The second tab executes an asynchronous call with a wait time of 1 millisecond. The application is not able to
complete the call within this time, so the call is merely accepted. (The status is "202 Accepted" and the response body
is blank.)

Asynchronous request administration

Performance considerations
The architecture for asynchronous requests is designed to support a large number of asynchronous requests on a daily
basis. However, it is not designed to support every request being executed asynchronously. Guidewire recommends that
you execute calls asynchronously only when necessary.

The AsyncApiRequest data model entity

Information about asynchronous Cloud API requests are stored in the AsyncApiRequest entity. You cannot extend this
entity.

The PurgeAsyncAPIRequests batch process

The PurgeAsyncAPIRequests batch process removes information about asynchronous Cloud API requests from the
AsyncAPIRequest database table that are more than X days old. In the base configuration:

• The value of X is 7.
• The batch process is scheduled to run once a day at 3:30 am.
You can configure the value of X by manually adding an AsynchApiRequestPurgeDaysOld configuration parameter to
[Link]. For example, if you wanted request information to be purged when it is 6 days old, you would add the
following to [Link]:

<param name="AsyncApiRequestPurgeDaysOld" value="6"/>

You can also configure when the batch process is scheduled to run. For more information, see the Administration
Guide.

Limitations on user session access

If a particular endpoint requires a session, or tries to create one, it cannot be used with the async header. The Cloud
API endpoints never do this. This limitation applies only to a custom endpoint an insurer has built on the REST API
Framework.
Any code that optionally looks at the user’s session to see if it is there will find that it is null when the request is made
asynchronously.

126 Asynchronous calls

part 3

Business flows: FNOL and adjudication

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in ClaimCenter so that caller
applications can request data from or initiate action within ClaimCenter.
The following topics discuss how caller applications can initiate specific ClaimCenter business flows related to FNOL
and adjudication. This includes:
• Executing FNOL
• Working with existing claims
• Working with ClaimContacts
• Working with incidents
• Working with exposures
• Working with service requests
Business flows related to ClaimCenter financials are covered in a separate section of this document.

Business flows: FNOL and adjudication 127

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

128 Business flows: FNOL and adjudication

chapter 14

Executing FNOL

This topic describes how to create claims for FNOL (First Notice of Loss) through Cloud API. This topic assumes you
are familiar with the ClaimCenter FNOL process. For a more detailed discussion of that process, see the Application
Guide.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: Creating a policy using the Test Util API” on page 137
• “Tutorial: POSTing a minimal draft claim for personal auto” on page 138
• “Tutorial: PATCHing a draft claim for personal auto” on page 139
• “Tutorial: POSTing a typical draft claim for personal auto” on page 140
• “Tutorial: Submitting a draft claim” on page 150
For sample FNOL payloads, see the “Sample payload addendum” on page 151.

The FNOL process in ClaimCenter

FNOL (First Notice of Loss) is the event in which the insurer is informed of a potentially covered loss.
The following section provides an overview of FNOL behavior in ClaimCenter.

Draft claims and open claims

During the FNOL process, the claim is first created. The claim passes through two states: draft and open.
• A draft claim is a claim that has been saved to the ClaimCenter database, but there is not yet enough information
for the claim to enter the adjudication process. Draft claims are not assigned to any user.
• An open claim is a claim that has been saved to the ClaimCenter database with enough information to enter the
adjudication process. Once a claim becomes open, it is assigned to an adjuster. (Open claims are often referred to
simply as "claims".)
During the FNOL process, a claim can have two different claim numbers: a draft claim number and an open claim
number.
• Draft claim numbers are assigned when the draft is initially saved. In the base configuration, draft claim numbers
typically start with "999".
• Open claim numbers are assigned when the claim moves from draft to open. In the base configuration, open claim
numbers typically start with "000".

Executing FNOL 129

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

All open claims initially start as draft claims, regardless of how they are created. However, the New Claim Wizard hides
most of the distinction between draft and open claims. For example, in the base configuration, draft claim numbers are
not shown in the New Claim Wizard during claim creation.
Prior to finishing a draft claim in the New Claim Wizard, you can cancel the draft claim by clicking the Cancel button.
This discards the claim information from the database. This action can be taken only on draft claims. Once the New
Claim Wizard is finished, the claim cannot be canceled.

Verified and unverified policies

When a claim is created, ClaimCenter creates a copy of the relevant policy and attaches it to the claim. This can be
either a verified policy or an unverified policy.

Verified policies
A verified policy is a copy of the policy based on information retrieved from the Policy Administration System (PAS).
In a production system, verified policies are the most common types of policies.
Every claim has its own copy of the policy. If two claims are created from the same policy, they will each have their
own copy.
Verified policies can be used in either a test or production system. However, they require a PAS (or test PAS) and an
integration point to that PAS.

Unverified policies
An unverified policy is a policy that is created during the FNOL process based on information supplied by an adjuster
or by the caller application. This information may or may not correctly correspond to information in a PAS. Unverified
policies let adjusters start the FNOL process without information from the PAS. This could be necessary if the reporter
does not know or cannot recall enough information to find the policy.
Eventually, the unverified policy must be refreshed with data from the PAS, thereby converting it to a verified policy.
You cannot complete the claims process and make payments on a claim while the policy is still unverified.
Unverified policies can be used in either a test or production system. In a test system, unverified policies may be a
useful way to create policies without having an integration point to a PAS and without needing to enable the Test Util
API.

The FNOL process in Cloud API

FNOL can be accomplished entirely through Cloud API. The following section provides an overview of the FNOL
process when it is executed through Cloud API.

The Cloud API FNOL process

The following diagram illustrates the FNOL process as executed through Cloud API:

130 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Prior to making any Cloud API call to ClaimCenter:

1. The caller application queries the Policy Administration System for information on the relevant policy and its
contacts, covered items, and coverages.
To execute the FNOL process with ClaimCenter:
2A. The caller application executes a POST /claims with a payload that describes the claim. If the call is successful,
ClaimCenter saves a draft claim to the database with a draft claim number. The response object returned to the caller
application includes the claim's id and its draft claim number.
2B. During the creation of the draft claim, ClaimCenter retrieves information about the policy from the PAS and copies
it into the ClaimCenter policy graph.
3. Optionally, the caller application can execute a PATCH /claims/{claimID} one or more times. This may be
appropriate when you want to create a draft claim before you have all of the information needed to submit it, and you
later want to update that claim with additional information.
4A. The caller application executes a POST /claims/{claimId}/submit. If the call is successful, ClaimCenter
promotes the claim to being open and assigns it an open claim number. The response object returned to the caller
application includes the open claim number.
4B. As part of the process to promote the claim, ClaimCenter executes the automated claim setup rules. These rules can
segment the claim, assign the claim, and create and assign activities for the claim.
The entire process always consists of at least two Cloud API calls to ClaimCenter:
• A POST /claims that creates a draft claim
• A POST /submit that submits the claim and promotes it to being open.

FNOL use cases by policy state

You cannot create a claim without a policy, and every policy belongs uniquely to one claim. (If two of more claims are
based on the same policy, each has its own copy of the policy.)

Executing FNOL 131

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

There are three use cases for how FNOL can be executed through Cloud API. Each use case involves policies in a
different state.

Claims with Test Util API policies

The Test Util API is an API that provides functionality to facilitate testing during development. You can use the Test
Util API to create and test policies. Test Util API policies are appropriate for development environments that are not
connected to a PAS.
You cannot PATCH a Test Util API policy. Because the policy reflects test data, the expectation is that it is created
correctly in the initial POST.
To create an open claim with a Test Util API policy, you must execute the following calls:
1. POST /test-util/v1/policies to create the test policy.
2. POST /claims/v1/claim to create the draft claim.
3. POST /claims/v1/{claimId}/submit to submit the draft claim, thereby converting it to an open claim.

Claims with verified policies

You can create claims with verified policies. This approach requires an environment connected to a PAS.
There is current no endpoint to PATCH a verified policy.
To create an open claim with a verified policy, you must execute the following calls:
1. POST /claims/v1/claim to create the draft claim. The policy is automatically copied over from the PAS as part
of the processing of this call.
2. POST /claims/v1/{claimId}/submit to submit the draft claim, thereby converting it to an open claim.
Note: In ClaimCenter, the New Claim Wizard permits the creation of a claim using a verified policy that is not
in effect as of the claim's loss date. This type of claim cannot reach the end of the adjudication process unless
the coverage is somehow verified. But, it can be created. In contrast, Cloud API does not permit the creation of
claims using a verified policy if the policy is not in force as of the claim's loss date.

Claims with unverified policies

You can create claims with unverified policies. This approach can be done in either a test or production system. The
policy is based on information provided by the call, so it does not require an environment connected to a PAS.
However, you typically cannot make payments on a claim while the claim's policy is still unverified.
You can PATCH an unverified policy. However, there is currently no endpoint to refresh an unverified policy, which is
the action that converts an unverified policy into a verified policy.
Claims with unverified policies can only be created in a composite request. Thus, to create an open claim with a
unverified policy, you must execute the following call:
1. POST /composite/v1/composite to create a composite request with the following subrequests:
a. POST /claim/v1/unverified-policies to create an unverified policy.
b. POST /claims/v1/claim to create the draft claim.
c. POST /claims/v1/{claimId}/submit to submit the draft claim, thereby converting it to an open claim.
To view an example of a payload that creates and submits a claim with an unverified policy in a composite request, see
“Sample composite claim payload” on page 154.

Composite request limitations with claims

You cannot have a single composite request operate on more than one claim.
Claims with unverified policies can only be created in a composite request.

132 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Canceling claims
You can cancel a draft claim through Cloud API. This is done using the /claim/{claimId}/cancel endpoint. This has
the same effect as when a user clicks the Cancel button in the New Claim Wizard.
You cannot cancel a claim after it has been submitted and therefore promoted to being an open claim. Once a claim has
been submitted, the only way to discontinue processing of it is to close it.

Claim modes
In the base configuration, some lines of business let you create claims in different "modes". For example, for personal
auto, you can create a "regular" claim, a "quick" claim, or a "first and final" claim. These modes are distinctions that
exist primarily in the user interface. Each mode may require a greater or lesser amount of information, and some modes
may assist in executing tasks beyond simply reporting the claim. But from a technical standpoint, the claims created in
each mode are not fundamentally different from one another.
Thus, Cloud API does not have an analog for "modes". When you create a claim through Cloud API, as long as you
provide the minimum required information, you can provide whatever amount of information is appropriate for the use
case.

The Test Util API

To create a claim, you must have information from a Policy Administration System. In some situations, you may also
need information from an external user management system or contact management system. However, during
development, your instance of ClaimCenter may not have access to any of these systems.
To facilitate development, Cloud API includes a Test Util API. The Test Util API is an API that provides functionality
to facilitate testing during development. You can use the Test Util API to:
• Create and search for test policies
• Create and search for test contacts and test user roles
• Create and search for test users

WARNING: The Test Util API is intended for use in a development environment only. Do not use the Test Util
API on a production system.

Viewing Test Util API information

The Test Util API is available only when the ClaimCenter environment is set to ci-test. The environment can be set
only during start-up. For more information on how to start ClaimCenter in a given environment, refer to the System
Administration Guide.

Set the ClaimCenter environment in Studio

About this task
In Studio, you can specify an environment for ClaimCenter to use whenever it is started from Studio.

Procedure
1. In Studio, select Run > Edit Configurations. Studio opens the Run/Debug Configurations dialog box.
2. In the left pane, click Server.
3. Add the following to the end of the VM Options field: -[Link]=ci-test
• If the VM Options field already contains an env setting, replace the existing setting with ci-test.
4. Click OK.

Executing FNOL 133

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Results
Whenever the server is started from Studio, it will be started using the ci-test environment. This includes:
• Starting the server from the Run menu.
• Starting the server using the Run tools in the upper right corner of the Studio user interface.

View the Test Util API in Swagger UI

About this task
Once ClaimCenter has been started using the ci-test environment, you can use Swagger UI to view the Test Util API.

Procedure
1. Start ClaimCenter using the ci-test environment.
2. In a web browser, enter the URL for Swagger UI. This loads the Swagger UI tool.
• The format of the URL is <applicationURL>/resources/swagger-ui/
• For example, for a local instance of ClaimCenter, use: [Link]
3. In the text field at the top of the Swagger UI interface, enter the following URL:
• <applicationURL>/rest/test-util/v1/[Link]
4. Click Explore.

Creating test policy data

The TestSupportPolicyPlugin class
At the beginning of the FNOL process, the user or service that is executing FNOL must identify the relevant policy.
Once identified, ClaimCenter copies information about that policy to its own policy graph. These processes are referred
to as policy search and policy retrieval. The details for how to execute these processes are specified by the
IPolicySearchAdapter plugin.

The base configuration includes an implementation of the IPolicySearchAdapter plugin that points to a Gosu class
named TestSupportPolicyPlugin. This implementation is used only when ClaimCenter is started in the ci-test
environment.

The Test Util endpoints

In the base configuration, none of the API roles provide access to the endpoints in the Test Util API. Therefore, the
only user who can create test policies is the super user su, who inherently has access to all endpoints.
You can configure the existing API roles to extend access to these endpoints to other users. For more information on
configuring API roles, see the Cloud API Developer Guide.

Creating test policies

You can use the /test-util/v1/policies endpoint to create test policies. When you execute this endpoint, the
system APIs take the data specified in the payload and add it to the data in the TestSupportPolicyPlugin class. This
allows you to reference test policies and their data in later calls that create claims and claim data.
There is no minimum data needed to create a test policy. If you create a policy with an empty request payload, the
policy will have the following attributes:
• The policy currency will be set to the ClaimCenter default currency.
• The effective date will be set to the current date.
• The expiration date will be set to one year from the current date.
• The policy will be an unverified policy.
You can use the policies in the sample data as models for how to build test policies. To do this, identify the claim ID of
a claim whose policy is an appropriate model. Then, execute a GET on any of the endpoints starting with /claims/

134 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{claimId}/policy to view how to structure data in a JSON payload. For a complete description of the data that can be
specified in the request payload, refer to Swagger UI.

Use a unique policy number for each policy

When creating a test policy, the system APIs do not require that the policy number be unique from any existing policy
numbers. However, if there are two or more policies with the same policy number, you will not be able to create a
claim using that policy number. This is because the system API that creates claims will find multiple policies and will
not be able to identify which policy to use.

Examples of test policy data

The following sections provide examples of some of the more frequently used fields. To access these examples
compiled into a single payload, see “Sample policy payload” on page 151.

Common scalar fields

The following code block creates a policy that is effective from January 1, 2020 to January 1, 2021. Its policy number
is FNOL-POLICY, and it is a verified policy.

{
"data": {
"attributes": {
"effectiveDate": "2020-01-01T07:00:00.000Z",
"expirationDate": "2021-01-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY",
"verifiedPolicy": true
}
}
}

Common typekey fields

The following code block creates a personal auto policy that is in force. (In other words, the policy has not been
canceled.)

{
"data": {
"attributes": {
"policyType": {
"code": "PersonalAuto"
},
"status": {
"code": "inforce"
}
}
}

Policy contacts
The following code block creates a policy where the insured is a person named Ray Newton who lives at 287
Kensington Rd. #1A, South Pasadena, CA. The ID in the Policy Administration for this contact is ab:0001-1.
When creating test policies, policy contacts are specified using request inclusion. For more information on this
approach, see “Request inclusion” on page 99.

{
"data": {
"attributes": {
"policyContacts": [
{
"contact": {
"refid": "rayNewton"
},
"roles": [
{
"code": "insured"
}
]
}
]
}
},

Executing FNOL 135

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"included": {
"Contact": [
{
"attributes": {
"firstName": "Ray",
"lastName": "Newton",
"primaryAddress": {
"addressLine1": "287 Kensington Rd. #1A",
"city": "South Pasadena",
"country": "US",
"postalCode": "91145",
"state": {
"code": "CA"
}
},
"subtype": {
"code": "Person"
},
"policySystemId": "ab:0001-1"
},
"method": "post",
"refid": "rayNewton",
"uri": "/test-util/v1/contacts"
}

]
}
}

Policy locations
The following code block creates a policy location.

{
"data": {
"attributes": {
"policyLocations": [
{
"address": {
"addressLine1": "287 Kensington Rd. #1A",
"city": "South Pasadena",
"postalCode": "91145",
"state": {
"code": "CA"
}
}
}
]
}
}
}

Policy-level coverages
The following code block creates a policy-level coverage. Note that the coverage has a coverage type (a typekey field),
and two currency amount fields. A policy can also contain risk unit coverages, which are shown in the next section.

{
"data": {
"attributes": {
"policyCoverages": [
{
"coverageType": {
"code": "PALiabilityCov"
},
"incidentLimit": {
"amount": "30000.00",
"currency": "usd"
},
"exposureLimit": {
"amount": "15000.00",
"currency": "usd"
}
}
]
}
}
}

136 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Risk units
A risk unit is something on a policy to which coverages are attached, such as a vehicle or a building. The following
code block creates a risk unit. There are different types of risk units, depending on the policy's product type. Because
the other examples are from a personal auto policy, this example is a vehicle risk unit.
Risk units typically include risk unit coverages (such as Collision coverage on a vehicle). For each coverage, you must
specify a coverageType, which must be set to a value from the coverageType typelist. The coverage can also have
coverage terms (such as a deductible). If you include coverage terms, each coverage term must have a
covTermPattern (set to a code from the covTermPattern typelist) and a covTermSubtype (set to a code from the
covTerm typelist). Additional fields may be necessary based on the type of coverage term. For example, coverage terms
that are financial amounts require a financialAmount field.

{
"data": {
"attributes": {
"vehicleRiskUnits": [
{
"RUNumber": 1,
"vehicle": {
"licensePlate": "1HGJ465",
"make": "Saturn",
"model": "SL",
"policySystemId": "pcveh:0001-1",
"state": {
"code": "CA"
},
"vin": "1GV234TV347463345",
"year": 1997
},
"coverages": [
{
"coverageType": {
"code": "PACollisionCov"
},
"covTerms": [
{
"covTermPattern": {
"code": "PACollDeductible"
},
"covTermSubtype": "FinancialCovTerm",
"financialAmount": {
"amount": "500.00",
"currency": "usd"
}
}
],
"incidentLimit": {
"amount": "15000.00",
"currency": "usd"
}
}
]
}
]
}
}
}

Tutorial: Creating a policy using the Test Util API

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” on page 29.
In this tutorial, you will add a policy to the policy data stored in the TestSupportPolicyPlugin class. You can then
reference this policy when creating a new claim.
1. If you have not already done so, configure Studio to start ClaimCenter using the ci-test environment.
a. In Studio, select Run > Edit Configurations. Studio opens the Run/Debug Configurations dialog box.
b. In the left pane, click Server.
c. Add the following to the end of the VM Options field: -[Link]=ci-test
d. Click OK.
2. Start ClaimCenter from Studio by selecting Run > Run and selecting Server.

Executing FNOL 137

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

3. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user su and password gw.
4. Enter the following call, but do not click Send yet:
• POST [Link]
5. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the text in the “Sample policy payload” on page 151 into the text field underneath the radio buttons.
6. Click Send.

Checking your work

ClaimCenter does not show data related to policies that are not associated with a claim. Therefore, there is no
independent way to check your work for this tutorial, other than confirming that you get a response code and then
attempting to create a claim using the policy.

Creating test data for related objects

You can also use the Test Util API to create objects related to policies, such as contacts and specialist services. This
may be useful when you want to test functionality during development and it is too cumbersome to create the required
objects manually.

POSTing a minimal draft claim

You can use the Claim API's POST /claims endpoint to create a draft claim. The minimum amount of information to
create a draft claim is:
• Policy number
• Loss date
A policy with the given policy number must exist in the system or class that is acting as the Policy Administration
System, and the loss date must occur while the policy is in force. If you provide a policy number that does not exist or
is not in effect on the given date, you will get a 400 response with an error message similar to one of the following:
"userMessage": "No policy was found with policy number ABC123 for loss date
2020-01-01T07:00:00.000Z"

Tutorial: POSTing a minimal draft claim for personal auto

This tutorial assumes you have completed the following prerequisite tutorials:
• “Tutorial: Set up your Postman environment” on page 29
• “Tutorial: Creating a policy using the Test Util API” on page 137
In this tutorial, you will create a draft claim for a personal auto policy using the minimum amount of information
needed.
1. Start ClaimCenter using the ci-test environment.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user su and password gw.
3. Enter the following call, but do not click Send yet:
• POST [Link]
4. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.

138 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

b. In the row of radio buttons, select raw.

c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons:
{
"data" : {
"attributes": {
"lossDate": "2020-02-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY"
}
}
}

e. If necessary, modify the payload's lossDate to ensure the loss occurred while the policy from the previous
tutorial is in force, but not in the future.
5. Click Send.
6. The response payload includes the claim's ID and claim number. Copy both of these values to a separate location,
as they are needed for later tutorials.

Checking your work

1. View the new draft claim in ClaimCenter.
a. In the response payload, note the claim number of the new draft claim. (It is on or near line 8, and it likely
starts with "999-99".)
b. Log on to ClaimCenter as su.
c. Click the Claim tab, enter the claim number in the Claim # menu item, and press Enter.
ClaimCenter navigates to the draft claim. Because the claim has minimal information only, ClaimCenter navigates to
the Basic Info step of the New Claim Wizard. The policy number and loss date are listed in the Info Bar. (Policy number
is labeled Pol, and loss date is labeled DoL.) The policy number and loss date should match the data in the POST /
claims request payload.

Note that, in the base configuration, the New Claim Wizard does not display claim numbers while the claim is in a draft
state.

PATCHing a draft claim

You can use the PATCH /claim/v1/claims/{claimId} endpoint to PATCH a draft or open claim. PATCHing a draft
claim may be appropriate when you want to create the draft claim before you have all of the information needed to
submit it, and you later need to update that claim with additional information. (It is also possible to create a draft claim
with a single POST. For more information, see “POSTing a typical draft claim” on page 140.)

Tutorial: PATCHing a draft claim for personal auto

This tutorial assumes you have completed the following prerequisite tutorials:
• “Tutorial: Set up your Postman environment” on page 29
• “Tutorial: Creating a policy using the Test Util API” on page 137
• “Tutorial: POSTing a minimal draft claim for personal auto” on page 138
◦ That ID of the resulting claim is referred to below in this tutorial as TutorialClaimID.
In this tutorial, you will patch a draft claim for a personal auto policy.
1. Start ClaimCenter using the ci-test environment.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user su and password gw.
3. Enter the following call, but do not click Send yet:
• PATCH [Link]
4. Specify the request payload.

Executing FNOL 139

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons. (You may need to adjust the loss date to
match the effective and expiration dates of the test policy.)
{
"data" : {
"attributes": {
"howReported": {
"code": "internet"
}
}
}
}

5. Click Send.

Checking your work

1. View the draft claim in ClaimCenter.
a. In the response payload, note the claim number of the new draft claim. (It is on or near line 8, and it likely
starts with "999-99".)
b. Log on to ClaimCenter as aapplegate.
c. Click the Claim tab, enter the claim number in the Claim # menu item, and press Enter.
ClaimCenter navigates to the draft claim. Because the claim has minimal information only, ClaimCenter navigates to
the Basic Info step of the New Claim Wizard. The How Reported field should be set to Internet.
Note that, in the base configuration, the New Claim Wizard does not display claim numbers while the claim is in a draft
state.

POSTing a typical draft claim

You can create a typical draft claim in a single POST. This approach usually involves either composite requests or
request inclusion.
A composite request is a set of requests that are executed in a single InsuranceSuite bundle (which corresponds to a
single database transaction).
• For more information on composite requests, see “Composite requests” on page 87.
• For an example of a draft claim created in a composite request, see “Sample composite claim payload” on page
154.
Request inclusion is a technique you can use with POSTs where you specify a root resource (such as a claim), one or
more related child resource (such as one or more ClaimContacts), and the relationship between the root and the
children.
• For more information on request inclusion, see “Request inclusion” on page 99.
• For an example of a draft claim created using request inclusion, see “Sample draft claim payload” on page 153.
New claims often include ClaimContacts, incidents, exposures, and service requests. For more information on how to
work with each of these resource types, see the following:
• “ClaimContacts” on page 179
• “Incidents” on page 191
• “Exposures” on page 205
• “Service requests” on page 217

Tutorial: POSTing a typical draft claim for personal auto

This tutorial assumes you have completed the following prerequisite tutorials:

140 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• “Tutorial: Set up your Postman environment” on page 29

• “Tutorial: Creating a policy using the Test Util API” on page 137
In this tutorial, you will create a draft claim for a personal auto policy using a typical amount of information needed.
This claim is for Ray Newton, who has a personal auto policy that covers his Toyota Prius. On March 1, Ray hit a
Honda Civic driven by Robert Farley. Both vehicles suffered minor damage.
1. Start ClaimCenter using the ci-test environment.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user su and password gw.
3. Enter the following call, but do not click Send yet:
• POST [Link]
4. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the text in the “Sample draft claim payload” on page 153 addendum into the text field underneath the
radio buttons. If necessary, modify the payload's lossDate to ensure the loss occurred while the policy from
the previous tutorial is in force, but not in the future.
5. Click Send.
6. The response payload includes the claim's ID and claim number. Copy both of these values to a separate location,
as they are needed for later tutorials.

Checking your work

1. View the new draft claim in ClaimCenter.
a. In the response payload, note the claim number of the new draft claim. (It is on or near line 8, and it likely
starts with "999-99".)
b. Log on to ClaimCenter as su.
c. Click the Claim tab, enter the claim number in the Claim # menu item, and press Enter.
ClaimCenter navigates to the draft claim. Because the claim has minimal information only, ClaimCenter navigates to
the Basic Info step of the New Claim Wizard. The policy number and loss date are listed in the Info Bar. (Policy number
is labeled Pol, and loss date is labeled DoL.) The policy number and loss date should match the data in the POST /
claims request payload.

Note that, in the base configuration, the New Claim Wizard does not display claim numbers while the claim is in a draft
state.

Creating claims with unverified policies

An unverified policy is a policy that is created during the FNOL process based on information supplied by an adjuster
or by the caller application. This information may or may not correctly correspond to information in a Policy
Administration System.
Unverified policies let an adjuster start the FNOL process without information from the PAS. Eventually, the policy
must be refreshed with data from the PAS, thereby converting it to a verified policy. You cannot complete the claim
process and make payments on a claim while the policy is still unverified.
Unverified policies can be used in either a test or production system. In a test system, unverified policies may be a
useful way to create policies without having an integration point to a PAS and without needing to enable the Test Util
API. In a production system, unverified policies are useful when there is a need to start the FNOL process and, for
some reason, the policy is unavailable to ClaimCenter or cannot be found.

Executing FNOL 141

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Unverified policies and composite requests

In ClaimCenter, you cannot create a policy that is not attached to a claim. Also, you cannot create a claim that has no
policy. Therefore, when creating claims with unverified policies, you must create the unverified policy and the claim in
the same call. The only way to do this is in the context of a composite request.
For more information on how to work with composite requests, see “Composite requests” on page 87.
The following sections discuss the endpoints used to create unverified policies and their child objects. In most cases,
these endpoints are used as URIs inside a composite request, and not as the main URL for the request itself. The main
URL for composite requests is always POST /composite/v1/composite.
To view an example of a payload that creates a complete claim with an unverified policy in a composite request, see
“Sample composite claim payload” on page 154.

Minimum criteria for an unverified policy and claim

To create an unverified policy, use the following endpoint:
• POST /claim/v1/unverified-policies
To create a draft claim (regardless of whether the policy is verified or unverified), use the following endpoint:
• POST /claim/v1/claims

Minimum creation criteria

At a minimum, an unverified policy must have:
• A policy number (a String value)
• A policy type (a typecode from the PolicyType typelist)
At a minimum, a claim with an unverified policy must have:
• A policy number (which must match the unverified policy's policy number)
• A loss date
The following composite request creates an unverified policy and claim with the minimum amount of data. As is
always the case with JSON, the fields can be listed in any order. Response payloads list fields in alphabetic order.
However, the examples in the documentation list these fields in the most human readable order.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-minimum",
"policyType": {
"code": "PersonalAuto"
}
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-minimum"
}
}
}
}
]
}

142 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Contacts on an unverified policy

The only time you can add contacts to an unverified policy is in the composite request after the unverified policy has
been created and before the claim is created. If you need to add contacts after the claim has been created, you must add
them to the claim directly.
This requirement exists because all contacts in the ClaimCenter database must be ClaimContacts associated with a
claim. When an unverified policy is created, any contacts associated with it are in a temporary state. When the
associated claim is created, the contacts are copied over to the claim and become ClaimContacts. This occurs before
the claim is committed to the database. If the system APIs gave you the ability to add contacts to the unverified policy
after this point, those contacts would be associated only with the policy and would not be ClaimContacts, and
ClaimCenter does not allow this.
To create a policy contact, use the following endpoint:
• POST /claim/v1/unverified-policies/policyId/contacts
When creating a policy contact, you must specify a contactSubtype. This is a typecode from the Contact typelist.
Based on the chosen value, there may be additional required fields. For example, a contact whose contactSubtype is
Person also requires a last name.
The following example creates an unverified policy with a policy contact (and a claim for the unverified policy). Note
that the contact is created after the unverified policy and before the claim.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-contact",
"policyType": {
"code": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "policyId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/contacts",
"body": {
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Ray",
"lastName": "Newton"
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-contact"
}
}
}
}
]
}

Executing FNOL 143

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Locations on an unverified policy

To create or modify a policy location, use the following endpoint:
• POST /claim/v1/unverified-policies/{policyId}/locations
• PATCH /claim/v1/unverified-policies/{policyId}/locations/{locationId}
There is no information required to create a location on an unverified policy. ClaimCenter provides default values for
all required fields.
The following example creates an unverified policy with a location.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-location",
"policyType": {
"code": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "policyId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/locations",
"body": {
"data": {
"attributes": {
}
}
},
"vars": [
{
"name": "locationId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-location"
}
}
}
}
]
}

Risk units on an unverified policy

A risk unit is a thing covered by the policy (other than the policyholder and any additional insureds). The type of risk
units on a policy vary based on the type of policy. For example:
• On a personal auto policy or commercial auto policy, risk units are typically vehicles.
• On a homeowner's policy, risk units are typically dwellings, other structures on the property (fences, sheds), or
items of value in the home (electronics, jewelry).
ClaimCenter policies make use of two types of risk units:

144 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• Location-based risk units, for risk units that have a fixed location (such as a house)
• Vehicle risk units, for vehicles
To create a risk unit, use the following endpoints:
• POST /claim/v1/unverified-policies/{policyId}/location-based-risk-units
• POST /claim/v1/unverified-policies/{policyId}/vehicle-risk-units
To modify a risk unit, use the following endpoints:
• PATCH /claim/v1/unverified-policies/{policyId}/location-based-risk-units/
{locationBasedRiskUnitId}
• PATCH /claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}
The information required to create a risk unit can vary with the risk unit type. For example:
• For vehicle risk units, no information is required.
• For location-based risk units, you must provide a location.
If a field is not required and not specified, ClaimCenter provides a default value.
The following example creates an unverified policy with a vehicle risk unit.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-vehicle-risk-unit",
"policyType": {
"code": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "policyId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units",
"body": {
"data": {
"attributes": {
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-vehicle-risk-unit"
}
}
}
}
]
}

Coverages on unverified policies

There are two types of coverages on a policy: policy-level coverages and risk unit coverages.
• A policy-level coverage is a coverage that typically covers the policyholder or other additional insureds listed on
the policy.

Executing FNOL 145

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ For example, personal auto policies typically come with a "Liability - Bodily Injury and Property Damage"
coverage. This covers any damage to other people or other properties that is caused by the policyholder (or the
additional insureds) while driving a vehicle. It does not matter which vehicle the policyholder was driving. The
coverage applies to the policyholder.
• A risk unit coverage is a coverage that covers an associated risk unit.
◦ For example, every vehicle listed on a personal auto policy typically comes with a "Collision" coverage. This
covers damage done to the associated vehicle. Suppose there is a policy with two vehicles and only the first
vehicle has collision coverage. If the second vehicle is involved in a collision, the policyholder will not be able
to file a claim for damages done to the second vehicle.
Within the context of underwriting policies, a given type of coverage is either a policy-level coverage (and never gets
attached to a risk unit) or a risk unit coverage (and always gets attached to a risk unit). However, ClaimCenter does not
store information about whether a given type of coverage ought to be policy-level or risk unit level. ClaimCenter
typically gets policy information from the Policy Administration System, and it assumes coverages are attached to the
policy at the appropriate place.
When you create an unverified policy, it is possible to attach a coverage that is normally policy-level to a risk unit, or
to attach a coverage that is normally risk unit level to the policy. This is allowed both in the ClaimCenter application
and through the system APIs. However, you cannot make payments on claims with unverified policies. In order to
verify a policy, you must retrieve updated information from the Policy Administration System. So if an unverified
policy has a coverage attached to the wrong location, an adjuster will need to address the error before payments on the
claim can be made.

Creating an unverified policy with a policy coverage

To create or modify a policy coverage, use the following endpoints:
• POST /claim/v1/unverified-policies/policyId/coverages
• PATCH /claim/v1/unverified-policies/policyId/coverages/{coverageId}
The minimum amount of information for a policy coverage is the coverage type. This is a code from the CoverageType
typelist. Coverage types are part of the ClaimCenter Line of Business Model, and only certain coverages can be
attached to a policy based on its policy type. For more information, see the Application Guide.
The following example creates an unverified policy with a policy coverage.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-policy-coverage",
"policyType": {
"code": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "policyId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/coverages",
"body": {
"data": {
"attributes": {
"coverageType" : {
"code": "PALiabilityCov"
}
}
}
}
},

146 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-policy-coverage"
}
}
}
}
]
}

Creating an unverified policy with a risk unit coverage

To create a risk unit coverage, use the following endpoints:
• POST /claim/v1/unverified-policies/{policyId}/location-based-risk-units/ location-based-risk-
units/{locationBasedRiskUnitId}/coverages
• POST /claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}/
coverages

To modify a risk unit coverage, use the following endpoints:

• PATCH /claim/v1/unverified-policies/{policyId}/location-based-risk-units/
{locationBasedRiskUnitId}/{coverageId}
• PATCH /claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}/
{coverageId}

The minimum amount of information for a risk unit coverage is the coverage type. This is a code from the
CoverageType typelist. Coverage types are part of the ClaimCenter Line of Business Model, and only certain
coverages can be attached to a risk unit based on the policy's policy type. For more information, see the Application
Guide.
The following example creates an unverified policy with a vehicle risk unit and a coverage for that risk unit.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-risk-unit-coverage",
"policyType": {
"code": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "policyId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units",
"body": {
"data": {
"attributes": {
}
}
},
"vars": [
{
"name": "riskUnitId",
"path": "$.[Link]"
}
]
},

Executing FNOL 147

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units/${riskUnitId}/coverages",
"body": {
"data": {
"attributes": {
"coverageType" : {
"code": "PACollisionCov"
}
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-risk-unit-coverage"
}
}
}
}
]
}

PATCH an unverified policy

To modify information directly on the policy, use the following endpoint:
• PATCH /unverified-policies/{policyId}
You can theoretically PATCH an unverified policy in the same composite request that creates it. However, it is more
common to PATCH an unverified policy in a subsequent call.
The following example specifies a service tier of gold for an existing unverified policy with id cc:59.

PATCH claim/v1/unverified-policies/cc:59

{
"data" : {
"attributes": {
"serviceTier": {
"code": "gold"
}
}
}
}

Retrieving information about an unverified policy

You can use the following endpoints to retrieve information about an unverified policy:
• GET claim/v1/unverified-policies/{policyId}
• GET claim/v1/unverified-policies/{policyId}/coverages
• GET claim/v1/unverified-policies/{policyId}/coverages/{coverageId}
• GET claim/v1/unverified-policies/{policyId}/location-based-risk-units
• GET claim/v1/unverified-policies/{policyId}/location-based-risk-units/
{locationBasedRiskUnitId}
• GET claim/v1/unverified-policies/{policyId}/location-based-risk-units/
{locationBasedRiskUnitId}/coverages
• GET claim/v1/unverified-policies/{policyId}/location-based-risk-units/
{locationBasedRiskUnitId}/coverages/{coverageId}
• GET claim/v1/unverified-policies/{policyId}/locations
• GET claim/v1/unverified-policies/{policyId}/locations/{locationId}
• GET claim/v1/unverified-policies/{policyId}/vehicle-risk-units
• GET claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}
• GET claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}/coverages

148 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• GET claim/v1/unverified-policies/{policyId}/vehicle-risk-units/{vehicleRiskUnitId}/coverages/
{coverageId}

Note: There is a GET /claim/v1/unverified-policies endpoint. Guidewire has deprecated this endpoint to
indicate that, although it is backwards compatible, new usage of this endpoint is no longer recommended. This
endpoint may perform poorly on large databases because it adds a query restriction on the Policy entity's
Verified column, and this column is not indexed.

Submitting a draft claim

You can use the POST /claim/v1/claims/{claimId}/submit endpoint to submit a draft claim. If the call executes
successfully, then:
• The draft claim becomes an open claim.
• The claim is assigned an open claim number.
• Automated claim setup is executed on the claim. This includes executing business rules to:
◦ Segment the claim
◦ Assign the claim
◦ Create and assign activities for the claim

Minimum information to submit a draft claim

From an internal standpoint, the minimum amount of information to submit a draft claim is the same as to create a draft
claim:
• Policy number
• Loss date
However, ClaimCenter also includes a series of validation rules. Each rule can throw an error that is tied to a specific
level of claim maturity. The two lowest levels are LoadSave and NewLossCompletion. The /submit endpoint will not
succeed if the claim violates any rule at either of these levels.
In the base configuration, in addition to policy number and loss date, you must also specify a reporter. The requirement
to include a reporter is implemented by the "CLV04000 - ClaimContact Role Configuration" validation rule, which
throws an error at the NewLossCompletion level if the reporter is null. For an example of a payload that creates a
minimum base-configuration-submittable claim, see the “Sample payload addendum” on page 151.

Draft claims that trigger errors

When you submit a draft claim, ClaimCenter generates an open claim number for the claim. If the submit action
generates no errors, the open claim number is assigned to the claim in place of the draft claim number.
However, it is possible for the submit action to throw either a validation error (because it is missing information
required for the LoadSave and NewLossCompletion levels) or an assignment error (because the assignment rules
cannot successfully assign the claim to a group and user). If either of these occurs, the claim remains in a draft state
and retains its draft claim number. The generated open claim number is discarded. The system APIs also return an error
message stating that the claim could not be submitted. This error message references the claim by its draft number.

Minimum criteria for submitting a claim with an unverified policy

You can create a draft claim with only a policy number and loss date. However, in the base configuration, a claim must
also have a reporter before it can be submitted.
The following composite request creates an unverified policy, a claim, and a ClaimContact who is then listed as the
reporter. It then submits the claim. Note that this requires five sub-requests:
1. Create the unverified policy.
2. Create the claim.
3. Create the ClaimContact.

Executing FNOL 149

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

4. Modify the claim to assign the role of reporter to the ClaimContact.

5. Submit the claim.
In the base configuration, this is the minimum amount of information needed to create and submit a claim with an
unverified policy.

POST /composite/v1/composite

{
"requests": [
{
"method": "post",
"uri": "/claim/v1/unverified-policies",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-minimum-submittable",
"policyType": {
"code": "PersonalAuto"
}
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-minimum-submittable"
}
}
},
"vars": [
{
"name": "claimId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"body": {
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Ray",
"lastName": "Newton"
}
}
},
"vars": [
{
"name": "contactId",
"path": "$.[Link]"
}
]
},
{
"method": "patch",
"uri": "/claim/v1/claims/${claimId}",
"body": {
"data": {
"attributes": {
"reporter": {
"id": "${contactId}"
}
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
}
]
}

Tutorial: Submitting a draft claim

This tutorial assumes you have completed the following prerequisite tutorials:

150 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• “Tutorial: Set up your Postman environment” on page 29

• “Tutorial: Creating a policy using the Test Util API” on page 137
• “Tutorial: POSTing a typical draft claim for personal auto” on page 140
◦ That ID of the resulting claim is referred to below in this tutorial as TutorialClaimID.
In this tutorial, you will submit a draft claim for a personal auto policy.
1. Start ClaimCenter using the ci-test environment.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user su and password gw.
3. Enter the following call and click Send:
• POST [Link]

Checking your work

1. View the open claim in ClaimCenter.
a. In the response payload, note the claim number of the new draft claim. (It is on or near line 36, and it likely
starts with "000-00-".)
b. Log on to ClaimCenter as aapplegate.
c. Click the Claim tab, enter the claim number in the Claim # menu item, and press Enter.
ClaimCenter navigates to the Summary screen for the claim. (If the claim is open, ClaimCenter takes you to the
Summary screen, not the New Claim Wizard.)

Canceling a draft claim

You can use the POST claim/v1/claims/{claimId}/cancel endpoint to cancel a draft claim. If the call executes
successfully, then the draft claim is discarded. All information about the draft claim is removed from the ClaimCenter
database.
You can cancel only draft claims. Once a claim has been submitted, it can be closed. But it can no longer be canceled.

Sample payload addendum

This section contains sample payloads referenced in previous topics that are too long to include within those topics.

Sample policy payload

The following payload creates a sample Test Util policy.

{
"data": {
"attributes": {
"effectiveDate": "2020-01-01T07:00:00.000Z",
"expirationDate": "2031-01-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY",
"verifiedPolicy": true,
"policyType": {
"code": "PersonalAuto"
},
"status": {
"code": "inforce"
},
"policyContacts": [
{
"contact": {
"refid": "rayNewton"
},
"roles": [
{
"code": "insured"
}
]
}
],
"policyLocations": [

Executing FNOL 151

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"address": {
"addressLine1": "287 Kensington Rd. #1A",
"city": "South Pasadena",
"postalCode": "91145",
"state": {
"code": "CA"
}
}
}
],
"policyCoverages": [
{
"coverageType": {
"code": "PALiabilityCov"
},
"incidentLimit": {
"amount": "30000.00",
"currency": "usd"
},
"exposureLimit": {
"amount": "15000.00",
"currency": "usd"
}
}
],
"vehicleRiskUnits": [
{
"RUNumber": 1,
"vehicle": {
"licensePlate": "1HGJ465",
"make": "Toyota",
"model": "Prius",
"policySystemId": "pcveh:0001-1",
"state": {
"code": "CA"
},
"vin": "1GV234TV347463345",
"year": 2007
},
"coverages": [
{
"coverageType": {
"code": "PACollisionCov"
},
"covTerms": [
{
"covTermPattern": {
"code": "PACollDeductible"
},
"covTermSubtype": "FinancialCovTerm",
"financialAmount": {
"amount": "500.00",
"currency": "usd"
}
}
],
"incidentLimit": {
"amount": "15000.00",
"currency": "usd"
}
}
]
}
]
}
},
"included": {
"TestUtilContact": [
{
"attributes": {
"firstName": "Ray",
"lastName": "Newton",
"primaryAddress": {
"addressLine1": "287 Kensington Rd. #1A",
"city": "South Pasadena",
"country": "US",
"postalCode": "91145",
"state": {
"code": "CA"
}
},
"subtype": {
"code": "Person"
},
"policySystemId": "ab:0001-1"
},
"method": "post",
"refid": "rayNewton",
"uri": "/test-util/v1/contacts"

152 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
]
}
}

Sample draft claim payload

The following payload creates a sample draft claim using an existing policy.

{
"data": {
"attributes": {
"lossDate": "2020-03-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY",
"lossCause": {
"code": "vehcollision"
},
"mainContact": {
"policySystemId": "ab:0001-1"
},
"reporter": {
"policySystemId": "ab:0001-1"
}
}
},
"included": {
"ClaimContact": [
{
"attributes": {
"firstName": "Robert",
"lastName": "Farley",
"contactSubtype": "Person"
},
"method": "post",
"refid": "robertFarley",
"uri": "/claim/v1/claims/this/contacts"
}
],
"VehicleIncident": [
{
"attributes": {
"collision": true,
"damageDescription": "Minor collision",
"driver": {
"policySystemId": "ab:0001-1"
},
"lossParty": {
"code": "insured"
},
"vehicle": {
"policySystemId": "pcveh:0001-1"
}
},
"method": "post",
"uri": "/claim/v1/claims/this/vehicle-incidents"
},
{
"attributes": {
"collision": true,
"damageDescription": "Minor collision",
"driver": {
"refid": "robertFarley"
},
"lossParty": {
"code": "third_party"
},
"vehicle": {
"licensePlate": "2PIX534",
"make": "Honda",
"model": "Civic",
"state": {
"code": "CA"
},
"vin": "3DT6YUQ3K9003LP19",
"year": 2019
}
},
"method": "post",
"uri": "/claim/v1/claims/this/vehicle-incidents"
}
]
}
}

Executing FNOL 153

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Sample composite claim payload

The following payload creates a sample claim in a composite request. This includes creating an unverified policy,
creating a draft claim for that policy, and then submitting the claim. (For information on how to create the claim's child
objects, such as ClaimContacts and incidents, refer to the other topics in the ClaimCenter Business Flows section.)

{
"requests": [
{
"body": {
"data": {
"attributes": {
"policyNumber": "composite-FNOL-example",
"policyType": {
"code": "PersonalAuto"
}
}
}
},
"method": "post",
"uri": "/claim/v1/unverified-policies",
"vars": [
{
"name": "policyId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"coverageType": {
"code": "PALiabilityCov"
},
"covTerms": [
{
"covTermSubtype": "FinancialCovTerm",
"covTermOrder": 1,
"covTermPattern": {
"code": "PALiability"
},
"modelAggregation": {
"code": "pi"
},
"modelRestriction": {
"code": "acc"
},
"financialAmount": {
"amount": "50000.00",
"currency": "usd"
}
},
{
"covTermSubtype": "ClassificationCovTerm",
"covTermOrder": 2,
"code": "Classification Code - 1",
"description": "ClassificationCovTerm description"
}
],
"currency": {
"code": "usd"
},
"exposureLimit": {
"amount": "15000.00",
"currency": "usd"
},
"incidentLimit": {
"amount": "10000.00",
"currency": "usd"
},
"notes": "Coverage of unverified policy",
"state": {
"code": "CA"
}
}
}
},
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/coverages"
},
{
"body": {
"data": {
"attributes": {
"addressBookUID": "UID-RayNewton-001",

154 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"emailAddress1": "RayNewton@[Link]",
"firstName": "Ray",
"lastName": "Newton",
"primaryAddress": {
"addressLine1": "287 Kensington Rd. #1A",
"city": "South Pasadena",
"country": "US",
"postalCode": "91145",
"state": {
"code": "CA"
}
},
"primaryPhoneType": {
"code": "work"
},
"contactSubtype": "Person",
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "818-446-1206"
}
}
}
},
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/contacts",
"vars": [
{
"name": "insuredId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"insured": {
"id": "${insuredId}"
}
}
}
},
"method": "patch",
"uri": "/claim/v1/unverified-policies/${policyId}"
},
{
"body": {
"data": {
"attributes": {
"addressBookUID": "UID-HelenNewton-001",
"emailAddress1": "HelenNewton@[Link]",
"firstName": "Helen",
"lastName": "Newton",
"primaryAddress": {
"addressLine1": "287 Kensington Rd. #1A",
"city": "South Pasadena",
"country": "US",
"postalCode": "91145",
"state": {
"code": "CA"
}
},
"primaryPhoneType": {
"code": "work"
},
"contactSubtype": "Person",
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "818-446-1206"
}
}
}
},
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/contacts",
"vars": [
{
"name": "coveredContactId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {

Executing FNOL 155

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"coveredParties": [
{
"id": "${coveredContactId}"
}
]
}
}
},
"method": "patch",
"uri": "/claim/v1/unverified-policies/${policyId}"
},
{
"body": {
"data": {
"attributes": {
"description": "Vehicle Risk Unit Description",
"vehicle": {
"color": "Green",
"licensePlate": "1ABC234",
"make": "Honda",
"manufacturer": {
"code": "HOND"
},
"model": "Accord",
"state": {
"code": "CA"
},
"style": {
"code": "passengercar"
},
"vin": "QWE327UH534NMK09P",
"year": 2010
}
}
}
},
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units",
"vars": [
{
"name": "vehicleId",
"path": "$.[Link]"
},
{
"name": "vehicleRUId",
"path": "$.[Link]"
},
{
"name": "RUNumber",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"claimAggLimit": {
"amount": "7000.00",
"currency": "usd"
},
"personAggLimit": {
"amount": "8000.00",
"currency": "usd"
},
"coverageType": {
"code": "PACollisionCov"
},
"covTerms": [
{
"covTermSubtype": "FinancialCovTerm",
"covTermOrder": 1,
"covTermPattern": {
"code": "PACollDeductible"
},
"modelAggregation": {
"code": "pi"
},
"modelRestriction": {
"code": "acc"
},
"financialAmount": {
"amount": "500.00",
"currency": "usd"
}
},
{
"covTermSubtype": "NumericCovTerm",
"covTermOrder": 2,
"numericValue": "20.20",

156 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"units": {
"code": "days"
}
}
],
"currency": {
"code": "usd"
},
"exposureLimit": {
"amount": "10000.00",
"currency": "usd"
},
"incidentLimit": {
"amount": "20000.00",
"currency": "usd"
},
"notes": "Coverage of vehicle risk unit"
}
}
},
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units/${vehicleRUId}/coverages"
},
{
"body": {
"data": {
"attributes": {
"lossDate": "2021-02-01T07:00:00.000Z",
"lossLocation": {
"addressLine1": "100 Main St.",
"city": "San Mateo",
"postalCode": "90123",
"state": {
"code": "CA"
}
},
"policyNumber": "composite-FNOL-example",
"reporter": {
"id": "${insuredId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims",
"vars": [
{
"name": "claimId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"body": "Test note body"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/notes"
},
{
"body": {
"data": {
"attributes": {
"collision": true,
"collisionPoint": {
"code": "03"
},
"damageDescription": "Damaged front bumper",
"driver": {
"id": "${insuredId}"
},
"lossParty": {
"code": "insured"
},
"severity": {
"code": "major-auto"
},
"vehicle": {
"id": "${vehicleId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/vehicle-incidents",
"vars": [

Executing FNOL 157

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"name": "vehicleIncidentId",
"path": "$.[Link]"
},
{
"name": "driverUri",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"coverageSubtype": {
"code": "PACollisionCov"
},
"claimant": {
"id": "${insuredId}"
},
"primaryCoverage": {
"code": "PACollisionCov"
},
"vehicleIncident": {
"id": "${vehicleIncidentId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/exposures",
"vars": [
{
"name": "exposureId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"cellPhone": {
"countryCode": {
"code": "US"
},
"number": "555-555-5555"
},
"dateOfBirth": "1928-11-18",
"emailAddress1": "MitchMochizuki@[Link]",
"firstName": "Mitch",
"homePhone": {
"countryCode": {
"code": "US"
},
"number": "555-555-5556"
},
"lastName": "Mochizuki",
"licenseNumber": "ABCDE12345",
"licenseState": {
"code": "CA"
},
"primaryAddress": {
"addressLine1": "1313 Albian Dr.",
"city": "Anaheim",
"country": "US",
"county": "Orange County",
"postalCode": "92802",
"state": {
"code": "CA"
}
},
"primaryLanguage": {
"code": "en_US"
},
"primaryLocale": {
"code": "en_US"
},
"primaryPhoneType": {
"code": "home"
},
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "mitchMochizukiId",

158 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"addressBookUID": "DOCTOR-12345",
"dateOfBirth": "1959-06-11",
"emailAddress1": "DanaEdwards@[Link]",
"firstName": "Dana",
"lastName": "Edwards",
"primaryAddress": {
"addressLine1": "1000 Hospital Dr.",
"city": "Princeton",
"country": "US",
"postalCode": "08540",
"state": {
"code": "NJ"
}
},
"primaryLanguage": {
"code": "en_US"
},
"primaryLocale": {
"code": "en_US"
},
"primaryPhoneType": {
"code": "work"
},
"contactSubtype": "Doctor",
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "666-666-6666"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "danaEdwardsId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"ambulanceUsed": true,
"bodyParts": [
{
"detailedBodyPart": {
"code": "57"
},
"detailedBodyPartDesc": {
"code": "57B"
},
"impairmentPercentage": 77,
"ordering": 12,
"primaryBodyPart": {
"code": "lower"
},
"sideOfBody": {
"code": "left"
}
}
],
"description": "Head trauma, possible concussion",
"detailedInjuryType": {
"code": "07"
},
"disabledDueToAccident": {
"code": "notdisabled"
},
"generalInjuryType": {
"code": "specific"
},
"injuredPerson": {
"id": "${mitchMochizukiId}"
},
"lossParty": {
"code": "third_party"
},
"lostWages": false,

Executing FNOL 159

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"primaryDoctor": {
"id": "${danaEdwardsId}"
},
"severity": {
"code": "major-injury"
},
"treatmentType": {
"code": "er"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/injury-incidents"
},
{
"body": {
"data": {
"attributes": {
"collision": true,
"collisionPoint": {
"code": "03"
},
"damageDescription": "Damaged rear bumper",
"driver": {
"id": "${mitchMochizukiId}"
},
"lossParty": {
"code": "third_party"
},
"severity": {
"code": "major-auto"
},
"vehicle": {
"color": "silver",
"licensePlate": "MERLIN0",
"make": "Subaru",
"model": "Outback",
"year": 2005
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/vehicle-incidents"
},
{
"body": {
"data": {
"attributes": {
"addressBookUID": "REPAIRSHOP-12345",
"companyName": "#([Link])",
"editableRoles": [
{
"active": true,
"relatedTo": {
"id": "${claimId}",
"type": "Claim"
},
"role": {
"code": "repairshop"
}
}
],
"contactSubtype": "AutoRepairShop"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts"
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
}
],
"selections": [
{
"uri": "${driverUri}"
}
]
}

Sample composite first-and-final

Composite requests can mimic the functionality of ClaimCenter Auto First-and-Final, in which a claim is created, paid
out, and closed without adjudication.

160 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For more information about Auto First-and-Final, see the ClaimCenter Application Guide.
Note:

• Mimicing auto first-and-final claim processing can create entities that cannot be closed in the composite
request. For example, workplan rules can create activities that the composite request is unaware of and
therefore cannot complete. Depending on your configuration, you may need to execute additional steps to
completely close the claim.
• Activities can prevent claims and exposures from closing, and therefore you may need to close all activities
automatically created during a composite request for claim closure.
• You can POST /check-sets for composite requests for only non-recurring, final-payment checks; you
cannot complete a partial payment transaction using composite requests.

Subrequest order
When executing a first and final claim within a composite request, you must execute the steps in the following order. If
steps are executed in a different order, then some objects may get created automatically by ClaimCenter that conflict
with objects created in later subrequests.
1. POST the claim.
2. POST the vehicle incident.
3. POST an exposure with the following attributes
a. The exposure's incident is the vehicle incident.
b. The exposure's coverage is Comprehensive.
c. The exposure's claimant is the insured.
4. Submit the claim.
5. POST the payment with the following attributes:
a. The payment draws from the exposure's reserve line.
b. The payment's payee is the insured.

Minimum composite request example

The following composite request uses the minimum composite requests for an immediate closing of claim and
transaction payment (depending on your activity patten configuration).
1. POST the claim:
{
"requests": [
{
"body": {
"data": {
"attributes": {
"coverageInQuestion": false,
"description": "Rear-ended by distracted driver",
"faultRating": {
"code": "nofault"
},
"howReported": {
"code": "phone"
},
"incidentOnly": false,
"jurisdiction": {
"code": "CA"
},
"lossCause": {
"code": "FallingObject"
},
"lossDate": " 2020-08-31T07:00:00.000Z)",
"lossLocation": {
"addressLine1": " 2850 S Delaware St ",
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"postalCode": "94404",
"state": {
"code": "CA"
}
},
"mainContact": {

Executing FNOL 161

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"policySystemId": "pc:contact_1"
},
"policyNumber": "POLICY-ID",
"reportedByType": {
"code": "self"
},
"reporter": {
"policySystemId": "pc:contact_1"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims",
"vars": [
{
"name": "claimId",
"path": "$.[Link]"
}
]
},

2. POST the vehicle incident.

{
"body": {
"data": {
"attributes": {
"collision": true,
"damageDescription": "Tree fell",
"lossParty": {
"code": "insured"
},
"vehicle": {
"policySystemId": "pcveh:1"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/vehicle-incidents",
"vars": [
{
"name": "firstPartyVehicleIncidentId",
"path": "$.[Link]"
}
]
},

3. POST an exposure associated with the vehicle incident from step 2 with comprehensive coverage and the insured
and the claimant.
{
"body": {
"data": {
"attributes": {
"coverage": {
"policySystemId": "pc:coverage_2"
},
"coverageSubtype": {
"code": "PAComprehensiveCov"
},
"claimant": {
"policySystemId": "pc:contact_1"
},
"primaryCoverage": {
"code": "PAComprehensiveCov"
},
"vehicleIncident": {
"id": "${firstPartyVehicleIncidentId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/exposures",
"vars": [
{
"name": "exposureId",
"path": "$.[Link]"
}
]
},

162 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

4. Submit the claim.

{
"body": {
"data": {
"attributes": {
"initialAssignment": {
"groupId": "#([Link])",
"userId": "#([Link])"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
},

5. POST a payment to the insured.

{
"body": {
"data": {
"attributes": {
"primaryCheckToWrite": {
"paymentsToWrite": [
{
"lineItems": [
{
"transactionAmount": {
"amount": "500",
"currency": "usd"
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "${exposureId}"
},
"reservingCurrency": {
"code": "usd"
}
},
"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
"policySystemId": "pc:contact_1"
},
"payeeType": {
"code": "other"
}
}
],
"paymentMethod": {
"code": "check"
},
"mailTo": "Ray Newton",
"payTo": "Ray Newton",
"mailingAddress": {
"addressLine1": "2850 S Delaware St ",
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
}
}
}
},
"method": "post",
"uri": "#('/claim/v1/claims/${claimId}/check-sets')",
"vars": [
{

Executing FNOL 163

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"name": "checkId",
"path": "$.[Link][0].id"
}
]
}
]
}

164 Executing FNOL

chapter 15

Claims

This topic covers the different ways that a caller application can get information on existing claims, and additional
actions they can take on open claims.
For information on creating claims or working with draft claims, see “Executing FNOL” on page 129.

Querying for claims associated with you

Typically, the GET /claim/v1/claims endpoint does not return all claims in ClaimCenter. The endpoint is restricted
by the caller's resource access. In the base configuration, this means the following:
• For internal users, the endpoint returns only claims that would be on that user's Access Control List (ACL)
• For external users who are policyholders, the endpoint returns only claims related to policies the user holds.
• For external users who are vendors, the endpoint returns only claims with a service request where the vendor is the
service provider.
• For services, all claims are returned. (Services are not bound by resource access.)
For example, both Andy Applegate and Wendy Gompers are internal users defined in the sample data. Suppose that the
sample data has been loaded and each adjuster executes the following:
GET /claim/v1/claims?fields=id
The count and data sections of the response payload for Andy Applegate consists of the 5 open claims on his ACL:

{
"count": 5,
"data": [
{
"attributes": {
"id": "cc:34"
}
},
{
"attributes": {
"id": "cc:33"
}
},
{
"attributes": {
"id": "demo_sample:20"
}
},
{
"attributes": {
"id": "demo_sample:2"
}
},
{
"attributes": {

Claims 165
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"id": "demo_sample:1"
}
}
],
...

The count and data sections of response payload for Wendy Gompers consists of the 6 open claims on her ACL:

{
"count": 6,
"data": [
{
"attributes": {
"id": "trucking:7"
}
},
{
"attributes": {
"id": "trucking:8"
}
},
{
"attributes": {
"id": "demo_sample:30002"
}
},
{
"attributes": {
"id": "demo_sample:30001"
}
},
{
"attributes": {
"id": "gl:1"
}
},
{
"attributes": {
"id": "trucking:6"
}
}
],
...

You can view this output for yourself in Postman by doing the following:
1. Open a request tab. From the Authorization tab, set the TYPE drop-down list to Basic Auth. For the Username and
Password, specify aapplegate and gw.
2. Execute GET /claim/v1/claims.
3. Open a second request tab. From the Authorization tab, set the TYPE drop-down list to Basic Auth. For the
Username and Password, specify wgompers and gw.
4. Execute GET /claim/v1/claims.
5. Compare the two response payloads.
For more information on resource access, see the Cloud API Developer Guide.

Closed claims
By default, the GET /claim/v1/claims endpoint returns only open claims. You can query for open and closed claims
by adding the following query parameter:
?filter=state:in:open,closed

Draft claims
Draft claims are claims that have been saved to the database, but the claim does not yet have enough information for it
to be assigned to an adjuster or vendor. Therefore, for some callers, the GET /claim/v1/claims endpoint does not
return draft claims.

Querying for a claim by claim ID

The GET /claim/v1/claims/{claimId} endpoint returns information on the given claim, assuming the caller's
resource access permits the caller to view the claim.

166 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For example, Andy Applegate owns the claim with ID cc:33. Betty Baker belongs to the same group as Andy
Applegate, and therefore she has resource access permission to view claims assigned to Andy. Amy Baxter is a clerical
user who works in a different group. She does not have resource access permission to view claim cc:33.
Suppose that each of these users triggers the following call:
GET /claim/v1/claims/cc:33?fields=claimNumber
The response for Andy Applegate is:

{
"data": {
"attributes": {
"claimNumber": "235-53-425891"
}
}
}

The response for Betty Baker is:

{
"data": {
"attributes": {
"claimNumber": "235-53-425891"
}
}
}

The response for Amy Baxter is:

{
"status": 404,
"errorCode": "[Link]",
"userMessage": "No resource was found at path /claim/v1/claims/cc:33"
}

Resource access is a component of the system API authentication and authorization framework. For more information
on resource access, see the Cloud API Developer Guide.

Searching for active and archived claims

By default, the GET /claims endpoint returns only claims that are associated with the caller and are not archived. If
you want to search for claims that are not associated with you, are archived, or are otherwise excluded from the GET /
claims results, you can use one of the following endpoints:

• POST /claim/v1/search/claims-v2
• POST /claim/v1/search/claims-freetext
The /claim/v1/search/claims-v2 endpoint can be used to find claims unassociated with the caller and archived
claims. Note that, for any claim that the caller does not have access to, the claim will appear in the search results. But
the caller will not be able to view it using the GET /claims/{claimId} endpoint.
The /claim/v1/search/claims-freetext can also be used to find claims unassociated with the caller and archived
claims, but only if free text search has been enabled. For more information about using free-text search, see the
Application Guide.
Note: There is an additional search endpoint, POST /claim/v1/search/claims. Guidewire has deprecated
this endpoint to indicate that, although it is backwards compatible, new usage of this endpoint is no longer
recommended. The POST /claim/v1/search/claims-v2 offers all of the capabilities of the deprecated
endpoint and provides additional request parameters, a more detailed response payload, and it can include
archived claims.

Claims 167
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

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:
Note:

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"
}
}
}

Request payload for free-text search

The request object for a POST /claim/v1/search/claims-freetext call must include a body. The body must specify
search parameters that use free-text search; the field name returns results from the free-text search index. For example:

{
"data": {
"attributes": {
"address": {
"addressLine1": "1313 Monroe Lane",

168 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"city": "Pomona",
"country": "US",
"state": {
"code": "CA",
}
},
"name": "Ray Newton",
"nameSearchType": {
"code": "any",
},
"phoneNumber": "555 413 4545"
}
}
}

For more information about using free-text search, see the ClaimCenter Application Guide.

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.
Note:

If archiving is not enabled on your instance of ClaimCenter, the response payload returns a 400 error. Note
that the error message does not mention archiving explicitly:
{
"status": 400,
"errorCode": "[Link]",
"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",
}

Claims 169
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

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
"assignedUser": { "adjusterName": "Andy Applegate"
"displayName": "Andy Applegate",
"id": "demo_sample:1"
}

Claim ID
"id": "cc:33", "claimId": "cc:33"

Insured
"insured": { "insuredName": "Bill Kinman"
"displayName": "Bill Kinman ",
"id": "cc:33",
"uri": "/claim/v1/claims/cc:33/
contacts/cc:101"
}

Claimants
"included": { "claimants": [
"ClaimContact": [ "Bill Kinman"
{ ],
"attributes": {
...
"id": "cc:101",
"roles": [
{
"relatedTo": {
"id": "cc:47",
"type": "Exposure"
},
"role": {
"code": "claimant"
}
},
...

Note:

You can use query parameters to refine the response payload to exclude default fields and include non-default
fields. For more information, see “Query parameters” on page 43.
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.

170 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

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 user
• assignedGroup provides the group assigned to the claim
• claimID
• 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 sent
• insuredName
• lossDate of the claim
• The total amount paid
• policyNumber of the claim
• remainingReserves left on the claim
• status 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 the claimInfo object that allows the archived claim to be
retrieved

Retrieving policy information

During the initial POST of a draft claim, ClaimCenter copies information about the relevant policy from the Policy
Administration System into ClaimCenter. This information is a snapshot of the policy as it existed on the claim's loss
date.

Claims 171
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The Policy Administration System is considered the System of Record for policy information. Consequently, for
verified policies, you cannot edit policy information in ClaimCenter through the system APIs. (The user interface does
allow you to edit policy information, though this causes the policy to become unverified. For more information on
unverified policies, refer to the Application Guide.)
The system APIs include several endpoints that let you view policy information.

Summary of the policy endpoints

The information returned by the following endpoints comes from the ClaimCenter snapshot of the policy. It does not
come directly from the Policy Administration System.

The policy itself

The following endpoint returns information that is directly on the policy resource, such as effective date, expiration
date, policy number and policy type:
• /claims/{claimId}/policy

Risk units
A risk unit is a thing covered by the policy (other than the policyholder and any additional insureds). The type of risk
units on a policy vary based on the type of policy. For example:
• On a personal auto policy or commercial auto policy, risk units are typically vehicles.
• On a homeowner's policy, risk units are typically dwellings, other structures on the property (fences, sheds), or
items of value in the home (electronics, jewelry).
The following endpoints return information about the risk units on the policy:
• /claims/{claimId}/policy/location-based-risk-units
• /claims/{claimId}/policy/location-based-risk-units/{locationBasedRiskUnitId}
• /claims/{claimId}/policy/vehicle-risk-units
• /claims/{claimId}/policy/vehicle-risk-units/{vehicleRiskUnitId}

Coverages
There are two types of coverages on a policy: policy-level coverages and risk unit coverages.
• A policy-level coverage is a coverage that typically covers the policyholder or other additional insureds listed on
the policy.
◦ For example, personal auto policies typically come with a "Liability - Bodily Injury and Property Damage"
coverage. This covers any damage to other people or other properties that is caused by the policyholder (or the
additional insureds) while driving a vehicle. It does not matter which vehicle the policyholder was driving. The
coverage applies to the policyholder.
• A risk unit coverage is a coverage that covers an associated risk unit.
◦ For example, every vehicle listed on a personal auto policy typically comes with a "Collision" coverage. This
covers damage done to the associated vehicle. Suppose there is a policy with two vehicles and only the first
vehicle has collision coverage. If the second vehicle is involved in a collision, the policyholder will not be able
to file a claim for damages done to the second vehicle.
The following endpoints return information about the policy-level coverages on the policy:
• /claims/{claimId}/policy/coverages
• /claims/{claimId}/policy/coverages/{coverageId}
The following endpoints return information about the risk units on the policy. This includes the risk unit coverages
attached to each risk unit:
• /claims/{claimId}/policy/location-based-risk-units
• /claims/{claimId}/policy/location-based-risk-units/{locationBasedRiskUnitId}

172 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• /claims/{claimId}/policy/vehicle-risk-units
• /claims/{claimId}/policy/vehicle-risk-units/{vehicleRiskUnitId}

Locations
A location is a physical place listed on a policy. The ways in which locations are used vary based on the type of policy.
For example:
• On a personal auto policy, a location can be used to identify where a vehicle is garaged.
• On a homeowner's policy, a location can be used to identify where the home is located.
The following endpoints return information about the locations on the policy:
• /claims/{claimId}/policy/locations
• /claims/{claimId}/policy/locations/{locationId}

Endorsements
An endorsement is a physical document detailing some aspect of the policy. Occasionally, an endorsement can become
relevant to claims processing. Endorsements are also referred to as forms.
For example, suppose a home owner elects to get a homeowner's policy for a home that is in a flood zone. The insurer
attaches an endorsement to the policy that excludes any damage caused by flooding. Later, the home owner files a
claim for damage caused by a flood. When determining if payment will be made on the claim, the adjuster needs to see
if the policy included a flood damage exclusion endorsement.
The following endpoints return information about the endorsements on the policy:
• /claims/{claimId}/policy/endorsements
• /claims/{claimId}/policy/endorsements/{endorsementId}

Assigning claims
When a claim completes the FNOL process (either through the user interface or through the /submit endpoint), it is
assigned to a group and a user in that group. The assigned user has the primary responsible for managing the claim.
When you submit a claim through the system APIs, ClaimCenter automatically executes the claim assignment rules to
initially assign the claim to a group and user. You can use the POST /claims/{claimId}/assign endpoint to reassign
the claim as needed.
Note: The functionality for assigning claims is a subset of the functionality for assigning activities. All
assignment options that are applicable to both activities and claims have the same behavior.

Assignment options
A claim can be assigned through the system APIs in the following ways:
• To a specific group and user in that group
• To a specific group only (and then ClaimCenter uses assignment rules to select a user in that group)
• By re-running the claim assignment rules
◦ This can be appropriate if you have modified the claim since the last time assignment rules were run and the
modification might affect who the claim would be assigned to.
The root resources for the /claims/{claimId}/assign endpoints is ClaimAssignee. This resource specifies
assignment criteria. The schema has the following fields:

Field Type Description

autoAssign Boolean Whether to assign the claim using assignment rules
groupId string The ID of the group to assign the claim to
userId string The ID of the user to assign the claim to

Claims 173
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The ClaimAssignee resource cannot be empty. It must specify a single logical assignment option (group and user,
group only, or automatic assignment). For more information on how assignment rules execute assignment, see the Gosu
Rules Guide.

Assignment example - Assigning to a specific group (and user)

The following assigns claim cc:34 to group demo_sample:31 (Auto1 - TeamA) and user demo_sample:2 (Sue Smith).

POST /claim/v1/claims/cc:34/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:2"
}
}
}

The following assigns claim cc:34 to group demo_sample:31 (Auto1 - TeamA). Because no user has been specified,
ClaimCenter will execute assignment rules to assign the claim to a user in group demo-sample:31.

POST /claim/v1/claims/cc:34/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31"
}
}
}

Note that there is currently no endpoint that returns groups or group IDs. To assign claims to a specific group, the caller
application must determine the group ID using some method other than a groups system API.

Assignment example - Using automated assignment

The following assigns claim cc:34 using automated assignment rules.

POST /claim/v1/claims/cc:34/assign

{
"data": {
"attributes": {
"autoAssign" : true
}
}
}

Validating claims
ClaimCenter validation levels
During a claim's lifecycle, a claim passes through one or more levels of maturity. Within ClaimCenter, these are called
validation levels. The base configuration comes with the following levels:
• Load and save - The claim has enough information to be saved to the database.
• New loss completion - The claim has enough information to be assigned to an adjuster.
• Valid for ISO - The claim has enough information to be filed with ISO. (ISO is a national database used in the
United States to verify that the same loss is not being filed with multiple insurers.)
• Send to external (systems) - The claim has enough information to send information about it to external systems
within the insurer, such as a Policy Administration System that may be trying to assess policy renewal rates.
• Ability to pay - The claim has enough information such that payments can be written for it.
A claim's validation level is determined and enforced by a set of claim validation rules. Whenever a change is made to
a claim, the validation rules determine if the claim can be advanced to a later stage of validation. The validation rules

174 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

also prevent a claim from moving backwards to a lower level of validation. For more information on validation rules,
see the Gosu Rules Guide.
Note: In the base configuration, the "load and save" level applies only to claims that are being imported through
the ClaimCenter SOAP-based ClaimAPI API. Draft claims submitted through the system APIs do not need to
pass any level. In order for a draft claim to be promoted to an open claim, the draft claim must pass both the
"load and save" level and the "new loss completion" level. For more information, see “Executing FNOL” on
page 129.

Validating a claim through the Cloud API

The Claim API includes a POST /claim/{claimId}/validate endpoint. This endpoint can be used to:
• Determine the current validation level and all previous validation levels reached by the claim
• Perform validation on the claim for a specific validation level. (This returns information that identifies the
conditions that must be true for the claim to advance to the specified level.)
Checking a claim's validation level can be useful in the following situations:
• You want to determine whether or not the claim has enough information to be assigned to an adjuster. You can use
the /validate endpoint to determine if the claim is at or beyond the "new loss completion" level.
◦ If the claim is below the "new loss completion" level, the payload identifies the conditions needed to reach "new
loss completion".
• You want to execute a payment for a claim. You can use the /validate endpoint to determine if the claim is at the
"ability to pay" level.
◦ If the claim is below the "ability to pay" level, the payload identifies the conditions needed to reach "ability to
pay".

Example of a claim at the "Load and save" level

Suppose you execute a POST /claim/{claimId}/validate for claim cc:706 and this is the response:

"attributes": {
"allValidationLevelsReached": [
{
"code": "loadsave",
"name": "Load and save"
}
],
"hasErrors": true,
"validationIssues": [
{
"field": "contacts",
"id": "cc:SsCzMkFw0Vk6bO8HCLh3p",
"message": "The role Reporter is required on Claim 999-99-999945.",
"severity": {
"code": "error",
"name": "Error"
},
"type": "Claim",
"url": "/claim/v1/claims/cc:SsCzMkFw0Vk6bO8HCLh3p",
"validationLevel": {
"code": "newloss",
"name": "New loss completion"
}
}

From this payload, you can determine the following:

• The claim is at the "load and save" level. ([Link] is loadsave,
allValidationLevelsReached has only one member whose code is loadsave).
• To move to the "new loss completion" level, the reporter must be specified. (This comes from the first
validationIssues message.)
• To move to the "valid for iso" level, the loss location must be non-null, and the claim must not be in a draft state
(This comes from the second, third, and fourth validationIssues message.) The payload does not specify error
messages beyond “valid for iso.” Therefore, once the claim reaches “valid for iso”, the claim will automatically be
promoted to “ability to pay”.

Claims 175
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Example of a claim at the "New loss completion" level

Suppose you execute a POST /claim/{claimId}/validate for claim cc:709 and this is the response:
{
"data": {
"attributes": {
"allValidationLevelsReached": [
{
"code": "newloss",
"name": "New loss completion"
},
{
"code": "loadsave",
"name": "Load and save"
}
],
"hasErrors": true,
"validationIssues": [
{
"field": "firstName",
"id": "cc:SYVsCEg_23xuVpJwrN2lH",
"message": "The insured Newton first name must not be empty",
"severity": {
"code": "error",
"name": "Error"
},
"type": "Claim",
"url": "/claim/v1/claims/cc:SYVsCEg_23xuVpJwrN2lH",
"validationLevel": {
"code": "iso",
"name": "Valid for ISO"
}
}
],
"validationLevelReached": {
"code": "newloss",
"name": "New loss completion"
}
}
}
}

From this payload, you can determine the following information:

• The claim is at the "new loss completion" level ([Link] is new loss completion).
• The claim had previously reached the “load and save” level before reaching the “New loss completion” level
(allValidationLevelsReached has the members Load Save and New loss completion.)
• To move to the "valid for ISO", the insured’s first name must be specified. (This comes from the
validationIssues message.) Once the claim reaches “valid for iso”, the claim will automatically be promoted to
“ability to pay”.

Example of a claim at the "ability to pay" level

Suppose you execute a POST /claim/{claimId}/validate for claim demo_sample:31 and this is the response:

{
"data": {
"attributes": {
"allValidationLevelsReached": [
{
"code": "payment",
"name": "Ability to pay"
},
{
"code": "external",
"name": "Send to external system"
},
{
"code": "iso",
"name": "Valid for ISO"
},
{
"code": "newloss",
"name": "New loss completion"
},
{
"code": "loadsave",
"name": "Load and save"
}
],
"hasErrors": false,

176 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"validationLevelReached": {
"code": "payment",
"name": "Ability to pay"
}
}
}
}

From this payload, you can determine that the claim is at “ability to pay” and has reached all previous validation levels.
The claim then meets all validation rules. (The hasErrors value is false.)

Retrieving claims from archive

After an archival process, closed claims are placed into an archive, and can only be searched for read-only information.
When you need to revert the claim back to an editable active state, you can retrieve the claim from the archive using
the POST /claim-infos/{claimInfoId}/retrieve endpoint.

Obtaining the claimInfoId to retrieve an archived claim

After an archival process, ClaimCenter adds the claimInfoID attribute to the archived claim for search and reference
purposes. When retrieving archived claims, you first must find the claimInfoId for the associated claim you want to
retrieve from archive.
To locate the claimInfoId, search or query for archived claims using /claims/v1/search/claims-v2. Using the /
claims/v1/search/claims-v2 endpoint provides claimInfoId for archived claims regardless if the caller originally
had access to the claim.
For more information about searching claims, see “Searching for active and archived claims”.
For example, the following is a response payload from a POST /claims/v1/search/claims-v2 call that searched for
an archived claim:
POST /claims/v1/search/claims-v2

{
"attributes": {
"archived": true,
"archivedAdjuster": "Betty Baker",
"claimInfoId": "cc:SLmj",
"claimNumber": "235-53-365870",
"insuredName": "Richard Jackson",
"lossDate": "2021-10-19T00:00:00.000Z",
"policyNumber": "4775949863-0",
"archiveState": {
"code": "archived",
"name": "Archived"
}
}
}

Reference the claimInfoId field for claim retrieval.

Retrieving archived claims to return to active status

After obtaining the claimInfoId, retrieve the archived claim using POST /claim/v1/claim-infos/{claimInfoId}/
retrieve with an empty request payload.

A successful retrieval returns a standard claim object in the response payload, indicating that the claim has been
retrieved from archive and has re-entered an active status.

Claims 177
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

178 Claims
chapter 16

ClaimContacts

This topic provides a high-level overview of ClaimContacts, discussing both what they are and how to work with them
through the system APIs.
For a more detailed discussion of the business functionality of ClaimContacts, refer to the Application Guide.

Overview of ClaimContacts in ClaimCenter

The following section provides an overview of ClaimContact behavior in ClaimCenter.
Note that, in ClaimCenter, ClaimContact information is stored across multiple entities, including Contact,
ClaimContact, and ClaimContactRole. The system APIs capture this information in a single resource named
ClaimContact. This documentation uses the term "ClaimContact" to refer to a ClaimContact resource in the system
APIs, or its corresponding information in the ClaimCenter Contact, ClaimContact, and ClaimContactRole entities.

What is a ClaimContact?
A ClaimContact is a person or organization who has a relationship with a claim. This includes people and
organizations who:
• Are covered by the relevant policy
• Suffered a covered loss
• Provided information relevant to the claim
• Provided a service to address the loss
For example, suppose that Ray Newton has a personal auto policy. He informs the insurer that, while driving his
Toyota, he hit Robert Farley's Honda and damaged both cars. Wilma Weeks witnessed the collision. Robert Farley's
Honda was repaired at Joe's Auto Body Shop. This claim has the following ClaimContacts:
• Ray Newton, who is covered by the personal auto policy and who suffered a loss.
• Robert Farley, who also suffered the loss.
• Wilma Weeks, who provided information relevant to the claim.
• Joe's Body Shop, who provided service to address the loss.

What is a ClaimContact related to?

Claims typically have child objects. This can include:
• A policy, which contains a copy of information from the policy that is relevant to the claim.
• One or more incidents, which represent anything that was damaged, stolen, or otherwise representative of the loss
(such as a vehicle, a property, or an injured person).
ClaimContacts 179
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• One or more exposures, which track a potential payment for one claimant from one coverage.
• One or more service requests, which are requests to outside vendors to provide service that addresses the loss.
Every ClaimContact is related to the claim itself. A ClaimContact can also be related to one or more specific child
objects.
For example, the claim described above might have the following child objects:
• The personal auto policy
◦ Ray Newton is related to this.
• A vehicle incident for Ray's damaged Toyota.
◦ Ray Newton is related to this.
• An exposure to pay Ray Newton from the policy's collision damage coverage.
◦ Ray Newton is related to this.
• A vehicle incident for Robert's damaged Honda.
◦ Robert Farley is related to this.
• An exposure to pay Robert Farley from the policy's third-party property damage coverage.
◦ Robert Farley is related to this.
• A service request to repair Robert's Honda.
◦ Joe's Body's Shop is related to this.

What is the nature of the relationship?

Every ClaimContact must have one or more roles with each object the ClaimContact is related to. A ClaimContact role
defines the nature of a relationship between a ClaimContact and the claim.
For example, the claim described above might have these ClaimContacts with the following roles:
• The claim itself
◦ Ray Newton is the insured, the reporter, and a claimant.
◦ Robert Farley is a claimant.
◦ Wilma Weeks is a witness.
• The vehicle incident for Ray's Toyota.
◦ Ray Newton is the driver.
• The vehicle incident for Robert's Honda.
◦ Robert Farley is the driver.
• The exposure to pay Ray Newton from the policy's collision coverage.
◦ Ray Newton is the claimant.
• The exposure to pay Robert Farley from the policy's third-party property damage coverage.
◦ Robert Farley is the claimant.
• The service request to repair Robert's Honda.
◦ Joe's Body's Shop is the service vendor.

Overview of ClaimContacts in Cloud API

The following section provides an overview of ClaimContact behavior as it exists in Cloud API.

ClaimContact roles
Every ClaimContact has a roles array. This is a read-only list of all the roles the ClaimContact has.
Every member of the roles array includes the following properties:
• relatedTo - the type and ID of the object that the ClaimContact is related to
• role - the role the ClaimContact has on that object

180 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• active - a Boolean identifying whether the ClaimContact actively holds the role on the claim.
The active field is used to identify ClaimContacts who previously held a role on the claim but are no longer actively
involved in the claim. For example, suppose an injured person is treated by one doctor, but then the case is reassigned
to a second doctor. Both doctors could be ClaimContacts on the claim, but active would be set to true only for the
second doctor.
You can modify the roles a ClaimContact has, but this is not done by modifying the roles array. The way in which it is
done depends on whether the role is reserved or not.

Reserved roles
A reserved role is a role that cannot be set on a ClaimContact explicitly. Instead, the role must be set implicitly through
a field, array, or action on another object.
For example, reporter is a reserved role. You cannot add this role directly to a ClaimContact. However, you can set a
Claim's reporter field to a given ClaimContact. This implicitly adds the reporter role to that ClaimContact. This also
removes the reporter role from any other ClaimContact that previous had it.
The reserved roles are defined in the [Link] file in the integration/contactroles/v1 directory.
In general, the reserved roles are either:
• Roles for which there can be at most one ClaimContact with the role. (For example, reporter is reserved. A claim
can have at most one reporter.)
• Roles that are set through an array on a non-ClaimContact object. (For example, witness is reserved. A claim can
have several witnesses. These witnesses are defined on the Claim resource's witnesses array.)
For more information on assigning a reserved role to a ClaimContact, see “Setting reserved roles” on page 183.

Non-reserved roles
A non-reserved role is a role that can be set on a ClaimContact explicitly. Every role that is not listed in the
[Link] file is a non-reserved role. For example, alternate contact is a non-reserved role. A claim
can have any number of alternate contacts, and this type of ClaimContact is not managed by an array on Claim.
For more information on assigning a non-reserved role to a ClaimContact, see “Setting non-reserved roles” on page
184.

Identifiers
When specifying a ClaimContact in a payload, there are several different identifiers you can use.
• id - The ClaimContact's system API ID. This is equal to the ClaimContact's Public ID in ClaimCenter.
• policySystemId - An identifier in the Policy Administration System that uniquely identifies the contact.
• refid - When the ClaimContact is being created in a given payload, other parts of the payload can reference it
using an arbitrary "reference id".
For more information on the different options for identifying a ClaimContact, see “Identifying the ClaimContact” on
page 186.

Masking the taxID field

The ClaimContact resource has a taxID field which stores the tax ID of the contact. In the Cloud API base
configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the
response for a GET that retrieves a contact.

{
"data": {
"attributes": {
"displayName": "Ray Newton",
"taxId": "***-**-6789"
}
}
}

ClaimContacts 181
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For some callers, such as internal or external users, the masking of tax ID may be appropriate as it protects personally
identifiable information. For other callers, such as services, this masking may cause a problem as the callers may
reference contacts internally using the tax ID.
There are two ways that the taxId field can be unmasked:
• You can configure the field so that it is always unmasked. For information on how to configure this, see the Cloud
API Developer Guide.
• You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission
will get responses with unmasked tax IDs. For information on how to configure this, see the section on API role
special permissions in the Cloud API Developer Guide.

Contrasting ClaimContacts and "contacts"

The name of the resource that captures contact information is ClaimContact. This documentation refers to contacts
related to claims as ClaimContacts.
Be aware that there are places where Cloud API uses the term "contacts" to refer to ClaimContacts:
• For endpoints that have ClaimContact as the root resource, the endpoint path refers to the resources as a "contact".
For example:
◦ GET /claim/v1/claims/{claimId}/contacts
◦ PATCH /claim/v1/claims/{claimId}/contacts/{contactId}
• When using the include query parameter to include related ClaimContacts, the resources are referred to as
"contacts". For example:
◦ GET /claim/v1/claims?include=contacts

ClaimContact endpoints
You can use the following endpoints to interact with ClaimContacts directly:

Operation Endpoint Description

GET /claims/{claimId}/contacts Retrieve the ClaimContacts for a given claim
POST /claims/{claimId}/contacts Create a new ClaimContact on the given claim
GET /claims/{claimId}/contacts/{contactId} Retrieve information about the given ClaimContact
PATCH /claims/{claimId}/contacts/{contactId} Update information on the given ClaimContact
DELETE /claims/{claimId}/contacts/{contactId} Delete the given ClaimContact
GET /claims/{claimId}/contact-role-owners Retrieve a list of objects on the given claim that can
have ClaimContacts associated with them

For reserved roles, you can also modify a ClaimContact indirectly by modifying the object that controls the role. For
example, when you execute a PATCH /claims/{claimId} and set or modify the Claim's reporter field to a given
ClaimContact, this assigns the reporter role to that ClaimContact.
The /claims/{claimId}/contact-role-owners endpoint returns all objects on the claim that can have
ClaimContacts associated with them. This includes:
• The claim itself
• The policy
• Any existing incidents
• Any existing exposures
• Any existing service requests
• Any existing negotiations or matters
◦ A negotiation is a history of the offers and counter-offers related to one disputed aspect of the loss.
◦ A matter is a collection of information pertaining to a lawsuit or potential lawsuit.

182 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Be aware that the /claims/{claimId}/contact-role-owners endpoint returns the objects that are able to have
associated ClaimContacts. These objects may or may not have ClaimContacts already associated with them. If there are
ClaimContacts associated with them, the ClaimContacts are not included in the response

External user authorization for ClaimContacts

Cloud API supports authorization for different types of callers. One of the supported caller types is external users. An
external user is a person who is known to the insurer but who is not listed as a user in the operational database. For
ClaimCenter, one of the external user types is policyholders. They are users who want to interact with information
about claims on their policies. For example, Ray Newton, who is a policyholder and wants to check on the status of a
claim filed against his personal auto policy. For more information on external user authorization, see the Cloud API
Developer Guide.
In the base configuration, external users have the ability to view and edit ClaimContact information on claims related
to their policies. But, they can view and edit only the ClaimContacts that are related to the policy with the role of
Insured. They cannot view information about ClaimContacts that are not related to the policy (such as a third-party
ClaimContact or a vendor), or that are related to the policy but without this role of Insured (such as an agent).
For example, suppose Ray Newton files a claim for an accident involving himself and another driver, David Preston.
Ray's vehicle is repaired by Sam's Towing and Auto Service.
• Ray Newton can do the following.
◦ View information about himself, as this ClaimContact is related to the policy with the role of Insured.
◦ Create new ClaimContacts (who may or may not be related to the policy with the role of Insured).
• Ray Newton cannot do the following
◦ View or edit information about David Preston.
◦ View or edit information about Sam's Towing.
◦ View or edit information about any ClaimContacts he created that are not related to the policy with the role of
Insured.

Modifying ClaimContact roles

The ClaimContact resource has two role-related array properties:
• roles - A read-only array of all roles held by the ClaimContact
• editableRoles - An editable array of non-reserved roles held by the ClaimContact
Both properties use the ContactRole schema.
You can modify the roles a ClaimContact has, but this is never done by modifying the roles array. Instead, you either
modify a field or array on a related object, or you modify the editableRoles array. Which approach to use is
determined by whether the role is reserved or not.

Setting reserved roles

A reserved role is a role that cannot be set on a ClaimContact explicitly. Instead, the role must be set by:
• Setting a field on another object
• Modifying an array on another object
• Executing an action on another object
The reserved roles are defined in the [Link] file in the integration/contactroles/v1 directory.
To assign a reserved role to a ClaimContact, you must identify the field, array, or action that implicitly sets the role.

Reserved roles that are set from a field

For example, the reporter role is set from the Claim's reporter field. To add the reporter role to a ClaimContact,
modify the Claim's reporter field so that it references the ClaimContact.

ClaimContacts 183
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Suppose that there is a claim with ID cc:610 , and there is a ClaimContact with ID cc:1306. The following is an
example of adding the reporter role to that ClaimContact:

PATCH [Link]

{
"data": {
"attributes": {
"reporter": {
"id": "cc:1306"
}
}
}
}

Reserved roles that are set from an array

As another example, the witness role is set from the Claim's witnesses array. To add the witness role to a
ClaimContact, add the ClaimContact the witnesses array.
Suppose that there is a claim with ID cc:610 , and there is a ClaimContact with ID cc:1306. The claim has no
witnesses. The following is an example of adding the witness role to ClaimContact cc:1306.

PATCH [Link]

{
"data": {
"attributes": {
"witnesses": [
{
"contact": {
"id": "cc:1306"
}
}
]
}
}
}

Keep in mind that, within the system APIs, PATCHing an array does not add new members to the existing members. It
replaces the existing members with the new members. If you want to add members to an array, you must first
determine the existing members, and then specify an array with those members and the ones you wish to add. For more
information, see “PATCHes” on page 69.

Reserved roles that are set through actions

In some situations, a reserved role is set when an action is executed on a resource other than the ClaimContact itself.
For example, when a service request is created, the ServiceRequestInstruction can specify a ClaimContact as the
CustomerContact. This ClaimContact is given the reserved role servicerequestparticipant.

Setting non-reserved roles

A non-reserved role is a role that can be set on a ClaimContact explicitly. Every role that is not listed in the
[Link] file is a non-reserved role.
To assign a non-reserved role to a ClaimContact, you must modify the ClaimContact's editableRoles array.

JSON syntax for the editableRoles array

When POSTing or PATCHing a ClaimContact, every member of the editableRoles array must include three pieces of
information:
• The role's code
• The type of object on which the ClaimContact has this role
• The ID of the object on which the ClaimContact has this role
The syntax used to specify this is:

"editableroles": [
{

184 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"role": {
"code": "<roleCode>"
},
"relatedTo": {
"type": "<parentObjectType>",
"id": "<parentObjectId>"
}
},
... <additionalRoles>

For example, the following PATCHes Claim cc:610 so that ClaimContact cc:777 has the alternate contact role (whose
code is altcontact) on the claim itself.

PATCH [Link]

{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "altcontact"
},
"relatedTo": {
"type": "Claim",
"id": "cc:610"
}
}
]
}
}
}

Similarly, this example shows how to PATCH Claim cc:610 so that ClaimContact cc:208 has the owner role (whose
code is incidentowner) on the vehicle incident whose ID is cc:102. (In other words, ClaimContact cc:208 is the owner
of the vehicle specified in vehicle incident cc:102.)

PATCH [Link]

{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "incidentowner"
},
"relatedTo": {
"type": "vehicleIncident",
"id": "cc:102"
}
}
]
}
}
}

PATCHing editableRoles scenarios

Keep in mind that, within the system APIs, PATCHing an array does not add new members to the existing members. It
replaces the existing members with the new members. If you want to add members to an array, you must first
determine the existing members, and then specify an array with those members and the ones you wish to add. For more
information, see “PATCHes” on page 69.
When PATCHing editableRoles, the following table details the possible request payloads and they way the system
APIs will respond.

If the request payload contains... ...then...

No editableRoles array The non-reserved roles on the ClaimContact remain unchanged.
An editableRoles array with one or more non- The existing non-resolved roles are replaced by the non-reserved roles
reserved roles specified in the payload.

ClaimContacts 185
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

If the request payload contains... ...then...

An empty editableRoles array All existing non-reserved roles are removed. (However, if this would result
in the ClaimContact no longer having any roles, the system API returns an
error.)
An editableRoles array with one or more reserved The system API returns an error.
roles
A roles array The system API returns an error.

Identifying the ClaimContact

There are several ways you can add ClaimContact information to a claim. You can:
• Create a new ClaimContact and specify its role
• Specify a role for a contact that is on the policy in the Policy Administration System
• Specify a role for a ClaimContact that is already on the claim
Each of these approaches uses a different property to identify the ClaimContact.

Creating a new ClaimContact and specifying its role

You can create a new ClaimContact and specify its role in the same payload using request inclusion. When using this
approach, you identify the ClaimContact by refid. For more information on this approach, see “Request inclusion” on
page 99.
The following example is the payload for a PATCH to an existing claim with id cc:402. This PATCH creates a new
ClaimContact and sets the claim's reporter to that ClaimContact. Note that the value used for refid, "newContact", is
arbitrary. Any value could be used so long as the same value is used for the reporter's refid in the data section and the
refid in the included ClaimContact section.

PATCH /claim/v1/claim/cc:402

{
"data": {
"attributes": {
"reporter": {
"refid": "newContact"
}
}
},
"included": {
"ClaimContact": [
{
"refid": "newContact",
"attributes": {
"contactSubtype": "Person",
"firstName": "Carol",
"lastName": "Daniels"
},
"method": "post",
"uri": "/claim/v1/claims/cc:402/contacts"
}
]
}
}

Specifying a role for a ClaimContact that is already on the claim

When a ClaimContact is created in ClaimCenter, it is assigned an id. This value is the ClaimContact's Public ID in
ClaimCenter.
ClaimContact roles can be specified using the id field. This is useful when the caller application is constructing the
payload for a PATCH to an existing claim, the ClaimContact already exists on the claim, and the caller application
knows the value of the ClaimContact's id.

186 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following example is the payload for a PATCH to an existing claim. This PATCH sets the Claim's reporter to the
ClaimContact whose id is cc:202.

{
"data": {
"attributes": {
"reporter": {
"id": "cc:202"
}
}
}
}

Specifying a role for a contact that is on the policy

When a draft claim is initially POSTed to ClaimCenter, information on the policy is copied from the Policy
Administration System to ClaimCenter. This typically includes contacts listed on the policy.

Policy system IDs

One of the policy contact attributes that is copied to ClaimCenter is the contact's policy system ID. Policy system ID is
a value that uniquely identifies a given type of object on the policy. For example, on a given policy, every contact's
policy system ID must be used by only one contact.
The value that is used as the policy system ID is determined by the integration code that copies the policy information
over to ClaimCenter. This code is written during implementation and will be different for each insurer and each Policy
Administration System. A policy system ID is not required to be unique across the entire Policy Administration
System. But, it is required to be unique across all instances of the given type of object on a given policy.

Specifying roles by policy system ID

In the system APIs, the name of the policy system ID field is policySystemId. Specifying roles through
policySystemId is useful in the following circumstances:

• The caller application is constructing the payload for the initial POST /claims and wants to include an existing
ClaimContact and its role in the payload. At this point, the policy information (including policy contacts) have not
yet been copied to ClaimCenter. Therefore, the relevant contact does not yet have a ClaimCenter ID.
• The caller application is constructing the payload for a PATCH to an existing draft or open claim. The application
knows the policy system ID from a previous call to the Policy Administration System, and it does not want to
execute a separate GET to retrieve the ClaimCenter ID. Therefore, it identifies the ClaimContact by policy system
ID.
Note: All resource field names are case-sensitive. Unlike refid and id, which use lower-case i's,
policySystemId uses an upper-case I.

The following example is the payload for a PATCH to an existing claim. This PATCH sets the Claim's reporter to the
ClaimContact whose policy system ID is ab:0001-1.

{
"data": {
"attributes": {
"reporter": {
"policySystemId": "ab:0001-1"
}
}
}
}

ClaimContact role constraints

Role constraints
In ClaimCenter, a role constraint is an logical expression that prevent users from assigning roles to ClaimContacts in a
manner that does not make business sense.

ClaimContacts 187
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

There are two types of role constraints:

• Entity role constraint - This identifies which type of objects can make use of the role, and how many
ClaimContacts can be associated with that object using that role (exactly one, at least one, at most one, or
unlimited).
◦ For example, this constraint could stipulate that the role of driver can be held by ClaimContacts associated with
a vehicle incident, and that there can be at most one driver on a given vehicle incident.
◦ This type of constraint can be thought of as both a "which type of object" constraint and a "how many"
constraint.
• Contact role type constraint - This identifies the subtype for which a given role is allowed.
◦ For example, this constraint could stipulate that the role of primary doctor can be held by ClaimContacts with
an associated contact whose subtype is Doctor, but not ClaimContacts with an associated contact whose subtype
is Attorney.
◦ This type of constraint can be thought of as a "which subtype" constraint.
In ClaimCenter, ClaimContact role constraints are configured in [Link]. For more
information, refer to the Configuration Guide.

Role constraint endpoints

You can use the following endpoints to retrieve information about role constraints.

Operation Endpoint Description

GET /role-constraints Retrieve a list of all contact role constraints for the given
instance of ClaimCenter
GET /role-constraints/{contactRoleId} Retrieve information for the given contact role. Note
that contactRoleId is the contact role's code, such as
reporter.

These are metadata endpoints. They return information about the configuration of the given instance of ClaimCenter,
not about any of its business resources.

Role constraint example: Doctor

This is a portion of the payload when GET /role-constraints/doctor is executed on the base configuration:

{
"data": {
"schemaConstraints": [
{
"constraints": [
{
"constraintType": "ZeroToMore"
}
],
"schema": "Claim"
},
{
"constraints": [
{
"constraintType": "ZeroToMore"
}
],
"schema": "Exposure"
}
],
"subtype": "Doctor"
},

From this payload, you can determine the following about doctor:
• It can be used as a role for a ClaimContact that is associated with a claim.
◦ There can be any number of doctors on an claim, including 0.
• It can be used as a role for a ClaimContact that is associated with an exposure.
◦ There can be any number of doctors on an exposure, including 0.

188 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The role of doctor can only be used on ClaimContacts whose associated contact has a subtype of Doctor (or a child
subtype of Doctor).

Role constraint example: Reporter

This is a portion of the payload when GET /role-constraints/reporter is executed on the base configuration:

{
"data": {
"attributes": {
"schemaConstraints": [
{
"constraints": [
{
"constraintType": "Exclusive"
},
{
"constraintType": "Required"
}
],
"schema": "Claim"
},
{
"constraints": [
{
"constraintType": "ZeroToMore"
}
],
"schema": "Exposure"
}
]

From this payload, you can determine the following about reporter:
• It can be used as a role for a ClaimContact that is associated with a claim.
◦ The role is "exclusive". (There can be at most one ClaimContact on a Claim with this role.)
◦ The role is "required". (There must be at least one ClaimContact on a Claim with this role.)
◦ Taken together, these two constraints mean there must be exactly one reporter on a Claim.
• It can be used as a role for a ClaimContact that is associated with an Exposure.
◦ There can be any number of reporters on an exposure, including 0.
• There is no subtype restriction. Therefore, the role of reporter can be used with any ClaimContact, regardless of the
subtype of its associated contact.

ClaimContacts 189
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

190 ClaimContacts
chapter 17

Incidents

This topic provides a high-level overview of incidents, discussing both what they are and how to work with them
through Cloud API.
For a more detailed discussion of the business functionality of incidents, refer to the Application Guide. For a more
detailed discussion of the configuration of incidents, refer to the Configuration Guide.

Overview of incidents in ClaimCenter

The following section provides an overview of incident behavior in ClaimCenter. For a complete description of the
business functionality of incidents, see the Application Guide.

What is an incident?
An incident is a collection of information about an item that was lost or damaged, such as:
• A vehicle
• A property (such as a house or a fence)
• A person suffering one or more injuries
For example, a vehicle incident can store the following information:
• Where was the point of collision?
• Who was the driver?
• What is the severity of the damage?
• Were the airbags deployed?
• Is the vehicle so damaged that it is considered a "total loss"?

Incident subtypes
Incident is a subtyped entity. In the base configuration, there are several levels to the subtyping.

For example, the following list identifies a portion of the base configuration hierarchy for incidents.
• Injury
• Property
◦ Fixed property
▪ Dwelling
▪ Other structure
Incidents 191
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ Living expense
◦ Mobile property
▪ Baggage
▪ Property contents
▪ Vehicle
• Trip

Incidents and policy types

Every claim is attached to a policy with a specific policy type, such as PersonalAuto or HOPHomeowners. Every
incident type is indirectly associated with one or more of these policy types. Incidents of a given type can be created
only on claims with a matching policy type.
For example, vehicle incidents are associated with four policy types:
• BusinessAuto
• Businessowners
• PersonalAuto
• PersonalTravel

You can create vehicle incidents on a claim whose policy type is one of these types. You cannot create vehicle incidents
on a claim whose policy type is not one of these types.
The association between incident type and policy type occurs in the Line of Business typelists. For more information
see the Configuration Guide.

Incidents and ClaimContacts

Incidents can have ClaimContacts associated with them. When a ClaimContact is associated with an incident, the
ClaimContact also has a role defining the relationship.
For example, with a vehicle incident, a ClaimContact could be:
• An owner
• A driver
• A passenger
For more information on ClaimContacts, see “ClaimContacts” on page 179.

Incidents and exposures

Every exposure is associated with an incident. You cannot create an exposure without an incident. For more
information on exposures, see “Exposures” on page 205.

Overview of incidents in Cloud API

In the Cloud API base configuration, every supported incident type typically has five endpoints for the CRUD
operations. For example, vehicle incidents has the following endpoints:
• GET /claims/{claimId}/vehicle-incidents
• POST /claims/{claimId}/vehicle-incidents
• GET /claims/{claimId}/vehicle-incidents/{incidentId}
• PATCH /claims/{claimId}/vehicle-incidents/{incidentId}
• DELETE /claims/{claimId}/vehicle-incidents/{incidentId}
Insurers can also add custom subtypes to the hierarchy. For more information on how to generate endpoints for custom
incident subtypes, see the Cloud API Developer Guide.

Minimum creation criteria for incidents

In the base configuration, there are no required fields for creating any type of incident. All fields are optional.

192 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Inline damageables
An incident can also be associated with a damageable. A damageable is a data model entity that captures information
about the covered object that is inherent to the object itself. For example, the base configuration has a Vehicle entity,
which is a damageable used by VehicleIncident.
• Information that is inherent to the vehicle, such as Make, Model, and Vin (Vehicle identification number) is stored
on Vehicle.
• Information about damage to the vehicle, such as the CollisionPoint and whether the AirbagsDeployed, is stored
on the VehicleIncident.
When an incident has an associated damageable, you could theoretically have separate endpoints for the incident and
the damageable. However, it is sometimes more convenient to embed the damageable information in the incident.
When this is done, the damageable is referred to as an inline damageable. This is because the damageable information
appears inline in the schema.

Incompatible incident types

You cannot create an incident whose type is incompatible with the policy type. For example, you cannot create a
dwelling incident on a claim associated with a personal auto policy. If you attempt to do so, Cloud API responds with
an error message similar to the following:

{
"status": 404,
"errorCode": "[Link]",
"userMessage": "No resource was found at path /claim/v1/claims/cc:34/dwelling-incidents"
}

External user authorization for incidents

Cloud API supports authorization for different types of callers. One of the supported caller types is external users. An
external user is a person who is known to the insurer but who is not listed as a user in the operational database. For
ClaimCenter, one of the external user types is policyholders. They are users who want to interact with information
about claims on their policies. For example, Ray Newton, who is a policyholder and wants to check on the status of a
claim filed against his personal auto policy. For more information on external user authorization, see the Cloud API
Developer Guide.
In the base configuration, external users have the ability to view and edit incident information on claims related to their
policies. But, they can view and edit only the incidents that are related to a ClaimContact that is related to the policy
with the role of Insured. They cannot view information about any other type of incident (such as a third-party incident).
For example, suppose Ray Newton files a claim for an accident involving himself and another driver, David Preston.
The claim has two vehicle incidents: one for Ray Newton's vehicle and one for David Preston's vehicle.
• Ray Newton can do the following.
◦ View information about his vehicle incident, as this incident is related to himself, and he is related to the policy
with the role of Insured.
◦ Create new incidents (that may or may not be related to a ClaimContact that is an Insured on the policy).
• Ray Newton cannot do the following
◦ View or edit information about David Preston's vehicle incident.
◦ View or edit information about any incidents he created that are not related to a ClaimContact that is an Insured
on the policy.

Fixed property incidents

A fixed property incident is an object that captures loss information about a fixed piece of property (such as a house or
a fence).
In ClaimCenter, the FixedPropertyInident entity has two subtypes: DwellingIncident (for fixed properties that are
dwellings, such as a house) and OtherStructureIncident (for fixed properties that are not dwellings, such as fences).
Cloud API provides endpoints for all three types of incidents.

Incidents 193
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Managing fixed property incidents

Overview of the fixed property incident parent
At the parent level, the fixed property incident is an object that captures loss information about a fixed piece of
property (such as a building). Cloud API supports the management of fixed property incidents at this parent level, as
opposed to working at the child level with either dwelling incidents or other structure incidents.
A fixed property incident typically includes an inline damageable called location, with fields that describe inherent
qualities of the property's location, such as address. The fixed property incident also contains additional information
specific to the loss, such as lossparty and severity. You do not have to specify location when you create a fixed
property incident. If you do want to specify location, you can either:
• Specify an existing location on the policy by providing its policySystemId.
• Specify an existing location on the claim by providing its ClaimCenter id.
• Create a new location by providing its attributes inline.
Unlike some other damageables, a location cannot be created as a referenced resource in the included section and
then specified by refid. A new location must be created as an inlined damageable.

Endpoints for managing fixed property incidents

Use the following endpoints to manage fixed property incidents:
• GET /claims/{claimId}/fixed-property-incidents
• POST /claims/{claimId}/fixed-property-incidents
• GET /claims/{claimId}/fixed-property-incidents/{incidentId}
• PATCH /claims/{claimId}/fixed-property-incidents/{incidentId}
• DELETE /claims/{claimId}/fixed-property-incidents/{incidentId}
For example, the following request creates a fixed property incident for claim cc:73. In the request, the inline
damageable (the incident's location) is included, and it is created as an inlined resource.

POST /claim/v1/claims/cc:73/fixed-property-incidents

{
"data": {
"attributes": {
"location": {
"address": {
"addressLine1": "1313 Monroe Lane",
"city": "Pomona",
"country": "US",
"state": {
"code": "CA"
}
},
"primaryLocation": false
},
"severity" : {
"code" : "major-prop"
}
}
}
}

Managing dwelling incidents

A dwelling incident is an object that captures loss information about a place where people live. In the data model,
DwellingIncident is a subtype of FixedPropertyIncident.

A dwelling incident typically includes an inline damageable called location, with fields that describe inherent
qualities of the dwelling's location, such as address. The dwelling incident also contains additional information
specific to the loss, such as damagedAreaSize and severity. You do not have to specify location when you create a
dwelling incident. If you do want to specify location, you can either:
• Specify an existing location on the policy by providing its policySystemId.

194 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• Specify an existing location on the claim by providing its ClaimCenter id.

• Create a new location by providing its attributes inline.
Unlike some other child objects, a location cannot be created as a referenced resource in the included section and
then specified by refid. A new location must be created as an inlined damageable.

Endpoints for managing dwelling incidents

Use the following endpoints to manage dwelling incidents:
• GET /claims/{claimId}/dwelling-incidents
• POST /claims/{claimId}/dwelling-incidents
• GET /claims/{claimId}/dwelling-incidents/{incidentId}
• PATCH /claims/{claimId}/dwelling-incidents/{incidentId}
• DELETE /claims/{claimId}/dwelling-incidents/{incidentId}
For example, the following request creates a dwelling incident for claim cc:61. In the request, the inline damageable
(the incident's location) is included, and it is specified by policySystemId.

POST /claim/v1/claims/cc:61/dwelling-incidents

{
"data": {
"attributes": {
"description": "water from heavy rains leaked through the roof damaging walls and floor.",
"location" : {
"policySystemId" : "pcdwl:0001-1"
} ,
"yearsInHome" : 7
}
}
}

Managing other structure incidents

An other structure incident is an object that captures loss information about structures other than a main dwelling, such
as a detached garage, shed, or fence.
Other structure incidents do not make use of any inline damageable.

Endpoints for managing other structure incidents

Use the following endpoints to manage other structure incidents:
• GET /claims/{claimId}/other-structure-incidents
• POST /claims/{claimId}/other-structure-incidents
• GET /claims/{claimId}/other-structure-incidents/{incidentId}
• PATCH /claims/{claimId}/other-structure-incidents/{incidentId}
• DELETE /claims/{claimId}/other-structure-incidents/{incidentId}
For example, the following request creates a dwelling incident for claim cc:77.

POST /claim/v1/claims/cc:77/other-structure-incidents

{
"data": {
"attributes": {
"description": "Shed damaged by falling tree",
"lossParty": {
"code": "insured"
}
}
}
}

Incidents 195
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

General incidents
In some cases, you may want to create an incident at the Incident supertype level. This can be appropriate for claims
that make use of incidents not covered at one of the subtype levels. For example, an insurer may offer a special type of
policy for covering fine art, such as paintings. The insurer opts not to create a new incident subtype for fine art losses
and uses the Incident supertype instead.
In Cloud API, you can create incidents at the Incident supertype level by using the /general-incidents endpoints.
In the base configuration, this provides access to fields available to all incident types, such as description,
lossParty, and severity.

General incidents can also make use of assessment content items. An assessment content item is an individual item
covered by the policy.

Endpoints for managing general incidents

Use the following endpoints to manage general incidents:
• GET /claims/{claimId}/general-incidents
• POST /claims/{claimId}/general-incidents
• GET /claims/{claimId}/general-incidents/{incidentId}
• PATCH /claims/{claimId}/general-incidents/{incidentId}
• DELETE /claims/{claimId}/general-incidents/{incidentId}
For example, the following request creates a general incident for claim cc:10.

POST /claim/v1/claims/cc:10/general-incidents

{
"data": {
"attributes": {
"description": "Haywain Triptych painting",
"lossParty": {
"code": "insured"
},
"severity": {
"code": "severe-gen"
}
}
}
}

Endpoints for managing general incident assessment content items

Use the following endpoints to manage general incident assessment content items:
• GET /claims/{claimId}/general-incidents/{incidentId}/assessment-content-items
• POST /claims/{claimId}/general-incidents/{incidentId}/assessment-content-items
• GET /claims/{claimId}/general-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}
• PATCH /claims/{claimId}/general-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}
• DELETE /claims/{claimId}/general-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}

For example, the following request creates an assessment content item for general incident cc:567 on claim cc:10.

POST /claim/v1/claims/cc:10/general-incidents/cc:567/assessment-content-items

{
"attributes": {
"itemComment": "Left portion of Haywain Triptych",
"numberOfItems": 1,
"purchaseCost": {
"amount": "20000.00",
"currency": "usd"
}

196 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

Injury incidents
An injury incident is an object that captures loss information about a single injury that a claimant suffered.
An injury incident typically includes an inline damageable named injuredPerson, with fields that describe inherent
qualities of the person, such as firstName and lastName. The injury incident also contains additional information
specific to the injury, such as ambulenceused, primaryDoctor, and treatmentType. You do not have to specify
injuredPerson when creating an injury incident. If you do want to specify injuredPerson, you can either:

• Specify an existing ClaimContact on the policy by providing its policySystemId.

• Specify an existing ClaimContact on the claim by providing its ClaimCenter id.
• Create a new ClaimContact in the included section and reference that ClaimContact by refid.

Endpoints for managing injury incidents

Use the following endpoints to manage injury incidents:
• GET /claims/{claimId}/injury-incidents
• POST /claims/{claimId}/injury-incidents
• GET /claims/{claimId}/injury-incidents/{incidentId}
• PATCH /claims/{claimId}/injury-incidents/{incidentId}
• DELETE /claims/{claimId}/injury-incidents/{incidentId}
For example, the following request creates an injury incident for claim cc:332. In the request, the injury incident's
injuredPerson is provided, and it is specified using the ClaimCenter id.

POST /claim/v1/claims/cc:332/injury-incidents

{
"data": {
"attributes": {
"bodyParts": [
{
"primaryBodyPart": {
"code": "head"
}
}
],
"description": "Potential vision loss",
"detailedInjuryType": {
"code": "58"
},
"generalInjuryType": {
"code": "specific"
},
"injuredPerson": {
"id": "cc:102"
},
"lossParty": {
"code": "third_party"
},
"lostWages": true,
"severity": {
"code": "major-injury"
},
"treatmentType": {
"code": "hospital"
}
}
}
}

Living expenses incidents

A living expenses incident is an object that captures loss information about expenses incurred as a result of the loss of
use of a property. (For example, staying in a hotel while a damaged home is repaired.)

Incidents 197
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Endpoints for managing living expense incidents

Use the following endpoints to manage living expense incidents:
• GET /claims/{claimId}/living-expense-incidents
• POST /claims/{claimId}/living-expense-incidents
• GET /claims/{claimId}/living-expense-incidents/{incidentId}
• PATCH /claims/{claimId}/living-expense-incidents/{incidentId}
• DELETE /claims/{claimId}/living-expense-incidents/{incidentId}
For example, the following request creates a living expense incident for cc:5433.

POST /claim/v1/claims/cc:5433/living-expenses-incidents

{
"data": {
"attributes": {
"description": "7-day hotel stay during flood damage repair",
"lossParty" : {
"code" : "insured"
},
"startDate" : "2020-08-31T07:00:00.000Z"
}
}
}

Mobile property incidents

A mobile property incident is an incident that tracks information about lost or damaged items that are moveable, such
as:
• Lost baggage covered by a travel policy
• Stolen jewelry covered by a home owner's policy
• A damaged vehicle covered by a personal auto policy
In ClaimCenter, there is a MobilePropertyIncident entity. But incidents are typically not created at this level. They
are created at one of the child levels: BaggageIncident, PropertyContentsIncident, or VehicleIncident.
Some mobile property incidents make use of assessment content items. An assessment content item is an individual
item covered by the policy, such as a laptop in lost baggage or jewelry stored in a house safe.

Baggage incidents
A baggage incident is an object that captures loss information about a piece of baggage that was lost or damaged
during a covered trip. Travel policies may also cover individual items within the baggage. Each covered item is an
assessment content item.
In ClaimCenter, baggage incidents are stored in the BaggageIncident entity, which is a subtype of
MobilePropertyIncident. Assessment content items are stored in the AssessmentContentItem entity.

In Cloud API, the Claim API has multiple sets of endpoints for baggage incident information:
• One set for the baggage incident itself
• One set for assessment content items
In each set, there is a collection GET, a POST, an element GET, a PATCH, and a DELETE.

Endpoints for managing baggage incidents

Use the following endpoints to manage baggage incidents:
• GET /claims/{claimId}/baggage-incidents
• POST /claims/{claimId}/baggage-incidents
• GET /claims/{claimId}/baggage-incidents/{incidentId}

198 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• PATCH /claims/{claimId}/baggage-incidents/{incidentId}
• DELETE /claims/{claimId}/baggage-incidents/{incidentId}
For example, the following request creates a baggage incident for claim cc:76.

POST /claim/v1/claims/cc:76/baggage-incidents

{
"data": {
"attributes": {
"baggageType": {
"code": "suitcase",
},
"description": "Item lost in transit",
"relatedTripRiskUnit": {
"id": "cc:SHEXDGWJHfyVMKSxBLFZ9",
}
}
}
}

Endpoints for managing assessment content items

Use the following endpoints to manage assessment content items:
• GET /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items
• POST /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items
• GET /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}
• PATCH /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}
• DELETE /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}

For example, the following request retrieves the assessment content items for baggage incident cc:443 on claim cc:76.

GET /claim/v1/claims/cc:76/baggage-incidents/cc:443/assessment-content-items

RESPONSE:

{
"count": 2,
"data": [
{
"attributes": {
"contentCategory": {
"code": "computers",
"name": "Computers"
},
"contentSchedule": {
"code": "travel",
"name": "Travel"
},
"description": "iPad Pro",
"id": "cc:SxxdfwnGPPus1JO9lUrPh",
"incidentOrder": 1,
"numberOfItems": 1,
"purchaseCost": {
"amount": "760.00",
"currency": "usd"
}
},
...
},
{
"attributes": {
"contentCategory": {
"code": "cameras",
"name": "Cameras"
},
"contentSchedule": {
"code": "travel",
"name": "Travel"
},
"description": "Nikon TX-40",
"id": "cc:SC3nyG7KaG6yypqDvE76X",
"incidentOrder": 2,
"numberOfItems": 1,
"purchaseCost": {

Incidents 199
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"amount": "1200.00",
"currency": "usd"
}
},
...

Property contents incidents

Some types of policies cover property owned by the insured that is stored in a given location. For example:
• On a homeowner's policy, jewelry or electronics could be covered on the policy.
• On a business owner's policy, business equipment could be covered on the policy.
A property contents incident is an object that contains a set of these covered items. Each covered piece is an
assessment content item.
In ClaimCenter, property content incidents are stored in the PropertyContentIncident entity. Items covered by a
property contents incident are usually small enough to be moveable. Thus, the PropertyContentIncident entity is a
subtype of MobilePropertyIncident. Assessment content items are stored in the AssessmentContentItem entity.
In Cloud API, the Claim API has multiple sets of endpoints for property content incident information:
• One set for the property content incident itself
• One set for assessment content items
In each set, there is a collection GET, a POST, an element GET, a PATCH, and a DELETE.
When working with assessment content items, there are differences between the ClaimCenter user interface and Cloud
API.
• In the user interface, the Notes field is read-only, and its content is populated by business rules. In Cloud API, the
corresponding field, itemComment, is editable.
• In the user interface, the Description is required. The Cloud API, the corresponding field, description, is not
required.

Endpoints for managing property contents incidents

Use the following endpoints to manage property contents incidents:
• GET /claims/{claimId}/property-contents-incidents
• POST /claims/{claimId}/property-contents-incidents
• GET /claims/{claimId}/property-contents-incidents/{incidentId}
• PATCH /claims/{claimId}/property-contents-incidents/{incidentId}
• DELETE /claims/{claimId}/property-contents-incidents/{incidentId}
For example, the following request creates a property contents incident for claim cc:117.

POST /claim/v1/claims/cc:117/property-contents-incidents

{
"data": {
"attributes": {
"description": "Items stolen during burglary",
"location": {
"address": {
"id": "cc:SztgJU4ZkQ_tZx0rIW2fL",
}
},
"primaryLocation": false
}
}
}
}

Endpoints for managing assessment content items

Use the following endpoints to manage assessment content items:

200 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• GET /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items
• POST /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items
• GET /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}
• PATCH /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}
• DELETE /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items/
{assessmentContentItemId}

For example, the following request creates an assessment content item for property contents incident cc:505 on claim
cc:117.

POST /claim/v1/claims/cc:117/property-contents-incidents/cc:505/assessment-content-items

{
"data": {
"attributes": {
"contentCategory": {
"code": "jewelry"
},
"contentSchedule": {
"code": "homeowners"
},
"description": "Necklace",
"numberOfItems": 1,
"purchaseCost": {
"amount": "1200.00",
"currency": "usd"
}
}
}
}

Vehicle incidents
A vehicle incident is an object that captures loss information about a vehicle.
A vehicle incident typically includes an inline damageable called vehicle, with fields that describe inherent qualities
of the vehicle, such as make, model, and licenseplate. The vehicle incident also contains additional information
specific to the loss, such as airbagsdeployed, collisionpoint, and driver. You do not have to specify vehicle
when creating a vehicle incident. If you do want to specify vehicle, you can either:
• Specify an existing vehicle on the policy by providing its policySystemId.
• Specify an existing vehicle risk unit on the claim by providing its ClaimCenter id.
• Create a new vehicle by providing its attributes inline.
Unlike some other inline damageables, a vehicle cannot be created as a referenced resource in the included section
and then specified by refid. A new vehicle must be created as an inlined damageable.

Endpoints for managing vehicle incidents

Use the following endpoints to manage property contents incidents:
• GET /claims/{claimId}/vehicle-incidents
• POST /claims/{claimId}/vehicle-incidents
• GET /claims/{claimId}/vehicle-incidents/{incidentId}
• PATCH /claims/{claimId}/vehicle-incidents/{incidentId}
• DELETE /claims/{claimId}/vehicle-incidents/{incidentId}
For example, the following request creates a vehicle incident for claim cc:1134. The vehicle incident's vehicle is
provided, and it is created as an inlined resource.

POST /claim/v1/claims/cc:1134/vehicle-incidents

{
"data": {
"attributes": {

Incidents 201
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"collisionPoint": {
"code": "front"
},
"damageDescription": "Damage to bumper and front panels",
"driver": {
"id": "cc:102"
},
"severity": {
"code": "moderate-auto"
},
"vehicle": {
"licensePlate": "7FDG745",
"make": "Mercury",
"model": "Sable",
"state": {
"code": "CA",
"name": "California"
},
"vin": "6GYF54637HD645370",
"year": 1993
}
}
}
}

Trip incidents
Overview of trip incidents
A trip incident is an incident that captures loss information related to a covered trip on a travel policy, such as a
Personal Travel policy.

Trip incidents in ClaimCenter

Trip incidents are managed using the TripIncident entity. This entity has two arrays:
• An array of TripAccommondations
◦ Members of this array track the original and changed accommodation on the travel schedule
• An array of TripSegments
◦ Members of this array track the original and changed segments on the travel schedule

Trip incidents in Cloud API

In Cloud API, the Claim API has multiple sets of endpoints for trip incident information:
• One set for the trip incident itself
• One set for trip accommodations
• One set for trip segments
In each set, there is a collection GET, a POST, an element GET, a PATCH, and a DELETE.
When POSTing a trip incident, trip accommodation, or trip segment, there are no required fields.

Managing trip incidents

Use the following endpoints to manage trip incidents:
• GET /claims/{claimId}/trip-incidents
• POST /claims/{claimId}/trip-incidents
• GET /claims/{claimId}/trip-incidents/{incidentId}
• PATCH /claims/{claimId}/trip-incidents/{incidentId}
• DELETE /claims/{claimId}/trip-incidents/{incidentId}
For example, the following request creates a trip incident for claim cc:411.

POST /claim/v1/claims/cc:411/trip-incidents

202 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"data": {
"attributes": {
"description": "Flight cancelled due to airline strike",
"tripRiskUnit": {
"id": "cc:SHEXDGWJHfyVMKSxBLFZ9"
}
}
}
}

Managing trip accommodations

Use the following endpoints to manage a trip incident's trip accommodations:
• GET /claims/{claimId}/trip-incidents/{incidentId}/trip-accommodations
• POST /claims/{claimId}/trip-incidents/{incidentId}/trip-accommodations
• GET /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-accommodations/
{accommodationId}
• PATCH /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-accommodations/
{accommodationId}
• DELETE /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-accommodations/
{accommodationId}

For example, the following request creates a trip accommodation for trip incident cc:9811 on claim cc:411.

POST /claim/v1/claims/cc:411/trip-incidents/cc:9811/trip-accommodations

{
"data": {
"attributes": {
"cancelOnly": false,
"paidAmount": {
"amount": "508.00",
"currency": "aud"
},
"propertyName": "Yotel Syndey"
}
}
}

Managing trip segments

Use the following endpoints to manage a trip incident's trip segments:
• GET /claims/{claimId}/trip-incidents/{incidentId}/trip-segments
• POST /claims/{claimId}/trip-incidents/{incidentId}/trip-segments
• GET /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-segments/{segmentId}
• PATCH /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-segments/{segmentId}
• DELETE /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-segments/{segmentId}
For example, the following request creates a trip segment for trip incident cc:9811 on claim cc:411.
POST /claim/v1/claims/cc:411/trip-incidents/cc:9811/trip-segments

{
"data": {
"attributes": {
"arrivalDateTime": "2022-10-16T00:00:00.000Z",
"cancelOnly": false,
"carrierName": "Jetstar",
"carrierNumber": "607",
"departureDateTime": "2022-10-16T00:00:00.000Z",
"otherFees": {
"amount": "50.00",
"currency": "usd"
},
"portOfDisembarkation": "Brisbane",
"portOfEmbarkation": "Sydney",
"transportType": {
"code": "airline"
}
}

Incidents 203
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

204 Incidents
chapter 18

Exposures

This topic provides a high-level overview of exposures, discussing both what they are and how to work with them
through the system APIs.
For a more detailed discussion of the business functionality of exposures, see the Application Guide. For a more
detailed discussion of the configuration of exposures, see the Configuration Guide.

Overview of exposures in ClaimCenter

The following section provides an overview of exposure behavior in ClaimCenter.

What is an exposure?
An exposure is an object associated with a claim which is used to track a potential payment or a set of related potential
payments. Every exposure is linked to one coverage (where the money is "coming from") and one claimant (where the
money is "going to").
For example, suppose that Ray Newton has a personal auto policy. He informs the insurer that, while driving his
Toyota, he hit Robert Farley's Honda and damaged both cars. Robert Farley also suffered a neck injury. The associated
claim would have three exposures to track these potential payments:

Claimant Coverage
A potential payment to... Ray Newton ...from the policy's... collision coverage ...to pay for repairs to Ray's
car.
A potential payment to... Robert Farley ...from the policy's... third-party property damage ...to pay for repairs to
coverage Robert's car.
A potential payment to... Robert Farley ...from the policy's... third-party bodily damage coverage ...to pay for Robert's
medical bills to treat his
neck injury.

Some exposures result in a single payment. This is likely to be true for the first and second exposure in the previous
example. Typically, repairs to a vehicle can be covered in a single payment. Other exposures manage a set of related
payments. This could be true for the third exposure in the previous example. Medical treatment might occur over an
extended period of time, and multiple payments may be needed, one for each treatment.

Exposures and coverages

Every exposure is directly linked to a coverage type. A coverage type is a type of loss specified on a policy. For
example, for personal auto policies, PACollisionCov and PALiabilityCov are two coverage types. PACollisionCov
Exposures 205
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

covers damage to a vehicle owned by the insured. PALiabilityCov covers damages to vehicles owned by a third party
where the damage was caused by the insured.
Every exposure is indirectly linked to an exposure type. An exposure type is a set of information to gather for an
exposure. For example, VehicleDamage is an exposure type. It consists of information to gather about a damaged
vehicle, such as where on the vehicle is the damage, who was the driver, and were the airbags deployed.
Two exposures can be linked to the same exposure type, even if the coverages are different. For example,
PACollisionCov and PALiabilityCov are different coverages, but they can both involve damaged vehicles. The same
set of information needs to be gathered about a damaged vehicle, regardless of which coverage is involved. Therefore,
the two coverages are mapped to a single exposure type - the VehicleDamage exposure type. This exposure type is
used to determine the information to gather during the claims process.
Some coverages link to multiple exposure types. Therefore, ClaimCenter does not link coverage types directly to
exposure types. Instead, ClaimCenter links them through coverage subtypes. A coverage subtype is a value that links a
coverage type to an exposure type. For example:
• PACollisionCov is a coverage subtype that links the PACollisionCov coverage to the VehicleDamage exposure
type. (In this case, the coverage type and coverage subtype have the same name.)
• PALiabilityCov_vd is a coverage subtype that links the PALiabilityCov coverage to the VehicleDamage
exposure type.
When you create an exposure, you must specify both its coverage and coverage subtype.

Exposures and reserve lines

When an exposure is created, ClaimCenter also creates a reserve line for the exposure. A reserve line is an amount of
money set aside for expected payments related to a given exposure. Insurers are often legally required to create reserve
lines to ensure that they maintain financial solvency.
Reserve lines can be created:
• Automatically by business rules
• Manually by adjusters
When a payment is made from an exposure, the money comes from this reserve line.

Exposures and validation levels

Just as is the case with claims, during an exposure's lifecycle, an exposure passes through one or more levels of
maturity. Within ClaimCenter, these are called validation levels. The base configuration comes with the following
levels, which are common to both claims and exposures:
• Load and save - The claim/exposure has enough information to be saved to the database.
• New loss completion - The claim/exposure has enough information to be assigned to an adjuster.
• Valid for ISO - The claim/exposure has enough information to be filed with ISO. (ISO is a national database used
in the United States to verify that the same loss is not being filed with multiple insurers.)
• Send to external (systems) - The claim/exposure has enough information to send information about it to external
systems within the insurer, such as a Policy Administration System that may be trying to assess policy renewal
rates.
• Ability to pay - The claim/exposure has enough information such that payments can be written for it.
Note: In the base configuration, the "load and save" level applies only to claims and exposures that are being
imported through the ClaimCenter SOAP-based ClaimAPI API. Draft exposures submitted through the system
APIs do not need to pass any level. In order for a draft claim to be promoted to an open claim, the draft claim
and all of its exposures must pass both the "load and save" level and the "new loss completion" level. For more
information, see “Executing FNOL” on page 129.
A exposure's validation level is determined and enforced by a set of exposure validation rules. Whenever a change is
made to an exposure, the validation rules determine if the exposure can be advanced to a later stage of validation. The
validation rules also prevent an exposure from moving backwards to a lower level of validation. For more information
on validation rules, see the Gosu Rules Guide.

206 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

A claim and its exposures are not necessarily always at the same validation level. For example, suppose there is a claim
with two exposures. It is possible for the claim to be at "send to external" while one of the exposures is at "new loss
completion" and other is at "ability to pay".
In order to make a payment, both the claim and the exposure from which the payment is coming must be at "ability to
pay". If a claim has multiple exposures, and the claim and one of the exposures are at "ability to pay", you can make
payments from that one exposure, even though the other exposures are not yet at "ability to pay".

Exposures and ClaimContacts

Every exposure has at least one ClaimContact - the claimant. Exposures can have additional ClaimContacts associated
with them.
For more information on ClaimContacts, see “ClaimContacts” on page 179.

Exposures and incidents

Every exposure is associated with an incident. An incident is a collection of information that typically represents an
item that was lost or damaged, such as:
• A vehicle
• A property (such as a house or a fence)
• A person suffering one or more injuries
You cannot create an exposure without an incident. For more information on incidents, see “Incidents” on page 191.

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": ...

Exposures 207
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"ClaimContact": ...
}
}

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 [Link]

Response payload (snippet)

"RUNumber": 1,
"coverages": [
{
...
"coverageType": {
"code": "PACollisionCov",
"name": "Collision"
}

208 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

...
}
],
"id": "cc:9",
"vehicle": {
...
"id": "demo_sample:4",
"make": "Honda",
"model": "Civic"
...

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"
},
...

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” on page 317.

Request to determine the coverage subtype

GET [Link]
?typekeyFilter=category:cn:[Link]

Response payload (snippet)

"description": "Subtype of coverage, filtered by CoverageType",

"name": "CoverageSubtype",
"typeKeys": [
{
"code": "PACollisionCov",
"description": "Collision",
"name": "Collision",
"priority": -1
}
]

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"
},
...

Exposures 209
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

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” on page 99.
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 [Link]

Response payload (snippet)

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

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"
},
...

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” on page 99. 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.

210 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

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"
}
]
}
}

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 [Link]
policy/vehicle-risk-units/cc:121

Exposures 211
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Response payload (snippet)

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

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"
}
]
}
}

Querying for and modifying exposures

You can query for exposures using:
• GET /claims/{claimId}/exposures
• GET /claims/{claimId}/exposures/{exposureId}
You can modify an exposure using:
• PATCH /claims/{claimId}/exposures/{exposureId}

Assigning exposures
Every exposure is assigned to a group and a user in that group. The assigned user has the primary responsible for
managing the exposure.
Most exposures are assigned to the same user and group that owns the claim. However, exposures occasionally require
special expertise that require assignment to a different user and group than that of the claim. For example, suppose
there is a personal auto claim that includes three exposures: two exposures for damaged vehicles and one exposure for
medical payments related to a fatal injury. The claim and the vehicle exposures are routine and can all be assigned to
the same group and user. But the injury exposure is likely to involve a significant payment or litigation. This exposure
is assigned to a group and user that specialize in fatalities.

212 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

When you create an exposure through the system APIs, ClaimCenter automatically executes the exposure assignment
rules to initially assign the exposure to a group and user. You can use the POST /claims/{claimId}/exposures/
{exposureId}/assign endpoint to reassign the exposure as needed.

Note: The functionality for assigning exposures is a subset of the functionality for assigning activities. All
assignment options that are applicable to both activities and exposures have the same behavior.

Assignment options
An exposure can be assigned through the system APIs in the following ways:
• To a specific group and user in that group
• To a specific group only (and then ClaimCenter uses assignment rules to select a user in that group)
• To the claim owner
• By re-running the exposure assignment rules
◦ This can be appropriate if you have modified the exposure since the last time assignment rules were run and the
modification might affect who the exposure would be assigned to.
The root resources for the /exposures/{exposureId}/assign endpoints is ExposureAssignee. This resource
specifies assignment criteria. The schema has the following fields:

Field Type Description

autoAssign Boolean Whether to assign the exposure using assignment rules
claimOwner Boolean Whether to assign the exposure to the claim owner
groupId string The ID of the group to assign the exposure to
userId string The ID of the user to assign the exposure to

The ExposureAssignee resource cannot be empty. It must specify a single logical assignment option (group and user,
group only, claim owner, or automatic assignment).
For more information on how assignment rules execute assignment, see the Gosu Rules Guide.

Assignment example - Assigning to a specific group (and user)

The following assigns exposure cc:48 (on claim cc:34) to group demo_sample:31 (Auto1 - TeamA) and user
demo_sample:2 (Sue Smith).

POST /claim/v1/claims/cc:34/exposures/cc:48/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:2"
}
}
}

The following assigns exposure cc:48 (on claim cc:34) to group demo_sample:31 (Auto1 - TeamA). Because no user
has been specified, ClaimCenter will execute assignment rules to assign the exposure to a user in group demo-sample:
31.

POST /claim/v1/claims/cc:34/exposures/cc:48/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31"
}
}
}

Note that there is currently no endpoint that returns groups or group IDs. To assign exposures to a specific group, the
caller application must determine the group ID using some method other than a groups system API.

Exposures 213
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Assignment example - Assigning to the claim owner

The following assigns exposure cc:48 (from claim cc:34) to the group and user that owns the parent claim.

POST /claim/v1/claims/cc:34/exposures/cc:48/assign

{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}

Assignment example - Using automated assignment

The following assigns exposure cc:48 (from claim cc:34) using automated assignment rules.

POST /claim/v1/claims/cc:34/exposures/cc:48/assign

{
"data": {
"attributes": {
"autoAssign" : true
}
}
}

Additional exposure endpoints

The system APIs provide additional endpoints to interact with exposures.

Deleting draft exposures

During the FNOL process, the claim passes through two states: draft and open.
• A draft claim is a claim that has been saved to the ClaimCenter database, but there is not yet enough information
for the claim to enter the adjudication process. Draft claims are not assigned to any user.
• An open claim is a claim that has been saved to the ClaimCenter database with enough information to enter the
adjudication process. Once a claim becomes open, it is assigned to an adjuster.
A draft exposure is an exposure on a draft claim. While a claim is in a draft state, you can delete any exposures created
on the claim using the DELETE /claims/{claimId}/exposures/{exposureId} endpoint.
Executing a POST /claims/{claimId}/submit on a draft claim promotes the claim and all of its exposures to open
status. Once a claim has been submitted, you can no longer delete its exposures.

Validating exposures
Similar to claim validation, the POST /claim/{claimId}/exposures/{exposureId}/validate endpoint returns
allvalidation levels reached for the given exposure. It can also be used to determine what conditions must be met for
the exposure to advance to a given validation level.
Checking an exposure's validation level can be useful in the following situations:
• You want to determine whether the exposure has enough information to be assigned to an adjuster. You can use
the /validate endpoint to determine if the exposure has reached the "new loss completion" level. If the exposure is
below the "new loss completion" level, the payload identifies the conditions needed to reach "new loss completion".
• You want to execute a payment for an exposure. You can use the /validate endpoint to determine if the exposure
has reached the "ability to pay" level, as well as all levels before “ability to pay”. If the exposure is below the
"ability to pay" level, the payload identifies the conditions needed to reach "ability to pay".
• Your instance of ClaimCenter has custom validation levels. You can use the /validate endpoint to determine all
the levels the exposure has reached in its lifecycle, including those custom levels.
For more information on validation through system APIs, see “Validating claims” on page 174.

214 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Closing exposures
During an exposure's life cycle, the exposure's status typically moves from draft to open to closed. An exposure is
closed to indicate that no further payments are expected to be made from the exposure.
In the base configuration, ClaimCenter automatically closes an exposure when a "final payment" is made from the
exposure's reserve line. (A "final payment" is a payment whose payment type is final, as opposed to a payment whose
type is partial.)
You can also close exposures through the system APIs at any time. Broadly speaking, once an exposure is closed,
payments can no longer be made from that exposure. However, there are exceptions to this rule. For more information,
see the Application Guide.
To close an exposure, use the POST /claim/{claimId}/exposures/{exposureId}/close endpoint.

Exposures 215
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

216 Exposures
chapter 19

Service requests

A claim can have one or more service requests. This topic provides a high-level overview of service requests,
discussing both what they are and how to work with them through the system APIs.
For a more detailed discussion of the business functionality of service requests, refer to the Application Guide. For a
more detailed discussion of the configuration of service requests, refer to the Configuration Guide.

Overview of service requests in ClaimCenter

The following section provides an overview of service request behavior in ClaimCenter.

What is a service request?

A service is an action performed by a vendor to address a loss associated with a claim. For example:
• For a damaged car, services could include towing, auto body repair, and replacement car rental.
• For a damaged house, services could include plumbing and roof repair.
• For an injury, services could include conducting an examination, taking an x-ray, or performing surgery.
A service request is a collection of services managed by ClaimCenter for a given claim. Services are grouped into
service requests because a single vendor often provides multiple services. When this occurs, it is easier to have the
group of service requests associated with a single instruction, a single set of invoices, and a single payment for the
related services. The service request provides this grouping.

Components of a service request

A service request includes the following information:
• The vendor (also referred to as the "specialist")
• A service instruction, which specifies:
◦ The customer
◦ The location where the service is being performed
◦ The set of services being performed
• The relevant exposure and incident

Service request kinds

Every service request has a service request kind. A service request kind is a business flow that describes the steps to be
used to quote, process, and invoice the services. ClaimCenter uses the following service request kinds:
Service requests 217
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• Quote Only - This kind of service request requires only a quote from the vendor.
◦ This kind is appropriate when an insurer wishes to compare quotes from multiple vendors before deciding who
to assign the work to. (This kind of service request can be promoted to Quote and Service.)
◦ In the user interface, this kind of service request is labeled "Quote".
• Quote and Service - This kind of service request involves a quote, which is followed by the vendor providing the
service and sending invoices for the service.
◦ This kind is appropriate when you want the vendor to provide a quote, but you expect to use the assigned
vendor regardless of the quote.
◦ In the user interface, this kind of service request is labeled "Quote and Perform Service".
• Service Only - This kind of service request involves the vendor providing the service (without preparing a quote)
and sending invoices for the service.
◦ This kind is appropriate when you want the vendor to provide a service and you do not need a quote. This is
often used for "flat fee" services, such as car rentals, whose prices do not vary from claim to claim.
◦ In the user interface, this kind of service request is labeled "Perform Service".
• Unmanaged - This kind of service request is appropriate when you want the vendor to provide a service and you
wish to have minimal processing in ClaimCenter. There are no associated quotes. The service request can be
invoiced and paid immediately.
◦ This kind of service request is for services that are to be performed as quickly as possible, such the repair to a
cracked windshield for an "Auto - First and Final" claim.
◦ In the user interface, this kind of service request is labeled "Service".

Service type compatibility

Every service is not necessarily compatible with all service request kinds. For example, in the base configuration:
• An "auto appraisal" service can be attached only to a Quote Only service request.
• An "auto towing" service can be attached only to a Quote and Service, Service Only, or Unmanaged service
request.
Service type compatibility is configured in the [Link] file. This file is accessible through Studio.

The service request lifecycle

The lifecycle of a service request involves several stages. The current stage is listed in the service request's Progress
field. In some cases, a service request advances to the next stage because of activity completed by ClaimCenter or a
ClaimCenter user. In other cases, a service request advances to the next stage because of activity completed by the
vendor.
The following diagram identifies the stages in the lifecycle. Each rectangle is a stage. Thick green arrows lead to stages
that are typically reached because of ClaimCenter activity. Thin brown arrows lead to stages that are typically reached
because of vendor activity.

218 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

A service request that is fully executed goes through the following stages:
1. Draft
• The service request has been created in ClaimCenter but not yet submitted to the vendor.
2. Requested
• The service request has been submitted to the vendor, but not yet accepted.
3. In Progress
• The vendor has accepted the service request and started the work.
• For a Quote Only service request, the "work" consists of generating a quote.
• For a Quote and Service service request, the "work" consists of generating a quote and then, once the quote is
approved, providing the services.
• For all other service request kinds, the "work" consists of directly providing the services.
4. Work Complete
• The work (the quote or the set of services) is complete.
• At this point, the vendor may or may not have submitted invoices for the work.
• At this point, the invoices may or may not have been paid.
There are additional stages that a service request could reach:
• Declined
◦ A service request can reach this stage if the vendor decides to not accept a service request. For example, this
could happen if the service request is for a rental car and the vendor has no available cars.
◦ A service request can reach this stage if the vendor accepts a service request, but then later states they cannot
complete it. For example, this could happen if the vendor experiences an unexpected reduction in available
mechanics.
• Canceled
◦ A service request can reach this stage when the insurer decides the service request is no longer needed. For
example, the insured could decide to buy a new car instead of fixing the damaged car.
• Vendor Waiting
◦ A service request can reach this stage when the vendor cannot take action on the service without further input
from ClaimCenter. For example, the vendor could have submitted a quote that requires approval from an
adjuster.

Service requests 219

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Invoices for service request

For all service requests whose kind is Quote and Service, Service Only, or Unmanaged, once the work is complete, the
vendor typically submits one or more invoices. These invoices are attached to the service request. They are paid using
money from one of the claim's reserve lines. Depending on the nature of the service request, they may also require
adjuster approval.

Straight-through invoice processing

Straight-through invoice processing is a configurable ClaimCenter behavior in which invoices that meet certain criteria
are automatically approved and paid. Straight-through invoice processing is frequently used with Unmanaged service
requests, as these service requests are designed to involve minimal processing.

Overview of service requests in the Cloud API

Service request APIs and vendor portals
In previous releases of ClaimCenter, service requests were primarily managed by two systems: ClaimCenter and a
vendor portal. The vendor portal is an application used by a vendor to manage information about service requests from
ClaimCenter. In this paradigm:
ClaimCenter is responsible for actions such as:
• Creating the service request
• Submitting the service request to the vendor
• Paying the vendor.
The vendor is responsible for actions such as:
• Accepting the service request
• Quoting the service request
• Submitting invoices for the service request
Cloud API provides a wider range of options for processing service requests. The service request APIs can be used by
a vendor portal. But they can also be used by:
• An alternate front-end application for adjusters who specialize in service requests
• A service that submits or pays for vendor invoices in bulk
• A vendor management system that manages service requests for multiple vendors
Thus, the service request functionality exposed by Cloud API is not limited to only the functionality that would be used
by vendor portals. Rather, it exposes the service request functionality needed to manage the entire service request
process.

Lifecycle management
Cloud API provides a number of endpoints to manage the lifecycle of a service request. This includes both endpoints
for actions taken by the insurer (such as submitting a service request) and endpoints for actions taken by the vendor
(such as accepting a service request).
As of this release, there are endpoints to advance a service request to most stages in the lifecycle. However, there are
currently no endpoints to move a service request to the "Vendor Waiting" status.

Required service request data model

ClaimCenter includes two service requests data models: the "legacy model" and the Core Service Request data model.
Each instance of ClaimCenter can use only one of these models. In the base configuration, the Core Service Request
data model is enabled by default. In general, Guidewire recommends insurers use the Core Service Request data model.

220 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Note: In order to use the service request system APIs in Cloud API, the Core Service Requests data model must
be enabled. Guidewire recommends that insurers who are going into production on this version of ClaimCenter
use the Core Service Requests data model. Some insurers may be upgrading from a previous release that
offered only the legacy model. If an upgrading customer wishes to use the service request APIs, the insurer
must modify their configuration to use the Core Service Requests data model. For more information, refer to
the Upgrade Guide.

Service request numbers

In addition to a public ID, every service request is assigned a "service request number". By default, this number is
included in the response payload for most service request actions (in the serviceRequestNumber field). Unlike public
IDs, service request numbers are shown in the user interface. During testing, you can use the service request number to
match a service request as seen in a system API response with the corresponding service request in the user interface.

Support for each service request kind

If an insurer wants to go into production with this release and requires the ability to create quotes or pay invoices
through an integration point, then the insurer must write their own integration points. For more information on service
request functionality that may be available in future release, check with your Guidewire account manager or your
project manager.

Quote Only and Quote and Service service requests

The following table lists the stages that a Quote Only or Quote and Service service request can advance to through the
system APIs. It identifies which system API action advances the service request to the next stage, and the value of the
service's Next Action column in the ClaimCenter Services list.

System API endpoint Moves Progress to... Services list's Next Action is...
POST /service-requests Draft "Submit request"
POST /{serviceRequestId}/submit Requested "Agree to provide quote"
POST /{serviceRequestId}/accept In Progress "Add quote"

As of this release, there are no endpoints to create quotes or pay invoices. However, users can create quotes, pay
invoices, and take other actions that advance the service request to completion, through the user interface.

Service Only service requests

The following table lists the stages that a Service Only service request can advance to through the system APIs. It
identifies which system API action advances the service request to the next stage, and the value of the service's Next
Action column in the ClaimCenter Services list.

System API endpoint Moves Progress to... Services list's Next Action is...
POST /service-requests Draft "Submit request"
POST /{serviceRequestId}/submit Requested "Agree to perform service"
POST /{serviceRequestId}/accept In Progress "Finish the work"
POST /{serviceRequestId}/complete- Work Complete "Add invoice"
work
POST /{serviceRequestId}/invoices Work Complete "Pay invoice"

As of this release, there are no endpoints to pay invoices. However, invoices can be paid through the user interface.

Unmanaged service requests

The following table lists the stages that an Unmanaged service request can advance to through the system APIs. It
identifies which system API action advances the service request to the next stage, and the value of the service's Next
Action column in the ClaimCenter Services list.

Service requests 221

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

System API endpoint Moves Progress to... Services list's Next Action is...
POST /service-requests Work Complete "Add invoice"
POST /{serviceRequestId}/invoices Work Complete "Pay invoice"

As of this release, there are no endpoints to pay invoices. Unmanaged service requests are expected to make use of
straight-through invoice processing to automatically approve and pay invoices. However, if required, invoices can be
paid through the user interface.

Composite request limitations with service requests

For service requests that are Quote Only, Quote and Service, or Service Only, you can create and submit a service
request in a single composite request. But you cannot advance these types of service requests to any other stage in its
life cycle (such as in progress, declined, or canceled at vendor or insurer request) in the same composite request.

Querying for service requests

The following Claim API endpoints can be used to request information about service requests:

Endpoint Response
GET /service-requests All service requests
By default, the payload in the response includes the ID of each service request and
each claim the service request belongs to.
GET /claims/{claimId}/service- All service requests for the specified claim
requests
GET /claims/{claimId}/service- The specified service request.
requests/{serviceRequestId} Note that in order to get information about a specific service request, you must
access the service request through its parent claim.

Creating service requests

To create a service request, use the following endpoint:
• POST /claims/{claimId}/service-requests
Once a service request has been created, its Progress field is set to Draft.

Minimum creation criteria

At a minimum, a service request must specify:
• The service request kind, such as Service Only or Unmanaged (in the kind field)
• The vendor (in the specialist field)
• A service instruction (in the instruction field), which at a minimum must contain:
◦ The customer (in the customer field)
◦ The location where the service is being performed (in the serviceAddress field)
◦ The set of services being performed (in the services array)
• A requested quote completion date, if the service request is Quote Only or Quote and Service
• A requested service completion date, if the service request is Service Only

Additional details on each required field

A service request must specify the service request kind. This is specified in the kind field, and it must be set to a
typecode from the ServiceRequestKind typelist, such as:

222 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• quoteonly
• quoteandservice
• serviceonly
• unmanaged

A service request must specify the vendor. This is specified in the specialist field.
• You can specify an existing ClaimContact by listing the id field and setting it to the ClaimContact ID.
• You can create a new ClaimContact by listing the refid field and specifying a new ClaimContact in the included
section.
A service request must include a service instruction. This is specified in the instruction field. At a minimum, a
service instruction must have a customer, a location where the service is being performed, and a set of services.
The customer is specified in the customer field. This must be a reference to an existing or new ClaimContact. You can
specify the ClaimContact:
• By id (if it already exists in ClaimCenter)
• By policySystemId (if it exists in the Policy Administration System)
• By refid (if it does not yet exist and is being created in the POST's included section.)
The location where the service is being performed is specified in the serviceAddress field. You can specify the
address:
• By id (if it already exists in ClaimCenter)
• Inline (if it does not already exist in ClaimCenter)
The set of services being performed is specified in the services array. Each entry in this array specifies the service's
code. The codes come from the [Link] file, which you can access through Studio. Each service must
be a leaf-level service in the service tree. Also, each service must be compatible with the service request kind. Service
compatibility is defined in the [Link] file, which you can also access through Studio.
If the service request's kind is quoteonly or quoteandservice, you must also specify a requested quote completion
date in the requestedQuoteCompletionDate.
If the service request's kind is serviceonly, you must also specify a requested service completion date in the
requestedServiceCompletionDate.

Sample Service Only service request

The following payload shows an example of a minimal Service Only service request for claim 235-53-365889 in the
sample data (whose ID is cc:33). The service request will be performed by Joe's Auto Body Shop (ClaimContact cc:16)
at 1313 Mockingbird Lane in Arcadia, California, for Robert Farley (ClaimContact cc:13). There is one service to be
performed: Salvage (autoothersalvage). The service is requested to be completed by March 3, 2021.

POST [Link]

{
"data": {
"attributes": {
"kind": {
"code": "serviceonly"
},
"specialist": {
"id": "cc:16"
},
"instruction": {
"customer": {
"id": "cc:13"
},
"serviceAddress": {
"addressLine1": "1313 Mockingbird Lane",
"city": "Arcadia",
"country": "US",
"postalCode": "91006",
"state": {
"code": "CA",
"name": "California"
}
},

Service requests 223

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"services": [
{
"code": "autoothersalvage"
}
]
},
"requestedServiceCompletionDate": "2021-03-19"
}
}
}

Sample Unmanaged service request

The following payload shows an example of a minimal Unmanaged service request for claim 235-53-365889 in the
sample data (whose ID is cc:33). The service request will be performed by Joe's Auto Body Shop (ClaimContact cc:16)
at 1313 Mockingbird Lane in Arcadia, California, for Robert Farley (ClaimContact cc:13). There is one service to be
performed: Towing (autoothertowing).

POST [Link]

{
"data": {
"attributes": {
"kind": {
"code": "unmanaged"
},
"specialist": {
"id": "cc:16"
},
"instruction": {
"customer": {
"id": "cc:13"
},
"serviceAddress": {
"addressLine1": "1313 Mockingbird Lane",
"city": "Arcadia",
"country": "US",
"postalCode": "91006",
"state": {
"code": "CA",
"name": "California"
}
},
"services": [
{
"code": "autoothertowing"
}
]
}
}
}
}

Modifying existing service requests

Use the following endpoints to modify a service request without advancing it through its lifecycle.

PATCHing service requests

To PATCH a service request, use:
• PATCH /claims/{claimId}/service-requests/{serviceRequestId}
You cannot PATCH any field in the base configuration, as all of them can be set during creation only. But, if your
instance includes extension fields on ServiceRequest or a related entity, you could use this endpoint to update those
fields.

Specifying the reason for change

In ClaimCenter, the ServiceRequest entity has a History array which contains a set of ServiceRequestChange
instances. The ServiceRequestChange entity has a Description field, which is used to capture the reason for the
change.

224 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Whenever a service request is modified through a PATCH, the Description field is set using the following display
key:

[Link] = Service request values changed\: {0}

The {0} placeholder is populated with a list of the schema properties that have been changed. You can configure the
value of the Description field by modifying this display key.

Assigning service requests to users

Every service request is assigned to a group and a user in that group. This user has the primary responsible for
managing the service request.
When you create a service request through the system APIs, ClaimCenter automatically executes the service request
assignment rules to initially assign the service request to a group and user. You can use the POST /claims/
{claimId}/service-requests/{serviceRequestId}/assign endpoint to reassign the service request as needed.

Note: The functionality for assigning service requests is a subset of the functionality for assigning activities.
All assignment options that are applicable to both activities and service requests have the same behavior.

Assignment options
A service request can be assigned through the system APIs in the following ways:
• To a specific group and user in that group
• To a specific group only (and then ClaimCenter uses assignment rules to select a user in that group)
• To the claim owner
• By re-running the service request assignment rules
◦ This can be appropriate if you have modified the service request since the last time assignment rules were run
and the modification might affect who the service request would be assigned to.
The root resource for the /{serviceRequestId}/assign endpoint is ServiceRequestAssignee. This resource
specifies assignment criteria. The ServiceRequestAssignee schema has the following fields:

Field Type Description

autoAssign Boolean Whether to assign the service request using assignment rules
claimOwner Boolean Whether to assign the service request to the claim owner
groupId string The ID of the group to assign the service request to
userId string The ID of the user to assign the service request to

The Assignee resource cannot be empty. It must specify a single assignment option (group and user, group only, claim
owner, or automatic assignment).
For more information on how assignment rules execute assignment, see the Gosu Rules Guide.

Assignment example - Assigning to a specific group (and user)

The following assigns service request cc:102 (from claim demo_sample:20) to group demo_sample:31 (Auto1 -
TeamA) and user demo_sample:2 (Sue Smith).

POST /claim/v1/claims/demo_sample:20/service-requests/cc:102/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:2"
}
}
}

Service requests 225

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following assigns service request cc:102 (from claim demo_sample:20) to group demo_sample:31 (Auto1 -
TeamA). Because no user has been specified, ClaimCenter will execute assignment rules to assign the service request
to a user in group demo-sample:31.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:102/assign

{
"data": {
"attributes" : {
"groupId": "demo_sample:31"
}
}
}

Note that there is currently no endpoint that returns groups or group IDs. To assign service requests to a specific group,
the caller application must determine the group ID using some method other than a groups system API.

Assignment example - Assigning to the claim owner

The following assigns service request cc:102 (from claim demo_sample:20) to the group and user that owns the parent
claim (demo_sample:20).

POST /claim/v1/claims/demo_sample:20/service-requests/cc:102/assign

{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}

Assignment example - Using automated assignment

The following assigns service request cc:102 (from claim demo_sample:20) using automated assignment rules.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:102/assign

{
"data": {
"attributes": {
"autoAssign" : true
}
}
}

Advancing a service request in its lifecycle

Summary of the service request lifecycle
The following diagram identifies the lifecycle of a service request and the endpoints used to advance the service
request to each stage.

226 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Note: As of this release, there are no system API endpoints to advance a service request to the Vendor Waiting
stage.
Composite request limitations
For Quote Only, Quote and Service, and Service only service requests, you can create and submit a service request in a
composite request. But you cannot advance a service request to any other stage in its life cycle (such as in progress,
declined, or canceled).
For Unmanaged service requests, you can create, submit, invoice, and approve the service request in a single composite
request. You can also mark service request invoices as paid in that same composite request.

The ServiceRequestOperationContext resource

The endpoints that advance a service request to the next stage in the lifecycle use a
ServiceRequestOperationContext resource. This resource contains fields that map to the ServiceRequest entity in
ClaimCenter. In most cases, when using a service request lifecycle endpoint, there is a single field you must specify,
such as the reason field, which must be specified when declining or canceling a service request. Required fields are
specified in the following sections.
If an insurer has extended the behavior of the service request workflow in ClaimCenter, the insurer may also need to
extend the ServiceRequestOperationContext resource so that values can be provided by system APIs as needed. For
more information on extended base configuration resources, see the Cloud API Developer Guide.

Submitting, accepting, and declining service requests

Submitting service requests
Service requests that are Quote Only, Quote and Service, or Service Only must be submitted to a vendor. (Unmanaged
service requests are automatically marked as submitted to the specified vendor.)
To indicate that a service request has been submitted to the vendor, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/submit
When submitting a service request, there is no additional required information. The response can have no body.

Service requests 227

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following submits service request cc:9:

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/submit

<no request body>

When a Draft service request has been submitted, its Progress field is set to Requested.

Accepting service requests

Once a service requests that is Quote Only, Quote and Service, or Service Only is submitted to a vendor, it can be
accepted by the vendor. This means the vendor has agreed to take on the service request. (Unmanaged service requests
are automatically accepted by the specified vendor.)
To indicate a vendor has accepted a service request, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/accept
When accepting a submitted service request, you must specify an expectedCompletionDate.
The following accepts service request cc:9:

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/accept

{
"data": {
"attributes": {
"expectedCompletionDate" : "2021-03-22"
}
}
}

When a Requested service request has been accepted, its Progress field is set to In Progress.

Declining service requests

After a service requests that is Quote Only, Quote and Service, or Service Only has been submitted to a vendor, it can
be declined by the vendor. This means the vendor is not going to take on the service request.
To indicate a vendor has declined a service request, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/decline
When declining a submitted service request, you must specify a reason for the decline.
The following declines service request cc:9:

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/decline

{
"data": {
"attributes": {
"reason" : "All mechanics are booked through the end of the month."
}
}
}

When a Requested service request has been declined, its Progress field is set to Declined.

Completing and canceling service requests

Completing service requests
Once a service requests has been accepted by the vendor, you can specify that the work is completed.
To indicate that work on a service request is complete, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/complete-work
When indicating work is completed on a service request, there is no additional required information. The response can
have no body.

228 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following indicates the work is complete for service request cc:9:

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/work-complete

<no request body>

When an In Progress service request has been completed, its Progress field is set to Work Complete.

Canceling service requests (at the vendor's request)

Even after a service request has been accepted, it can be canceled by the vendor.
To indicate that work on a service request is canceled at the vendor's request, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/cancel
When canceling an accepted service request, you must specify a reason for the cancellation.
The following cancels service request cc:9 at the vendor's request:

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/cancel

{
"data": {
"attributes": {
"reason" : "Vendor realized they cannot service this type of auto."
}
}
}

When an In Progress service request has been canceled by the vendor, its Progress field is set to Declined. This is the
same state a service request is set to if the service request is initial declined rather than accepted.

Canceling service requests (at the insurer's request)

Even after a service request has been accepted, it can be canceled by the insurer.
To indicate that work on a service request is canceled at the insurer's request, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/internal-cancel
When canceling an accepted service request, you must specify a reason for the cancellation.
The following cancels service request cc:9 at the insurer's request:

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/internal-cancel

{
"data": {
"attributes": {
"reason" : "Claimant has decided not to request service."
}
}
}

When an In Progress service request has been canceled by the insurer, its Progress field is set to Canceled.

Service request quotes

If a service request is Quote Only or Quote and Perform Service, the vendor provides a quote for the service. For Quote
and Perform Service service requests, the quote is typically approved by the adjuster before the work is started.
In addition to the life cycle of the service request (which is shown in the user interface's Progress field), quotes have a
separate life cycle (which is shown in the Quote Status field).
The following table summarizes the status of each life cycle for a Quote Only service request after each life cycle
event.

Service requests 229

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Event Progress (of the service request) Quote Status

Service request is created Requested Waiting for Quote
Quote is created Work Complete Quoted

The following table summarizes the status of each life cycle for a Quote and Perform Service service request after each
life cycle event.

Event Progress (of the service request) Quote Status

Service request is created Requested Waiting for Quote
Quote is created Vendor waiting Waiting for Approval
Quote is approved In Progress Approved

Adding quotes
To add a quote, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/add-quote
When you add a quote, you must provide a statement object, which is defined by the ServiceRequestStatement
schema. The minimum required fields are:
• A description
• The expectedDaysToPerformService (an integer)
• An array of lineItems. Each item must have an amount, which is specified as a JSON object with an amount and
currency.
The following payload is an example of adding a quote to service request cc:101 (for claim demo_sample:2). The
quote is for $250 USD and specifies it will take 10 days to perform the service.

POST claim/v1/claims/demo_sample:2/service-requests/cc:101/add-quote

{
"data": {
"attributes": {
"statement": {
"description" : "Quote for repair",
"expectedDaysToPerformService": 10,
"lineItems": [
{
"amount": {
"amount": "250.00",
"currency": "usd"
}
}
]
}
}
}
}

You can provide additional quotes for a service request. There can only be one active quote at a time, which is also
referred to as the "latest quote". To add an additional quote, use the same endpoint. ClaimCenter makes the new quote
the active quote.

Approving quotes
To approve a quote, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/approve-quote
The request payload must include a requestedCompletionDate.
The following approves the quote for service request cc:9.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/approve-quote

230 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"data": {
"attributes": {
"requestedCompletionDate": "2021-08-31"
}
}
}

Service request invoices

Once a service request that is Quote and Perform Service, Service Only, or Unmanaged reaches the Work Complete
stage, invoices can be created for the service request.
An invoice consists of:
• A description
• An optional reference number
• One or more line items. Each line item consists of:
◦ A monetary amount (an amount and currency)
◦ A category
◦ An optional description
Once an invoice has been added, it can be approved. Approving an invoice signifies that the invoice is acceptable and
is ready to be paid. You can also mark an invoice as paid.
Note that there are mechanisms for suspending further work on both accepted service requests and service request
invoices. But the verb used for each mechanism is different.
• To stop further work on an accepted service request, you cancel it (or internal-cancel it).
• To stop further work on an invoice, you withdraw it.
Note: You cannot create or update the child objects of a service request (such as service request invoices) in a
composite request.

Querying for invoices

The following Claim API endpoints can be used to request information about service request invoices:

Endpoint Response
GET /claims/{claimId}/service-requests/ All invoices for the specified service request
{serviceRequestId}/invoices
GET /claims/{claimId}/servicerequests/ The specified invoice. Note that in order to get information about a specific
{serviceRequestId}/invoices/{invoiceId} invoice, you must access the invoice from its parent claim and service
request.

Creating invoices for service requests

To create an invoice for a service request, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices

Minimum creation criteria

An invoice must have the following information:
• A description
• A set of one of more line items. Each line item must specify:
◦ A monetary amount (with amount and currency values)
◦ A category (a code from the ServiceRequestStatementLineItemCategory typelist)

Service requests 231

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following creates an invoice for service request cc:9. The invoice contains two line items: a $150 USD charge for
labor, and a $50 USD charge for parts. It also includes an optional reference number for the invoice, and optional
descriptions for each line item.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices

{
"data": {
"attributes": {
"description": "Invoice submitted using system APIs",
"referenceNumber": "771-DX5667",
"lineItems": [
{
"amount": {
"amount": "150.00",
"currency": "usd"
},
"category": {
"code": "labor"
},
"description": "Invoiced labor"
},
{
"amount": {
"amount": "50.00",
"currency": "usd"
},
"category": {
"code": "parts"
},
"description": "Invoiced parts"
}
]
}
}
}

Approving service request invoices

To approve an invoice, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/approve
The POST invoices/{invoice-id}/approve endpoint does not require a request body.
The following approves invoice cc:06 for service request cc:9.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/approve

(no request body)

Marking invoices as paid

To mark an invoice as paid, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/mark-as-paid
When an invoice is marked as paid, there must be an associated check (which was presumably used to pay the invoice).
In the /mark-as-paid request payload, you must include a check attribute with the ID of the associated check. For
example, the following payload marks invoice cc:6 (for service request cc:9 on claim demo_sample:20) as paid. The
associated check is cc:413.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/mark-as-paid

{
"data": {
"attributes": {
"check": {
"id": "cc:413"
}
}
}
}

Note that ClaimCenter has validation rules that limit the ability to mark an invoice as paid based on the invoice's state.

232 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Withdrawing service request invoices

To withdraw an invoice, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/withdraw
When withdrawing an invoice, you must specify a reason. This can be set to any string value.
When you withdraw an invoice, the invoice is flagged as withdrawn in the user interface.
The following withdraws invoice cc:06 for service request cc:9.

POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/withdraw

{
"data": {
"attributes": {
"reason": "Invoice submitted in error"
}
}
}

Service requests 233

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

234 Service requests

part 4

Business flows: Financials

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in ClaimCenter so that caller
applications can request data from or initiate action within ClaimCenter.
The following topics discuss how caller applications can initiate specific ClaimCenter business flows related to
financials. This includes:
• Working with reserves
• Working with checks and check sets (including recurrences and deductible handling)
• Advancing checks through their life cycle (such as marking a check as issued)
• Working with financials in a multicurrency instance of ClaimCenter
Business flows related to FNOL and adjudication are covered in a separate section of this document.

Business flows: Financials 235

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

236 Business flows: Financials

chapter 20

Reserves

This topic provides a high-level overview of reserves, discussing both what they are and how to work with them
through Cloud API.
For a more detailed discussion of the business functionality of reserves, see the Application Guide. For a more detailed
discussion of the configuration of reserves, see the Configuration Guide.

Overview of reserves in ClaimCenter

Reserve lines
An exposure is an object associated with a claim which is used to track a potential payment or a set of related potential
payments. Every exposure is linked to one coverage (where the money is metaphorically "coming from") and one
claimant (where the money is metaphorically "going to").
To ensure solvency, government regulations often require insurers to set aside money when a claim is initially filed,
even if all of the details have not yet been gathered. A reserve transaction is a transaction that marks money as being
set aside for the purpose. Reserve transactions are typically referred to simply as reserves.
For example, suppose that there is a claim with an exposure associated with collision coverage for a damaged car. The
exposure requires an inspection and then some auto repair work. For this exposure, there might be two reserve
transactions: a $500 transaction to set aside money for the inspection, and a $3000 transaction to set aside money for
the auto repair work.
To help organize these reserve transactions, every exposure has one or more reserve lines. From a data model
perspective, a reserve line is a category that can be applied to a financial transaction. Every reserve line is categorized
by two primary values: cost type and cost category.
• Cost type identifies if the money is for indemnity or expense.
◦ Expense reserves are used to cover costs incurred by the insurer as a result of processing this portion of the
claim. From the previous example, the $500 transaction for the auto inspection would be associated with an
expense reserve.
◦ Indemnity reserves are used to indemnify claimants (in other words, "to restore them to the original state prior
to the loss"). From the previous example, the $3000 transaction for the auto repair work would be associated
with an indemnity reserve.
• Cost category classifies cost types at a more granular level.
◦ For example, reserve lines for a personal auto claim could have cost categories of "Auto body (repair)" or
"vehicle inspection".
◦ Cost categories are used for financial and business tracking purposes.
Reserves 237
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Creating reserves
Reserves can be created automatically by business rules based on the nature of a claim. For example, a business rule
might create a reserve of $500 for any auto claim where the only loss is windshield damage.
Reserves can be created through the user interface.
Reserves can also be created through integration points, such as through Cloud API.

Reserve sets and approval

When a financial transaction is created, insufficient authority limits or transaction approval rules may cause the
transaction to require approval. If so, the transaction must be approved by another user. Otherwise, the transaction is
automatically approved.
For a given claim, multiple reserve transactions may be created at the same time and ought to be approved as a unit.
(Either all transactions are approved or none of them are approved.) To facilitate this behavior, reserve transactions are
grouped into reserve sets. A reserve set is a set of one or more reserve transactions submitted for approval as a unit.
Approval is executed through the use of approval activities. For more information on the business functionality of
approval, see the Application Guide. For more information on activities and Cloud API, see “Activities” on page 281.
(When the reserve set is submitted through Cloud API, the user whose authority limits are checked is the session user.
For more information on how the session user is determined, refer to the Cloud API Authentication Guide.)

Reserve transactions and acknowledgment

ClaimCenter is typically integrated with several downstream systems, including a general ledger system. When
ClaimCenter executes financial activity, it typically informs the general ledger. At some later point, the general ledger
may acknowledge that the information about the activity has been received.
When a reserve transaction is created and approved, its status is initially set to "submitting". Once the transaction has
been acknowledged, its status is changed to "submitted".

Querying for reserves

You can use the following endpoints to query for reserve-related information.

Endpoint Description
GET /claims/{claimId}/reserve-sets Retrieve a list of reserve sets
GET /claims/{claimId}/reserve-sets/{reserveSetId} Retrieve details of a reserve set
GET /claims/{claimId}/reserves The reserves associated with a given claim
GET /claims/{claimId}/reserves/{transactionId} The details of a specific reserve

Sample response for a reserve set

For example, the ClaimCenter sample data includes a claim whose ID is demo_sample:1. This claim has one reserve
set. The following is the call to get that reserve set, and the response. The response has been edited for clarity. Note the
following:
• The reserve set includes 9 transactions, three of which are shown in the output below.
• The reserve set was approved on 2021-08-08.
• The reserve set was submitted by Andy Applegate.
• The first three transactions in the reserve set are as follows:
◦ A reserve for the first exposure, with a cost type of "Claim cost" and a cost category of "Auto body".
◦ A reserve for the first exposure, with a cost type of "Expense - A&O" and a cost category of "Other".
◦ A reserve for the second exposure, with a cost type of "Claim cost" and a cost category of "Medical".

GET claims/demo_sample:1/reserve-sets/cc:17

238 Reserves
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"data": {
"attributes": {
"approvalDate": "2021-08-08T07:00:00.000Z",
"approvalStatus": {
"code": "approved",
"name": "Approved"
},
"id": "cc:17",
"requestingUser": {
"displayName": "Andy Applegate",
},
"reserves": [
{
"displayName": "(1) 1st Party Vehicle...Claim Cost/Auto body...",
"id": "cc:22",
"type": "Reserve"
},
{
"displayName": "(1) 1st Party Vehicle...Expense - A&O/Other...",
"id": "cc:36",
"type": "Reserve"
},
{
"displayName": "(2) 1st Party Med Pay...Claim Cost/Medical...",
"id": "cc:40",
"type": "Reserve"
},
...
]
},
...
}

Sample response for a reserve transaction

Following on from the previous example, the following is the call to get the first reserve in the reserve set, and the
response. The response has been edited for clarity. Note the following:
• The reserve is for an exposure whose coverage is PACollisionCov.
• The reserve's line items specify a claim amount, reporting amount, reserving amount, and transaction amount of
$500 USD.
• The reserve line is for exposure 1 (demo_sample:10001) and has a cost type of Claim Cost, a cost category of Auto
Body.

GET claims/demo_sample:1/reserves/cc:17

{
"data": {
"attributes": {
"coverage": {
"code": "PACollisionCov",
"name": "Collision"
},
"currency": {
"code": "usd",
"name": "USD"
},
"id": "cc:22",
"lineItems": [
{
"claimAmount": {
"amount": "500.00",
"currency": "usd"
},
"comments": "Repairs",
"id": "cc:56",
"lineCategory": {
"code": "other",
"name": "Other"
},
"reportingAmount": {
"amount": "500.00",
"currency": "usd"
},
"reservingAmount": {
"amount": "500.00",
"currency": "usd"
},
"transactionAmount": {
"amount": "500.00",
"currency": "usd"
}
}

Reserves 239
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

],
"reserveLine": {
"costCategory": {
"code": "body",
"name": "Auto body"
},
"costType": {
"code": "claimcost",
"name": "Claim Cost"
},
"exposure": {
"displayName": "(1) 1st Party Vehicle - Ray Newton",
"id": "demo_sample:10001",
},
"reservingCurrency": {
"code": "usd",
"name": "USD"
}
},
"status": {
"code": "submitted",
"name": "Submitted"
},
"type": {
"code": "Reserve",
"name": "Reserve"
}
},
..
}

Creating reserves
When creating reserves from Cloud API, there is no POST endpoint whose root resource is a reserve line or a reserve
transaction. Reserve lines and reserve transactions are created within the context of a reserve set.
To create a reserve set, use the following endpoint:
• POST /claims/{claimId}/reserve-sets
When you create a reserve set, you must specify the reservesToWrite. This is reserve set which consists of an array
of reserve transactions. For each member of the array, you must specify:
• The reserveLine for the reserve. To identify this, you must specify:
◦ costCategory (a value from the CostCategory typelist)
◦ costType (a value from the CostType typelist)
◦ The id of the parent exposure (This can also be explicitly set to null, in which case the reserve line is created at
the claim level.)
◦ reservingCurrency
• An array of one or more transaction lineItems, each of which must specify:
◦ A transactionAmount (specified as an amount and a currency)
• The reserve transaction currency

Currencies in the POST reserve-sets payload

Every reserve transaction consists of one of more line items. Reserve transactions and line items are stored in different
database tables. However, for a given reserve transaction, the currency of every line item in the reserve transaction
must match the currency of the reserve transaction.
This distinction may not be evident when using the user interface. The user chooses a currency for the transaction, and
all line items automatically default to that transaction. This hides the fact that they are technically distinct values.
However, this distinction must be taken into consideration when writing a reserve set payload. There is no mechanism
for the line items to inherit the reserve transaction's currency. Therefore, the currency of the reserve transaction and
each line item must be explicitly stated, and they must be the same.
There is a third field that is set to a currency value, reservingCurrency. In an instance of ClaimCenter that makes use
of multicurrency, this can be set to a currency other than the reserve transaction's currency. For more information, see
“Multicurrency” on page 269.

240 Reserves
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Approval status
When a reserve set is submitted, ClaimCenter checks the corresponding user's authority limits.
• If the amount is at or below the user's authority limit, the reserve set is approved. The appropriate amount is added
to the reserve line, and the response object's approvalStatus field is set to approved.
• If the amount is above the user's authority limit, the reserve set requires approval. An approval activity is created
and sent to a user with sufficient approval authority. No amount is added to the reserve line, and the response
object's approvalStatus field is set to unapproved.
A given user can have an authority limit for "claim total reserves", "exposure total reserves", or both. For more
information on authority limits, see the Application Guide.
When the reserve set is submitted through Cloud API, the user whose authority limits are checked is the session user.
For more information on how the session user is determined, see the Cloud API Developer Guide.

Reserves and composite requests

Within a composite request, you cannot create or modify financial objects. This includes reserve sets and reserve
transactions. However, within a composite request, you can GET information on financial objects.

Example of creating reserves

The following payload is an example of creating a reserve line.
• The ID of the claim is cc:61.
• The ID of the exposure is cc:79.
• There is only one reserve transaction.
◦ The transaction is for a reserve line whose cost type and cost category is Claim Cost / Auto Body (claimcost
and body).
◦ The transaction's currency is USD.
◦ The transaction has a single line item for $1000.

POST /claims/cc:61/reserve-sets

{
"data": {
"attributes": {
"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:79"
},
"reservingCurrency": {
"code": "usd"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "1000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

Reserves 241
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Example of adding to reserves

The following payload is an example of adding to an existing reserve line. This call is executed after the previous
example.
• The ID of the claim is cc:61.
• The ID of the exposure is cc:79.
• There is only one reserve transaction.
◦ The transaction is for a reserve line whose cost type and cost category is Claim Cost / Auto Body (claimcost
and body).
◦ The transaction's currency is USD.
◦ The transaction has a single line item for $250.
Note that this payload has no significant differences from the previous payload. When you create a reserve transaction,
you only need to identify the cost type, cost category, and currency (and amount). ClaimCenter determines whether this
is a new reserve line or part of an existing reserve line on its own.

POST /claims/cc:61/reserve-sets

{
"data": {
"attributes": {
"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:79"
},
"reservingCurrency": {
"code": "usd"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "250.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

Acknowledging reserve transactions

ClaimCenter is typically integrated with a general ledger system. When ClaimCenter executes financial activity, it
typically informs the general ledger. At some later point, the general ledger may acknowledge that the information
about the activity has been received.
When a reserve transaction is created and approved, its status is initially set to "submitting". Once the transaction has
been acknowledged, its status is changed to "submitted".
To acknowledge a reserve transaction, use the following endpoint:
• POST /claims/{claimId}/reserves/{transactionId}/acknowledge-submission
When acknowledging a transaction, there is no additional required information. The response can have no body.

242 Reserves
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following acknowledges transaction cc:84 for claim cc:61.

POST /claim/v1/claims/ claims/cc:61/reserves/cc:84/acknowledge-submission

<no request body>

Reserves 243
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

244 Reserves
chapter 21

Creating checks

This topic provides a high-level overview of checks, discussing both what they are and how to work with them through
Cloud API.
For a more detailed discussion of the business functionality of checks, see the Application Guide. For a more detailed
discussion of the configuration of checks, see the Configuration Guide.

Overview of checks in ClaimCenter

When issuing money for claims, ClaimCenter makes use of two distinct types of objects: payments and checks.

Payments
Within the context of ClaimCenter, a payment transaction (often referred to simply as a payment) is a monetary amount
paid to satisfy a claim, categorized by exactly one reserve line. For example, suppose that Allen Robertson files a claim
because he hit both his neighbor's car and his neighbor's fence. The claim has an exposure with one reserve line. To
satisfy this claim, ClaimCenter creates two payment transactions associated with the reserve line: one $1200 payment
for the damage to the car and one $600 payment for the damage to the fence.
At the level of a payment, there are no details as to who will be paid or how. For example, from the payments alone,
you cannot say who the payee is, if the payments are made at the same time or a month apart, or if they are made with a
physical check or an electronic transfer.

Checks
A check is a group of one or more payments to be sent to a single recipient. In addition to payment-level information
(such as amount and reserve line), a check includes information on who the payments are made to and how.
Consider the previous example of Allen Robertson's claim. There are two payments: a $1200 payment for the damage
to the car and a $600 payment for the damage to the fence. The payments could be grouped into a single check for
$1800 made payable to the neighbor, or two separate checks for $1200 and $600 respectively made payable to the auto
repair shop and fence contractor. For each check, the check could be issued as a physical check or as an electronic
funds transfer.
The reserves from a reserve line can provide money for one or more checks, and a check's money can come from the
reserves of one or more reserve lines. The following is a list of claim examples showing how the reserves from one or
more reserve lines and be associated with one or more checks.
• Example: Multiple reserves and one check
Creating checks 245
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ Description: Ray Newton hit a tree. His car was damaged, and he suffered a broken arm.
◦ Exposures: The claim has two exposures. The first is tied to his collision coverage. The second is tied to his
medical payments coverage. Each exposure has one reserve line.
◦ Payments: One payment for $2000 associated with the collision reserve line. One payment for $1715 associated
with the medical payments reserve line.
◦ Checks: Ray receives a single $3715 check. This check includes both payments.
• Example: One reserve and multiple checks
◦ Description: Ray Newton was involved in an auto collision which involved damage to his vehicle and a doctor's
exam.
◦ Exposures: One exposure tied to his collision coverage. The exposure has one reserve line.
◦ Payments: One payment for $2000 associated with the collision reserve line (for the vehicle damage). One
payment for $500 associated with the collision reserve line (for the medical exam).
◦ Checks: The auto repair show receives a $2000 check to repair the vehicle damage. The doctor receives a $500
check for the medical exam.
Every check has at least one payee. A payee is a person or organization to whom a check is made payable. Payees can
be either claimants or vendors who provided services for the claim (such as auto repair shops, doctors, or lawyers).

Check sets
When a financial transaction is created, insufficient authority limits or transaction approval rules may cause the
transaction to require approval. If so, the transaction must be approved by another user. Otherwise, the transaction is
automatically approved.
For a given claim, multiple payment transactions may be created at the same time and ought to be approved as a unit.
(Either all transactions are approved or none of them are approved.) To facilitate this behavior, payment transactions
are grouped into check sets. A check set is a set of one or more checks (and their associated payment transactions)
submitted for approval as a unit.
Approval is executed through the use of approval activities. For more information on the business functionality of
approval, see the Application Guide. For more information on activities and Cloud API, see “Activities” on page 281.
When the check set is submitted through Cloud API, the user whose authority limits are checked is the session user.
(For more information on how the session user is determined, see the Cloud API Developer Guide.)

Querying for check sets and checks

You can use the following endpoints to query for check-related information.

Endpoint Description
GET /claims/{claimId}/check-sets Retrieve a list of check sets
GET /claims/{claimId}/check-sets/{checkSetId} Retrieve details of a check set
GET /claims/{claimId}/checks The checks associated with a given claim
GET /claims/{claimId}/checks/{checkId} The details of a specific check
GET /claims/{claimId}/payments The payment transactions associated with a given claim
GET /claims/{claimId}/payments/{transactionId} The details of a specific payment transaction

Sample response for a check set

For example, the ClaimCenter sample data includes a claim whose ID is demo_sample:1. This claim has one check set.
The following is the call to get that check set, and the response. The response has been edited for clarity. Note the
following:
• The check set has one check.
• The check set was approved on 2021-08-11.

246 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The check set was submitted by Andy Applegate.

• Based on the check's display name, the check number was 10436. It was a check for Ray Newton for $2000.

GET claims/demo_sample:1/check-sets/cc:28

{
"data": {
"attributes": {
"approvalDate": "2021-08-11T07:00:00.000Z",
"approvalStatus": {
"code": "approved",
"name": "Approved"
},
"checks": [
{
"displayName": "Check #10436: Ray Newton -- $2,000.00"
...
}
],
"createTime": "2021-08-24T19:00:02.529Z",
"id": "cc:28",
"requestingUser": {
"displayName": "Andy Applegate"
...
}
...
}
}
}

Sample response for a check

Following on from the previous example, the following is the call to get the check in the check set, and the response.
The response has been edited for clarity. Note the following:
• The check number is 10436.
• The check's gross amount is $2000 USD.
• The check has one payee - Ray Newton.
• The check's money comes from 5 payment transactions.
• The check has been issued.

GET claims/demo_sample:1/checks/cc:34

{
"data": {
"attributes": {
"checkNumber": "10436",
"grossAmount": {
"amount": "2000.00",
"currency": "usd"
},
"id": "cc:34",
"issueDate": "2021-08-11T07:00:00.000Z",
"payees": [
{
"contact": {
"displayName": "Ray Newton"
...
},
"id": "cc:41",
"payeeType": {
"code": "claimant",
"name": "Claimant"
}
}
],
"paymentMethod": {
"code": "check",
"name": "Check"
},
"payments": [
{
"displayName": "(1) 1st Party Vehicle - Ray Newton;
Claim Cost/Auto body; Submitted"
},
{
"displayName": "(2) 1st Party Med Pay - Stan Newton;
Claim Cost/Medical; Submitted"
},
{
"displayName": "(2) 1st Party Med Pay - Stan Newton;

Creating checks 247

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Claim Cost/Medical; Submitted"

},
{
"displayName": "(1) 1st Party Vehicle - Ray Newton;
Expense - A&O/Other; Submitted"
},
{
"displayName": "(2) 1st Party Med Pay - Stan Newton;
Expense - A&O/Other; Submitted"
}
],
"status": {
"code": "issued",
"name": "Issued"
}
}
}
}

POSTing checks
Check creation in ClaimCenter
Checks and validation levels
Both claims and exposures have validation levels. A validation level is a designation of how mature the claim or the
exposure is. Every validation level can have a set of validation criteria tied to it. A claim or an exposure cannot reach a
given validation level until all the associated validation criteria have been met.
In most instances of ClaimCenter, the highest validation level is "Ability to pay". This means that the claim or
exposure is at the point where checks can be written.
In order to create a check set, the following must be true:
• The claim's validation must be "Ability to pay".
• Each exposure that owns a reserve line that payment transactions are coming from must also be at "Ability to pay".
For more information on validating claims, see “Validating claims” on page 174. For more information on validating
exposure, see “Validating exposures” on page 214.

Checks and payment types

When a check is created, each underlying payment can have one of three types:
• Final - This applies to open claims and exposures. This indicates that no additional payments are expected to be
made from the corresponding reserve line.
• Partial - This applies to open claims and exposures. This indicates that additional payments may be made from the
corresponding reserve line.
• Supplement - This is used to make payments on closed claims and exposures.

Check creation through Cloud API

When creating checks from Cloud API, there is no POST endpoint whose root resource is a check or a payment
transaction. Checks and payment transactions are created within the context of a check set. Keep in mind that check
sets can be created only for claims at or above "Ability to pay" and using only exposures at or above "Ability to pay".
To create a check set, use the following endpoint:
• POST /claims/{claimId}/check-sets
Prior to creating the check set, you will need the following:
• For each reserve line the checks will be drawing from:
◦ The ID of the parent exposure. (If the reserve line is at the claim level, then specify "null" for the exposure ID.)
◦ The reserve line's cost type, cost category, and currency.

248 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• For each payee that is already on the claim:

◦ The ID of the corresponding contact.

The primaryCheckToWrite object

When you create a reserve set, you must specify the primaryCheckToWrite . At a minimum, it must consists of the
following three items.
You must specify an array of paymentsToWrite. For each member of the array, you must specify:
• An array of one or more transaction lineItems, each of which must specify:
◦ A transactionAmount (specified as an amount and a currency)
• A paymentType (a value from the PaymentType typelist, such as partial or final)
• The reserveLine that the money is coming from. To identify this, you must specify:
◦ costCategory (a value from the CostCategory typelist)
◦ costType (a value from the CostType typelist)
◦ The id of the parent exposure
◦ The reservingCurrency
• The payment transaction currency
You must also specify an array of payees. For each payee you must specify:
• An ID for the payee
◦ If the contact already exists on the claim, you can reference it by its id.
◦ If the contact does not exist on the claim, you can create it in the same call using request inclusion and reference
it using a refid.
• The payeeType (a value from the ContactRole typelist filtered by payee, such as insured, claimant, vendor, or
other)

You must also specify the paymentMethod. This is a value from the PaymentMethod typelist, such as check or eft.

Currencies in the POST check-sets payload

Every payment transaction consists of one of more line items. Payment transactions and line items are stored in
different database tables. However, for a given payment transaction, the currency of every line item in the payment
transaction must match the currency of the payment transaction.
This distinction may not be evident when using the user interface. The user chooses a currency for a check set, and all
line items automatically default to that currency. This hides the fact that they are technically distinct values.
However, this distinction must be taken into consideration when writing a check set payload. There is no mechanism
for the line items to inherit the payment transaction's currency. Therefore, the currency of the payment transaction and
each line item must be explicitly stated, and they must be the same.
There is a third field that is set to a currency value, reservingCurrency. This must always be specified. In an instance
of ClaimCenter that makes use of multicurrency, this can be set to a currency other than the reserve transaction's
currency. For more information, see “Multicurrency” on page 269.

Checks and composite requests

Within a composite request, you cannot create or modify financial objects. This includes check sets and payment
transactions. However, within a composite request, you can GET information on financial objects.

Example of creating a minimal check set

The following payload is an example of creating a check set.
• The ID of the claim is cc:55. This claim is at "Ability to pay".
• The money will come from a single exposure, which is also at "Ability to pay".

Creating checks 249

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ The exposure's ID is cc:58.

◦ The cost type is claimcost.
◦ The cost category is Auto Body (body).
• There is only one payment transaction.
◦ The currency and reserving currency is USD.
◦ The amount is $75.50.
◦ The payment is final.
• There is only one payee.
◦ The payee's contact ID is cc:613.
◦ The payee's type is insured.
• The payment method is Electronic Funds Transfer (eft).

POST /claims/cc:55/check-sets

{
"data": {
"attributes": {
"primaryCheckToWrite": {
"paymentsToWrite": [
{
"lineItems": [
{
"transactionAmount": {
"amount": "75.50",
"currency": "usd"
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:58"
},
"reservingCurrency": {
"code": "usd"
}
},
"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
"id": "cc:613"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
}
}

Recurrences

250 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Recurrences in ClaimCenter
A recurrence is a series of one or more checks that Claim Center issues periodically. This is a common requirement for
claims involving injuries that require long-term medical treatment, such as an injury that requires weekly physical
therapy. Recurrences are also referred to a recurring check sets.
Recurring checks must be written to the same payees and be for the same amount.
For more information on recurrences, see the Application Guide.

Specifying the frequency

Recurrences can be specified monthly or weekly.
Monthly frequencies can be specified as "every X months on the Nth day" (such as "every 2 months on the 14th").
They can also be specified as "every X months on the Nth dayOfWeek" (such as "every 1 month on the first Friday").
Weekly frequencies are specified as "every X weeks on dayOfWeeks" (such as "every 3 weeks on Tuesdays").
Technically, the frequency of a recurring check set starts with the second check in the sequence, not the first. It is
possible to send the first check either "in sequence" or "out of sequence". For example, suppose you have a monthly
check set of five checks. You could send the first check on March 19th, with the following checks on April 19, May 19,
June 19, and July 19. But, you could also send the first check on March 19th, with the following checks on April 1,
May 1, June 1, and July 1.

Recurrences in Cloud API

To specify that a check set is recurring, the POST payload must specify a recurrence object in the check set payload. In
the recurrence object, the following fields are always required:
• firstDueDate - The due date of the first check (You can set this to either match the frequency of the subsequent
checks, or to be "out of sequence".)
• numChecks - The total number of checks in the recurrence
• subtype - The recurrence frequency, typically MonthlyCheckReccurence or WeeklyCheckRecurrence
There are additional required fields, but these vary based on how the frequency is specified.

Sending checks every X months on the Nth day

You can send checks with a recurrence of every X months on the Nth day. For example:
• Send checks every 1 month (every month) on the 15th
• Send checks every 2 months on the 10th
For this type of frequency, the following fields are required:
• firstDueDate - The due date of the first check (You can set this to either match the frequency of the subsequent
checks, or to be "out of sequence".)
• numChecks - The total number of checks in the recurrence
• subtype - set to MonthlyCheckRecurrence
• monthlyFrequency - The number of months in each iteration (1 to send checks every month, 2 for every other
month, and so on).
• recurrenceDate (the day of the month on which the check is set)
For example, the following recurrence could be used to send 10 checks, once every month, on the 7th. The first check
will be sent January 7. The next check will be sent February 7, and so on.

"recurrence": {
"firstDueDate": "2021-01-07",
"monthlyFrequency": 1,
"numChecks": 10,
"recurrenceDate": 7,
"subtype": {
"code": "MonthlyCheckRecurrence"

Creating checks 251

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

Sending checks every X months on the Nth dayOfWeek

You can send checks with a recurrence of every X months on the Nth dayOfWeek. For example:
• Send checks every 1 month (every month) on the 1st Friday
• Send checks every 2 months on the 3rd Tuesday
For this type of frequency, the following fields are required:
• firstDueDate - The due date of the first check (You can set this to either match the frequency of the subsequent
checks, or to be "out of sequence".)
• numChecks - The total number of checks in the recurrence
• subtype - Set to MonthlyCheckRecurrence
• monthlyFrequency - The number of months in each iteration (1 to send checks every month, 2 for every other
month, and so on).
• recurrenceWeek
◦ [Link] - Set to a typecode from the RecurrenceWeek typelist (first, second, third, fourth,
or last)
• recurrenceDay
◦ [Link] - Set to a typecode from the RecurrenceDay typelist (mon, tue, weds, thurs, fri, sat, or
sun)

For example, the following recurrence could be used to send 7 checks, once every month, on the first Thursday. The
first check will be sent January 7 (the first Thursday in January). The next check will be sent February 4 (the first
Thursday in February), and so on.
"recurrence": {
"firstDueDate": "2021-01-07",
"monthlyFrequency": 1,
"numChecks": 7,
"recurrenceDay": {
"code": "thurs"
},
"recurrenceWeek": {
"code": "first"
},
"subtype": {
"code": "MonthlyCheckRecurrence"
}
}

Sending checks every X weeks on dayOfWeek

You can send checks with a recurrence of every X weeks on dayOfWeeks. For example:
• Send checks every 1 week (every week) on Fridays
• Send checks every 2 weeks on Tuesdays
For this type of frequency, the following fields are required:
• firstDueDate - The due date of the first check (You can set this to either match the frequency of the subsequent
checks, or to be "out of sequence".)
• numChecks - The total number of checks in the recurrence
• subtype - Set to WeeklyCheckRecurrence
• weeklyFrequency - The number of weeks in each iteration (1 to send checks every week, 2 for every other week,
and so on).
• recurrenceDay
◦ [Link] - Set to a typecode from the RecurrenceDay typelist (mon, tue, weds, thurs, fri, sat, or
sun)

252 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For example, the following recurrence could be used to send 12 checks, once every week, on Thursdays. The first
check will be sent January 7. The next check will be sent January 14, and so on.

"recurrence": {
"firstDueDate": "2021-01-07",
"numChecks": 12,
"recurrenceDay": {
"code": "thurs"
},
"subtype": {
"code": "WeeklyCheckRecurrence"
},
"weeklyFrequency": 1
}

Deductible handling
Deductible handling in ClaimCenter
A deductible is an amount of money associated with a specific coverage that the insured must pay out of pocket for a
loss before the coverage takes effect. The insurer provides payment only for the amount above and beyond the
deductible. For example, suppose there is a personal auto policy with a collision coverage that has a deductible of
$2000. The associated vehicle is involved in a collision, and the repairs cost $6000. The insured is responsible for
paying the first $2000. The insurer pays the remaining $4000.
ClaimCenter provides functionality to handle deductibles during check creation. This includes keeping track of the
total amount, the amount applied, and the amount remaining to be applied.
For more information on deductible handling, see the Application Guide.

Deductible handling in Cloud API

For Cloud API, deductible handling is part of check creation. A check set has one or more checks, and each check has
one or more payments. A payment is comprised of one or more line items. For an exposure with a deductible,
payments typically have at least two line items.
• One or more line items that represent the total amount of the service or reimbursement.
◦ These line items have a transaction amount, which is typically positive.
• One line item that represents the deductible.
◦ The line item has a transaction amount, which is typically negative.
◦ The line item also has a lineCategory object with a code property set to deductible.
For example, suppose that you are writing the payload for a check the previous example in which a car needs $6000 of
repairs, and there is a $2000 deductible. The lineItems array for the check would have two members:
• The $6000 line item (for the repair service)
• The -$2000 line item with a [Link] of deductible (for the deductible)
The lineItems portion of the POST /check-sets payload would appear as follows:

"lineItems": [
{
"transactionAmount": {
"amount": "6000.00",
"currency": "usd"
}
},
{
"transactionAmount": {
"amount": "-2000.00",
"currency": "usd"
},
"lineCategory": {
"code": "deductible"
}
}
]

Creating checks 253

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

This payload would result in a check whose amount was $4000.

The following is the complete payload for the check set described in the previous example.

POST /claim/v1/claims/cc:SzVCozO9dRQI_Ao1dBccV/check-sets

{
"data": {
"attributes": {
"primaryCheckToWrite": {
"paymentsToWrite": [
{
"lineItems": [
{
"transactionAmount": {
"amount": "6000.00",
"currency": "usd"
}
},
{
"transactionAmount": {
"amount": "-2000.00",
"currency": "usd"
},
"lineCategory": {
"code": "deductible"
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:SFaWbxZwJOCFh_UWbbC_8"
},
"reservingCurrency": {
"code": "usd"
}
},
"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
"id": "cc:SHLpehV4HdCDJSJhilgCA"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
}
}

Underpaying and overpaying deductibles

A deductible can be met through more than a single line item. (For example, a deductible of $500 could be met through
two deductible line items of $250 each in two different check sets.) Also, a single deductible can apply to more than
one exposure. Consequently, Cloud API does not perform validation to verify that the amount of the coverage's
deductible matches the deductible line items in a check set.
As a result, it is possible to underpay or overpay a deductible. For example, suppose there is a personal auto policy
with a collision coverage that has a deductible of $2000. The associated vehicle is involved in a collision, and the
repairs cost $6000.

254 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• You could create a check set with a $6000 line item and a -$1000 deductible line item. The corresponding check
would be for $5000. This would underpay the deductible and provide the payee with $1000 more than they were
entitled to.
• You could create a check set with a $6000 line item and a -$3000 deductible line item. The corresponding check
would be for $4000. This would overpay the deductible and provide the payee with $1000 less than they were
entitled to.
The responsibility of determining the correct amount of deductible to specify in a check set lies with the caller
application.

Deductibles with positive amounts

It is possible to have a deductible line item with a positive amount. This can occur when an insurer has overcharged the
deductible amount, and needs to give a refund to the insured.

PATCHing checks
To patch a check, use the following endpoint:
• PATCH /claims/{claimId}/checks/{checkId}
For example, the following payload modifies check cc:601 on claim cc:400 so that the payment method is now
"manual".

PATCH claim/v1/claims/cc:400/checks/cc:601

{
"data": {
"attributes": {
"paymentMethod": {
"code": "manual"
}
}
}
}

Keep in mind that ClaimCenter has business constraints around when and how a check can be modified. For example,
some fields cannot be changed after the check has been submitted to the check processing system.

DELETEing checks
To delete a check, use the following endpoint:
• DELETE /claims/{claimId}/checks/{checkId}
You do not need to provide a body.
For example, the following payload deletes check cc:601 on claim cc:400.

DELETE claim/v1/claims/cc:400/checks/cc:601

<no request body>

Note that the DELETE endpoint is at the check level, not the check set level. If you want to delete an entire check set,
you must delete each check in the check set individually.
Also keep in mind that ClaimCenter has business constraints around when and how a check can be deleted. For
example, checks cannot be deleted once they have been escalated.

Creating checks 255

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

256 Creating checks

chapter 22

Managing the check life cycle

This topic discusses how you can manage the check life cycle and the payment life cycle using Cloud API.

The check life cycle prior to submission

The process of issuing a check typically involves ClaimCenter and one or more downstream systems. Initially, the
check passes through some processing within ClaimCenter. At some point, the check is "submitted" to the check
processing system.
The following diagram identifies the statuses that a check can have up to the point that it is submitted, and how the
check moves from one status to another.

1. While a check is being created, it is in a draft state with no status.

2. Once the check is created, ClaimCenter checks the corresponding user's authority limits.
Managing the check life cycle 257
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

a. If the check does not exceed any of the user's authority limits, the check moves to "Awaiting submission".
b. If the check does exceed any of the user's authority limits, the check moves to "Pending Approval".
ClaimCenter creates an approval activity and assigns it to the appropriate approving user.
3. If a check is "Pending approval", the approving user can take the following actions.
a. They could approve the activity, which causes the check to advance to "Awaiting submission".
b. They could reject the activity, which causes the check to move to "Rejected".
4. Once a check reaches "Awaiting submission" it remains in this state until its due date. Once the due date is
reached, the Financial Escalation batch process submits the check to the downstream system and advances the
check's status to "Requesting".
You can view the status of a given check through the ClaimCenter user interface. Navigate to the claim and then, in the
left-hand side bar, click Financials > Checks. This shows a list of checks for the claim and the status of each check.

Advancing a check to submission through Cloud API

You can move a check through a portion of the "Requesting" life cycle through Cloud API. But you cannot manage the
entire life cycle through Cloud API.
• In the Claim API, the POST /{claimId}/checks endpoint creates a check. The check's status is set to either
"Pending approval" or "Awaiting submission".
• In the Common API, the POST /{activityId}/approve endpoint approves an approval activity. If the approval
activity is associated with a check whose status is "Pending approval", this advances the check to "Awaiting
submission".
However, as of this release:
• There is no endpoint to move a check from "Pending approval" to "Rejected".
• There is no endpoint to trigger the Financial Escalation batch process. Therefore, there is no way through Cloud
API to submit the check, thereby advancing it from "Awaiting submission" to "Requested".

The check life cycle after submission

The process of issuing a check typically involves ClaimCenter and one or more downstream systems. Initially, the
check passes through some processing within ClaimCenter. At some point, the check is "submitted" to the downstream
system.
The Claim API has several endpoints that advance a check in its lifecycle after it has been submitted. The following
diagram identifies the most common statuses used in the check life cycle, the most common ways checks flow through
the life cycle, and the endpoints used to advance the check to each status.

258 Managing the check life cycle

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Note the following:

• When a "Requesting" check is managed entirely by APIs, it most commonly moves to "Requested" using the
POST /acknowledge-submission endpoint. There are endpoints that can move a "Requesting" check directly to
"Pending stop" or "Pending void", but these are less common routes.
• Once a check is "Requested", the three most common outcomes are:
◦ The check moves to "Issued" (the check is sent) and then "Cleared" (the check is cashed).
◦ The check moves to "Pending stop" and then "Stopped".
◦ The check moves to "Pending void" and then "Voided".
The previous diagram does not exhaustively list every possible transition. For example, a check that is "Issued" can
move to "Pending stop", and a check that is "Pending stop" can moved to "Issued". This diagram identifies only the
most common paths. For a complete discussion of all possible transitions, see the Application Guide.
Also, there are some life cycle statuses that you cannot advance a check to through Cloud API. This includes:
• Denied
• Pending transfer
• Transferred
If you attempt to advance a check from one status to another in a way that is not possible, the call fails and Cloud API
returns an error message indicating the operation is not possible. For example, if you attempt to call POST /mark-
cleared on a check that is "Requesting", Cloud API returns the following message:

"The 'mark-cleared' operation is not currently available for this check"

Advancing a check beyond submission through Cloud API

To advance a check to a given status, use the corresponding endpoint as described in the following table.

Managing the check life cycle 259

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Status To Advance To Endpoint

Requested POST /claims/{claimId}/checks/{checkId}/acknowledge-submission
Issued POST /claims/{claimId}/checks/{checkId}/mark-issued
Cleared POST /claims/{claimId}/checks/{checkId}/mark-cleared
Pending stop POST /claims/{claimId}/checks/{checkId}/request-stop
Stopped POST /claims/{claimId}/checks/{checkId}/mark-stopped
Pending void POST /claims/{claimId}/checks/{checkId}/request-void
Voided POST /claims/{claimId}/checks/{checkId}/mark-voided

When using these endpoints, you do not need to provide a request body.
For example, suppose check cc:601 on claim cc:400 has a status of "Requesting". The following payload advances the
check to the "Requested" status.

POST claim/v1/claims/cc:400/checks/cc:601/acknowledge-submission

<no request body>

Then, the following payload advances the check to the "Issued" status.

POST claim/v1/claims/cc:400/checks/cc:601/mark-issued

<no request body>

Finally, the following payload advances the check to the "Cleared" status.

POST claim/v1/claims/cc:400/checks/cc:601/mark-cleared

<no request body>

You can also view the status of a given check through the ClaimCenter user interface. Navigate to the claim and then,
in the left-hand side bar, click Financials > Checks. This shows a list of checks for the claim and the status of each
check.

The check life cycle and composite requests

Within a composite request, you cannot create or modify financial objects. This includes use of the check life cycle
endpoints (such as POST /mark-issued). However, within a composite request, you can GET information on financial
objects.

Acknowledging payment transactions

ClaimCenter is typically integrated with one or more downstream financial systems. When ClaimCenter executes
financial activity, it typically informs the downstream systems. At some later point, one of these systems may
acknowledge that the information about the activity has been received.
Checks have associated payments. When a check set has been approved, the associated checks and payment
transactions have a status of "submitting". When you acknowledge a check, the status of the check and its associated
payments changes to "submitted". Thus, there is typically no need to explicitly acknowledge payments. they are
automatically acknowledged when the check is acknowledged. However, Cloud API does provide an endpoint to
acknowledge payments in the unusual circumstance where explicit acknowledgment is required.
To acknowledge a payment transaction, use the following endpoint:
• POST /claims/{claimId}/payments/{transactionId}/acknowledge-submission
When acknowledging a transaction, there is no additional required information. The request can have no body.

260 Managing the check life cycle

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following acknowledges payment transaction cc:88 for claim cc:61.

POST /claim/v1/claims/cc:61/payments/cc:88/acknowledge-submission

<no request body>

Managing the check life cycle 261

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

262 Managing the check life cycle

chapter 23

Recoveries and recovery reserves

Recoveries and recovery reserves refer to transactions for money received during the claim’s lifecycle. Most
ClaimCenter financial transactions track money that is sent during the claim's lifecycle. However, recoveries and
recovery reserves are transactions that track money received during the claim's lifecycle:
• Recovery reserves are transactions that account for the money expected to be received during a claim’s lifecycle.
• Recoveries are the transaction for the money received.
Recovery reserves estimate the amount of money received from future recoveries. Recovery reserves function similarly
to reserves but add to the ledger how much money is estimated to be received from a recovery instead of how much
money is estimated to be paid out with a check.
Recoveries include the following examples:
• Subrogation: The money received by an insurer from the at-fault driver’s insurance provider to pay for vehicle
damages.
• Deductibles: The money received from an insured contact that is paid to the insurer per the terms of the coverage
before the coverage goes into effect.
• Salvage: The money received from a destroyed vehicle from which the insurer can get back some of its cost by
selling the vehicle for scrap.

Recovery and recovery reserve example

Karen Egertson was involved in a collision where her car was damaged and she was injured. Her claim has two
exposures: one for the first-party vehicle claim cost and another for third-party liability and property damage.
First party vehicle claim:
• Recovery reserves: The insurer expects to receive $500 from the salvage of the vehicle.
• Recovery: The insurer receives $500 dollars from the salvage of Karen’s vehicle.
• Net total and remaining recovery reserves: $500 dollars goes towards the first part vehicle claim cost exposure,
accounting for the total amount of the recovery reserve.
Third-party liability and property damage:
• Recovery reserves: The insurer expects to receive $4000 from subrogation of the third-party.
• Recoveries: The insurer receives $3000 from the third party’s insurance policy in subrogation.
• Net total and remaining recovery reserves: $3000 goes towards the third party liability exposure, with an open
recovery reserve of $1000, which may or may or may not be accounted for before the claim is closed.

Recoveries and recovery reserves 263

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Querying for recoveries and recovery reserves

You can use the following endpoints to query for recovery-related information.

Endpoint Description
GET /claims/{claimId}/recovery-reserve-sets Retrieve a list of recovery reserve sets
GET /claims/{claimId}/recovery-reserve-sets/{recoveryReserveSetId} Retrieve details of a recovery reserve set
GET /claims/{claimId}/recovery-reserves Retrieve a list of recovery reserves
GET /claims/{claimId}/recovery-reserves/{transactionId} Retrieve the details from a specific recovery reserve
GET /claims/{claimId}/recovery-sets Retrieve a list of recovery sets
GET /claims/{claimId}/recovery-sets/{recoverySetId} Retrieve the details for a specific recovery set
GET /claims/{claimId}/recoveries Retrieve the recovery transactions
GET /claims/{claimId}/recoveries/{transactionId} Retrieve the details of a specific recovery

Sample response for a recovery reserve

You can query for all recovery reserves created in a recovery reserve set by performing a GET on recovery reserves.
The following call gets the recovery reserve. Note the following:
• The recovery reserve was created automatically from a recovery.
• The reserve amount and the transaction amount are equal because the recovery amount was already received.
• The recovery offsets costs paid out for Karen Egertson’s collision policy, which uses the exposure for Karen
Egertson’s first policy vehicle.
• The recovery reserve was created in the expectation of subrogation for the claim.
GET rest/claim/v1/claims/demo-sample:1/recovery-reserves

{
"data": {
"attributes": {
"comments": "Automatically created due to recovery for $100.00 on (1) 1st Party Vehicle - Karen Egertson; Claim
Cost/Auto body; USD; Subrogation",
"coverage": {
"code": "PACollisionCov",
"name": "Collision"
},
"createTime": "2021-11-19T18:29:08.386Z",
"currency": {
"code": "usd",
"name": "USD"
},
"id": "cc:901",
"lineItems": [
{
"claimAmount": {
"amount": "100.00",
"currency": "usd"
},
"comments": "Automatically created due to recovery for $100.00 on (1) 1st Party Vehicle - Karen
Egertson; Claim Cost/Auto body; USD; Subrogation",
"id": "cc:FJ2",
"reportingAmount": {
"amount": "100.00",
"currency": "usd"
},
"reservingAmount": {
"amount": "100.00",
"currency": "usd"
},
"transactionAmount": {
"amount": "100.00",
"currency": "usd"
}
}
],
"reserveLine": {
"costCategory": {
"code": "body",
"name": "Auto body"
},

264 Recoveries and recovery reserves

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"costType": {
"code": "claimcost",
"name": "Claim Cost"
},
"exposure": {
"displayName": "(1) 1st Party Vehicle - Karen Egertson",
"id": "cc:PV6",
"type": "Exposure",
"uri": "/claim/v1/claims/cc:901/exposures/cc:PV6 "
},
"recoveryCategory": {
"code": "subro",
"name": "Subrogation"
},
"reservingCurrency": {
"code": "usd",
"name": "USD"
}
},
"status": {
"code": "submitting",
"name": "Submitting"
},
"subtype": {
"code": "RecoveryReserve",
"name": "RecoveryReserve"
}
}
}
}

Creating recoveries and recovery reserves

Recovery and recovery reserve dependency criteria
A recovery reserve is an object that defines the amount of money you anticipate receiving for a claim, such as for
subrogation or salvage. A recovery can reference a recovery reserve to specify the amount of money received going
towards the recovery reserve total, whether that be a partial amount of the recovery reserve’s total amount of money
received.
You can also create a recovery without a referenced recovery reserve, in which case the recovery automatically creates
the recovery reserve. The recovery reserve is created for the recovery; creating a recovery without a recovery reserve
assumes that the full amount the money received in the reserve is the total expected amount of the recovery reserve.

Creating a recovery reserve

When creating recovery reserve from Cloud API, there is no POST endpoint whose root resource is a recovery reserve.
Recovery reserves are created in the context of a recovery reserve set.
To create a recovery reserve, use the following endpoint:
• POST /claims/{claimId}/recovery-reserve-sets
Prior to creating the recovery reserve set, you need the following information:
• Cost type
• Cost category
• Currency

The recoveryReservesToWrite object

When you create a recovery reserve set, you must specify the recoveryReservesToWrite. At a minimum, it must
consist of the following items:
• The reserveLine specifies where the money is coming from. To identify this, you must specify:
◦ costCategory (a value from the CostCategory typelist)
◦ costType (a value from the CostType typelist)
◦ The recovery category (a value from the RecoveryCategory typelist)

Recoveries and recovery reserves 265

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ The id of the parent exposure

◦ The reservingCurrency
An array of one or more transaction lineItems, each of which must specify:
• The transactionAmount, including the amount and currency
• The currency (a value from the currency typelist)
Note that transactions do not automatically inherit the reserveLine’s currency, such as in the ClaimCenter application.
Therefore, the currency must be defined three times in the request payload.

Recovery reserve and composite requests

Within a composite request, you cannot create or modify financial objects. This includes recoveries and recovery
reserves. However, within a composite request, you can GET information on financial objects.

Creating a recovery reserve set

The following payload is an example of creating a recovery reserve set.
• The reserveLine offsets money coming from a single exposure:
◦ The exposure’s ID is cc:SB1
• The cost type is claimcost.
• The cost category is Auto Body (body).
• The recovery category is salvage.
• The reserving currency is USD.
◦ The transactionAmount is for 5000.00.
POST /claims/cc:76b/recovery-reserve-sets

{
"data": {
"attributes": {
"recoveryReservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimCost"
},
"exposure": {
"id": "cc:SB1"
},
"recoveryCategory": {
"code": "salvage"
},
"reservingCurrency": {
"code": "usd"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "5000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

266 Recoveries and recovery reserves

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Acknowledging a recovery reserve

ClaimCenter is typically integrated with one or more downstream financial systems. When ClaimCenter executes
financial activity, it typically informs the downstream systems. At some later point, one of these systems may
acknowledge that the information about the activity has been received.
To acknowledge a recovery reserve transaction, use the following endpoint:
• claim/v1/claims/{claimdID}/recovery-reserves/{transactionID}/acknowledge-submission
To acknowledge a recovery transaction, use the following endpoint:
• claim/v1/claims/{claimdID}/recoveries /{transactionID}/acknowledge-submission
When acknowledging a transaction, there is no additional required information. The request can have no body.
The following example acknowledges recovery reserve transaction cc:88 for claim cc:61B.
POST claim/v1/claims/cc:61B/recovery-reserves/cc:88/acknowledge-submission

Creating a recovery
When creating recoveries from Cloud API, there is no POST endpoint whose root resource is a recovery. Recoveries
are created in the context of a recovery set.
When you create a recovery set, you must specify the recoveriesToWrite. At a minimum, it must consist of the
following items:
• The reserveLine that specifies where the money is coming from. To identify this, you must specify:
◦ costCategory (a value from the CostCategory typelist)
◦ costType (a value from the CostType typelist)
◦ The recovery category (a value from the RecoveryCategory typelist)
◦ The id of the parent exposure
◦ The reservingCurrency
• An array of one or more transaction lineItems, each of which must specify:
◦ The transactionAmount, including the amount and currency
◦ Currency (a value from the currency typelist)
If you want your recovery to reference a recovery reserve, and have its transaction amount go toward the total of the
expected recovery reserve, you must duplicate the following information from the recovery reserve:
• costCategory (a value from the CostCategory typelist)
• costType (a value from the CostType typelist)
• The recovery category (a value from the RecoveryCategory typelist)
• The id of the parent exposure
• The reservingCurrency
The currency in the lineItem object must also be the same.
Note: If you create a recovery with a transaction amount in excess of its referenced recovery reserve,
ClaimCenter creates an additional recovery reserve to make up for the difference.

Example of creating a recovery

The following payload is an example of creating a recovery that references the previous example recovery reserve:
• The reserveLine offsets money coming from a single exposure:
◦ The exposure’s ID is cc:SB1
• The cost type is claimcost.

Recoveries and recovery reserves 267

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The cost category is Auto Body (body).

• The recovery category is salvage.
• The reserving currency is USD.
◦ The transactionAmount is for 3000.00.
Note: The transaction accounts for 3000 dollars (USD) of the expected 5000 dollars (USD) in the recovery
reserve. The original recovery reserve total is reduced to the difference of 2000 dollars.
POST /claim/v1/claims/

{
"data": {
"attributes": {
"recoveriesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimCost"
},
"exposure": {
"id": " cc:SB1"
},
"recoveryCategory": {
"code": "salvage"
},
"reservingCurrency": {
"code": "usd"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "3000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

268 Recoveries and recovery reserves

chapter 24

Multicurrency

This topic describes how to work with financial objects for an instance of ClaimCenter where multicurrency is enabled.

Multicurrency overview

Multicurrency in ClaimCenter
By default, all ClaimCenter financial transactions are calculated and displayed in a single currency. You can configure
ClaimCenter to make use of multiple currencies. This functionality is often referred to as multicurrency.
When multicurrency is enabled, a claim can make use of multiple currencies at different levels.
• Every claim has a claim currency. This is the base currency for the claim.
• Every reserve has a reserving currency, which could be set to a currency different from the claim currency.
• Every reserve and payment has a transaction currency. This could be set to a currency different from either the
claim currency, the reserving currency, or both.
There is also a default currency for each instance of ClaimCenter. This is the currency that objects default to when the
object is created through the user interface. It is also referred to as the reporting currency.
In order to convert between different currencies, ClaimCenter stores a set of exchange rates. When a transaction
requires currency conversion, the ClaimCenter default behavior is to use whichever stored exchange rate has been
marked as the active rate. However, for a given transaction, you can specify a custom exchange rate.
For more information on multicurrency business functionality, see the Application Guide. For more information on
multicurrency configuration, see the Configuration Guide.

Multicurrency in Cloud API

Cloud API provides support for multicurrency transactions.

Multicurrency and reserves

When you create a reserve, you must always specify the currency. This is true whether or not multicurrency has been
enabled.
• If multicurrency has been enabled, you can specify a currency other than the claim currency.
• If you specify an alternate currency, you can also specify a custom exchange rate.
Multicurrency 269
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Multicurrency and checks

When you create a check set, you must always specify the currency of each payment. This is true whether or not
multicurrency has been enabled.
• If multicurrency has been enabled, you can specify a currency other than the claim currency or the reserve currency.
• If you specify an alternate currency, you can also specify a custom exchange rate.

Multicurrency and exchange rates

As of this release, there are no endpoints to create or modify exchange rates.
However, as noted above, you can specify a custom exchange rate for a transaction, as well as override the
automatically calculated values for the amount properties.

Retrieving multicurrency information

Multicurrency reserves
Currency information is part of the default response for the GET /reserves endpoint, whether or not multicurrency
has been enabled.
The following is a snippet of the response payload for a GET /reserves for a multicurrency reserve. Currency
information appears in bold. Note the following:
• The default currency for this instance of ClaimCenter is US dollars (usd).
◦ This is specified in the [Link] field.
• The claim's currency is US dollars (usd).
◦ This is specified in the [Link] field.
• The reserving currency is British pounds (gbp).
◦ This is specified in the [Link] field.
• The reserve transaction is British pounds (gbp).
◦ Every reserve transaction consists of one of more line items. Both transactions and line items have currency
values, but each is stored in different database tables. These currency values must always be explicitly stated
and must always be the same, regardless of whether or not multicurrency is enabled.
◦ The currency for the transaction is specified in the parent currency field.
◦ The currency for each associated line item is specified in the [Link]
field(s).

GET /claims/cc:SHRyrnPstWtq7HZ3nxLCC/reserves/cc:SojI8VceTmdlXU6k1pqOB

{
"data": {
"attributes": {
"currency": {
"code": "gbp",
"name": "GBP"
},
"id": "cc:SojI8VceTmdlXU6k1pqOB",
"lineItems": [
{
"claimAmount": {
"amount": "1920.82",
"currency": "usd"
},
"id": "cc:SyLnqtJEkcI4X4WaFXbgP",
"reportingAmount": {
"amount": "1920.82",
"currency": "usd"
},
"reservingAmount": {
"amount": "1000.00",
"currency": "gbp"
},
"transactionAmount": {
"amount": "1000.00",

270 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"currency": "gbp"
}
}
],
"reserveLine": {
"costCategory": {
"code": "body",
"name": "Auto body"
},
"costType": {
"code": "claimcost",
"name": "Claim Cost"
},
"exposure": {
"displayName": "(1) 1st Party Vehicle - Allen Robertson",
"id": "cc:SfXS3Pey0Al29PI13KC5C",
},
"reservingCurrency": {
"code": "gbp",
"name": "GBP"
}
}
}
}
}

There is also a currency value specified in the [Link] field. This field identifies the
currency of the associated reserve line. A reserve line is a category that can be applied to a financial transactions. For a
given exposure, each reserve line is uniquely identified by its cost type, cost category, and currency.

Multicurrency checks
Currency information is part of the default response for the GET /checks endpoint, whether or not multicurrency has
been enabled.
The following is a snippet of the response payload for a GET /checks for a multicurrency check. Currency
information appears in bold. Note the following:
• The default currency for this instance of ClaimCenter is US dollars (usd).
◦ This is specified in the [Link] field.
• The reserve currency is British pounds (gbp).
◦ The reserving currency is British pounds (gbp). This is indicated in the display names of the payments. To see
the actual currency code, you would need to GET the individual payment and inspect its reserve line.
• The check currency is Euros (eur).
◦ This is specified in the [Link] field.

GET /claims/cc:SHRyrnPstWtq7HZ3nxLCC/checks/cc:SqK_OuzG48empV3wtydTH

{
"data": {
"attributes": {
"grossAmount": {
"amount": "20.00",
"currency": "eur"
},
"id": "cc:SqK_OuzG48empV3wtydTH",
"paymentMethod": {
"code": "check",
"name": "Check"
},
"payments": [
{
"displayName": "(1) 1st Party Vehicle - Allen Robertson;
Claim Cost/Auto body; GBP; Awaiting submission",
"id": "cc:SXGn6K7Zeidw8MAkv2sGx",
"type": "Payment",
}
],
"reportableAmount": {
"amount": "20.00",
"currency": "eur"
}
}
}
}

Multicurrency 271
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

POSTing multicurrency information

Whenever you POST a reserve or check, you must specify currency information. For a single-currency instance of
ClaimCenter, all specified currencies must be the same. When multicurrency is enabled, the specified currencies can be
different.
When a request payload contains multiple currency values, the specified currencies must meet any relevant validation
criteria. For example, when creating a reserve, the claim currency does not need to match the reserve currency. But, the
currency for each reserve line item must match the reserve currency. If these types of validation criteria are not met,
Cloud API returns an error.

POSTing a reserve with multiple currencies

The following is an example of a request payload for a new reserve for claim cc:202. Although it is not evident from
the payload, the claim currency for cc:202 is US Dollars (usd).
• The reserving currency is Euros (eur).
• The reserve transaction currency is Japanese yen (jpy).

POST [Link]

{
"data": {
"attributes": {
"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},
"reservingCurrency": {
"code": "eur"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "100.00",
"currency": "jpy"
}
}
],
"currency": {
"code": "jpy"
}
}
]
}
}
}

POSTing a reserve with a custom exchange rate

To specify a custom exchange rate, use the transToReservingExchangeRate object. This specifies the rate to use
when converting the transaction currency into the reserving currency. The object takes three fields:
• An optional description string value.
• A Boolean market value. (This identifies whether ClaimCenter uses the market rate populated by the
ExchangeRateSetPlugin for this transaction or uses a new custom rate. If a custom exchange rate is being
specified, set market to false.)
• A decimal rate value.
The following is an example of a request payload for a new reserve for claim cc:202. Although it is not evident from
the payload, the claim currency for cc:202 is US dollars (usd).

272 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• The reserving currency is US dollars (usd).

• The reserve transaction currency is Canadian dollars (cad).
• The custom exchange rate is 4.0 (The transaction amount is 300. Thus, this will be recorded as $300 CAD, which is
equal to $1200 USD.)

POST [Link]

{
"data": {
"attributes": {
"reservesToWrite": [
{
"transToReservingExchangeRate": {
"description": "Custom exchange rate",
"market": false,
"rate": "4.0"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},
"reservingCurrency": {
"code": "usd"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "300.00",
"currency": "cad"
}
}
],
"currency": {
"code": "cad"
}
}
]
}
}
}

POSTing a check set with multiple currencies

The following is an example of a check set payload for a new check set for claim cc:202. Although it is not evident
from the payload, the claim currency for cc:202 is usd.
• The reserving currency is British pounds (gbp).
• The currency for the check (and any associated payment transaction) is Canadian dollars (cad).

POST [Link]

{
"data": {
"attributes": {
"primaryCheckToWrite": {
"paymentsToWrite": [
{
"lineItems": [
{
"transactionAmount": {
"amount": "75.00",
"currency": "cad"
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"

Multicurrency 273
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

},
"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},
"reservingCurrency": {
"code": "gbp"
}
},
"currency": {
"code": "cad"
}
}
],
"payees": [
{
"contact": {
"id": "cc:Sr-RcOtnyAd2_TsoU4Szy"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
}
}

POSTing a check set with a custom exchange rate

To specify a custom exchange rate, use the transToReservingExchangeRate object. This specifies the rate to use
when converting the transaction currency into the reserving currency. The object takes three fields:
• An optional description string value.
• A Boolean market value. (This identifies whether ClaimCenter uses the market rate populated by the
ExchangeRateSetPlugin for this transaction or uses a new custom rate. If a custom exchange rate is being
specified, set market to false.)
• A decimal rate value.
The following is an example of a request payload for a new reserve for claim cc:202. Although it is not evident from
the payload, the claim currency for cc:202 is US Dollars (usd).
• The reserving currency is British pounds (gbp).
• The currency for the check (and any associated payment transaction) is Canadian dollars (cad).
• The custom exchange rate is 0.5 (The transaction amount is 50. Thus, this will be recorded as $50 CAD, which is
equal to $25 GPB.)

POST [Link]

{
"data": {
"attributes": {
"primaryCheckToWrite": {
"paymentsToWrite": [
{
"lineItems": [
{
"transactionAmount": {
"amount": "50.00",
"currency": "cad"
}
}
],
"paymentType": {
"code": "partial"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},

274 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"reservingCurrency": {
"code": "gbp"
}
},
"currency": {
"code": "cad"
},
"transToReservingExchangeRate": {
"description": "Custom exchange rate",
"market": false,
"rate": "0.5"
}
}
],
"payees": [
{
"contact": {
"id": "cc:Sr-RcOtnyAd2_TsoU4Szy"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
}
}

Specifying multicurrency line items

Specifying the transactionAmount automatically calculates the reservingAmount, claimAmount and
reportingAmount line items based on market or custom exchange rates. This automatic conversion covers most use
cases for multicurrency. However, in certain instances, overriding the automatic calculation with a user-specified
amount field is warranted. An example of this instance is satisfying a coverage’s deductible in the policy currency.
For example, a policy that uses USD has a 500 USD deductible.
A payment is made in GBP to satisfy the 500 USD deductible, which means the GBP payment deducts transaction
amounts in GBP that is calculated to USD using exchange rates.
However, depending on the exchange rate, the exact conversion may be impossible, such as follows:
378.16GPV=499.96 USD, and 378.17 GVP = 500.01 USD. Either calculation does not satisfy the deductible and
prevents the exposure from being closed.
To work around edge cases such as this, you can specify transactionAmount, reservingAmount, claimAmount and
reportingAmount.

Multicurrency property amount dependency criteria

When posting multicurrency information that includes one or more of the four amount properties, the cloud API rules
ensure that all properties are initialized with a value, are overridden with a user-specified value, and that fields that
share the same currency use the same value. Multicurrency fields that use different values in the same currency will
always throw an error.
Note the following:
• The transactionAmount field is always required, and automatically calculates any line items you do not specify.
(This is the default behavior).
◦ reservingAmount is set to the transactionAmount if the reserving currency is the same as the transaction
currency. Otherwise, the reservingAmount is set to the converted value.
◦ claimAmount is set to the transactionAmount if the claim currency is the same as the transaction currency.
Otherwise, the claimAmount is set to the converted value.
◦ reportingAmount is set to the transactionAmount if the reporting currency is the same as the transaction
currency. Otherwise, is transactionAmount is set to the converted value.
• The reservingAmount field, if specified, cannot have the same currency as the transaction currency.

Multicurrency 275
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

◦ claimAmount is set to the reservingAmount if the claim currency is the same as the reserving currency.
◦ reportingAmount is set to reservingAmount if the reporting currency is the same as the reserving currency.
• The claimAmount field, if specified, cannot have the same currency as the transaction currency or claim currency.
◦ reportingAmount is set to claimAmount if the reporting currency is the same as the claim currency.
• The reportingAmount, if specified, cannot have the same currency as the transaction currency, reserving currency,
or claim currency.

WARNING: When PATCHing a multicurrency transaction, and specifying the transactionAmount, the other
three amount properties will be recalculated and overwritten with the transactionAmount exchange rate
calculations. This occurs even when the amount properties were previously specified.

As an example, consider that you encounter an edge case where the standard multicurrency calculations does not
satisfy the deductible amount. The exchange rate at the time of the check-set creation calculates 250.02 GBP to 499.99
USD. Thus, the exposure for this claim cannot be closed.
Note: When encountering the edge case where exchange rates calculate a value that does not satisfy the
deductible, and if the claim is a different currency than the transactionAmount, you must specify the
claimAmount on the deductible.

Consider the following:

• The exchange rate at the time of the check-set creation calculates 250.02 GBP to 499.99 USD. Thus, the exposure
for this claim cannot be closed.
• The user specifies the claimAmount as -500.00 USD, which overrides the calculated value of 499.99 USD.

"primaryCheckToWrite": {
"paymentsToWrite": [
{
"transToReservingExchangeRate": {
"description": "Custom exchange rate",
"market": false,
"rate": "1.9998"
},
"lineItems": [
{
"transactionAmount": {
"amount": "600",
"currency": "gbp"
},
"transactionAmount": {
"amount":"-250.02",
"currency": "gbp"
},
"claimAmount": {
"amount": "-500.00"
"currency": "USD"
},
"lineCategory": {
"code": "deductible"
}
}
],
...

POSTing multicurrency line items

When POSTing multicurrency line items in other instances, you need only add the line items to the request payload,
such as the following:

POST [Link]

{
"data": {
"attributes": {
"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},

276 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},
"reservingCurrency": {
"code": "eur"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "100.00",
"currency": "jpy"
},
"reservingAmount": {
"amount":"1.01",
"currency": "eur"
}
}
],
"currency": {
"code": "jpy"
}
}
]
}
}
}

Additional exchange rate schema fields

Response payloads can also include the following exchange rate fields:
• claimToReportingExchangeRate
• transToClaimExchangeRate
Note that these fields are read-only. When POSTing reserves and check sets, custom exchange rates are always
specified using the transToReservingExchangeRate field.

Multicurrency 277
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

278 Multicurrency
part 5

Business flows: Framework APIs

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in ClaimCenter so that caller
applications can request data from or initiate action within ClaimCenter.
The following topics discuss how caller applications can initiate business flows related to the Common API and the
Admin API. This includes:
• The Common API
◦ Working with activities
◦ Working with documents
◦ Working with notes
• The Admin API
◦ Working with users and groups

Business flows: Framework APIs 279

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

280 Business flows: Framework APIs

chapter 25

Activities

An activity is an action related to the processing of a claim that a user must attend to or be aware of. Activities are
ultimately assigned to a group and a user in that group. This user has the primary responsibility for closing the activity.
Activities are typically created by users or by automatic ClaimCenter processes, and they are typically closed by users.
But, activities can be both created and closed by Cloud API calls.
For a complete description of the functionality of activities in ClaimCenter, see the Application Guide.
Note: Activities exist in all core InsuranceSuite applications. To ensure that activities behave in a common way
across all applications, some activity endpoints, such as the endpoints for querying for or assigning activities,
are declared in the Common API. Activities can also belong to claims, which do not exist in all InsuranceSuite
applications. This means that other activity endpoints, such as the endpoint for creating an activity for a claim,
are declared in the Claim API. This topic always identifies the API in which each endpoint is declared.
Note: ContactManager for Cloud API includes the Common API and its endpoints for working with activities.
However, in the base configuration of the ContactManager application, there is no user interface or business
rule support for activities. The activities endpoints have been included in Cloud API for ContactManager
primarily for the sake of consistency, and also to support any insurer who wishes to configure ContactManager
so that it can work with activities.

Querying for activities

Activities cannot exist on their own. They must be attached to a parent object. In ClaimCenter, activities can be
attached only to claims (directly or indirectly).
You can use the following endpoints to GET activities.

Endpoint Returns
/common/v1/activities All activities
/common/v1/activities/{activityId} The activity with the given ID
/claim/v1/claims/{claimId}/activities All activities associated with the given claim

Creating activities
Activities must be created from an existing claim using the following endpoint:
• POST claim/v1/claims/{claimId}/activities
Activities 281
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Activity patterns
Activities are created from activity patterns. An activity pattern is a set of default values for fields in the activity (such
as description, subject, and priority). Every activity pattern has a code, such as contact_insured or legal_review.
When creating an activity through Cloud API, the only required field is activityPattern, which must specify the
activity pattern's code. Because the activity pattern typically contains all the necessary default values, the activity
pattern is often the only field the caller application needs to specify.
You can retrieve a list of activity patterns using the following:
• GET /claim/v1/claims/{claimId}/activity-patterns
You can optionally specify values for the following fields, each of which overrides the value coming from the activity
pattern:

Field Datatype Description Default

description string The activity's description Typically comes from the activity
pattern
dueDate datetime The date by which the activity is expected to Typically calculated based on
be completed values in the activity pattern
escalationDate datetime The date on which the activity will be Typically calculated based on
escalated if it has not yet been completed values in the activity pattern
externallyOwned Boolean Whether the activity is to be assigned to an Typically comes from the activity
external group or external user pattern
importance Typekey (a value from the The activity's importance, as reflected on Typically comes from the activity
ImportanceLevel typelist) the user's calendar pattern
mandatory Boolean Whether the activity must be completed Typically comes from the activity
(true) or can be skipped (false) pattern
priority Typekey (a value from the The activity's priority Typically comes from the activity
Priority typelist) pattern
recurring Boolean Whether the activity repeats. If true, Typically comes from the activity
completing the activity creates a new one. pattern
subject String The activity's subject Typically comes from the activity
pattern

Examples of creating activities

The following is an example of creating a contact_insured activity for claim cc:102. The activity defaults to all
values in the contact_insured activity pattern.

POST /claim/v1/claims/cc:102/activities

{
"data": {
"attributes": {
"activityPattern": "contact_insured"
}
}
}

The following is an example of creating a legal_review activity for claim cc:102. In this case, two activity pattern
values are overridden: the activity is mandatory (it cannot be skipped) and the priority is urgent.

POST /claim/v1/claims/cc:102/activities

{
"data": {
"attributes": {
"activityPattern": "legal_review",
"mandatory": true,
"priority": {
"code": "urgent"
}
}

282 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

Assigning activities
Ultimately, every activity is assigned to a group and a user in that group. This user has the primary responsible for
closing the activity.
Activities can be temporarily assigned to queues. A queue is a repository belonging to a group which contains activities
assigned to the group but not yet to any user in that group. Users in the group can then take ownership of activities
manually as desired.
When you create an activity through Cloud API, ClaimCenter automatically executes the activity assignment rules to
initially assign the activity to a group and user. You can use the /{activityId}/assign endpoint to reassign the
activity as needed.

Assignment options
An activity can be assigned through Cloud API in the following ways:
• To a specific group and user in that group
• To a specific group only (and then ClaimCenter uses assignment rules to select a user in that group)
• To a specific group and queue
• To the claim owner
• By re-running the activity assignment rules
◦ This can be appropriate if you have modified the activity since the last time assignment rules were run and the
modification might affect who the activity would be assigned to.
The root resource for the /{activityId}/assign endpoint is Assignee. This resource specifies assignment criteria.
The Assignee schema has the following fields:

Field Type Description

autoAssign Boolean Whether to assign the activity using assignment rules
claimOwner Boolean Whether to assign the activity to the claim owner
groupId string The ID of the group to assign the activity to
queueId string The ID of the queue to assign the activity to
userId string The ID of the user to assign the activity to

The Assignee resource must specify an assignment option. It cannot be empty.

Assignment examples
When assigning activities to users, the user must be active and must have the "own activity" system permission.

Assigning to a specific group (and user)

The following payload assigns activity xc:1 to group demo_sample:31 and user demo_sample:1.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:1"
}
}
}

Activities 283
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following payload assigns activity xc:1 to group demo-sample:31. Because no user has been specified,
ClaimCenter will execute assignment rules to assign the activity to a user in group demo-sample:31.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes" : {
"groupId": "demo_sample:31"
}
}
}

Assigning to a specific queue

The following payload assigns activity xc:1 to queue cc:32. Every queue is associated with a single group, so the
activity will also be assigned to that group. Users in that group who have access to this queue can then manually take
ownership of the activity.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes" : {
"queueId": "cc:32"
}
}
}

Assigning to the claim owner

The following payload assigns activity xc:1 to the group and user that owns the claim that the activity is associated
with.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}

Using automated assignment

The following payload assigns activity xc:1 using automated assignment rules.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes": {
"autoAssign" : true
}
}
}

For more information on assignment rules, see the Gosu Rules Guide.

Retrieving recommended assignees

When ClaimCenter users are assigning activities manually, the user interface includes a drop-down list of
"recommended assignees". Typically, this list includes:
• The option to use assignment rules
• The option to assign the activity to the user who owns the activity's claim
• Users in the group the activity is currently assigned to.
• Any queues belonging to the group the activity is currently assigned to.

284 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The contents of this drop-down list are generated by an application-specific SuggestedAssigneeBuilder class. You
can access the same contents by executing a GET with one of the following /assignees endpoints:

Endpoint Returns
/common/v1/activity/{activityId}/assignees The list of suggested assignees for this activity
/claim/v1/claims/{claimId}/activity-assignees The list of suggested assignees for activities on this claim

The following is a portion of an example response from the Common API's /assignees endpoint.

GET /common/v1/activities/cc:301/assignees

RESPONSE:
{
"count": 16,
"data": [
{
"attributes": {
"autoAssign": true,
"name": "Use automated assignment"
}
},
{
"attributes": {
"claimOwner": true,
"name": "Claim/Exposure Owner"
}
},
{
"attributes": {
"groupId": "demo_sample:31",
"name": "Sue Smith (Auto1 - TeamA)",
"userId": "demo_sample:2"
}
},
{
"attributes": {
"groupId": "demo_sample:31",
"name": "Andy Applegate (Auto1 - TeamA)",
"userId": "demo_sample:1"
}
},
...
{
"attributes": {
"name": "FNOL - Acme Insurance",
"queueId": "default_data:1"
}
}
],
...

Closing activities
A general activity is closed either by completing it or skipping it. In order to be closed, the activity must be opened and
assigned to a user. (Approval activities, which are discussed later in this topic, are closed in a different way.)
When closing an activity, there are two options for the request payload:
• An empty payload
• A payload with an included note. (This option is used when you want to create a note while you close the activity.
The payload has no data section, but it does have an included section.)
All endpoints for closing activities are in the Common API.
Completing an activity
Completing an activity indicates that the corresponding action has been taken or the assignee is aware of the
corresponding issue.
The following payload completes activity xc:1.

POST /common/v1/activities/xc:1/complete

<no request payload>

Activities 285
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following payload completes activity xc:1 and creates a note.

POST /common/v1/activities/xc:1/complete

{
"included": {
"Note": [
{
"attributes": {
"body": "This activity was completed through a system API call."
},
"method": "post",
"uri": "/common/v1/activities/xc:1/notes"
}
]
}
}

Skipping an activity
Skipping an activity indicates that there is no longer a need to take the action that the activity originally identified.
Activities have a mandatory Boolean field. If this is set to true, the activity cannot be skipped.
The following payload skips activity xc:1.

POST /common/v1/activities/xc:1/skip

<no request payload>

The following payload skips activity xc:1 and creates a note.

POST /common/v1/activities/xc:1/skip

{
"included": {
"Note": [
{
"attributes": {
"body": "This activity was skipped by a system API call."
},
"method": "post",
"uri": "/common/v1/activities/xc:1/notes"
}
]
}
}

Approving an approval activity

Approval activities are associated with actions that require approval from a user with sufficient authority, such as a
manager. Approval activities are closed either by approving or rejecting the activity. This either allows or prevents the
associated action.
Approval activities can be closed only by being approved or rejected. This is unlike general activities, which must be
closed by being completed or skipped.
Approval activities often involve financial activities, such as sending money to an insured or a third party. As an added
layer of protection, caller applications may want to use checksums with calls to the /approve endpoint to ensure that
no changes were made to the activity between the time it was retrieved and the time it is to be approved. For more
information on checksums, see “Lost updates and checksums” on page 111.
When approving an activity, the options for the request payload are:
• An empty payload
• A payload with an approval rationale. (This is a string value that describes why the activity was approved or
rejected.)
• A payload with an included note.
• A payload with an approval rationale and an included note.

286 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following payload approves activity xc:2.

POST /common/v1/activities/xc:2/approve

<no request payload>

The following payload approves activity xc:2 with an approval rationale.

POST /common/v1/activities/xc:2/approve

{
"data":
{
"attributes": {
"approvalRationale": "Higher reserve approved because claimant is gold-tier customer."
}
}
}

The following payload approves activity xc:2 with an approval rationale and a note.

POST /common/v1/activities/xc:2/approve

{
"data":
{
"attributes": {
"approvalRationale": " Higher reserve approved because claimant is gold-tier customer"
}
},
"included": {
"Note": [
{
"attributes": {
"body": "This activity was approved through a Cloud API call."
},
"method": "post",
"uri": "/common/v1/activities/xc:2/notes"
}
]
}
}

There are currently no Cloud API endpoints that reject approval activities.

Additional activity functionality

The Common API contains these additional activity endpoints.

PATCHing activities
• PATCH /activities/{activityId}

Working with activity notes

• GET /activities/{activityId}/notes
• POST /activities/{activityId}/notes
For more information on notes, see “Notes” on page 295.

Activities 287
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

288 Activities
chapter 26

Documents

In ClaimCenter, a document is a file (such as a PDF, Word document, or digital photograph) which contains
information relevant to a claim. Typically, a document is an electronic file, though some insurers may also maintain
documents as physical files. Examples of documents could include reports filed by police offices, assessments of
damage from home inspectors, or correspondences with the insured.
For a complete description of the functionality of documents in ClaimCenter, see the Application Guide.
Note: Documents exist in all core InsuranceSuite applications. To ensure that documents behave in a common
way across all applications, some document endpoints, such as the endpoints for querying for document
metadata or contents, are declared in the Common API. Documents can also belong to claims, which do not
exist in all InsuranceSuite applications. This means that other document endpoints, such as the endpoint for
creating a document for a claim, are declared in the Claim API. This topic always identifies the API in which
each endpoint is declared.
Note: ContactManager provides the ability to attach documents to contacts. However, the contact must have the
"vendor" tag. Documents cannot be attached to non-vendor contacts.

Overview of documents
Document owners
Documents cannot exist on their own. They must be attached to a parent object. From a Cloud API perspective,
ClaimCenter documents are always attached to claims.
In ContactManager, documents can be attached only to vendor contacts (contacts with the "vendor" tag).

Document metadata and content

The ClaimCenter data model includes a Document entity. Instances of Document contain only document metadata, such
as the author, MIME type, and status (draft, final, and so on).
Document contents are stored in and managed by a Document Management System. ClaimCenter is almost always
integrated with a Document Management System so that users can upload documents and view and edit document
contents.
Note: The base configuration includes code to mimic Document Management System integration. This code is
suitable for demonstration purposes, but it is not recommended for production as it lacks the full range of
features found in a Document Management System, such as versioning.
Documents can exist in an InsuranceSuite application with metadata but no contents. For example, this may be
appropriate when a document is a physical piece of paper retained by the insurer. The insurer may want to track the
Documents 289
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

existence of the document and metadata about the document, even though the contents are not in the Document
Management System.
Documents cannot exist in an InsuranceSuite application with contents but no metadata.

Querying for document information

Querying for document metadata
Use the following endpoints to GET document metadata.

Endpoint Returns
/common/v1/documents/{documentId} Metadata for the given document
/claim/v1/claims/{claimId}/documents Metadata for documents on the given claim
/claim/v1/claims/{claimId}/documents/{documentId} Metadata for the given document

ContactManager also has its own /contact/v1/contacts/{contactId}/documents endpoint.

The following is a portion of an example response from the Common API's /documents/{documentId} endpoint.

GET /common/v1/documents/xc:101

{
"data": {
"attributes": {
"author": "Sue Smith",
"dateModified": "2020-12-07T23:40:23.534Z",
"docUID": "2020/11/7/235-53-425892/Legal Ownership of Property",
"id": "xc:101",
"inbound": false,
"mimeType": "text/plain",
"name": "Legal Ownership of Property",
"obsolete": false,
"section": {
"code": "legal",
"name": "Legal"
},
"status": {
"code": "final",
"name": "Final"
},
"type": {
"code": "other",
"name": "Other"
}
},
...

Querying for document content

You can use the following to GET document contents. However, these contents are base64 encoded and therefore are
not human-readable until they are decoded.
• /common/v1/documents/{documentId}/content
• /claim/v1/claims/{claimId}/documents/{documentId}/content
The following is a portion of an example response from the Common API's /documents/{documentId}/content
endpoint.

GET /common/v1/documents/xc:101/content

RESPONSE:
{
"data": {
"attributes": {
"contents": "REVWIEJVSUxEDQoNCklmIHRoZXJlIGlzIG9ubHkgYSB2aXN1YWxp
emVkIHByb2R1Y3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzIGlua
XRpYWxseSBzZXQgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRGlzYW
JsZWQNCiAgVEhFTiB0aGUgcHJvZHVjdCBpcyBpbW1lZGlhdGVseSB1bmF2YWlsYWJsZSB0byB0aGU
gc3lzdGVtIEFQSXMNCg0KSWYgdGhlcmUgaXMgYSB2aXN1YWxpemVkIHByb2R1Y3QgYW5kIGEgZmlu

290 Documents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

YWxpemVkIHByb2R1Y3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzI
GluaXRpYWxseSBzZXQgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRG
lzYWJsZWQNCiAgVEhFTiB0aGUgZmluYWxpemVkIHByb2R1Y3QgaXMgaW1tZWRpYXRlbHkgYXZhaWx
hYmxlIHRvIHRoZSBzeXN0ZW0gQVBJcw0KDQpDVVNUT01FUiBCVUlMRA0KDQpJZiB0aGVyZSBpcyBv
bmx5IGEgdmlzdWFsaXplZCBwcm9kdWN0DQogIEFORCB0aGUgIkVuYWJsZWQgZm9yIFJlc3QgQVBJI
iBmaWVsZCBpcyBpbml0aWFsbHkgc2V0IHRvIEVuYWJsZWQNCiAgQU5EIHlvdSBjaGFuZ2UgdGhlIG
ZpZWxkIHRvIERpc2FibGVkDQogIFRIRU4gdGhlIHByb2R1Y3QgaXMgaW1tZWRpYXRlbHkgdW5hdmF
pbGFibGUgdG8gdGhlIHN5c3RlbSBBUElzDQooSSBhc3N1bWUgdGhpcyBpcyB0aGUgc2FtZSBhcyAN
Cg0KSWYgdGhlcmUgaXMgYSB2aXN1YWxpemVkIHByb2R1Y3QgYW5kIGEgZmluYWxpemVkIHByb2R1Y
3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzIGluaXRpYWxseSBzZX
QgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRGlzYWJsZWQNCiAgVEh
FTiB0aGUgZmluYWxpemVkIHByb2R1Y3QgaXMgaW1tZWRpYXRlbHkgYXZhaWxhYmxlIHRvIHRoZSBz
eXN0ZW0gQVBJcw==",
"responseMimeType": "text/plain"
},
...

POSTing documents
Use the following endpoints to POST documents:
• /claim/v1/claims/{claimId}/documents
• (ContactManager) /contact/v1/contacts/{contactId}/documents
◦ In ContactManager, documents can be posted only to contacts with the "vendor" tag.

FormData objects
For most Cloud API endpoints, the request object is constructed as a body with a single string of JSON text. However,
this format is not sufficiently robust for documents. When working with documents, the caller application must send
two sets of data: the document metadata and the document contents. This is accomplished using FormData objects.
FormData is an industry-standard interface that constructs an object as a set of key/value pairs. When a caller
application is constructing a POST /documents call, the request object must be a FormData object with the following
keys:
• metadata, whose value is a JSON string identifying the document metadata
• content, whose value is the contents of the document (and whose format varies based on the document type)

Two approaches to POSTing documents

There are two ways that a caller application can create a document:
1. POST both the document metadata and content to ClaimCenter using a /documents endpoint. In this approach:
• ClaimCenter adds the document to the Document Management System through its own integration point.
• The integration point is responsible for storing values created by the Document Management System in the
document metadata (such as the document's DocUID).
2. Add the document to the Document Management System directly, and then POST the document metadata to
ClaimCenter. In this approach:
• The POST /documents call must provide any required information that comes from the Document
Management System in the metadata (such as the document's DocUID).

Minimum creation criteria

When POSTing a document:
• The metadata JSON must include the following fields:
◦ name
◦ status (a typecode from the DocumentStatusType typelist)
◦ type (a typecode from the DocumentType typelist)
• The content value is not required. For example, it may be appropriate to omit content when the document is a
physical piece of paper that does not exist in the Document Management System, or when the caller application has
added the document to the Document Management System directly.

Documents 291
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Examples of POSTing documents

The following is an example of POSTing a "Property Assessment [Link]" file for claim cc:102 through
ClaimCenter.

POST /claim/v1/claims/cc:102/documents

METADATA:
{
"data": {
"attributes": {
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}

CONTENTS:
<contents of "Property Assessment [Link]" file>

POSTing documents using Postman

About this task
From Postman, you can POST documents using FormData objects. When doing so, both the metadata and content must
be stored in separate files referenced by the Postman call.
Note: Every POST /documents endpoint supports the ability to receive the metadata as either a string or a file.
However, there is a known issue with Postman which prevents the sending of metadata as a string. When using
Postman, the metadata can be sent only as file. This is described in the following procedure. (Client
applications other than Postman may support both string and file.)

Procedure
1. Identify the files needed for the FormData object. This includes:
• A JSON file that contains the metadata. (The file extension must be .json.)
• The document file that has the content.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Under the Untitled Request label, select POST.
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to POST a document to a claim on an instance of ClaimCenter on your machine, enter: http://
localhost:8080/cc/rest/claim/v1/claims/{claimId}/documents
5. On the Authorization tab, specify authorization information as appropriate.
6. Specify the request payload.
a) In the first row of tabs (the one that starts with Params), click Body.
b) In the row of radio buttons, select form-data.
c) On the first line, for KEY, enter: metadata
d) Click outside of the metadata cell. Then, mouse over the right side of the cell. A drop-down list appears.
Change the value from Text to File.
e) For VALUE, click the Select Files button and navigate to the JSON file containing the metadata.
f) On the second line, for KEY, enter: content
g) Click outside of the content cell. Then, mouse over the right side of the cell. A drop-down list appears.
Change the value from Text to File.
h) For VALUE, click the Select Files button and navigate to the file containing the document content.
7. Click Send. The response payload appears below the request payload.

292 Documents
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

PATCHing documents
Use the following to PATCH documents:
• /common/v1/documents/{documentId}
• /claim/v1/claims/{claimId}/documents/{documentId}
Logically speaking, a PATCH call can modify only the metadata of a document, only the content of a document, or
both.

PATCHing document metadata

Every PATCH /{documentId} call must include a metadata key/value pair, even if you want to modify only the
content.
• If you want to modify the metadata, specify the fields to modify in the JSON referenced by the metadata key.
• If you do not want to modify the metadata, have the metadata key reference a payload with no attribute values, as
shown below:

{
"data": {
"attributes": {
}
}
}

PATCHing document content

A PATCH /{documentId} call is not required to include a content key/value pair. If no content is specified, the
PATCH will update the document metadata only.
PATCHes to content are destructive, not additive. If you specify content, the new content replaces the previous
content entirely.

Examples of PATCHing documents

The following is an example of PATCHing only the metadata for document xc:101. In this example, the document
status is changed to final.

PATCH /common/v1/documents/xc:101

METADATA:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}

(No contents included with the call)

The following is an example of PATCHing only the contents for document xc:101. Presumably, the contents of
"Property Assessment [Link]" are different than the current contents of document xc:101.

PATCH /common/v1/documents/xc:101

METADATA:
{
"data": {
"attributes": {
}
}
}

CONTENTS:
<contents of "Property Assessment [Link]" file>

Documents 293
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

The following is an example of PATCHing both the metadata for document xc:101 and the content.

PATCH /common/v1/documents/xc:101

METADATA:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}

CONTENTS:
<contents of "Property Assessment [Link]" file>

DELETEing documents
Use the following to DELETE documents:
• /common/v1/documents/{documentId}
• /claim/v1/claims/{claimId}/documents/{documentId}
For example, the following request DELETEs document xc:101:

PATCH /common/v1/documents/xc:101

<no request body>

294 Documents
chapter 27

Notes

A note is a free-form record of the actions or thinking of a user or process. Notes are typically used to capture
information that cannot be easily captured in some other way on some other business object. Notes are typically
created by users, but they can be created by batch processes or other system behavior within ClaimCenter. They can
also be created by caller applications using Cloud API.
Through Cloud API, a note can be attached to a claim. It can also optionally be attached to an exposure, a
ClaimContact, or a service request on that claim. Notes can also be attached to activities.
For a complete description of the functionality of notes in ClaimCenter, see the Application Guide.
Note: Notes exist in all core InsuranceSuite applications. To ensure that notes behave in a common way across
all applications, some note endpoints, such as the endpoint for querying for a note with a given ID, are declared
in the Common API. Notes can also belong to claims, which do not exist in all InsuranceSuite applications.
This means that other note endpoints, such as the endpoint for querying for notes related to a given claim, are
declared in the Claim API. This topic always identifies the API in which each endpoint is declared.
Note: ContactManager for Cloud API includes the Common API and its endpoints for working with notes.
However, in the base configuration of the ContactManager application, there is no user interface or business
rule support for notes. The notes endpoints have been included in Cloud API for ContactManager primarily for
the sake of consistency, and also to support any insurer who wishes to configure ContactManager so that it can
work with notes.

Querying for notes

Use the following endpoints to query for notes:

Endpoint Returns
/common/v1/notes/{noteId} The note with the given ID (see below)
/claim/v1/claims/{claimId}/notes All notes associated with the given claim
/common/v1/activities/{activityId}/notes All notes associated with the given activity

The /common/v1/notes/{noteId} endpoint can be used to retrieve any note in ClaimCenter. This includes notes that
are attached to a parent object other than a claim.

Creating claim notes

Notes must be created from an existing claim or activity using one of the following endpoints:
Notes 295
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• POST claim/v1/claims/{claimId}/notes
• POST common/v1/activities/{activityId}/notes
The only field required for a note is body, which stores the note's text. You can optionally specify these fields:

Field Datatype Description Default

confidential Boolean Whether the note is confidential false
relatedTo Inline object For notes attached to claims, this is either the parent The parent claim
claim, or the child object (the ClaimContact, exposure,
or service request), if any, that the note is related to
securityType Typekey (a value from the The note's security type NULL
NoteSecurityType typelist)
subject string The note's subject NULL
topic Typekey (a value from the The note's topic type general
NoteTopicType typelist)

Minimal notes
The following is an example of creating a minimal note for claim cc:102.

POST /claim/v1/claims/cc:102/notes

{
"data": {
"attributes": {
"body": "The insured's last name, Cahill, is pronounced 'KAH-hill', not 'KAY-hill'."
}
}
}

Notes with additional details

The following is an example of creating a detailed note for claim cc:102.

POST /claim/v1/claims/cc:102/notes

{
"data": {
"attributes": {
"body": "The insured's last name, Cahill, is pronounced 'KAH-hill', not 'KAY-hill'." ,
"confidential": false,
"securityType": {
"code": "public"
},
"subject": "Pronunciation note",
"topic": {
"code": "general"
}
}
}
}

Notes attached to child objects

By default, every note is attached only to the parent claim. You can attach a note to one of the claim's child objects
using the relatedTo field. This field has the following syntax:

"relatedTo": {
"id": "<childObjectId>",
"type": "<childObjectType>"

For example, the following creates a note on claim cc:102 for the exposure with id cc:48:

POST /claim/v1/claims/cc:102/notes

{
"data": {
"attributes": {
"body": "The claimant's last name, Cahill, is pronounced 'KAH-hill', not 'KAY-hill'.",

296 Notes
 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"relatedTo": {
"id": "cc:48",
"type": "Exposure"
}
}
}
}

Notes for an activity

The following is an example of creating a note for activity xc:22.

POST /common/v1/activities/xc:22/notes

{
"data": {
"attributes": {
"body": "This activity was completed during a telephone call with the insured on 11/17."
}
}
}

Additional notes functionality

The Common API contains these additional notes endpoints.

PATCHing notes
• PATCH common/v1/notes/{noteId}

DELETEing notes
• DELETE common/v1/notes/{noteId}

Notes 297
Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

298 Notes
chapter 28

Users and groups

Cloud API provides endpoints in the Admin API to support several of the tasks associated with user and group
management.

Users
In most cases, a user is a person who is known to ClaimCenter and who is listed in the ClaimCenter database (such as
policy underwriters, claims adjusters, and billing clerks). Within the context of Cloud API authentication, this is also
referred to as an internal user.
In some cases, a user can represent a service. This occurs for caller applications which are services which are mapped
to user accounts for the purpose of managing access.
Do not confuse internal users with external users. External users are users known to ClaimCenter but who are not listed
in the ClaimCenter database (such as account holders, policy holders, and service vendors).
For information on working with services and external users, see the Cloud API Developer Guide.

Querying for user information

To retrieve information about a user, you can use the following endpoints:
• GET /admin/v1/users
• GET /admin/v1/users/{userId}
For example, the following is the snippet of the response payload when retrieving the information for user
demo_sample:1 (Andy Applegate).

GET /admin/v1/users/demo_sample:1

{
"data": {
"attributes": {
"active": true,
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},
"displayName": "650-333-3333",
"number": "6503333333"
},
"displayName": "Andy Applegate",
"employeeNumber": "1000001",
"externalUser": false,
"firstName": "Andy",
"id": "demo_sample:1",

Users and groups 299

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"lastName": "Applegate",
"roles": [
{
"displayName": "Adjuster",
"id": "adjuster",
"type": "Role"
},
{
"displayName": "Trusted for Sensitive Claims",
"id": "sensitive_claims",
"type": "Role"
}
],
"username": "aapplegate",
"vacationStatus": {
"code": "atwork",
"name": "At work"
},
"workPhone": {
"displayName": "213-555-8164",
"number": "2135558164"
}
}
}
}

Creating users
To create a user, use the following endpoint:
• POST /admin/v1/users
Note: When a user is created through Cloud API, the user's password is set to a value that cannot be used for
authentication. (The password is set to a value that is not a valid Base64 string, but the authentication
framework can authenticate passwords only when they are valid Base64 strings.) In order for the new user to
authenticate, the password must first be changed to a valid Base64 string through some other method, such as
through the user interface.

Create a minimal user

The minimum creation criteria for a user is the username. For example, the following request creates a user with the
user name "amartin".

{
"data": {
"attributes": {
"username": "amartin"
}
}
}

The following is the response payload.

POST /admin/v1/users

{
"data": {
"attributes": {
"active": true,
"displayName": "",
"externalUser": false,
"id": "cc:SVA-tE4oV6qcNvofjff8v",
"username": "amartin",
"vacationStatus": {
"code": "atwork",
"name": "At work"
}
},
"checksum": "590697d4d0c3ccc1728d9f2d1d8c4051",
"links": {
"self": {
"href": "/admin/v1/users/cc:SVA-tE4oV6qcNvofjff8v",
"methods": [
"get",
"patch"
]
}
}

300 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}

Create a typical user

You can specify additional information about a user as specified in the User schema. For example, the following
payload creates a user with the following attributes:
• First name: Adriana
• Last name: Diaz
• User name: adiaz
• Employee number: ACME-02027
• Roles: account manager (account_manager) and adjuster (adjuster)

POST /admin/v1/users

{
"data": {
"attributes": {
"firstName": "Adriana",
"lastName": "Diaz",
"username": "adiaz",
"employeeNumber": "ACME-02027",
"roles" : [
{
"id": "account_manager"
},
{
"id": "adjuster"
}
]
}
}
}

When you create a user, you can also specify the user's roles and authority limit profile.
• For more information on working with user roles, see “User roles” on page 307.
• For more information on working with authority limit profiles, see “Authority limit profiles” on page 310.

Assigning a user to a group

You cannot assign a user to a group using the /admin/v1/users endpoint. You must use the /admin/v1/groups/
{groupId}/users endpoint. For more information, see “Assigning users to groups” on page 303.

Updating users
Use the following endpoint to modify an existing user:
• PATCH /admin/v1/users/{userId}
For example, the following request updates the first name of user xc:2156

PATCH /admin/v1/users/xc:2156

{
"data": {
"attributes": {
"firstName": "Alex"
}
}
}

Deleting users
Use the following endpoint to delete an existing user:
• DELETE /admin/v1/users/{userId}

Users and groups 301

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

For example, the following request deletes user xc:2156:

DELETE /admin/v1/users/xc:2156

<no request body>

Groups
A group is a set of users who represent a single business unit or who are assigned a single body of work.
You cannot create groups through Cloud API. However, you can retrieve information about groups, and you can assign
users to groups and unassign them from groups.

Querying for groups

To retrieve information about a group, use the following endpoints:
• GET /admin/v1/groups
• GET /admin/v1/groups/{groupId}
For example, the following is the snippet of the response payload when retrieving the information for group
demo_sample:31.

GET /admin/v1/users/demo_sample:31

{
"data": {
"attributes": {
"displayName": "Alexandria Branch",
"groupType": {
"code": "branch",
"name": "Branch office"
},
"id": "demo_sample:31",
"name": "Alexandria Branch",
"parent": {
"displayName": "Eastern Region",
"id": "demo_sample:29",
"type": "Group",
"uri": "/admin/v1/groups/demo_sample:29"
},
"securityZone": {
"displayName": "Auto and Property",
"id": "default_data:1"
},
"supervisor": {
"displayName": "Sue Smith",
"id": "demo_sample:2",
"type": "User",
"uri": "/admin/v1/users/demo_sample:2"
}
},
...
}
}

Creating groups
To create a group, use the following endpoint:
• POST /admin/v1/groups
When creating a group, you must specify the following values:
• groupType - a value from the GroupType typelist, such as general
• name - a string value
• parent - A JSON object with an id field that references the id of the parent group
• securityZone - A JSON object with an id field that references the id of the group's security zone
• supervisor - A JSON object with an id field that references the id of the user who is the supervisor

302 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

As of this release, there is no endpoint for retrieving information about security zones. To identify the ID of the desired
security zone, you must use some other method.
The user who is designated as the supervisor of the group is not required to be a member of the group. Also, designated
a user as the supervisor does not automatically add the user to the group as a member.
For example, the following request creates a new group:
POST /admin/v1/groups

{
"data": {
"attributes": {
"groupType": {
"code": "general"
},
"name": "Cloud API Group 1",
"parent": {
"id": "systemTables:1"
},
"securityZone": {
"id": "default_data:1"
},
"supervisor": {
"id": "demo_sample:7"
}
}
}
}

Assigning users to a group

You cannot assign a user to a group using the /admin/v1/users endpoint. You must use the /admin/v1/groups/
{groupId}/users endpoint. For more information, see “Assigning users to groups” on page 303

Assigning users to groups

The GroupUser entity
In ClaimCenter, users and groups are tracked as separate User and Group entities. There is a third entity, GroupUser,
whose purpose is to track information about one assignment of a user to a group. For example, if an instance of
GenericCenter has two groups and three users and every user belongs to every group:
• There would be two instances of Group
• There would be three instances of User
• There would be six instances of GroupUser (user 1 to group A, user 1 to group B, user 2 to group A, and so on)
In addition to tracking a single user assignment to a group, the GroupUser entity also tracks information about the
user’s capabilities within the group. This includes the following fields:
• manager - Boolean indicating whether the user has permission to view the activity of others in the group
• member - Boolean indicating whether the user is a working member of the group (for purposes of work assignment),
as opposed to simply being associated with the group as a manager or other auxiliary person
• loadFactor - Percent of work that can be assigned to the user

Querying for group/user information

To retrieve information about user assignments for a group, use the following endpoints:
• GET /admin/v1/groups/{groupId}/users
◦ Returns a collection of user assignments for the group
• GET /admin/v1/groups/{groupId}/users/[groupUserId}
◦ Returns information about a specific user assignment to the group
For example, the following is the snippet of the response payload when retrieving the information for the GroupUser
assignments in group demo_sample:31. Note that the count is 12, which means the group has 12 users. Information is

Users and groups 303

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

then provided about each GroupUser assignment, including who the user is, and whether the user is a member or a
manager.

GET /admin/v1/users/demo_sample:31/users

{
"count": 12,
"data": [
{
"attributes": {
"id": "cc:SfZwdri9ldAAUgR46xZT7",
"manager": false,
"member": true,
"user": {
"displayName": "Andy Applegate",
"id": "demo_sample:1",
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
}
},
...
},
{
"attributes": {
"id": "cc:SZPhG_CUIA3E1sO2AiZ_s",
"manager": false,
"member": true,
"user": {
"displayName": "Betty Baker",
"id": "demo_sample:8",
"type": "User",
"uri": "/admin/v1/users/demo_sample:8"
}
},
...
},
...

Adding a user to a group

To add a user to a group, use the following endpoint:
• POST /admin/v1/groups/{groupId}/users
In the request, you must specify the user to be added to the group. You can optionally specify other attributes. If you do
not, the following default values are used:
• member: true
• manager: false
• loadFactor: null
For example, the following request adds user demo_sample:18 to group demo_sample:31.

POST /admin/v1/groups/demo_sample:31/users

{
"data": {
"attributes": {
"user": {
"id": "demo_sample:18"
}
}
}
}

This assigns user demo_sample:18 to group demo_sample:31 as a member. The user is not a manager of the group and
has a null load factor. (If a field’s value is null, the field is not included in Cloud API responses.)

Modifying information about a user’s GroupUser assignment

To modify a user’s GroupUser assignment information, use the following endpoint:
• PATCH /admin/v1/groups/{groupId}/users/{groupID}
For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser
object whose id is xc:55. This user is a member of the group and not a manager of the group. The following PATCHes

304 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

the GroupUser assignment so that the user is a manager of the group and not a member. (They can view work assigned
to other users in the group, and they will not have work assigned to them.)

PATCH /admin/v1/groups/demo_sample:31/users/xc:55

{
"data": {
"attributes": {
"manager": true,
"member": false
}
}
}

Removing a user from a group

To remove a user from a group, you must delete the corresponding GroupUser assignment. To do this, use the
following endpoint:
• DELETE /admin/v1/groups/{groupId}/users/{groupUserId}
For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser
object whose id is xc:55. The following request removes user demo_sample:18 to group demo_sample:31.

DELETE /admin/v1/groups/demo_sample:31/users/xc:55

<no request body>

Updating groups
Use the following endpoint to modify an existing group:
• PATCH /admin/v1/groups/{groupId}
For example, the following request updates the supervisor of group xc:202:
PATCH /admin/v1/groups/xc:202

{
"data": {
"attributes": {
"supervisor": {
"id": "demo_sample:6"
}
}
}
}

Deleting groups
Use the following endpoint to delete an existing group:
• DELETE /admin/v1/groups/{groupId}
For example, the following request deletes group xc:202:
DELETE /admin/v1/groups/xc:202

<no request body>

Queues
A queue is a named repository that belongs to a specific group and that contains activities assigned to the group but not
yet to any user in the group. Users who belong to the group can assign activities in a queue to themselves. Queues are
often used to allow users in a group to take ownership of activities as their workload or expertise permits.
In the data model, queues are managed using the AssignableQueue data model entity.
In order to work with queues in the base configuration, the following must exist:

Users and groups 305

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• Support for queues in the data model

• Assignment methods that let activities be assigned to queues
• Rules that create queues automatically, and/or user interface controls that let administrators create queues manually
• User interface screens to let users view queues and the activities assigned to them, and to take ownership of
activities in the queue
The base configuration of ClaimCenter has all of the above items. Thus, the base configuration of ClaimCenter
supports queues.
The base configuration of PolicyCenter and BillingCenter have the first two items only. PolicyCenter and BillingCenter
can support queues, but further configuration is required.

Queues in Cloud API

Cloud API provides a set of endpoints for managing queues. These endpoints exist for ClaimCenter, PolicyCenter, and
BillingCenter.
• In ClaimCenter, users can readily work with queues created through Cloud API.
• In PolicyCenter and BillingCenter, additional user interface configuration is required to provide users with access to
any queues created through Cloud API.

Working with queues

Querying for queues
To query for information about queues, use the following endpoints:
• GET /admin/v1/groups/{groupId}/queues
• GET /admin/v1/groups/{groupId}/queues/{queueId}
For example, the following request retrieves information about queue cc:790 for group cc:118:

GET /admin/v1/groups/cc:118/queues/cc:790

{
"data": {
"attributes": {
"description": "Auto-created FNOL queue for group",
"id": "xc:790",
"name": "FNOL",
"subGroupVisible": false
},
...

Creating queues
Use the following endpoint to create queues:
• POST /admin/v1/groups/{groupId}/queues
When creating queues, the only required values are:
• name - A string
• subGroupVisible - A Boolean indicating whether the queue is visible from sub-groups of the group to which it
belongs
For example, the following request creates a new queue for group cc:118:

POST /admin/v1/groups/cc:118/queues

{
"data": {
"attributes": {
"name": "Damaged vehicle evaluations",
"subGroupVisible": true
}
}
}

306 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Modifying and deleting queues

To PATCH a queue, use the following endpoint:
• PATCH /admin/v1/groups/{groupId}/queues/{queueId}
For example, the following request PATCHES queue cc:990 for group cc:118:

PATCH /admin/v1/groups/cc:118/queues/cc:990

{
"data": {
"attributes": {
"description": "Queue for activities to process evaluations of damaged vehicles"
}
}
}

To DELETE a queue, use the following endpoint:

• DELETE /admin/v1/groups/{groupId}/queues/{queueId}
For example, the following request deletes queue cc:990 belonging to group cc:118:

DELETE /admin/v1/groups/cc:118/queues/cc:990

<no request body>

Assigning activities to queues

You can assign activities to queues through Cloud API. For more information, see “Assigning activities” on page 283.

User roles
A system permission is a granular permission that identifies something a user can view, edit, create, or otherwise work
with.
A user role is a named group of system permissions. User roles simplify the work of granting access by allowing a set
of related system permissions to be assigned to a user. (Note that in most Guidewire documentation, user roles are
referred to simply as "roles". The Cloud API documentation uses the term "user role" to help distinguish them from
"API roles", which is a feature with a similar purpose but different underlying functionality.)

Querying for user roles

To retrieve information about user roles, use the following endpoints:
• GET /admin/v1/roles
• GET /admin/v1/roles/{roleId}
For example, the following is the snippet of the response payload when retrieving the first four roles in the base
configuration.

GET /admin/v1/roles?pageSize=4

{
"count": 5,
"data": [
{
"attributes": {
"carrierInternal": true,
"description": "Permissions for account admin",
"displayName": "Account Manager",
"id": "account_manager",
"name": "Account Manager"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "All permissions related to activity rules",
"displayName": "Activity Rules Admin",
"id": "activity_rules_admin",

Users and groups 307

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"name": "Activity Rules Admin"

}
},
{
"attributes": {
"carrierInternal": true,
"description": "Permissions to edit activity rules",
"displayName": "Activity Rules Editor",
"id": "activity_rules_editor",
"name": "Activity Rules Editor"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "Permissions to view activity rules",
"displayName": "Activity Rules Viewer",
"id": "activity_rules_viewer",
"name": "Activity Rules Viewer"
}
}
]
}

Querying for permissions in a user role

To retrieve information about the permissions in a given user roles, use the following endpoints:
• GET /admin/v1/roles/{roleId}/permissions
• GET /admin/v1/roles/{roleId}/permissions/{permissionId}
For example, the following is the snippet of the response payload when retrieving the first three permissions associated
with a "claims_adjuster" role:

GET /admin/v1/roles/claims_adjuster/permissions

{
"count": 25,
"data": [
{
"attributes": {
"id": "sample_data:213",
"permission": {
"code": "lvprint",
"name": "Print listviews"
}
},
...
},
{
"attributes": {
"id": "sample_data:222",
"permission": {
"code": "searchpols",
"name": "Search related policies"
}
},
...
},
{
"attributes": {
"id": "sample_data:210",
"permission": {
"code": "actview",
"name": "View activities"
}
},
...
},
...

Creating user roles

To create a role through Cloud API, you must use multiple endpoints. The role itself is created using the /roles
endpoint. Permissions are added to the role using the /permissions endpoint.

Create the role

To create a role, use the following endpoint:

308 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

• POST /admin/v1/roles
For new roles, you must specify the following:
• name
• roleType
roleType must be a value from the RoleType typelist. The following table summarizes the role types available in
InsuranceSuite.

Name Code Description Application

User Role user Role associated with Users All InsuranceSuite applications
Producer Code Role producercode Role associated with Producer Codes PolicyCenter only
User Producer Code Role userproducercode Role associated with Users and Producer Codes PolicyCenter only

For example, the following creates a new user role for users named "finance_admin".

POST /admin/v1/roles

{
"data": {
"attributes": {
"roleType": {
"code": "user"
},
"name": "finance_admin"
}
}
}

Add permissions to the role

To add a permission to a role, use the following endpoint:
• POST /admin/v1/roles/{roleId}/permissions
You must specify the permission to be added by its code from the SystemPermissionType typelist.
For example, the following adds the notecreate permission to the user role with id xc:222.

POST /admin/v1/roles/xc:222/permissions

{
"data": {
"attributes": {
"permission": {
"code": "notecreate"
}
}
}
}

There is no way to specify multiple permissions in a single call to the /permissions endpoint. You must invoke the /
permissions endpoint once for each permission to be added to a role.

Creating user roles with permissions in a single call

You can create a user role and one or more permissions for the role in a single call using request inclusion. In this case,
the name of the included resource is RolePermission. For more information on request inclusion, see “Request
inclusion” on page 99.
For example, the following call creates a user role with one permission.

POST /admin/v1/roles

{
"data": {
"attributes": {
"roleType": {
"code": "user"
},

Users and groups 309

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"name": "finance_admin"
}
},
"included": {
"RolePermission": [
{
"attributes": {
"permission": {
"code": "noteview"
}
},
"method": "post",
"uri": "/admin/v1/roles/this/permissions"
}
]
}
}

Updating user roles

Use the following endpoints to modify an existing role.

Endpoint Description
PATCH /admin/v1/roles/{roleId} Modify attributes about the role, such as its name or description
DELETE /admin/v1/roles/{roleId}/permissions/ Remove a permission from a role
{permissionId}
DELETE /admin/v1/roles/{roleId} Delete a role

Example of PATCHing a role

The following request modifies the name and description of role xc:222.

PATCH /admin/v1/roles/xc:222

{
"data": {
"attributes": {
"name": "Finance Administrator",
"description": "User role for finance administrators"
}
}
}

Example of removing a permission

The following request removes the permission with id xc:515 (notecreate) from role xc:222.

DELETE /admin/v1/roles/xc:222/permissions/xc:515

<no request body>

Example of DELETEing a role

The following request deletes role xc:222.

DELETE /admin/v1/roles/xc:222

<no request body>

You cannot a delete a role if it is associated with one or more users.

Authority limit profiles

In ClaimCenter, an authority limit is a restriction placed upon a user that limits the types of transactions that user can
make. It can also determine whether these new transactions require approval from someone with greater authority. An
authority limit profile is a named collection of authority limits. Through Cloud API, you can create, modify, delete, and
retrieve information about authority limit profiles.

310 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Note that there are two types of authority limit profiles: assignable and custom. The information used by an authority
profile limit changes based on its type.
• An assignable authority limit profile is created outside of the context of any user and it can be assigned to multiple
users. Assignable authority limit profiles capture logic that is needed by a large group of users.
• A custom authority limit profile is created for a specific user. Custom authority limit profiles are a convenient way
of specifying authority limits for a user whose needs are unlikely to be shared by any other user. Custom authority
limit profiles cannot be shared across users.

Retrieving information about authority limit profiles

To retrieve information about an authority limit profile and its limits, use the following endpoints.

Endpoint Retrieves
GET /admin/v1/authority-limit-profiles A list of all authority limit profiles
GET /admin/v1/authority-limit-profiles/ Information about a specific authority limit profile
{authorityLimitProfileId}
GET /admin/v1/authority-limit-profiles/ A list of limits for a specific authority limit profile
{authorityLimitProfileId}/limits
GET /admin/v1/authority-limit-profiles/ Information about a specific limit in a specific authority
{authorityLimitProfileId}/limits/{limitId} limit profile

For example, the following request retrieves information about authority profile limit "default_data:1".

GET /admin/v1/authority-limit-profiles/default_data:1

{
"data": {
"attributes": {
"currency": {
"code": "usd",
"name": "USD"
},
"custom": false,
"description": "Adjuster default authority",
"displayName": "Adjuster",
"id": "default_data:1",
"name": "Adjuster"
}
}
...
}

The following request retrieves information about the limits for authority profile limit "default_data:1". There are two
limits, one limiting claim payments to date to $15,000 USD and one limiting claim total reserves to $15,000 USD.

GET /admin/v1/authority-limit-profiles/default_data:1/limits

{
"count": 2,
"data": [
{
"attributes": {
"id": "default_data:2",
"limitAmount": {
"amount": "15000.00",
"currency": "usd"
},
"limitType": {
"code": "cptd",
"name": "Claim payments to date"
}
},
...
},
{
"attributes": {
"id": "default_data:1",
"limitAmount": {
"amount": "15000.00",
"currency": "usd"
},
"limitType": {

Users and groups 311

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"code": "ctr",
"name": "Claim total reserves"
}
},
...
}
]

Creating authority limit profiles

To create an assignable authority limit profile, use the following endpoint:
• POST /admin/v1/authority-limit-profiles
Create an assignable profile
An assignable authority limit profile is created outside of the context of any user and it can be assigned to multiple
users. Assignable authority limit profiles capture logic that is needed by a large group of users.
For assignable authority limit profiles, you must specify the following:
• name
• currency (a typecode from the Currency typelist)
The AuthorityLimitProfile resource also has a custom field, which defaults to false. Therefore, for assignable
authority limit profiles, you do not need to specify it.
For example, the following creates a new assignable authority limit profile whose name is "financial admin" and whose
currency is USD.

POST /admin/v1/authority-limit-profiles

{
"data": {
"attributes": {
"name": "Financial admin",
"currency": {
"code": "usd"
}
}
}
}

Create a custom profile

A custom authority limit profile is created for a specific user. Custom authority limit profiles are a convenient way of
specifying authority limits for a user whose needs are unlikely to be shared by any other user. Custom authority limit
profiles cannot be shared across users.
For custom authority limit profiles, you must specify the following:
• custom (which must be set to true)
• currency (a typecode from the Currency typelist)
You cannot specify a name for a custom authority limit profile.
For example, the following creates a new custom authority limit profile whose currency is USD.

POST /admin/v1/authority-limit-profiles

{
"data": {
"attributes": {
"custom": true,
"currency": {
"code": "usd"
}
}
}
}

Note that in the ClaimCenter user interface, you cannot create a custom profile that is not assigned to any user. Custom
profiles are always created in the context of a specific user. In Cloud API, you can create a custom profile that is not

312 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

assigned to any user. You can then assign that profile to a single user. However, if you attempt to assign it to multiple
users, the second attempt will fail.
Assigning authority limit profiles to users
You can assign an authority profile limit to a user either when you POST the user or by PATCHing the user. To assign
the profile, include the authorityLimitProfile attribute, and set the child id field to the id of the appropriate profile.
For example, the following request assigns authority limit profile cc:999 to user demo_sample:10.

PATCH /admin/v1/users/demo_sample:10

{
"data": {
"attributes": {
"authorityLimitProfile": {
"id": "cc:999"
}
}
}
}

You can assign assignable profiles to any number of users. You can assign custom profiles to only a single user. If you
attempt to assign a custom profile to multiple users, you will get a validation error similar to the following:

"The custom authority limit profile is associated with another user. Each custom authority
limit profile can be associated to only a single user."

Adding limits to the profile

To add a limit to a profile, use the following endpoint:
• POST /admin/v1/authority-limit-profiles/{authorityLimitProfileId}/limits
Each call to the /authority-limit-profiles/{authorityLimitProfileId}/limits endpoint can specify only one
limit. To create multiple limits for a profile, you must invoke the endpoint multiple times.
You must specify two values for each limit:
• The limitType, which is a code from the AuthorityLimitType typelist.
• The limitAmount, which must specify an amount and a currency
For example, the following adds the claims total reserves limit (ctr) to authority limit profile cc:1208. The amount is
15,000 USD.

POST /admin/v1/authority-limit-profiles/cc:1208/limits

{
"data": {
"attributes": {
"limitType": {
"code": "ctr"
},
"limitAmount": {
"currency": "usd",
"amount": "15000"
}
}
}
}

Creating authority limit profiles and grants in a single call

You can create an authority limit profile and one or more limits for the profile in a single call using request inclusion.
In this case, the name of the included resource is AuthorityLimit. For more information on request inclusion, see
“Request inclusion” on page 99.
For example, the following call creates an authority limit profile and two limits (claim total reserves limited to $15000
and payment amount limited to $5000).

POST /admin/v1/authority-limit-profiles

Users and groups 313

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

{
"data": {
"attributes": {
"name": "Financial admin",
"currency": {
"code": "usd"
}
}
},
"included": {
"AuthorityLimit": [
{
"attributes": {
"limitType": {
"code": "ctr"
},
"limitAmount": {
"currency": "usd",
"amount": "15000"
}
},
"method": "post",
"uri": "/admin/v1/authority-limit-profiles/this/limits"
},
{
"attributes": {
"limitType": {
"code": "pa"
},
"limitAmount": {
"currency": "usd",
"amount": "5000"
}
},
"method": "post",
"uri": "/admin/v1/authority-limit-profiles/this/limits"
}
]
}
}

Updating authority limit profiles

Use the following endpoints to modify an existing authority limit profile.

Endpoint Description
PATCH /admin/v1/authority-limit-profiles/ Modify attributes about the given authority limit profile
{authorityLimitProfileId}
PATCH /admin/v1/authority-limit-profiles/ Modify attributes about the given limit for the given
{authorityLimitProfileId}/limits/{limitId} authority limit profile
DELETE /authority-limit-profiles/ Remove the given limit from the given authority limit
{authorityLimitProfileId}/limits/{limitId} profile
DELETE /admin/v1/authority-limit-profiles/ Delete the given authority limit profile
{authorityLimitProfileId}

Examples of PATCHing an authority limit profile

The following request modifies the name and description of authority limit profile cc:1208.

PATCH /admin/v1/authority-limit-profile/cc:1208

{
"data": {
"attributes": {
"name": "Finance Administrator",
"description": "Authority limit profile for finance administrators"
}
}
}

The following request modifies the cc:33 limit (claim total reserve) of authority limit profile cc:1208.

PATCH /admin/v1/authority-limit-profile/cc:1208/limits/cc:33

314 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"data": {
"attributes": {
"limitAmount": {
"currency": "usd",
"amount": "30000"
}
}
}
}

Example of removing a limit

The following request removes limit id cc:33 (claim total reserve) from authority limit profile cc:1208.

DELETE /admin/v1/authority-limit-profile/cc:1208/limits/cc:33

<no request body>

Example of DELETEing an authority limit profile

The following request deletes authority limit profile cc:1208.

DELETE /admin/v1/authority-limit-profile/cc:1208

<no request body>

You cannot a delete an authority limit profile if it is associated with one or more users.

Users and groups 315

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

316 Users and groups

chapter 29

Typelist metadata

There may be situations where a caller application needs to retrieve information about ClaimCenter typelists. For
example, a caller application may need to know:
• The code for a specific typecode
• A list of all typecodes for a typelist
• A list of all typecodes for a typelist associated with a given typekey filter
The Common API contains two /typelist endpoints to help retrieve this information.

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.

Typelist metadata 317

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

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:[Link]
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:[Link],[Link]

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:[Link],[Link]

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:[Link],[Link]

318 Typelist metadata

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

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” on page 29.
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
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify Basic Auth authorization using user su and password gw.
3. Enter the following call and click Send:
• GET [Link]
4. The response payload contains all non-retired claimant types. Verify that the first three codes in the payload are:
insured, householdmember, veh_ins_driver.)
5. Modify the call by adding the following query parameter to the end, and then click Send:
• ?typekeyFilter=category:cn:[Link]
6. 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.)

Typelist metadata 319

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

320 Typelist metadata

chapter 30

Batch processes

The ClaimCenter base configuration comes with a set of batch processes that can be scheduled to run maintenance
tasks periodically. You can also run batch processes on demand.
Cloud API provides support for batch processes. This includes retrieving the status of a batch process, and starting and
stopping a batch process. Third-party batch process schedulers can also use the batch process endpoints to manage
batch process scheduling externally.
For more information on the base configuration functionality of batch processes, see the Administration Guide.

Overview of batch processes

A batch process is a process that typically runs on a scheduled basis to perform some sort of action on a set of business
objects. Batch processes usually perform actions that are needed due to the passing of time. For example, the Activity
Escalation batch process identifies all unescalated activities that are open past their due date and then escalates those
activities.

Batch process types

Every batch process has a batch process type. This is a value from the BatchProcessType typelist. For example, the
batch process type for the Activity Escalation batch process is ActivityEsc.

Running batch processes

Batch processes are typically scheduled to run on a recurring basis, such as twice every hour or once every month.
Batch process can also be run on demand. This can be done from the user interface, from a command line, from a
SOAP API call, and from Cloud API.

Batch process arguments

Some batch processes let you specify arguments when you run the batch process. These arguments perform the
function of input parameters.
For example, the Purge Async API Requests batch process removes stale information about API requests that were
executed asynchronously. By default, the batch process removes information for asynchronous requests that are more
than 7 days old. However, when running this batch process, you can include an argument that specifies a different
number of days.

Batch processes 321

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Querying for batch process information

Use the following endpoints to retrieve information about batch processes:
• GET /systemtools/v1/batch-processes
• GET /systemtools/v1/batch-processes/{batchProcessType}
When querying for information on a specific batch process, you must include the batch process type as defined in the
BatchProcessType typelist. This value is case-sensitive. For example, to query for information on the Activity
Escalation batch process, use the following:
GET /systemtools/v1/batch-processes/ActivityEsc

The BatchProcess resource

Cloud API manages batch process information using the BatchProcess resource. This resource contains the following
fields:

Field Description Returned By Default?

type The batch process's BatchProcessType. Yes
status An inline object with status information, such as startDate, Yes
dateCompleted, opsCompleted, and failedOps.
distributed A Boolean indicating whether the batch process is distributed. Yes
workQueueStatus If the batch process is distributed, this is an inline object Only if the batch process is distributed
containing information on the worker status for the batch process.
processId The ID for a newly created process. Only in the response to the /start
endpoint, and only if the call to the /
start endpoint started the batch
process
wasStopped A Boolean indicating whether the batch process was stopped. Only in the response to the /stop
endpoint

The information in the response varies based on whether the batch process has completed, is running, or has never been
run.

Response for a completed batch process

The following is an example of querying for the Activity Escalation batch process after the batch process has been run.
Note that the status object includes the dateCompleted field, and there is no opsExpected field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
"data": {
"attributes": {
"distributed": false,
"status": {
"dateCompleted": "2022-09-19T17:30:00.021Z",
"dateCreated": "2022-09-19T17:30:00.003Z",
"failedOps": 0,
"opsCompleted": 0,
"serverId": "55d109613ac9",
"startDate": "2022-09-19T17:30:00.011Z",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
}
},
...

322 Batch processes

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

Response for a running batch process

The following is an example of querying for the Activity Escalation batch process while the batch process is running.
Note that the status object includes the opsExpected field, and there is no dateCompleted field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
"data": {
"attributes": {
"distributed": false,
"status": {
"dateCreated": "2022-09-19T17:30:00.003Z",
"failedOps": 0,
"opsCompleted": 0,
"opsExpected": 0,
"progress": "1 out of 3",
"serverId": "55d109613ac9",
"startDate": "2022-09-19T17:30:00.011Z",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
}
},
...

Response for a batch process that has never been run

The following is an example of querying for the Activity Escalation batch process before the first iteration of the batch
process. Note that the status object includes only the failureReason field and the type field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
"data": {
"attributes": {
"distributed": false,
"status": {
"failureReason": "This batch process type has never run",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
}
},
...

Managing batch processes

You can use Cloud API endpoints to start and stop batch processes.

Starting a batch process

Use the following endpoint to start a batch process:
• POST /systemtools/v1/batch-processes/{batchProcessType}/start
The POST does not require a request body. However, if the batch process has arguments and Cloud API supports those
arguments, you can add an optional request body to specify arguments. For more information, see “Starting a batch
process with arguments” on page 324.
The response to the /start endpoint includes the processId field. This value serves two purposes:
• It verifies that the batch process was started as a result of the call to the /start endpoint. If the batch process could
not be started, such as when the process is already running, then this value does not appear in the response.
• This value may be required by other tools, such as the Guidewire SOAP-based MaintenanceToolsAPI, which needs
the process ID to get batch process status or request batch process termination.

Batch processes 323

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

A batch process can be categorized as MaintenanceOnly, which means the batch process is not available if the server's
run level is above NODAEMONS mode. The /start endpoint is not available for MaintenanceOnly batch processes
when the server's run level is above NODAEMONS mode.
Batch processes can also be categorized as APIRunnable. This setting impacts whether the batch process can be run
from the Guidewire SOAP-based MaintenanceToolsAPI. It does not impose any limitation on whether Cloud API can
start the batch process.

Example of starting a batch process

The following is an example of the response to starting the Activity Escalation batch process.

POST /systemtools/v1/batch-processes/ActivityEsc/start

RESPONSE:
{
"data": {
"attributes": {
"distributed": true,
"processId": 4055,
"status": {
"dateCreated": "2022-09-19T17:54:19.929Z",
"failedOps": 0,
"opsCompleted": 0,
"serverId": "55d109613ac9",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
},
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},
...

Starting a batch process with arguments

In ClaimCenter, some batch processes let you specify arguments when you run the batch process. These arguments
perform the function of input parameters, and they can change the way the batch process runs.
For example, the Purge Async API Requests batch process removes stale information about API requests that were
executed asynchronously. By default, the batch process removes information for asynchronous requests that are more
than 7 days old. However, when running this batch process, you can specify a different number of days.
In Cloud API, for some batch processes, the /start endpoint supports arguments. For these batch processes, you can
submit a request with no body, which is equivalent to starting the batch process without arguments. Or, you can submit
a request with a body that specifies arguments and their values.

Determining which arguments the /start endpoint supports

The root resource for the /start endpoint is BatchProcessArguments. This resource has one JSON object for each
base configuration batch process for which arguments are supported. To determine if you can submit arguments for a
given batch process, you must check the schema to see if a JSON object exists for that batch process.
For example, the BatchProcessArguments resource has a PurgeAsyncApiRequests object. This means that, when
using the /start endpoint to start the Purge Async API Requests batch process, you can submit arguments.

Syntax for the request body

When specifying arguments, the syntax for the request body is as follows:

{
"data": {
"attributes": {
"<batchProcessFieldName>": {
"<argument1>": <values>,
"<argument2>": <values>,
...
}

324 Batch processes

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

}
}
}

For example, the PurgeAsyncApiRequests object has one integer field, purgeDaysOld. The following request starts
the Purge Async API Requests batch process and passes in a purgeDaysOld value of 3.

POST /systemtools/v1/batch-processes/PurgeAsyncApiRequests/start

{
"data": {
"attributes": {
"purgeAsyncApiRequests": {
"purgeDaysOld": 3
}
}
}
}

Note that the structure of the JSON object varies based on the datatype of the arguments. For example, the following is
an example of starting the Database Consistency Check batch process with arguments. Note that one of the arguments,
tableNames, is an array, whereas the other, description, is a string.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
],
"description": "Start of Q1 maintenance"
}
}
}
}

If the attributes section contains any property with an unexpected name, Cloud API returns a 400 error.

Custom batch processes with arguments

Insurers can also create custom batch processes that have arguments. Starting custom batch processes with arguments
requires additional configuration. For more information, see the Cloud API Developer Guide.

Stopping a batch process

Use the following endpoint to stop a batch process:
• POST /systemtools/v1/batch-processes/{batchProcessType}/stop
The POST does not require a request body.
The response to the /stop endpoint includes the wasStopped field. This field is set to true if the batch process was
stopped while the batch process was executing. It is set to false if the batch process was not running when the /stop
request was made.
For example, the following request stops the Activity Escalation batch process:
POST /systemtools/v1/-batch-processes/ActivityEsc/stop

RESPONSE:
{
"data": {
"attributes": {
"distributed": true,
"status": {
"dateCompleted": "2022-09-19T18:00:51.304Z",
"dateCreated": "2022-09-19T18:00:51.291Z",
"failedOps": 0,
"opsCompleted": 0,
"serverId": "55d109613ac9",
"startDate": "2022-09-19T18:00:51.298Z",
"type": "ActivityEsc"
},

Batch processes 325

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
},
"wasStopped": true,
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},

326 Batch processes

chapter 31

Database consistency checks

A database consistency check (DBCC) is a check that ClaimCenter executes to verify that data in the database is
consistent.
Cloud API provides support for DBCCs. This includes running DBCCs, retrieving information about DBCCs, and
downloading DBCC reports in a zip file format.

Overview of database consistency checks (DBCCs)

A database consistency check (DBCC) is a check that ClaimCenter executes to verify that data in the database is
consistent. For example, every activity should be assigned to a group and a user (or a group and a queue). The
"Assignment check" DBCC verifies that every activity has a valid group/user/queue assignment. If there are activities
without valid assignments, it provides SQL queries to identify the number of inconsistent activities and the specific
inconsistent activities.
Cloud API provides support for DBCCs. This includes running DBCCs, retrieving information about DBCCs, and
downloading DBCC reports in a zip file format.

DBCC runs
A DBCC run refers to the execution of a DBCC. DBCC run information is stored in the ClaimCenter database. Each
DBCC run is assigned an id, the dbccId, which can be used to access that information any time after the DBCC was
run.

DBCC scopes
DBCC runs can execute every type of check on every table in the database. DBCC runs can also be limited to a
specific set of tables, and/or a specific set of check types, such as assignment checks. The complete list of DBCC check
types is defined in the ConsistencyCheckTypes typelist.

DBCC run descriptions

Every DBCC run has a description generated by ClaimCenter. It specifies which tables and checks were executed in
the DBCC run.
For example, when you execute a run with all check types on all tables, the DBCC run description is:

Tables: All.; Checks: All.

Database consistency checks 327

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

If you run the DBCCs only for the cc_activity table (but for all check types), then the description is:

Tables: cc_activity; Checks: All.

If you run only the assignment check DBCCs (on all tables), then the description is:

Tables: All.; Checks: assignmentcheck.

If you run only the assignment check DBCCs for only the cc_activity table, then the description is:

Tables: cc_activity.; Checks: assignmentcheck.

Running DBCCs
Use the following endpoint to run database consistency checks:
• POST /systemtools/v1/batch-processes/{batchProcessType}/start
The value of {batchProcessType} must be: DBConsistencyCheck.

Running all DBCCs

To run all DBCCs, execute the request with no request body. ClaimCenter runs all DBCCs on all tables for all check
types.
The following request runs all DBCCs.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

<no request body>

Running DBCCs for a specific set of tables

To limit a DBCC run to a single set of tables, you must include a request body. The body must contain a
dbconsistencycheck property with a tableNames array that names the tables.

For example, the following request runs all DBCCs for the cc_activity and cc_address tables.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
]
}
}
}
}

Note that ClaimCenter does not perform any validation to ensure that there are tables in the database with the specified
names. If there is no table corresponding to a provided table name, ClaimCenter ignores the name.

Running DBCCs for a specific set of check types

To limit a DBCC run to a single set of check types, you must include a request body. The body must contain a
dbconsistencycheck property with a checkTypes array that names the check types.

For example, the following request runs all DBCCs whose check type is either 0lengthstringcheck or
assignmentcheck.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {

328 Database consistency checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

"attributes": {
"dbconsistencycheck": {
"checkTypes": [
"0lengthstringcheck",
"assignmentcheck"
]
}
}
}
}

Note that ClaimCenter does not perform any validation to ensure that there are check types in the data model with the
specified names. If there is no check type corresponding to provided check type name, ClaimCenter ignores the name.

Adding a custom description to a DBCC run

Every DBCC has an automatically generated description that specifies which tables and checks were executed in the
DBCC.
You can optionally add a custom description to a DBCC run. To do this, you must include a request body. The body
must contain a description property. ClaimCenter prepends the user-provided description to its own generated
description.
For example, the following request runs all DBCCs with a description of "Start of Q1 maintenance".

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"description": "Start of Q1 maintenance"
}
}
}
}

The description stored in the database is:

"description": "Start of Q1 maintenance; Tables: All.; Checks: All.",

Combining Run DBCC criteria

You can combine multiple DBCC criteria in a single call.
For example, the following request runs all DBCCs for the cc_activity and cc_address tables whose check type is
either 0lengthstringcheck or assignmentcheck, and it adds a custom description of "Start of Q1 maintenance".

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
],
" checkTypes ": [
"0lengthstringcheck",
"assignmentcheck"
],
"description": "Start of Q1 maintenance"
}
}
}
}

Running a previously run DBCC

A DBCC can fail due to database consistency errors. After you have fixed the errors, you may want to rerun the DBCC
to ensure all errors have been fixed. You can do this through Cloud API by including a request body with a rerunKey
attribute. This attribute must be set to the Key value provided by the GET /systemtools/v1/database-consistency-

Database consistency checks 329

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

checks endpoint. Note that the Key value is expressed as an integer. For more information on this endpoint, see
“Querying for DBCC run information” on page 330.
For example, suppose you ran a DBCC that had errors. The GET /systemtools/v1/database-consistency-checks
endpoint identifies the Key for this run is 21. You have fixed the errors and now want to rerun the same DBCC. The
following request does this.
POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"rerunKey": 21
}
}
}
}

ClaimCenter reruns a DBCC run only when the original DBCC run reported errors. If you provide a Key value that
does not correspond to a previous run with errors, ClaimCenter ignores the request.

Querying for DBCC run information

General DBCC run information
Use the following endpoints to query for information about DBCC runs.
• GET /systemtools/v1/database-consistency-checks
• GET /systemtools/v1/database-consistency-checks/{dbccId}
For example, the following request retrieves information on DBCC run cc:303, which executed all checks against the
cc_activity and cc_address table.

GET /systemtools/v1/database-consistency-checks/cc:303

{
"data": {
"attributes": {
"description": "Tables: cc_activity, cc_address; Checks: All.",
"duration": "0.151",
"endTime": "2022-09-19T22:23:23.163Z",
"errors": 1,
"extensionsSchemaVersion": 508,
"id": "cc:303",
"key": 16,
"majorSchemaVersion": 50,
"minorSchemaVersion": 603,
"platformMajorSchemaVersion": 50,
"platformMinorSchemaVersion": 605,
"startTime": "2022-09-19T22:23:23.012Z",
"totalChecks": 17
},

The key value is needed to rerun DBCCs that report consistency errors on their first run.
The response does not include endTime if the DBCC is in progress.

DBCC run reports

Use the following endpoint to retrieve the consistency check report in a zip file format.
• GET /systemtools/v1/database-consistency-checks/{dbccId}/report
Note that the response for this endpoint is not JSON. Some API tools, such as Postman, may not be able to interact
with the response correctly.
This endpoint also accepts an errorOnly query parameter, which indicates whether to include only errors in the
consistency check report. The default is false.
If you execute a GET /report?errorsOnly=true, the response depends on the state of the DBCC.

330 Database consistency checks

 Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

DBCC is complete? Number of errors Response

Yes 1 or more A report of the errors and only the errors.
Yes 0 The following error message: "The count of consistency checks with errors
in this run is zero. To download the full report, retry the
request without the 'errorsOnly' query parameter."
No n/a The following error message: "Cannot generate the report because the
consistency check run '{0}' is still running. Retry after the
batch process is finished."

Note that when you run a DBCC using the POST /systemtools/v1/batch-processes/DBConsistencyCheck/start
endpoint, the response does not include the dbccId value. This is because, for most batch processes, the results are not
stored in the database. Therefore, there is no "ID value" that can be provided for all batch process types. If you want to
run a DBCC and then download the report through Cloud API, you must execute three calls:
1. Execute the batch process with POST /systemtools/v1/batch-processes/DBConsistencyCheck/start
2. Retrieve the dbccID value with GET /systemtools/v1/database-consistency-checks
3. Get the DBCC report with GET /systemtools/v1/database-consistency-checks/{dbccId}/report

Database consistency checks 331

Guidewire ClaimCenter for Guidewire Cloud 2022.09 Cloud API Consumer Guide

332 Database consistency checks