Guidewire ClaimCenter™

for Guidewire Cloud

Cloud API Consumer Guide

Release: 2024.11
© 2024 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: 2024.11
Document Name: Cloud API Consumer Guide
Document Revision: 05-December-2024
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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

Part 1
Basic REST operations........................................................................................................................ 15

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.............................................................................................. 21
The Guidewire API References site...........................................................................................................23
REST API fundamentals.................................................................................................................................... 24
Cloud API calls.......................................................................................................................................... 24
Resources................................................................................................................................................. 25
Endpoints................................................................................................................................................. 26
Requests and responses........................................................................................................................... 28
Testing requests and responses............................................................................................................... 29
2 GETs.................................................................................................................................................................. 33
Overview of GETs............................................................................................................................................. 33
Standard payload structures............................................................................................................................ 33
Viewing schemas...................................................................................................................................... 35
View a response schema in Swagger UI................................................................................................... 35
Sending GETs.................................................................................................................................................... 35
Send a GET using Postman....................................................................................................................... 36
Tutorial: Send a basic Postman request................................................................................................... 36
Payload structure for a basic response............................................................................................................ 36
Structure of a basic response................................................................................................................... 37
The count property.................................................................................................................................. 37
The data section....................................................................................................................................... 37
The attributes section.............................................................................................................................. 37
The checksum field................................................................................................................................... 39
The links subsection (for an element)...................................................................................................... 39
The collection-level links section.............................................................................................................. 40
Payload structure for a response with included resources.............................................................................. 40
Tutorial: Send a Postman request with included resources..................................................................... 41
Structure of a response with included resources..................................................................................... 42
The related section (for a resource)......................................................................................................... 42
The included section (for a response)...................................................................................................... 43
Including either a collection or a specific resource.................................................................................. 44
Determining which resources can be included........................................................................................ 44
3 Query parameters............................................................................................................................................47
Overview of query parameters........................................................................................................................ 47
Viewing query parameter definitions.......................................................................................................48
The fields query parameter.............................................................................................................................. 48

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

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

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

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

Tutorial: DELETE a note............................................................................................................................ 81

DELETEs and lost updates.................................................................................................................................82
7 Request headers.............................................................................................................................................. 83
HTTP headers................................................................................................................................................... 83
Overview of Cloud API headers................................................................................................................ 83
Send a request with a Cloud API header using Postman..........................................................................85
Language and locale......................................................................................................................................... 86
Preventing duplicate database transactions.................................................................................................... 87
Sticky sessions in clustered environments....................................................................................................... 87
Warming up an endpoint................................................................................................................................. 89
Handling a call with unknown elements.......................................................................................................... 89
Validating response payloads against additional constraints........................................................................... 89

Part 2
Optimizing calls.......................................................................................................................................91

8 Reducing the number of calls.......................................................................................................................... 93

Features that execute multiple requests at once............................................................................................. 93
Comparing features that execute multiple requests................................................................................ 93
Determining which feature to use............................................................................................................94
9 Composite requests......................................................................................................................................... 95
Constructing composite requests.....................................................................................................................95
The requests section................................................................................................................................ 96
Using variables to share information across subrequests........................................................................ 97
Responses to the subrequests..................................................................................................................98
The selections section............................................................................................................................ 100
Composite request examples................................................................................................................. 102
Composite request limitations....................................................................................................................... 103
Administering composite requests.................................................................................................................104
Error handling.........................................................................................................................................104
Logging................................................................................................................................................... 105
Configuring the maximum number of subrequests............................................................................... 106
Complete composite request syntax.............................................................................................................. 106
10 Request and response inclusion....................................................................................................................109
Syntax for simple parent/child relationships.................................................................................................. 109
Syntax for named relationships...................................................................................................................... 111
PATCHes in request inclusion......................................................................................................................... 113
Additional behaviors with write inclusion...................................................................................................... 114
Additional behaviors with read inclusion....................................................................................................... 115
11 Batch requests............................................................................................................................................... 117
Batch request syntax...................................................................................................................................... 117
Optional subrequest attributes.............................................................................................................. 118
Batch request examples................................................................................................................................. 118
Simple batch requests............................................................................................................................ 118
Batch requests with query parameters.................................................................................................. 119
Batch requests with request payloads................................................................................................... 119
Batch requests with distinct operations................................................................................................. 120
Administering batch requests........................................................................................................................ 120
Specifying subrequest headers.............................................................................................................. 120
Specifying onFail behavior......................................................................................................................121
Configuring the maximum number of subrequests............................................................................... 121

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

12 Lost updates and checksums......................................................................................................................... 123

Lost updates................................................................................................................................................... 123
Checksums..................................................................................................................................................... 124
Checksums for PATCHes and business action POSTs...................................................................................... 125
Tutorial: PATCH an activity using checksums.......................................................................................... 125
Tutorial: Assign an activity using checksums.......................................................................................... 126
Checksums for DELETEs..................................................................................................................................127
Send a checksum in a request header using Postman........................................................................... 127
Tutorial: DELETE a note using checksums...............................................................................................127
13 Asynchronous calls........................................................................................................................................ 131
Overview of asynchronous calls..................................................................................................................... 131
Determining when the call has been processed.................................................................................... 133
Retrieving the response using /requests/{asyncRequestId}...................................................................134
Retrieving the response from /requests/{asyncRequestId}/response................................................... 135
Sending a request asynchronously................................................................................................................. 136
Tutorial: Send a request asynchronously................................................................................................137
Retrieving the response to the original request.............................................................................................137
Response information in the /requests response.................................................................................. 137
Response information using the /response endpoint............................................................................ 138
Tutorial: Retrieve information about an asynchronous request.............................................................138
Waiting for a response synchronously........................................................................................................... 139
Tutorial: Send a request asynchronously with a wait time.....................................................................139
Asynchronous request administration........................................................................................................... 140

Part 3
Business flows: FNOL and adjudication.....................................................................................143

14 Executing FNOL.............................................................................................................................................. 145

The FNOL process in ClaimCenter.................................................................................................................. 145
Draft claims and open claims................................................................................................................. 145
Verified and unverified policies.............................................................................................................. 146
Claim validation at FNOL........................................................................................................................ 146
The FNOL process in Cloud API...................................................................................................................... 146
The Cloud API FNOL process.................................................................................................................. 146
FNOL use cases by policy state............................................................................................................... 147
Claim validation at FNOL........................................................................................................................ 148
Composite request limitations with claims............................................................................................ 149
Canceling claims..................................................................................................................................... 149
Claim modes........................................................................................................................................... 149
Creating test policies...................................................................................................................................... 149
Creating test policy data.........................................................................................................................149
Tutorial: Creating a policy using the Test Util API................................................................................... 153
Creating test data for related objects.....................................................................................................153
POSTing a minimal draft claim....................................................................................................................... 153
Tutorial: POSTing a minimal draft claim for personal auto.....................................................................154
PATCHing a draft claim....................................................................................................................................155
Tutorial: PATCHing a draft claim for personal auto................................................................................. 155
POSTing a typical draft claim.......................................................................................................................... 156
Tutorial: POSTing a typical draft claim for personal auto....................................................................... 156
Creating claims with unverified policies......................................................................................................... 157
Minimum criteria for an unverified policy and claim............................................................................. 157

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

Contacts on an unverified policy............................................................................................................ 158

Locations on an unverified policy........................................................................................................... 159
Risk units on an unverified policy........................................................................................................... 161
Coverages on unverified policies............................................................................................................ 162
PATCH an unverified policy..................................................................................................................... 165
Retrieving information about an unverified policy.................................................................................165
Submitting a draft claim................................................................................................................................. 166
Minimum criteria for submitting a claim with an unverified policy....................................................... 167
Tutorial: Submitting a draft claim........................................................................................................... 168
Canceling a draft claim................................................................................................................................... 168
Sample payload addendum............................................................................................................................168
Sample policy payload............................................................................................................................ 169
Sample draft claim payload.................................................................................................................... 170
Sample composite claim payload........................................................................................................... 171
Sample composite first-and-final........................................................................................................... 178
15 Claims.............................................................................................................................................................183
Querying for claims associated with you........................................................................................................183
Querying for a claim by claim ID.................................................................................................................... 185
Searching for active and archived claims....................................................................................................... 185
Request payload for a claim search........................................................................................................ 186
Response payload for a claim search..................................................................................................... 188
Retrieving policy information......................................................................................................................... 190
Summary of the policy endpoints.......................................................................................................... 190
Assigning claims............................................................................................................................................. 192
Validating claims.............................................................................................................................................193
ClaimCenter validation levels................................................................................................................. 193
Validating a claim through Cloud API..................................................................................................... 194
Retrieving claims from archive....................................................................................................................... 196
Closing claims................................................................................................................................................. 196
16 ClaimContacts................................................................................................................................................ 199
Overview of ClaimContacts in Cloud API........................................................................................................ 200
ClaimContact roles......................................................................................................................................... 201
Querying for ClaimContacts........................................................................................................................... 202
Creating new ClaimContacts.......................................................................................................................... 203
Creating a new ClaimContact with a reserved role................................................................................ 204
Creating a new ClaimContact with a non-reserved role.........................................................................206
Working with contacts from the policy.......................................................................................................... 208
Copying vendor contacts from ContactManager........................................................................................... 209
Creating ClaimContacts during FNOL............................................................................................................. 210
PATCHing ClaimContacts................................................................................................................................ 211
Assigning roles to existing ClaimContacts...................................................................................................... 212
Deleting ClaimContacts.................................................................................................................................. 213
Additional behaviors...................................................................................................................................... 213
Masking the taxID field...........................................................................................................................214
Role constraint endpoints...................................................................................................................... 214
Role owners endpoint............................................................................................................................ 216
Specifying pronouns for contacts........................................................................................................... 216
17 Incidents........................................................................................................................................................ 217
Overview of incidents in ClaimCenter............................................................................................................ 217
Overview of incidents in Cloud API................................................................................................................ 218
Fixed property incidents.................................................................................................................................220

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

Managing fixed property incidents........................................................................................................ 220

Managing dwelling incidents..................................................................................................................221
Managing other structure incidents.......................................................................................................222
General incidents........................................................................................................................................... 222
Injury incidents...............................................................................................................................................223
Medical diagnoses.................................................................................................................................. 224
Bodily injury points.................................................................................................................................226
Living expenses incidents............................................................................................................................... 228
Mobile property incidents..............................................................................................................................228
Baggage incidents...................................................................................................................................228
Property contents incidents................................................................................................................... 230
Vehicle incidents.................................................................................................................................... 232
Trip incidents.................................................................................................................................................. 235
Overview of trip incidents...................................................................................................................... 235
Managing trip incidents......................................................................................................................... 235
Managing trip accommodations............................................................................................................ 236
Managing trip segments.........................................................................................................................236
18 Exposures....................................................................................................................................................... 237
Overview of exposures in ClaimCenter.......................................................................................................... 237
Overview of exposures in Cloud API.............................................................................................................. 239
Creating exposures......................................................................................................................................... 240
Minimum creation criteria..................................................................................................................... 240
Building an exposure payload................................................................................................................ 241
Step 1: Identify the coverage type......................................................................................................... 241
Step 2: Identify the coverage subtype....................................................................................................242
Step 3: Create or identify the claimant.................................................................................................. 242
Step 4: Create or identify the incident................................................................................................... 243
Step 5: Identify the coverage................................................................................................................. 244
Querying for and modifying exposures.......................................................................................................... 245
Assigning exposures....................................................................................................................................... 245
Deductibles.................................................................................................................................................... 247
Additional exposure endpoints...................................................................................................................... 250
Deleting draft exposures........................................................................................................................ 250
Validating exposures.............................................................................................................................. 250
Closing exposures................................................................................................................................... 250
19 Service requests.............................................................................................................................................253
Overview of service requests in ClaimCenter.................................................................................................253
Service request kinds............................................................................................................................. 254
The service request lifecycle.................................................................................................................. 254
Invoices for service request....................................................................................................................256
Overview of service requests in the Cloud API.............................................................................................. 256
Service request APIs and vendor portals................................................................................................256
Required service request data model.................................................................................................... 257
Service request numbers........................................................................................................................257
Support for each service request kind................................................................................................... 257
Composite request limitations with service requests............................................................................ 258
Querying for service requests........................................................................................................................ 258
Creating service requests............................................................................................................................... 258
Minimum creation criteria..................................................................................................................... 258
Modifying existing service requests............................................................................................................... 260
PATCHing service requests......................................................................................................................261

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

Assigning service requests to users........................................................................................................ 261

Advancing a service request in its lifecycle.................................................................................................... 262
Submitting, accepting, and declining service requests.......................................................................... 263
Completing and canceling service requests........................................................................................... 264
Service request quotes................................................................................................................................... 265
Service request invoices................................................................................................................................. 267
Querying for invoices............................................................................................................................. 267
Creating invoices for service requests.................................................................................................... 267
Approving service request invoices........................................................................................................ 268
Marking invoices as paid........................................................................................................................ 268
Withdrawing service request invoices....................................................................................................269
20 Matters.......................................................................................................................................................... 271
Query for matters........................................................................................................................................... 271
Creating matters.............................................................................................................................................272
PATCHing matters........................................................................................................................................... 272
Assigning matters........................................................................................................................................... 273
Assignment options................................................................................................................................ 273
Assignment examples............................................................................................................................. 273
Closing and reopening matters...................................................................................................................... 274
21 Workers' compensation claims..................................................................................................................... 277
Workers' comp claims in ClaimCenter............................................................................................................ 277
Creating basic workers' comp claims............................................................................................................. 279
Creating lost wages workers' comp claims..................................................................................................... 281
Creating employer liability workers' comp claims.......................................................................................... 282
Typical basic workers' comp claim: Example.................................................................................................. 284
Managing ICD codes....................................................................................................................................... 287
Configuring Cloud API behavior with workers' comp claims.......................................................................... 292

Part 4
Business flows: Financials...............................................................................................................293

22 Reserves......................................................................................................................................................... 295
Overview of reserves in ClaimCenter............................................................................................................. 295
Querying for reserves..................................................................................................................................... 296
Creating reserves............................................................................................................................................298
Example of creating reserves................................................................................................................. 299
Example of adding to reserves............................................................................................................... 301
Acknowledging reserve transactions..............................................................................................................302
23 Creating checks.............................................................................................................................................. 303
Querying for check sets and checks............................................................................................................... 304
POSTing checks...............................................................................................................................................306
Check creation in ClaimCenter............................................................................................................... 306
Check creation through Cloud API..........................................................................................................307
Example of creating a minimal check set............................................................................................... 308
Recurrences....................................................................................................................................................309
Recurrences in ClaimCenter................................................................................................................... 309
Recurrences in Cloud API....................................................................................................................... 309
Sending checks every X months on the Nth day.................................................................................... 310
Sending checks every X months on the Nth dayOfWeek....................................................................... 310
Sending checks every X weeks on dayOfWeek....................................................................................... 311
Deductible handling....................................................................................................................................... 311

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

Deductible handling in ClaimCenter.......................................................................................................311

Deductible handling in Cloud API........................................................................................................... 312
Underpaying and overpaying deductibles.............................................................................................. 313
PATCHing checks............................................................................................................................................. 313
DELETEing checks........................................................................................................................................... 314
24 Managing the check life cycle....................................................................................................................... 315
The check life cycle prior to submission......................................................................................................... 315
Advancing a check to submission through Cloud API.............................................................................316
The check life cycle after submission............................................................................................................. 316
Advancing a check beyond submission through Cloud API.................................................................... 318
Acknowledging payment transactions........................................................................................................... 318
25 Recoveries and recovery reserves................................................................................................................. 321
Querying for recoveries and recovery reserves............................................................................................. 322
Creating recoveries and recovery reserves.................................................................................................... 323
Creating a recovery reserve....................................................................................................................323
Creating a recovery reserve set.............................................................................................................. 324
Acknowledging a recovery reserve.........................................................................................................325
Creating a recovery................................................................................................................................ 325
26 Financial calculations.................................................................................................................................... 327
Retrieving the available financial calculations................................................................................................328
Retrieving financial calculations..................................................................................................................... 329
Calculations that include all relevant transactions.................................................................................330
Calculations that filter transactions....................................................................................................... 330
Filtering transaction examples............................................................................................................... 332
Restricting access to financial calculation expressions...................................................................................337
27 Multicurrency................................................................................................................................................ 339
Multicurrency overview................................................................................................................................. 339
Multicurrency in ClaimCenter................................................................................................................ 339
Multicurrency in Cloud API.....................................................................................................................339
Retrieving multicurrency information............................................................................................................ 340
Multicurrency reserves.......................................................................................................................... 340
Multicurrency checks............................................................................................................................. 341
Exchange rate information for transactions........................................................................................... 342
POSTing multicurrency information............................................................................................................... 345
POSTing a reserve with multiple currencies........................................................................................... 345
POSTing a reserve with a custom exchange rate....................................................................................345
POSTing a check set with multiple currencies........................................................................................ 346
POSTing a check set with a custom exchange rate................................................................................. 347
Specifying multicurrency line items....................................................................................................... 348
Additional exchange rate schema fields................................................................................................. 350

Part 5
Business flows: Framework APIs.................................................................................................. 351

28 Activities........................................................................................................................................................ 353
Querying for activities.................................................................................................................................... 353
Creating activities........................................................................................................................................... 355
Assigning activities......................................................................................................................................... 356
Assignment options................................................................................................................................ 357
Assignment examples............................................................................................................................. 357
Retrieving recommended assignees.......................................................................................................359

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

Closing activities............................................................................................................................................. 359

Additional activity functionality..................................................................................................................... 362
29 Documents..................................................................................................................................................... 363
Overview of documents................................................................................................................................. 363
Querying for document information.............................................................................................................. 364
Querying for document metadata..........................................................................................................364
Querying for document content.............................................................................................................365
POSTing documents....................................................................................................................................... 365
POSTing documents using Postman....................................................................................................... 368
PATCHing documents..................................................................................................................................... 369
Sending document metadata only using JSON...............................................................................................370
DELETEing documents.................................................................................................................................... 370
30 Notes.............................................................................................................................................................. 373
Querying for notes......................................................................................................................................... 373
Creating claim notes.......................................................................................................................................374
Additional notes functionality........................................................................................................................ 375
31 Users and groups........................................................................................................................................... 377
Users.............................................................................................................................................................. 377
Querying for user information............................................................................................................... 377
Creating users.........................................................................................................................................378
Updating users....................................................................................................................................... 380
Deleting users.........................................................................................................................................380
Groups............................................................................................................................................................ 380
Querying for groups............................................................................................................................... 380
Creating groups...................................................................................................................................... 381
Assigning users to groups....................................................................................................................... 381
Updating groups..................................................................................................................................... 383
Deleting groups...................................................................................................................................... 383
Queues........................................................................................................................................................... 384
Working with queues............................................................................................................................. 384
User roles....................................................................................................................................................... 385
Querying for user roles...........................................................................................................................386
Creating user roles................................................................................................................................. 387
Updating user roles................................................................................................................................ 388
Authority limit profiles................................................................................................................................... 389
Retrieving information about authority limit profiles............................................................................ 389
Creating authority limit profiles............................................................................................................. 390
Adding limits to the profile.....................................................................................................................391
Updating authority limit profiles............................................................................................................ 392
32 Security zones................................................................................................................................................ 395
Querying for security zones........................................................................................................................... 395
Creating security zones.................................................................................................................................. 396
Modifying and deleting security zones.......................................................................................................... 396
Associating security zones with other objects............................................................................................... 397
33 Geographic zones.......................................................................................................................................... 399
34 History events................................................................................................................................................ 401
35 Typelist metadata.......................................................................................................................................... 403
The /typelists endpoints.................................................................................................................................403
Querying with typekey filters......................................................................................................................... 403
The /business-line-metadata endpoint.......................................................................................................... 405
Tutorial: Query for typelist metadata............................................................................................................. 406

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

36 Batch processes............................................................................................................................................. 407

Overview of batch processes......................................................................................................................... 407
Querying for batch process information........................................................................................................ 408
Getting information about batch process history.......................................................................................... 409
Managing batch processes............................................................................................................................. 411
Starting a batch process......................................................................................................................... 411
Starting a batch process with arguments............................................................................................... 411
Stopping a batch process....................................................................................................................... 413
37 Database consistency checks........................................................................................................................ 415
Overview of database consistency checks (DBCCs)........................................................................................415
Running DBCCs............................................................................................................................................... 416
Running a previously run DBCC.............................................................................................................. 417
Querying for DBCC run information............................................................................................................... 418
38 Business entity schemas................................................................................................................................421
Retrieve a business entity schema................................................................................................................. 421
Business entity schema query parameters.................................................................................................... 422
ETag support...................................................................................................................................................424
Schema properties......................................................................................................................................... 424
Schema properties overview.................................................................................................................. 424
Schema properties usage....................................................................................................................... 426
39 The Test Util API.............................................................................................................................................441
Enabling the Test Util API............................................................................................................................... 441
View the Test Util API in Swagger UI.............................................................................................................. 442
Test Util API endpoints................................................................................................................................... 442

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 2024.11 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 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 24 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 2024.11 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 Guidewire.

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 solely additive to the previous release.
• The July release is solely 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.

18 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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
April 1.1.0 ...is identical or additive /admin/v1
July 1.2.0 ...is identical or additive /admin/v1
October 1.3.0 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 straightforward 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.

Introduction to Cloud API 19

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
• 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:

20 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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].
• /[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.

Introduction to Cloud API 21

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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:
• [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.

22 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
◦ 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)

Introduction to Cloud API 23

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.

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.

24 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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
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 is stored in the resource's id field. For example, the
activity in the previous example has a resource ID of xc:20. For most endpoints, the id field maps to the data model
entity's PublicID field. (However, there are some endpoints that map id to a different field. For example, in
PolicyCenter, the resource ID for a line is its line prefix. This means that the line resource on a personal auto policy
has an id value of something similar to PersonalAutoLine, and not pc:114567.)
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.)

Introduction to Cloud API 25

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

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 33.

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.

26 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.

Method 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
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.

Introduction to Cloud API 27

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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)
◦ 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.

28 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 33.
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.)
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:

Introduction to Cloud API 29

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.

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]

30 Introduction to Cloud API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"

Introduction to Cloud API 31

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

32 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 47.
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 36
• “Tutorial: Send a Postman request with included resources” on page 41

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 straightforward. 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.
GETs 33
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

DataEnvelope standardizes the format of information for a single element. It specifies a data property with the
following child properties:
• 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.

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

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.
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 20.
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.

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

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.
• 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 40.

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

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
"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 48.

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

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

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 48.
Broadly speaking, there are four types of inlined resources: typelists, monetary amount values, simple references, and
complex references.

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

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.

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 123.

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": {

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

"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.
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.

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

• 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. However, the IDs of included objects are not
globally unique.

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.
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.

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

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
"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"
},

42 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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,
"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.

GETs 43
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 contacts related to the claim. 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.

Determining which resources can be included

For each endpoint, there are several ways to determine the resources that can be included.
For most endpoints, you can refer to the API definition for the endpoint to find the includable resources. There is 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 two child elements: Assignee and Note. This means that the only types of element you can
include on an activity query are assignees and notes.
For some endpoints, this method of determining inclusion resources doesn’t work. For example, in the Account API
(available in PolicyCenter), the model for GET /accounts references an AccountIncludes element. This element
shows many child elements, such as AccountContact. However, if you add ?include=AccountContact to your GET
query you’ll receive an error with a message similar to the following:

"userMessage": "Bad value for the 'include' query parameter - The requested inclusions
'[AccountContact]' are not valid for this resource. The valid options are [accountHolder,
activities, activity-assignees, activity-patterns, contacts, documents, jobs, locations, notes,
policies, primaryLocation]."

In cases such as this, the error message will specify which elements are allowed in the include.
Other than creating an error and viewing the results, there are a couple of general rules that can help determine which
elements are allowed in an include for a given endpoint: child endpoints and response payload references. (Note that
these are general guidelines, and don’t necessarily apply in all cases.)
Child endpoints
Suppose you have the following set of endpoints:
• /api/v1/endpoint
• /api/v1/endpoint/child1
• /api/v1/endpoint/child1/child2
In most cases, you can include child2 on any calls to endpoint or endpoint/child1:

GET /api/v1/endpoint?include=child2

GET /api/v1/endpoint/child1?include=child2

Response payload references

44 GETs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Suppose once again that you have the following endpoint:

• /api/v1/endpoint
Doing a GET on this endpoint returns the following response:

{
"data": {
"attributes": {
"foreignKeyEntity" {
"id": "100"
}
}
}
}

In many cases such as this you can do an include that specifies the returned attribute (or attributes, if there are more
than one):

GET /api/v1/endpoint?include=foreignKeyEntity

GETs 45
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

46 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 51
• “Tutorial: Send a GET with the filter parameters” on page 54
• “Tutorial: Send a GET with the sort query parameter” on page 56
• “Tutorial: Send a GET with the pageSize and totalCount parameters” on page 59
• “Tutorial: Send a GET with query parameters for included resources” on page 62

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
Query parameters 47
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• GET /common/v1/activities?filter=escalated:eq:false

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
With GETs, 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 60.

Field-specific query parameters may not be supported for all fields

If you attempt to use a field-specific 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, when working with activities, the sort parameter is not
supported for the escalationDate field. 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 60.
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".

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

• *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

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",

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

"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"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.

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

The fields query parameter with POSTs and PATCHes

You can also use the fields query parameter with POSTs and PATCHes to control which fields are returned in the
response. For example, the following request creates a new user. The response will contain the default fields for a User
resource (such as active, id, username, and vacationStatus).

POST /admin/v1/users

The following request also creates a new user. But, the response will contain only the id.

POST /admin/v1/users?fields=id

The fields query parameter is the only parameter you can use with POSTs and PATCHes.

Specifying fields for included resources

For information on how to use the fields parameter with included resources, see “Query parameters for included
resources” on page 60.

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.

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

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

op value Meaning Example using the GET /activities endpoint Returns activities where...
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)
• 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 60.

Determining which fields you can filter on

For a given endpoint, there are several different ways to determine which fields you can filter on. The simplest is to run
a query using a field you know to be invalid, such as GET ...?filter=dogsaregreat:eq:true. The resulting error
message will provide a list of valid fields you can filter on, similar to this:

"message": "The field 'dogsaregreat' is not a filterable field for this endpoint.
The set of filterable fields is [accountNumber, accountStatus, createdDate]."

Another option that allows you to identify some of the attributes that are filterable is by reviewing the schema
definition. If a field is filterable, then the schema definition includes the text: "filterable": true.

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

For example, the following is the schema description from Swagger UI for two fields returned by the Common API /
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.
The limitation to the preceding option is that it won't display custom filters. You might have to look at the Gosu
resource files to determine whether a customization has been added to make a field filterable. See Cloud API
Developer Guide for information on custom filters and where to find them.

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.

Filtering included resources

For information on how to use the filter parameter with included resources, see “Query parameters for included
resources” on page 60.

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.

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

◦ 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.

The assignedUser filters

Some endpoints that return assignable objects have two assignable-specific filters:
• filter=assignedUser:eq:<userID>
• filter=assignedUsername:eq:<userName>
You can use these filters to restrict a GET to return only the assignable objects that are assigned to the given user.
For example, in the sample data, claim demo_sample:1 has 14 activities. Two of them are assigned to Clara Levitt
(whose ID is demo_sample:39 and whose user name is clevitt).
The following call returns all activities for claim demo_sample:1 that are assigned to Clara, using her user ID.

GET /claim/v1/claims/demo_sample:1/activities?filter=assignedUser:eq:demo_sample::39

Note: In a REST URL, if you want to enter a String value with a colon, you must escape the character by
adding an additional colon. For example, by default, ClaimCenter generates all REST IDs with a colon, such as
demo_sample:39. When including this type of value in a filter parameter, you must specify it as
demo_sample::39 (with two colons). If you do not, you will get an error such as "The filter query
parameter 'assignedUser:eq:demo_sample:39' was specified with prefix 'assignedUser', which
does not correspond to any included resource"

The following call returns all activities for claim demo_sample:1 that are assigned to Clara, using her user name.
GET /claim/v1/claims/demo_sample:1/activities?filter=assignedUsername:eq:clevitt

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.

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

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:
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 60.

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

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

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.
• GET /common/v1/activities?sort=*none returns activities sorted only by id.

Sorting included resources

For information on how to use the sort parameter with included resources, see “Query parameters for included
resources” on page 60.

Potentially large endpoints

Some GET endpoints that retrieve a collection retrieve the data from database tables that are relatively large. The
database query that retrieves the members of the collection may perform poorly if a sort is requested on these
collections and if the sort cannot make use of an appropriate backing index.
To alert insurers to potentially bad performance, these endpoints are coded internally as being "potentially large". If a
request on a potentially large endpoint attempts to sort on columns that do not match a backing index and the query
returns too many results, the request is rejected with an error message telling the caller to add additional restrictions to
the query and/or to remove the sorts.

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 by 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.

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

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

Default and maximum pageSize values

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.
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.)

Specifying page size for included resources

For information on how to use the pageSize parameter with included resources, see “Query parameters for included
resources” on page 60.

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

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": {
"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"

58 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

]
}
}

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.
Note: 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.
Note: pageOffset is supported for root resources only. When executing a query that uses request inclusion,
you cannot use pageOffset to page through included resources.

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.

Including totals for included resources

For information on how to use the includeTotal parameter with included resources, see “Query parameters for
included resources” on page 60.

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.

Query parameters 59
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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. 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 40.
Most query parameters that can be used on primary resources can also be used on included resources.

Syntax for query parameters for included resources

To specify that a query parameter operates on an included resource, use the following syntax:

<queryParameter>=<includedResource>:<queryValue>

For example, the following GET retrieves activities and their notes. It also specifies that the number of notes to return
is limited to 5.

GET /activities?include=notes
&pageSize=notes:5

The following GET retrieves activities and their notes. It also specifies that the only fields to return for the notes are id
and subject.

GET /activities?include=notes
&fields=notes:id,subject

60 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Summary of query parameters for included resources

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.

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 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.

Query parameters 61
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Specifying query parameters at different levels

Specifying query parameters for both parent and included resources
You can specify query parameters for both a parent and included resources in the same GET. To do this, you must
specify a separate query expression for each parameter used at the parent level and for each parameter used at the
included resource level.
For example, the following query retrieves activities and their notes. For activities, only the id, description, and
dueDate fields are returned. For notes, only the id and subject are returned.

GET /activities?include=notes
&fields=id,description,dueDate
&fields=notes:id,subject

You can also use different query parameters for each resource. For example, the following query retrieves activities and
their notes. For activities, only the id, description, and dueDate fields are returned. For notes, the number of notes
per activity is limited to 5.

GET /activities?include=notes
&fields=id,description,dueDate
&pageSize=notes:5

Specifying query parameters for multiple types of included resources

You can also specify multiple types of included resources and specify different query parameters for each resource.
For example, suppose you want to GET all claims, with the main contact and reporter included. For claims, you want
only the id and claim number fields. For the main contact, you want only the id, display name, and primary phone
fields. For the reporter, you want only the display name field. To get this response, you must send the following:

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

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:
• For claims, the default claim fields are returned.

62 Query parameters
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.
In the first payload:
• For accounts, the default account fields are returned.
• For contacts, all contacts are returned.
In the second payload:
• For accounts, only the id and the accountNumber fields are returned.
• For contacts, only the contacts that are marked as primary payers are returned.

Query parameters for POSTs and PATCHes

You can use the fields query parameter with POSTs and PATCHes to control which fields are returned in the
response. For example, the following request creates a new user. The response will contain the default fields for a User
resource (such as active, id, username, and vacationStatus).

POST /admin/v1/users

The following request also creates a new user. But, the response will contain only the id.

POST /admin/v1/users?fields=id

The fields query parameter is the only parameter you can use with POSTs and PATCHes.

Query parameters 63
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

64 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 93.
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 71
• “Tutorial: Create a new note that specifies optional fields” on page 72

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 65
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

66 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 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 20.
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>
}
}
}

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

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

{
"data": {
"attributes": {
"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 353.
• The minimum required fields for activities are documented in “Documents” on page 363.
• The minimum required fields for activities are documented in “Notes” on page 373.
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

68 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Field value type Pattern Example Notes

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.
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",

POSTs 69
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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.)

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.

70 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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"
}
}
}

1. 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.

POSTs 71
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 is 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 topic (set to "Litigation").

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 is listed as one of the notes. This note is confidential and it has the category specified in the
request payload.

72 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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

POSTs 73
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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

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 123.

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

74 POSTs
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 89.

POSTs 75
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

76 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 79

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 66.

PATCHes 77
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 67.

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, select PATCH.
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.

78 PATCHes
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• Paste the request payload into the text field underneath the radio buttons.
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.

PATCHes 79
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 "!".

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 123.

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.

80 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 tutorial:
• Tutorial: “Tutorial: DELETE a note” on page 81

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 81
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.
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.
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 123.

82 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 123.
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

Request headers 83
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Header Datatype Description

be globally unique across all clients, APIs, and web
services.
For more information, see “Preventing duplicate
database transactions” on page 87.
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 89.
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 86.
GW-Locale String This sets the locale for the response.
For more information, see “Language and locale” on
page 86.
GW-UnknownPropertyHandling One of these string values: This specifies the behavior for handling request payloads
with unknown properties. The default behavior is
• log
reject.
• reject
For more information, see “Handling a call with
• ignore unknown elements” on page 89.
GW-UnknownQueryParamHandling One of these string values: This specifies the behavior for handling URLs with
unknown query parameters. The default behavior is
• log
reject.
• reject
For more information, see “Handling a call with
• ignore unknown elements” on page 89.
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 89.
Prefer String This gives the caller the ability to specify a wait time.

84 Request headers
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Header Datatype Description

(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
131.
x-gwre-session String This controls how related calls are routed on instances of
ClaimCenter running in a cluster.
(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 “Sticky sessions in clustered
environments” on page 87.
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.

Request headers 85
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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:
• 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.

86 Request headers
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.

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.

Sticky sessions 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. This behavior is sometimes referred to
as sticky sessions (or pod affinity). API Gateway provides two ways that you can implement sticky sessions with Cloud
API: session IDs (which is the default behavior) and cookies.
Note: The session ID and cookie behavior described below is a feature of API Gateway. In order for the
behavior to work as described, the caller application must use an appropriate API Gateway URL to connect to
ClaimCenter. For more information, contact Guidewire.

Request headers 87
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

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
• 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.

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.

88 Request headers
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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 placeholder 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

Request headers 89
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.

90 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 91
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

92 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 that 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 95.
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 and response inclusion” on page 109.
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 117.

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 93

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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's 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.

94 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.
◦ If the composite request has one or more subrequests, the subselections can retrieve data created or modified by
those subrequests.
◦ A composite request can also have no subrequests. In this case, the subselections merely execute multiple
queries to retrieve existing 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 consist entirely of subrequests that merely retrieve data. For more information, see “Composite
requests that execute only queries” on page 102.
Composite requests support the use of most endpoints, but not all of them. They also support many query parameters,
but not all of them. For more information, see “Composite request limitations” on page 103.
Composite requests can be submitted asynchronously. For more information, see “Asynchronous calls” on page 131.
Composite requests are limited to a maximum number of subrequests. For more information, see “Configuring the
maximum number of subrequests” on page 106.

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.

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

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.
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": {

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

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

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

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": [

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

{
"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."
}
}
}
}
]
}

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
},

98 Composite requests
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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, when executing a POST, 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.

Subresponse values can be out of date

As noted above, the individual subresponses to each subrequest specify data that has technically not been committed
yet. This means it is possible for some fields in a subresponse to be out of date by the time the entire composite request
has been processed.
For example, suppose you have a composite request that includes several subrequests. The first subrequest POSTs an
activity, and the subresponse for this subrequest includes a checksum value. When the composite request is actually
committed to the database, the actual checksum value may differ from the one initially provided in the subresponse.
If a composite request is followed by a related request and the related request must have the most up-to-date values,
then the composite request must contain a selections section that retrieves the required values. The GETs in the
selections section are always executed after all subrequests have been committed.

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.

Composite requests 99
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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": {
"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 (if any), 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": [

100 Composite requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

{
"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
106.

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.

Composite requests 101

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ 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"]
}

There may be additional query parameters you can use. For information on how to determine whether a query
parameter is supported in a composite request, see “Composite request limitations” on page 103.

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 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 171
• Creating, closing, and paying out a claim: “Sample composite first-and-final” on page 178

102 Composite requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Composite request limitations

General capabilities and limitations
Capabilities
Composite requests have the following general capabilities:
• The subrequests can make use of the following types of endpoints:
◦ Endpoints that are part of the base configuration
◦ Extension endpoints that have been created through the REST endpoint generator
• For base configuration endpoints, the subrequests can make use of extension fields added to the endpoints through
schema configuration, as described in the topic on Adding Properties to Resources in the Cloud API Developer
Guide)
Limitations
Composite requests have the following general limitations:
• The subrequests cannot make use of the endpoints that have been created outside of Cloud API, such as custom
endpoints created directly on the REST API Framework
• 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.)
• You cannot use request inclusion in composite requests.
◦ For more information on request inclusion, see “Request and response inclusion” on page 109.
• 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.
• You cannot use any POST /search/... endpoint in a composite request (such as the ClaimCenter POST /
claim/v1/search/claims-v2 or the PolicyCenter POST /policy/v1/search/policies endpoint). This is
primarily because there is no way to guarantee that a POST /search/... endpoint will return a single result.
• 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.

Supported endpoints and query parameters

By default, all endpoints can be used in a composite request. If an endpoint cannot be used in composite requests, the
definition of the endpoint includes allowForCompositeApi: false. You can search for this value in the swagger file
itself. You can also search for it in the output of the /[Link] and /[Link] endpoints. Be aware that in
the endpoint output, the value appears as x-gw-allowForCompositeApi: false.
By default, no query parameters can be used in a composite request. If a query parameter can be used in composite
requests, the definition of the query parameter includes allowForCompositeApi: true. You can search for this value
in the swagger file itself. You can also search for it in the output of the /[Link] and /[Link] endpoints.
Be aware that in the endpoint output, the value appears as x-gw-allowForCompositeApi: true.

Business-specific limitations
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.

Composite requests 103

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.

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": {

104 Composite requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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,
"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"}

Composite requests 105

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.)
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>",

106 Composite requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"parameters" : {
"fields" : "<value>",
"filter" : [<value>],
"includeTotal" : <value>,
"pageOffset" : <value>,
"pageSize" : <value>,
"sort" : [<value>]
}
},
{
<next subselection>
},
...
{
<final subselection>
}
]
}

Composite requests 107

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

108 Composite requests

chapter 10

Request and response inclusion

Inclusion is a way of accessing both a parent resource and resources relating to that parent in one command. The
availability of inclusion depends on the resource, and can be available for both requests and responses.

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".
Request inclusion can use endpoints from different APIs for included resources.

Response inclusion
Some endpoints allow you to use query parameters to include information about related resources in the response. See
“Additional behaviors with read inclusion” on page 115 and “Payload structure for a response with included
resources” on page 40 for more information.

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:
Request and response inclusion 109
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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. This
structure is used when the root resource and the included resource are being POSTed. If the root resource is being
PATCHed, the structure may differ slightly. For more information, see “PATCHes in request inclusion” on page 113.

{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"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 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".
If the included resource is being POSTed, 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. If the root resource is being PATCHed, the URI
field does not use this. For more information, see “PATCHes in request inclusion” on page 113.

110 Request and response inclusion

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 145.

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"
}
]
}
}

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:

Request and response inclusion 111

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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": [
{
"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".
If the included resource is being POSTed, 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. If the root resource is being PATCHed, the URI
field would not use this. For more information, see “PATCHes in request inclusion” on page 113.

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 145.

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"
}
]
}
}

112 Request and response inclusion

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

PATCHes in request inclusion

When using request inclusion, you can PATCH both root and included resources.
When PATCHing root resources using request inclusion, payloads generally have similar structures to POST payloads.
For more information on payload structures, see “Syntax for simple parent/child relationships” on page 109 and
“Syntax for named relationships” on page 111.
However, when PATCHing, the uri field for included resources is treated differently from POSTs.
The this keyword is invalid when PATCHing
The this keyword is a placeholder that is only used when the id of the root resource has not yet been generated. If the
root resource is being PATCHed, its id has already been generated, so the use of this results in an error.

PATCHing parent and POSTing child

Here is the basic syntax for PATCHing a parent and POSTing a child.

{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"method": "post",
"uri": "/../<parentId>/<resourceType>
}
]
}
}

PATCHing parent and PATCHing child

Here is the basic syntax for PATCHing a parent and PATCHing a child.

{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
"method": "patch",
"uri": "/../<childId>"
}
]
}
}

Note: The uri field may or may not include a placeholder for the parent id. It depends on the structure of the
endpoint the uri is referencing.
For example, if the children were a PATCHed ClaimContact and a PATCHed note, the uri fields would be:
• "uri": "/claim/v1/claims/<claimId>/contacts/<contactId>"
• "uri": "/common/v1/notes/<noteId>"

Additional example of PATCHing in request inclusion

Below is an example of a payload in which the root resource is PATCHed and included resources are PATCHed and
POSTed. This request performs the following actions:

Request and response inclusion 113

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• PATCHing a claim to set the main contact to an existing ClaimContact

• PATCHing a ClaimContact to add a cell phone number
• POSTing a note on the parent claim

PATCH [Link]
{
"data": {
"attributes": {
"mainContact": {
"id": "cc:SF6434QkBBFpxqB1dQEcJ"
}
}
},
"included": {
"ClaimContact": [
{
"attributes": {
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},
"number": "123-456-7890"
}
},
"method": "patch",
"uri": "/claim/v1/claims/demo_sample:2/contacts/cc:SF6434QkBBFpxqB1dQEcJ"
}
],
"Note": [
{
"attributes": {
"subject": "Updated main contact",
"body":"Added Allen Robertson as main contact and updated his cell phone number."
},
"method": "post",
"uri": "/claim/v1/claims/demo_sample:2/notes"
}
]
}
}

Additional behaviors with write inclusion

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.

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 note would have a value such as "/
claim/v1/claims/this/notes".

114 Request and response inclusion

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 response payload does not include child resources

When using request inclusion, the response payload just contains data about the root resource. Child resources that are
POSTed or PATCHed are not included in the response. Information on child resources cannot be retrieved using query
parameters in the initial request.
There are several ways to retrieve information on child resources that have been POSTed or PATCHed.
• Additional GET requests - Once you have successfully PATCHed or POSTed a child resource, retrieve
information on that resource with a follow-up GET request.
• Using a composite request - Composite requests are an alternate method to execute multiple requests in a single
call. The responses from each request are collected and returned in a single response payload. For more
information, see “Composite requests” on page 95.

Request inclusion can use endpoints from different APIs

Some included resources can be manipulated using different APIs. For example, notes on a claim are POSTed using the
Claim API, but notes are PATCHed using the Common API.
To POST a note, the method and uri fields look like this:
"method": "post",

"uri": "/claim/v1/claims/<claimid>/notes"

To PATCH a note, the method and uri fields look like this:
"method": "patch",

"uri": "/common/v1/notes/<noteid>"

However, some included resources are accessed through the same API as the root resource. For example,
ClaimContacts are POSTed and PATCHed through the Claim API. POSTing a ClaimContact as an included resource
would use method and uri fields similar to this:
"method": "post",

"uri": "/claim/v1/claims/<claimid>/contacts"

PATCHing a contact would use method and uri fields like this:
"method": "patch",

"uri": "/claim/v1/claims/<claimid>/contacts/<contactid>"

Additional behaviors with read inclusion

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. For more information on how to construct a GET with included
resources, see “Payload structure for a response with included resources” on page 40.

Request and response inclusion 115

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

You can also use query parameters to filter included resources. For example, the following call retrieves all activities
assigned to the current user and includes any related notes. The number of notes returned in this example is limited to
5.

GET /activities?include=notes&pageSize=notes:5

For more information on how to use query parameters with included resources, see “Query parameters for included
resources” on page 60.

116 Request and response 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 121.

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 117

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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",

118 Batch requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"path": "/claims/demo_sample:1"
},
{
"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 119

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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": [

120 Batch requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 121

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

122 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 125
• “Tutorial: Assign an activity using checksums” on page 126
• “Tutorial: DELETE a note using checksums” on page 127

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 123

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

124 Lost updates and checksums

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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).

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 127.)
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

Lost updates and checksums 125

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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]
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.

126 Lost updates and checksums

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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>"
}
}

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.

Lost updates and checksums 127

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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>.
4. Identify the id of the account in the payload. This value is referenced below as <accountId>.
5. 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.
6. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST [Link]
7. 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"
}
}
}

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

9. 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.
10. Change the operation to DELETE, enter the following URL, but do not click Send yet:
a. DELETE [Link]
11. DELETEs cannot specifies request bodies. On the third tab, navigate to the Body tab and select the none radio
button.
12. 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
13. 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.
14. Change the checksum value so that it matches the one from the POST payload.

128 Lost updates and checksums

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

15. 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".)

Lost updates and checksums 129

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

130 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 137
• “Tutorial: Retrieve information about an asynchronous request” on page 138
• “Tutorial: Send a request asynchronously with a wait time” on page 139

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.

Asynchronous calls 131

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.

132 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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:
• 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",
"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"

Asynchronous calls 133

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

],
"Content-Type": [
"application/json;charset=UTF-8"
],
"GW-Checksum": [
"321dff263827cbbd772c26676398d8ae"
],
"Location": [
"/admin/v1/users/pc:ScaA3kB5cImBkuh7bxjNn"
],
"X-Correlation-ID": [
"d516344d-5769-4964-adb7-79eaca41e4a2"
],
...
},
"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.

134 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

Asynchronous calls 135

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 139.

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
139.
• If the application is overloaded and unable to process or queue the request, it will return a 503 response.

136 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.

Asynchronous calls 137

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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:
• 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 137.

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.

138 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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
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:

Asynchronous calls 139

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.

140 Asynchronous calls

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

Asynchronous calls 141

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

142 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
• Functionality specific to workers' compensation claims
Business flows related to ClaimCenter financials are covered in a separate section of this document.

Business flows: FNOL and adjudication 143

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

144 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 153
• “Tutorial: POSTing a minimal draft claim for personal auto” on page 154
• “Tutorial: PATCHing a draft claim for personal auto” on page 155
• “Tutorial: POSTing a typical draft claim for personal auto” on page 156
• “Tutorial: Submitting a draft claim” on page 168
For sample FNOL payloads, see the “Sample payload addendum” on page 168.

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 145
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

Claim validation at FNOL

The New Claim wizard will not let you submit a claim unless:
• The claim, policy, and any incidents must reach a validation level of New Loss Completion.
• Any exposures must reach a validation level of Load Save.

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:

146 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 147

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 171.

Claim validation at FNOL

By default, claims submitted through Cloud API have the same validation requirements as claims submitted through
the New Claim wizard. That is:
• The claim, policy, and any incidents must reach a validation level of New Loss Completion.

148 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• Any exposures must reach a validation level of Load Save.

However, Cloud API supports the ability to require exposures to be at New Loss Completion along with the claim, the
policy, and any incidents. This behavior is controlled by the application configuration parameter
RequireExposuresToBeNewLossWhenSubmittingWithCloudAPI.

• When set to false, exposures are required to reach Load Save only. (This is the default.)
• When set to true, exposures are required to reach New Loss Completion.
For information on how to set application configuration parameters, see the Configuration Guide.

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.

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.

Creating test policies

To create a claim, you must have information from a Policy Administration 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.
By default, the Test Util API is not enabled. For information on how to enable Test Util API, see “Enabling the Test
Util API” on page 441.

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.

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.

Executing FNOL 149

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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, Cloud
API takes 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/
{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, Cloud API does 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 logic 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 169.

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"
},

150 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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 and response inclusion” on page 109.

{
"data": {
"attributes": {
"policyContacts": [
{
"contact": {
"refid": "rayNewton"
},
"roles": [
{
"code": "insured"
}
]
}
]
}
},
"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"
}
}
}
]
}
}
}

Executing FNOL 151

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
}
]
}
}
}

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"
}
}
]
}

152 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

]
}
}
}

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. Enable the Test Util API.
a. In Studio, open [Link].
b. Add the following to the end of the file:
published-apis.PUBLISHEDAPIS_testutil_publish = true
plugin.PLUGIN_IPOLICYSEARCHADAPTER_PROFILE = testutil-api

2. Start ClaimCenter.
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 169 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:

Executing FNOL 153

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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 153
In this tutorial, you will create a draft claim for a personal auto policy using the minimum amount of information
needed.
1. Start ClaimCenter.
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 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.

154 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 156.)

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 153
• “Tutorial: POSTing a minimal draft claim for personal auto” on page 154
◦ 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.
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.
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.

Executing FNOL 155

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 95.
• For an example of a draft claim created in a composite request, see “Sample composite claim payload” on page
171.
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 and response inclusion” on page 109.
• For an example of a draft claim created using request inclusion, see “Sample draft claim payload” on page 170.
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 199
• “Incidents” on page 217
• “Exposures” on page 237
• “Service requests” on page 253

Tutorial: POSTing a typical 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 153
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.
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 170 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.

156 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

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 95.
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 171.

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)

Executing FNOL 157

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.
Command

POST /composite/v1/composite

Request body

{
"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"
}
}
}
}
]
}

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.

158 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /composite/v1/composite

Request body

{
"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"
}
}
}
}
]
}

Locations on an unverified policy

To work with unverified policy locations, use the following endpoints:
• POST /claim/v1/unverified-policies/{policyId}/locations
• PATCH /claim/v1/unverified-policies/{policyId}/locations/{locationId}
• GET /unverified-policies/{policyId}/locations/{locationId}/property-items
• POST /unverified-policies/{policyId}/locations/{locationId}/property-items
• GET /unverified-policies/{policyId}/locations/{locationId}/property-items/{propertyItemId}
• PATCH /unverified-policies/{policyId}/locations/{locationId}/property-items/{propertyItemId}

Create an unverified policy location

There is no information required to create a location on an unverified policy. ClaimCenter provides default values for
all required fields.

Executing FNOL 159

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

The following example creates an unverified policy with a location as part of a composite request.

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"
}
}
}
}
]
}

Create a scheduled item on an unverified policy location

You can create a scheduled item on an unverified policy location with the following command:
POST /claim/v1/unverified-policies/{unverifiedPolicyId}/locations/{locationId}/property-items
No information is required in the request to create the scheduled item. However, omitting the appraisedValue and
description properties could make it difficult to retrieve scheduled items through the user interface. For example,
omitting all fields will create a blank scheduled item. This will display in the user interface as a selectable blank space
under the Loss Details Scheduled Items.
The following creates a scheduled item with an appraised value of $3,000 USD on policy cc:330 at location cc:500:
Command

POST /claim/v1/unverified-policies/cc:330/locations/cc:500/property-items

Request

{
"data": {
"attributes": {
"appraisedValue": {
"amount": "3000",

160 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"currency": "usd"
},
"description": "Ship in a bottle"
}
}
}

The following example creates a scheduled item on an unverified policy location as part of a composite request.

...
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/locations",
"body": {
"data": {
"attributes": {
}
}
},
"vars": [
{
"name": "locationId",
"path": "$.[Link]"
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/locations/${locationId}/property-items",
"body": {
"data": {
"attributes": {
"appraisedValue": {
"amount": "3000",
"currency": "usd"
},
"description": "Ship in a bottle"

}
}
}
...

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:
• 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.

Executing FNOL 161

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
Command

POST /composite/v1/composite

Request body

{
"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.
◦ 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.

162 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
Command

POST /composite/v1/composite

Request body

{
"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"
}
}
}
}
},
{
"method": "post",
"uri": "/claim/v1/claims",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-policy-coverage"
}

Executing FNOL 163

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}
}
]
}

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.
Command

POST /composite/v1/composite

Request body

{
"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]"
}
]
},

{
"method": "post",

164 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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.
Command

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

Request body

{
"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}

Executing FNOL 165

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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
• 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. In the base configuration, the claim, the policy, and
any incidents must reach or pass the New Loss Completion validation level. Exposures must reach or pass the Load
Save validation level. The /submit endpoint will not succeed if any of these objects do not reach the required
validation level. (For more information on how the required levels for exposures can be configured, see “Claim
validation at FNOL” on page 148.
For example, 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
168.

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.

166 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.
Command

POST /composite/v1/composite

Request body

{
"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]"
}
]
},
{

Executing FNOL 167

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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:
• “Tutorial: Set up your Postman environment” on page 29
• “Tutorial: Creating a policy using the Test Util API” on page 153
• “Tutorial: POSTing a typical draft claim for personal auto” on page 156
◦ 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.
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.

168 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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": [
{
"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": {

Executing FNOL 169

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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"
}
]
}
}

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"

170 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
{
"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"
}
]
}
}

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",

Executing FNOL 171

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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",
"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": {

172 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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": {
"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"
},

Executing FNOL 173

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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",
"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",

174 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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": [
{
"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"

Executing FNOL 175

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
"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",
"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": {

176 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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,
"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"

Executing FNOL 177

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}
],
"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.
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).

178 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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": {
"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]"
}
]
},

Executing FNOL 179

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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]"
}
]
},

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"
}
},

180 Executing FNOL

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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": [
{
"name": "checkId",
"path": "$.[Link][0].id"
}
]
}
]
}

Executing FNOL 181

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

182 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 145.

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"
}
},
{

Claims 183
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"attributes": {
"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.

184 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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 185
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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:
Command

POST /claim/v1/search/claims-v2

Request body

{
"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"
}
}
}

186 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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",
"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:
Command

POST /claim/v1/search/claims-v2

Request body

{
"data": {
"attributes": {
"firstName": "Ray",

Claims 187
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"lastName": "Newton",
"nameSearchType": {
"code": "insured"
}
}
}
}

The following payload searches for all the archived claims where the insured has the company name of Wright
Construction:

{
"data": {
"attributes": {
"archivedSearch": true,
"companyName": "Wright Construction",
}
}
}

Response payload for an empty claim search

The system APIs do not require you to provide any search parameters, but ClaimCenter will not execute a claim search
with no search parameters. If you attempt to execute a claim search without search parameters, either from the user
interface or through a system API, ClaimCenter returns the following error message:
Please specify Claim #, Policy #, any Contact field, Assigned To Group, Assigned To User,
Created By, Cat #, VIN or License Plate

Note that this message is intended primarily for user interface claim searches, which is why it makes reference to fields
not available to the /claim/v1/search/claims-v2 endpoint, such as Assigned To Group, Assigned To User, and
Created By.

Response payload for a claim search

The /claim/v1/claims and /claim/v1/claims/{claimId} endpoints return a claim or a collection of claims. The
claim/v1/search/claims-v2 endpoint returns a collection in the ClaimSearchResultWrapper. Consequently, the
endpoint returns a payloads with a slightly different structure.
The following table identifies the primary differences.

Information Claim payload example ClaimSearchResultWrapper payload example

Claim owner
"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": {

188 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Information Claim payload example ClaimSearchResultWrapper payload example

"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 47.
Depending on whether the search was for archived or active claims, the response payload will vary.
The following sections identify the differences between archived and active claim search results.

Active claim search results

In the following example, a policy holder searched for all claims associated with Bill Kinman:
• adjusterName states the name of the claim’s assigned 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"
}

Claims 189
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
},

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.
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.

190 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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}
• /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}

Location scheduled items

A policy can include scheduled items that are associated with a specific location. A scheduled item is an item on a
policy that has been singled out as having an unusual value. The item is covered for a specific value, separate from the
standard policy coverage.
The following endpoints return information about the scheduled items on a specific policy location:
• /claims/{claimId}/policy/locations/{locationId}/property-items
• /claims/{claimId}/policy/locations/{locationId}/property-items/{propertyItemId}

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.

Claims 191
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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

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).
Command

POST /claim/v1/claims/cc:34/assign

Request body

{
"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.

192 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /claim/v1/claims/cc:34/assign

Request body

{
"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.
Command

POST /claim/v1/claims/cc:34/assign

Request body

{
"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
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 145.

Claims 193
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Validating a claim through 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".

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": [
{

194 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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,
"validationLevelReached": {
"code": "payment",
"name": "Ability to pay"
}
}
}
}

Claims 195
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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:
Command

POST /claims/v1/search/claims-v2

Response body

{
"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.

Closing claims
Use the following endpoint to close a claim:
• POST /claim/v1/claims/{claimId}/close
A request body is not required, but you can include it to specify a closedOutcome, which must be set to a value from
the ClaimClosedOutcomeType typelist (such as completed or duplicate).
For example, the following request closes claim cc:706 with a closed outcome of completed.

196 Claims
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /claim/v1/claims/cc:706/close

Request body

{
"data": {
"attributes": {
"closedOutcome": {
"code": "completed"
}
}
}
}

Be aware that validation rules can prevent the closing of the claim. For example, in the base configuration, a claim
cannot be closed if it has open exposures. If you attempt to close a claim with open exposures, ClaimCenter responds
with a message similar to the following.
"message": "Claim: There are still open exposures for this claim. Please close all exposures
before closing the claim."

Reopening a closed claim

Use the following endpoint to reopen a closed claim:
• POST /claim/v1/claims/{claimId}/reopen
A request body is not required, but you can include it to specify either of the following:
• A note, which is a string value to explain why the claim has been reopened
• A reason, which must be set to a value from the ClaimReopenedReason typelist (such as mistake or
paymentdenied).

For example, the following request reopens claim cc:706 (assuming it is closed):
Command

POST /claim/v1/claims/cc:706/reopen

Request body
None
You cannot reopen exposures on a closed claim. The claim must be reopened before you can reopen its exposures.

Claims 197
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

198 Claims
chapter 16

ClaimContacts

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
• Provide information relevant to the claim
• Provide 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 would have the following ClaimContacts:
• Ray Newton
• Robert Farley
• Wilma Weeks
• Joe's Body Shop

ClaimContact roles
Claims have child objects, such as:
• 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).
• One or more exposures, which track a potential payment from one coverage to one claimant.
• One or more service requests, which are requests to outside vendors to provide service that addresses the loss.
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 Ray Newton claim described previously 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.

ClaimContacts 199
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ 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.

The ClaimContact data model

In ClaimCenter, ClaimContact information is stored across multiple entities, including:
• ClaimContact - Information about the contact, such as first and last name
• ClaimContactRole - Each object the contact is associated with and the role it has on that object
• Contact - A link entity between the claim, the ClaimContact , and the ClaimContactRole

Additional business functionality

For a more detailed discussion of the business functionality of ClaimContacts, refer to the Application Guide.

Overview of ClaimContacts in Cloud API

The ClaimContact resource in Cloud API
Even though ClaimCenter stores ClaimContact information in multiple entities, Cloud API captures this information in
a single resource. This resource is named ClaimContact. This documentation uses the term "ClaimContact" to refer to
a ClaimContact resource in Cloud API, and its corresponding information in the ClaimCenter ClaimContact,
ClaimContactRole, and Contact entities.

Cloud API identifiers for ClaimContacts

There are multiple identifier values that can be used to identify a ClaimContact. The following table lists them and
defines when they are used.

Identifier Description Use case More information

id The ClaimContact's Cloud API When querying for a specific • “Querying for
ID. ClaimContact
ClaimContacts” on page
When assigning a contact role 202
to an existing ClaimContact
• “Assigning roles to
When deleting a ClaimContact
existing ClaimContacts”
on page 212
• “Deleting ClaimContacts”
on page 213

refid A temporary reference ID When POSTing or PATCHing a • “Creating a new

ClaimContact using request
ClaimContact with a
inclusion

200 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Identifier Description Use case More information

reserved role” on page

204
• “Creating a new
ClaimContact with a non-
reserved role” on page
206

policySystemId An identifier from the Policy When adding a ClaimContact to • “Working with contacts
Administration System that a claim that is already listed on
from the policy” on page
uniquely identifies the contact. the policy
208
• “Assigning roles to
existing ClaimContacts”
on page 212

syncAddressBookUID An identifier from When adding a ClaimContact to • “Copying vendor

ContactManager that uniquely a claim that is already listed in
contacts from
identifies the contact. ContactManager
ContactManager” on
page 209

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 roles
ClaimContact roles and role owners
Every ClaimContact must have at least one contact role. A contact role is a name that identifies the type of relationship
the ClaimContact has on the claim. For example, on claim 523-45-111341:
• Ray Newton could be the reporter on the claim itself.
• Ray Newton could be the insured on the policy.
• Debbie Newton could an alternate contact on the claim itself.
• Stan Davidson could the driver of vehicle cc:4322.
• Mike's Auto Body Repair could be the auto repair shop for vehicle cc:4322.
Notice that every contact role applies to a specific object, which is either the claim or a child object of the claim (the
policy, a vehicle, an exposure, and so on.) In ClaimCenter, this is referred to as the role owner. In Cloud API, the field
that references this object is the relatedTo field.

ClaimContacts 201
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Reserved and non-reserved roles

In Cloud API, every contact role type (such as reporter or witness) can be classified as either reserved or non-reserved.
Reserved roles
A reserved role is a role that cannot be set directly on a ClaimContact. Instead, the role must be set indirectly 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. A claim can have at
most one reporter.)
• Roles that are set through an array on a non-ClaimContact object. (For example, witness. Witnesses are defined on
the Claim resource's witnesses array.)
Non-reserved roles
A non-reserved role is a role that can be set on a ClaimContact directly. 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.

Roles array properties

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.
Every member of these arrays includes the following properties:
• relatedTo - the type and ID of the object that the ClaimContact is related to (the "role owner")
• role - the role the ClaimContact has on that object
• 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 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.

Querying for ClaimContacts

Use the following endpoints to query for ClaimContacts:
• GET /claim/v1/claims/{claimId}/contacts
• GET /claim/v1/claims/{claimId}/contacts/{contactId}
For example, the following request queries for all ClaimContacts on claim demo_sample:1. The request returns only
the display name, id, and roles of each contact:

202 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

GET /claim/v1/claims/demo_sample:1/contacts?fields=displayName,id,roles

Response

{
"count": 7,
"data": [
{
"attributes": {
"authorizationID": "ctc-11457",
"displayName": "Mike's Auto detailing shop",
"id": "cc:5",
"roles": [
{
"active": true,
"relatedTo": {
"displayName": "235-53-365870",
"id": "demo_sample:1",
"type": "Claim",
"uri": "/claim/v1/claims/demo_sample:1"
},
"role": {
"code": "servicerequestspecialist",
"name": "Service Vendor"
}
}
]
}
},
{
"attributes": {
"displayName": "Karen Egertson",
"id": "cc:2",
"roles": [
{
"active": true,
"relatedTo": {
"displayName": "54-123456",
"id": "demo_sample:1",
"type": "Policy",
"uri": "/claim/v1/claims/demo_sample:1/policy"
},
"role": {
"code": "agent",
"name": "Agent"
}
}
]
}
},
...

Creating new ClaimContacts

For each claim, ClaimCenter automatically creates ClaimContacts for contacts listed on the policy (such as the
insured). In addition to these contacts, you can create a ClaimContact who:
• Is listed in ContactManager (such as a vendor who is known to the insurer and who provides service for multiple
claims)
• Is not listed in any other system (such as a third-party claimant, witness, or a vendor who is not yet known to the
insurer)
Use the following endpoint to create a new ClaimContact:
• POST /claim/v1/claims/{claimId}/contacts

Minimum creation criteria

When you create a ClaimContact, you must specify the following:
• contactSubtype (a subtype of Contact)
• Either:

ClaimContacts 203
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ lastName (for ClaimContacts whose subtype is Person or one of its subtypes)

◦ name (for ClaimContacts whose subtype is Company or one of its subtype)
• At least one ClaimContact role
◦ Note that the syntax of the request depends on whether the role is reserved or non-reserved

Creating a new ClaimContact with a reserved role

When you create a ClaimContact that has a reserved role, you must call two endpoints: one that POSTs or PATCHes
the claim, and one that creates the ClaimContact. You can do this using either request inclusion or composite requests.
For more information on request inclusion, see “Request and response inclusion” on page 109 and “Composite
requests” on page 95.
Reserved roles set from a field
In some cases, a reserved role is set through a field on the claim or one of its child objects.
For example, the reporter role is set from the Claim's reporter field. To create a new contact with the role of reporter,
you must do the following:
• POST the new contact.
• PATCH the claim to assign the reporter role to the new contact.
The order in which the commands are executed depends on whether you are using request inclusion or a composite
request.
The following is an example of adding the role of reporter to a new contact for an existing claim using request
inclusion. The claim is the parent object, so it appears in the payload first.
Command

PATCH /claim/v1/claims/cc:402

Request

{
"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"
}
]
}
}

The following is an example of adding the role of reporter to a new contact for an existing claim using a composite
request. The contact is created first so that its ID can be used when setting the reporter field on the claim.
Command

POST /rest/composite/v1/composite

Request
{
"requests": [

204 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

{
"method": "post",
"uri": "/claim/v1/claims/cc:402/contacts",
"body": {
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Carol",
"lastName": "Daniels"
}
}
},
"vars": [
{
"name": "newContactId",
"path": "$.[Link]"
}
]
},
{
"method": "patch",
"uri": "/claim/v1/claims/cc:402",
"body": {
"data": {
"attributes": {
"reporter": "${newContactId}"
}
}
}
}
]
}

Reserved roles that are set from an array

In some cases, a reserved role is set through an array on the claim or one of its child objects.
For example, the witness role is set from the Claim's witnesses array. To create a new contact with the role of witness,
you must do the following:
• POST the new contact.
• PATCH the claim to assign the new contact to the witnesses array
The order in which the commands are executed depends on whether you are using request inclusion or a composite
request.
Keep in mind that, within Cloud API, 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 77.
The following is an example of adding the role of witness to a new contact for an existing claim using request
inclusion. The claim is the parent object, so it appears in the payload first.
Command

PATCH /claim/v1/claims/cc:402

Request

{
"data": {
"attributes": {
"witnesses": [
{
"contact": {
"id": "newContact"
}
}
]
}
},
"included": {
"ClaimContact": [
{
"refid": "newContact",
"attributes": {
"contactSubtype": "Person",

ClaimContacts 205
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"firstName": "Matt",
"lastName": "Capaldi"
},
"method": "post",
"uri": "/claim/v1/claims/cc:402/contacts"
}
]
}
}

The following is an example of adding the role of witness to a new contact for an existing claim using a composite
request. The contact is created first so that its ID can be used when adding the contact to the witnesses araay on the
claim.
Command

POST /rest/composite/v1/composite

Request
{
"requests": [
{
"method": "post",
"uri": "/claim/v1/claims/cc:402/contacts",
"body": {
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Matt",
"lastName": "Capaldi"
}
}
},
"vars": [
{
"name": "newContactId",
"path": "$.[Link]"
}
]
},
{
"method": "patch",
"uri": "/claim/v1/claims/cc:402",
"body": {
"data": {
"attributes": {
"witnesses": [
{
"contact": {
"id": "${newContact}"
}
}
]
}
}
}
}
]
}

Creating a new ClaimContact with a non-reserved role

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.
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

206 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• The ID of the object on which the ClaimContact has this role

The syntax used to specify this is:

"editableroles": [
{
"role": {
"code": "<roleCode>"
},
"relatedTo": {
"type": "<parentObjectType>",
"id": "<parentObjectId>"
}
},
... <additionalRoles>

Example
For example, the following request PATCHes Claim cc:610 so that ClaimContact cc:777 has the alternate contact role
(whose code is altcontact) on the claim itself.
Command

PATCH [Link]

Request body

{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "altcontact"
},
"relatedTo": {
"type": "Claim",
"id": "cc:610"
}
}
]
}
}
}

Similarly, the following request PATCHes 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 specified as the
owner of the vehicle from vehicle incident cc:102.)
Command

PATCH [Link]

Request body

{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "incidentowner"
},
"relatedTo": {
"type": "vehicleIncident",
"id": "cc:102"
}
}
]
}
}
}

ClaimContacts 207
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Working with contacts from the policy

Every ClaimContact has an id, which is an identifier assigned by ClaimCenter. ClaimContacts that are listed on the
policy also have a policySystemId. This value comes from the PAS (Policy Administration System), and it is set by
the custom integration code that copies the policy and its contacts from the PAS to ClaimCenter. For example, suppose
Elsa Koplin is the insured on a claim. Once the claim has been created, the Elsa Koplin contact has both an id (such as
cc:3131) and a policySystemId (such as pc:2000-acme-12445).

Assigning roles to policy contacts during initial claim creation

When you are constructing an initial draft claim, contacts on the policy have not yet been copied over to ClaimCenter,
and therefore do not have id values yet. You can assign roles to policy contacts using their policy system ID. For
example, the following request creates a new claim with minimal information. It also specifies Elsa Koplin is the
reporter by using her policy system ID.
Command

POST /claim/v1/claims

Request

{
"data" : {
"attributes": {
"lossDate": "2023-02-01T07:00:00.000Z",
"policyNumber": "FNOL-POLICY",
"reporter": {
"policySystemId": "pc:2000-acme-12445"
}
}
}
}

Assigning roles to policy contacts after claim creation

When the claim is created, ClaimCenter copies the policy contacts over to ClaimCenter and assigns ClaimCenter IDs to
them. From this point forward, you can identify a policy contact using either their id or the policySystemId. For
example, the following command PATCHes claim cc:402 and set Elsa Koplin as the main contact. There are two
versions of the request payload. The first uses her id (cc:3131). The second uses her policySystemId (pc:2000-
acme-12445). Both payloads accomplish the same objective.
Command

PATCH /claim/v1/claims/cc:402

Request: Version 1 (using id)

{
"data": {
"attributes": {
"maincontact": {
"id": "cc:3131"
}
}
}
}

Request: Version 2 (using policySystemId)

{
"data": {
"attributes": {
"maincontact": {
"policySystemId": "pc:2000-acme-12445"
}
}
}
}

208 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Copying vendor contacts from ContactManager

You can add a ClaimContact to a claim by copying an existing contact from ContactManager. This is typically done for
vendor contacts, which are managed by ContactManager and shared across multiple claims.
When you copy an existing vendor contact from ContactManager, ClaimCenter links the new ClaimContact to its
associated contact in ContactManager. This means that any changes made to the contact in one application (such as
changes to its phone number) are shared with the other system. For information on linked ClaimContacts, refer to the
Application Guide.
When you copy an existing vendor from ContactManager, you must specify the contact's syncAddressBookUID and at
least one role for the contact. The way in which this is done depends on whether the role is reserved or non-reserved.
Copying shared vendors and giving them a reserved role
If the vendor needs to have a reserved role on the claim, you must use request inclusion. For more information on
request inclusion, see “Request and response inclusion” on page 109.
• The parent request is a POST or PATCH that creates or modifies the object on which the vendor has the role. For
example, this could be a service request, where the vendor is the specialist, or an injury incident, where the vendor
is the primary doctor.
◦ The parent request must include the role and reference the vendor using a refid.
• The child request is a POST that copies the vendor to ClaimCenter.
◦ The attributes section has only one field, syncAddressBookUID. This field is set to the vendor's linkID in
ContactManager.
◦ The refid is set to the same refid value used in the parent request.
For example, suppose claim cc:404 already exists in ClaimCenter. Helen Davis is an auto mechanic vendor who
already exists in ContactManager with a linkID of ab:68. You want to create a service request for claim cc:404 and
specify that the service request's specialist is Helen Davis. To do this, you would use request inclusion.
• The parent request is a POST that creates the service request.
◦ It includes the role (specialist) and references the vendor using a refid (such as
serviceSpecialistContact).
• The child request is a POST that copies the vendor to ClaimCenter.
◦ The attributes section has only one field, syncAddressBookUID. This field is set to the vendor's linkID in
ContactManager (ab:68).
◦ The refid is set to the same refid value used in the parent request (such as serviceSpecialistContact).
This example is depicted in the following request.
Command

POST /claim/v1/claims/cc:404/service-requests

Request body

{
"data": {
"attributes": {
"kind": {
"code": "serviceonly"
},
"specialist": {
"refid": "serviceSpecialistContact"
},
"instruction": {
"customer": {
"id": "cc:13"
},
"serviceAddress": {
"addressLine1": "1313 Mockingbird Lane",
"city": "Arcadia",

ClaimContacts 209
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"country": "US",
"postalCode": "91006",
"state": {
"code": "CA",
"name": "California"
}
},
"services": [
{
"code": "autoothersalvage"
}
]
},
"requestedServiceCompletionDate": "2025-03-19"
}
},
"included": {
"ClaimContact": [
{
"attributes":{
"syncAddressBookUID": "ab:68"
},
"refid": "serviceSpecialistContact",
"method": "post",
"uri": "/claim/v1/claims/cc:404/contacts",
}
]
}
}

Copying shared vendors and giving them a non-reserved role

If the vendor needs to have a non-reserved role on the claim, then you use a simple POST. The POST must specify the
following fields and only the following fields:
• syncAddressBookUID, which must be set to the contact's linkID in ContactManager
• The editableRoles array, with at least one role and its related object
For example, James Anderson is an attorney in ContactManager whose linkID is ab:68. The following request adds
him to claim cc:404 with the role of attorney on the claim itself.
Command

POST /claim/v1/claims/cc:404/contacts

Request body

{
"data": {
"attributes": {
"syncAddressBookUID": "ab:68",
"editableRoles": [
{
"role": {
"code": "attorney"
},
"relatedTo": {
"type": "Claim",
"id": "cc:404"
}
}
]
}
}
}

Creating ClaimContacts during FNOL

There is one limitation to ClaimContact behavior during FNOL.

Creating a ClaimContact with a reserved role during FNOL

When you create a draft claim, you can create a ClaimContact and assign that ClaimContact a reserved role in a single
request that uses request inclusion. For example, the following payload creates a new claim with a new ClaimContact
(Robert Farley) who is assigned the role of reporter.

210 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command
POST /claim/v1/claims

Request

{
"data" : {
"attributes": {
"lossDate": "2025-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"
}
]
}
}

Creating a ClaimContact with a non-reserved role during FNOL

However, when you create a draft claim, you cannot create a ClaimContact and assign that ClaimContact a non-
reserved role in a single request that uses request inclusion. This is because non-reserved roles are specified through
the editableRoles array. Every member of this array must have a relatedTo object identifying the object the
ClaimContact is related to. The [Link] field does not support use of the this keyword. Thus, there is no way to
reference the claim to be created in the ClaimContact payload.
In order to create a ClaimContact with a non-reserved role during FNOL, you must do one of the following:
• Create the claim and the ClaimContact in separate requests. (The second request must use the ID of the claim
created in the first request.)
• Create the claim and the ClaimContact in separate subrequests in a composite request. (The first subrequest must
pass the ID of the claim to the second subrequest.)

PATCHing ClaimContacts
Use the following endpoint to PATCH a ClaimContact:
• PATCH /claim/v1/claims/{claimId}/contacts/{contactId}
For example, the following request PATCHes contact cc:55 on claim cc:404.
Command

PATCH /claims/cc:404/contacts/cc:55

Request body

{
"data": {
"attributes": {
"emailAddress1": "kittenknitter@[Link]"
}
}
}

You can also use the PATCH /claims/{claimId}/contacts/{contactId} endpoint to modify a contact's non-
reserved roles. For more information, see “Assigning roles to existing ClaimContacts” on page 212.

ClaimContacts 211
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Assigning roles to existing ClaimContacts

Once a ClaimContact exists on a claim (with at least one role), you can modify its roles.

Assigning reserved roles

To assign a reserved role to an existing ClaimContact, PATCH the role field or array on the object that owns the role. If
the role can be held by only one ClaimContact, then the role is switched from any ClaimContact that previously held it
to the one specified in the PATCH.
For example, the following request assigns the role of reporter on claim cc:402 to existing ClaimContact cc:8181. The
previous ClaimContact to have the reporter role will no longer have it.
Command

PATCH /claim/v1/claims/cc:402

Request body

{
"data": {
"attributes": {
"reporter": {
"id": "cc:8181"
}
}
}
}

Assigning non-reserved roles

To assign a non-resolved role to an existing ClaimContact, PATCH the editableRoles array of the ClaimContact
itself.
For example, the following request PATCHes ClaimContact cc:777 on claim cc:610 so that it has the alternate contact
role (whose code is altcontact) on the claim itself.
Command

PATCH [Link]

Request body

{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "altcontact"
},
"relatedTo": {
"type": "Claim",
"id": "cc:610"
}
}
]
}
}
}

Similarly, the following request PATCHes ClaimContact cc:208 on claim cc:610 so that it 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.)
Command

PATCH [Link]

212 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Request body

{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "incidentowner"
},
"relatedTo": {
"type": "vehicleIncident",
"id": "cc:102"
}
}
]
}
}
}

Keep in mind that, within Cloud API , 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 77.

PATCHing editableRoles scenarios

When PATCHing editableRoles, the following table details the possible request payloads and they way Cloud API
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-reserved The existing non-resolved roles are replaced by the non-reserved roles
roles specified in the payload.
An empty editableRoles array All existing non-reserved roles are removed. (However, if this would
result in the ClaimContact no longer having any roles, Cloud API returns
an error.)
An editableRoles array with one or more reserved Cloud API returns an error.
roles
A roles array (which is read-only) Cloud API returns an error.

Deleting ClaimContacts
Use the following endpoint to delete a ClaimContact:
• DELETE /claim/v1/claims/{claimId}/contacts/{contactId}
For example, the following request deletes contact cc:202 from claim cc:404.
Command

DELETE /claim/v1/claims/cc:404/contacts/cc:202

Request

<none>

Note that ClaimCenter had validation logic that may prevent the deletion of the ClaimContact. For example, you
cannot delete a ClaimContact who is the reporter on a claim.

Additional behaviors
ClaimContacts 213
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 a
portion of the response for a GET that retrieves a ClaimContact.

{
"data": {
"attributes": {
"displayName": "Ray Newton",
"taxId": "***-**-6789"
}
}
}

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.

Role constraint endpoints

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.
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 driver (the role) can be held by ClaimContacts associated with a
vehicle incident (the object), and that there can be at most one driver (how many) 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

214 ClaimContacts
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Operation Endpoint Description

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.
• 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:

ClaimContacts 215
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.

Role owners endpoint

The /claim/v1/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 matters (A matter is a collection of information pertaining to a lawsuit or potential lawsuit.)
• Any existing negotiations (A negotiation is a history of the offers and counter-offers related to one disputed aspect
of the loss.)
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.

Specifying pronouns for contacts

Specifying pronouns for contacts
For contacts of type Person or any of its subtypes, you can specify a set of pronouns on a contact. You can reference an
existing set of pronouns from a typelist or input custom pronouns.
Use the pronounAggregate field to choose an existing set of pronouns from the PronounAggregateType typelist (for
example, hehimhis). If different pronouns are desired, set this field to a value of selfidentify, and add pronouns
using the following fields:
• pronounSubjective - the person’s subjective pronoun, as a string
• pronounObjective - the person’s objective pronoun, as a string
• pronounPossessive - the person’s possessive pronoun, as a string
The values added to these fields are aggregated and used to populate the pronounAggregateDisplay field.
If the pronounAggregate field is changed from self-identify to one of the default values, the values in the
pronounSubjective, pronounObjective, and pronounPossessive fields are cleared and set automatically. For
example, if a value of sheherhers is input, pronounSubjective is set to She, pronounObjective is set to Her, and so
on.

216 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
Incidents 217
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

▪ Dwelling
▪ Other structure
◦ 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 199.

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 237.

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}

218 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.

Damageables
A damageable is a separate entity that stores information about the state of an item before any loss or damage
occurred. 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.
Some incident types pertain to items that must be listed on the policy. For example, TripIncident is an incident type
that captures information about a trip where some sort of loss occurred, such as a cancellation or lost luggage. In order
to file a claim, the trip must be listed on the travel policy. You cannot file claims for trips not listed on the policy. These
types of incidents do not typically make use of damageables.
Other incident types pertain to items that may be listed on the policy or that may belong to a third party. For example,
VehicleIncident is an incident type that captures information about a damaged vehicle. The vehicle could be listed
on the insured's policy. The vehicle could also be a third-party vehicle that the insured damaged. These types of
incidents typically do make use of damageables.
When an incident type has an associated damageable, you could theoretically have separate endpoints for the incident
and the damageable. However, it is usually 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 incident's schema.

PATCH behavior for incidents with damageables

For most endpoints, when you try to PATCH a resource, there is one of two outcomes:
• The PATCH is successful, and the resource is modified as specified in the request body.
• The PATCH fails and no changes are made.
For incidents with inline damageables on claims with verified policies, there is a third possibility.
• If the PATCH modifies fields on the inline damageable and the inline damageable is listed on the policy,
ClaimCenter does not modify the existing policy damageable. Instead, ClaimCenter creates a new damageable,
populates the new damageable with the information in the PATCH payload, and then associates the new
damageable with the incident. The original policy damageable is still associated with the claim's policy, but it is no
longer associated with the incident.
For example, suppose there is a claim with vehicle incident cc:101, which has an associated policy vehicle cc:202. The
only information on the vehicle is make, model, and year (2020 Toyota Fusion). Then, you PATCH the vehicle, setting
year to 2010 and color to Black. ClaimCenter does the following:

• It creates a new vehicle. It is a non-policy vehicle with year set to 2010 and color set to Black. (make and model
are not set.)
• It associated the new vehicle with vehicle incident cc:101.
• It retains vehicle cc:202, but the vehicle is no longer associated with vehicle incident cc:101. Vehciel cc:202 is
associated only with the policy.
The reason for this behavior is Cloud API for ClaimCenter does not permit PATCHes to verified policy information.
Information for verified policies can come only from the Policy Administration System. If you attempt to PATCH

Incidents 219
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

information for an inline damageable listed on the policy, ClaimCenter interprets this as a desire to create a new non-
policy damageable.
This behavior can also be summarized in the following way. Whenever you PATCH an incident with an inline
damageable:
• PATCHing fields that are not part of the inline damageable behaves as normal.
• PATCHing fields that are part of the inline damageable behaves as normal if the inline damageable is for a third-
party object. (In other words, an object that is not listed on the policy.)
• PATCHing fields that are part of the inline damageable creates a new damageable if the inline damageable is listed
on the policy.

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"
}

Determining valid incident types for a given claim

The line of business model is a set of typelists that organizes policies, coverages, and covered losses into a single
hierarchy. Collectively, these typelists define the valid types of coverages, incidents, and exposures for a given policy
and type of loss.
A caller application may want to access the metadata for these typelists so that it can determine valid incident values
for a given claim. This information can be retrieved using the Claim API's /business-line-metadata endpoint. For
more information, see “The /business-line-metadata endpoint” on page 405.

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.

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.

220 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
• 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}

Incidents 221
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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"
}
}
}
}

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.

222 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
}
}

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:

Incidents 223
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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"
}
}
}
}

Medical diagnoses
An injury incident can have one or more associated medical diagnoses. Note that, in the data model, they are stored in
the InjuryDiagnosis entity. But in the user interface, they are referred to as Medical Diagnoses. Thus, in Cloud API,
they are managed by the MedicalDiagnosis schema.
For more information on the business functionality of medical diagnoses, see the Application Guide.

Querying for medical diagnoses

Use the following endpoints for query for the medical diagnoses on an injury incident.

• GET /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
medical-diagnoses

• GET /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
medical-diagnoses/{medicalDiagnosisId}

224 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

For example, the following request retrieves the medical diagnoses for injury incident cc:888 on claim cc:77.
Command

GET /claim/v1/claims/cc:77/injury-incidents/cc:888/medical-diagnoses

Response

{
"count": 1,
"data": [
{
"attributes": {
"icdCode": {
"displayName": "A00.0",
"id": "icd10:A00.0",
"type": "ICDCode",
"uri": "/admin/v1/icd-codes/icd10:A00.0"
},
"id": "cc:77077",
"isPrimary": true,
"provider": {
"displayName": "Beverly Cushing",
"id": "cc:4040",
"type": "ClaimContact",
"uri": "/claim/v1/claims/cc:77/contacts/cc:4040"
}
},
...

Creating medical diagnoses

Use the following endpoint to create a medical diagnosis:

• POST /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
medical-diagnoses

The are two required fields:

• icdCode, which is a JSON object with an id property that references the ID for an existing ICD code. (For more
information on ICD codes, see “Managing ICD codes” on page 287.)
• provider, which is a JSON object with an id property that references the ID for an existing contact on the claim.
For example, suppose that on claim cc:11, there is an injury incident with the ID of cc:222. Beverly Cushing is a doctor
on the claim with ID cc:4040. She diagnoses the injury incident as being caused by cholera. The ICD code for cholera
has an ID of icd10:A00.0. The following request creates this medical diagnosis.
Command

POST /claim/v1/claims/cc:11/injury-incidents/cc:222/medical-diagnoses

Request

{
"data": {
"attributes": {
"icdCode": {
"id": "icd10:A00.0"
},
"provider": {
"id": "cc:4040"
}
}
}
}

PATCHing and DELETEing medical diagnoses

Use the following endpoint to PATCH an existing medical diagnosis:

• PATCH /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
medical-diagnoses/{medicalDiagnosisId}

Incidents 225
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

For example, the following request specifies that, for injury incident cc:222 on claim cc:11, medical diagnosis cc:
77077 was made on October 10, 2024.
Command

PATCH /claim/v1/claims/cc:11/injury-incidents/cc:222/medical-diagnoses/cc:77077

Request

{
"data": {
"attributes": {
"startDate": "2024-10-10"
}
}
}

Use the following endpoint to DELETE an existing medical diagnosis:

• DELETE /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
medical-diagnoses/{medicaldiagnosisId}

For example, the following request deletes medical diagnosis cc:77077 for injury incident cc:222 on claim cc:11.
Command

DELETE /claim/v1/claims/cc:11/injury-incidents/cc:222/medical-diagnoses/cc:77077

Bodily injury points

An injury incident can have one or more associated bodily injury points. A bodily injury point is an indication of a
single point of injury done to the person. A bodily injury point has two fundamental attributes:
• InjuryPoint, which is a typekey to the BodilyInjuryPoints typelist and which identifies the location of the
injury
• InjurySeverity, which is a typekey to the DamageSeverity typelist and which optionally identifies the severity of
the injury
For more information on the business functionality of bodily injury points, see the Application Guide.

Querying for bodily injury points

Use the following endpoints for query for the bodily injury points on an injury incident.

• GET /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
bodily-injury-points

• GET /claim/v1//claims/{claimId}/injury-incidents/{incidentId}/
bodily-injury-points/{bodilyInjuryPointId}

For example, the following request retrieves the bodily injury points for injury incident cc:3030 on claim
demo_sample:1.
Command

GET /claim/v1/claims/demo_sample:1/injury-incidents/cc:3030/bodily-injury-points

Response

{
"count": 1,
"data": [
{
"attributes": {
"injuryPoint": {
"code": "hf_mouth",
"name": "Mouth"

226 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
"injurySeverity": {
"code": "moderate",
"name": "Moderate"
},
"id": "cc:SoYoLeedQxl8CMuJQw9t0"
},
...
}
],
...
}

Creating bodily injury points

Use the following endpoint to create a bodily injury point:

• POST /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
bodily-injury-points

The only required field is injuryPoint.

For example, the following request creates a bodily injury point for injury cc:2020 on claim demo_sample:1 to indicate
a moderate injury to the left lower arm. Note that the request provides the required injuryPoint value and the optional
injurySeverity value.

Command

POST /claim/v1/claims/demo_sample:1/injury-incidents/cc:2020/bodily-injury-points

Request

{
"data": {
"attributes": {
"injuryPoint": {
"code": "bfl_arm"
},
"injurySeverity": {
"code": "moderate"
}
}
}
}

PATCHing and DELETEing bodily injury points

Use the following endpoint to PATCH an existing bodily injury point:

• PATCH /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
bodily-injury-points/{bodilyInjuryPointId}

For example, the following request modifies the severity of bodily injury point cc:8888 for injury cc:2020 on claim
demo_sample:1.
Command

PATCH /claim/v1/claims/demo_sample:1/injury-incidents/cc:2020/bodily-injury-points/cc:8888

Request

{
"data": {
"attributes": {
"injurySeverity": {
"code": "severe"
}
}
}
}

Use the following endpoint to DELETE an existing bodily injury point:

Incidents 227
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• DELETE /claim/v1/claims/{claimId}/injury-incidents/{incidentId}/
bodily-injury-points/{bodilyInjuryPointId}

For example, the following request deletes bodily injury point cc:8888 for injury cc:2020 on claim demo_sample:1.
Command

DELETE /claim/v1/claims/demo_sample:1/injury-incidents/cc:2020/bodily-injury-points/cc:8888

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.)

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.

228 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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}
• 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",

Incidents 229
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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": {
"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 either an
assessment content item or a scheduled item.
A scheduled item is an item on a policy that has been singled out as having an unusual value. For example, a single
necklace could be valued higher than the policy’s overall coverage for jewelry. Therefore, the necklace could be added
as a scheduled item that is covered separately from any jewelry already covered as assessment content items.
In ClaimCenter, property content incidents are stored in the PropertyContentsIncident entity. Items covered by a
property contents incident are usually small enough to be moveable. Thus, the PropertyContentsIncident entity is a
subtype of MobilePropertyIncident. Assessment content items are stored in the AssessmentContentItem entity.
Scheduled items are stored in the PropertyContentsScheduledItem 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
• One set for scheduled 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. In Cloud API, the corresponding field, description, is not
required.
Endpoints for managing property contents incidents
Use the following endpoints to manage property contents incidents:

230 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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:
• 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"
}
}
}
}

Endpoints for managing scheduled items

Use the following endpoints to manage scheduled items on a property contents incident:
• GET /claims/{claimId}/property-contents-incidents/{incidentId}/scheduled-items
• POST /claims/{claimId}/property-contents-incidents/{incidentId}/scheduled-items

Incidents 231
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• GET /claims/{claimId}/property-contents-incidents/{incidentId}/scheduled-items/
{scheduledItemId}
• PATCH /claims/{claimId}/property-contents-incidents/{incidentId}/scheduled-items/
{scheduledItemId}
• DELETE /claims/{claimId}/property-contents-incidents/{incidentId}/scheduled-items/
{scheduledItemId}

The scheduled item must already exist before it can be added to an incident. For example, the following request adds
scheduled item cc:410 to property contents incident cc:505 on claim cc:117
Command

POST /claims/cc:117/property-contents-incidents/CC:505/scheduled-items

Request

{
"data": {
"attributes": {
"propertyItem": {
"id": "cc:410"
}
}
}
}

Note that in the base configuration there are no properties under propertyItem that can be modified with the PATCH
command. The PATCH command is available for potential use with custom extensions.

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": {

232 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"attributes": {
"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
}
}
}
}

Vehicle damage points

A vehicle incident can have one or more associated vehicle damage points. A vehicle damage point is an indication of a
single point of damage done to the vehicle. A vehicle damage point has two fundamental attributes:
• DamagePoint, which is a typekey to the VehicleDamagePoints typelist and which identifies the location of the
damage
• DamageSeverity, which is a typekey to the DamageSeverity typelist and which optionally identifies the severity of
the damage
For more information on the business functionality of vehicle damage points, see the Application Guide.

Querying for vehicle damage points

Use the following endpoints to query for the damage points on a vehicle incident.

• GET /claim/v1/claims/{claimId}/vehicle-incidents/{incidentId}/
vehicle-damage-points

• GET /claim/v1//claims/{claimId}/vehicle-incidents/{incidentId}/
vehicle-damage-points/{vehicleDamagePointId}

For example, the following request retrieves the vehicle damage points for vehicle cc:1010 on claim demo_sample:1.
Command

GET /claim/v1/claims/demo_sample:1/vehicle-incidents/cc:1010/vehicle-damage-points

Response

{
"count": 2,
"data": [
{
"attributes": {
"damagePoint": {
"code": "fr_door",
"name": "Front Right Door"
},
"damageSeverity": {
"code": "moderate",
"name": "Moderate"
},
"id": "cc:SwZ6FuftaXwcyOWRs6kG2"
},
...
},
{
"attributes": {
"damagePoint": {

Incidents 233
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"code": "f_bumper",
"name": "Front Bumper and Grill"
},
"id": "cc:SRlArWMDZmtKA8TScCZ3x"
},
...
}
],
...
}

Creating vehicle damage points

Use the following endpoint to create a vehicle damage point:

• POST /claim/v1/claims/{claimId}/vehicle-incidents/{incidentId}/
vehicle-damage-points

The only required field is damagePoint.

For example, the following request creates a vehicle damage point for vehicle cc:1010 on claim demo_sample:1 to
indicate minor roof damage. Note that the request provides the required damagePoint value and the optional
damageSeverity value.

Command

POST /claim/v1/claims/demo_sample:1/vehicle-incidents/cc:1010/vehicle-damage-points

Request

{
"data": {
"attributes": {
"damagePoint": {
"code": "roof"
},
"damageSeverity": {
"code": "minor"
}
}
}
}

PATCHing and DELETEing vehicle damage points

Use the following endpoint to PATCH an existing damage point:

• PATCH /claim/v1/claims/{claimId}/vehicle-incidents/{incidentId}/
vehicle-damage-points/{vehicleDamagePointId}

For example, the following request modifies the severity of damage point cc:9999 for vehicle cc:1010 on claim
demo_sample:1.
Command

PATCH /claim/v1/claims/demo_sample:1/vehicle-incidents/cc:1010/vehicle-damage-points/cc:9999

Request

{
"data": {
"attributes": {
"damageSeverity": {
"code": "severe"
}
}
}
}

Use the following endpoint to DELETE an existing damage point:

• DELETE /claim/v1/claims/{claimId}/vehicle-incidents/{incidentId}/
vehicle-damage-points/{vehicleDamagePointId}

234 Incidents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

For example, the following request deletes damage point cc:9999 for vehicle cc:1010 on claim demo_sample:1.
Command

DELETE /claim/v1/claims/demo_sample:1/vehicle-incidents/cc:1010/vehicle-damage-points/cc:9999

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

{
"data": {
"attributes": {
"description": "Flight cancelled due to airline strike",
"tripRiskUnit": {
"id": "cc:SHEXDGWJHfyVMKSxBLFZ9"
}
}
}
}

Incidents 235
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
}
}
}

236 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 237
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 type 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 type 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.
For more information on reserve lines, see “Reserves” on page 295.

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 145.

238 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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 199.

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 217.

Overview of exposures in Cloud API

In addition to the standard CRUD endpoints, Cloud API includes several business action POST endpoints related to
endpoints. This includes endpoints for:
• Assigning exposures
• Deleting exposures on draft claims
• Identifying an exposure's validation level
• Closing an exposure

Determining valid exposure types for a given claim

The line of business model is a set of typelists that organizes policies, coverages, and covered losses into a single
hierarchy. Collectively, these typelists define the valid types of coverages, incidents, and exposures for a given policy
and type of loss.
A caller application may want to access the metadata for these typelists so that it can determine valid exposure type
values for a given claim. This information can be retrieved using the Claim API's /business-line-metadata
endpoint. For more information, see “The /business-line-metadata endpoint” on page 405.

Producer access to exposures

By default, producers can access all exposures on a claim. This is controlled by the
GiveProducerAccessToAllExposures application configuration parameter, which by default is set to true. When this
is set to false, producers can access only exposures where the claimant has a producer accessible role.
For more information on producer accessible roles, refer to the section on the producerCodes access strategy in the
Cloud API Developer Guide.

Exposures 239
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Creating exposures
Use the POST /claims/{claimId}/exposures endpoint to create new exposures.

Minimum creation criteria

In order for an exposure to be assignable, the exposure must have the following:
• A coverage and coverage subtype
• A claimant
• An incident
The exposure resource also has a coverage attribute, which identifies the coverage object on the policy. This is not a
required attribute. However, there are features in ClaimCenter that require this attribute to be set in order to work
properly. For example, deductible handling works only when the exposure is associated with the appropriate coverage
object so that ClaimCenter can determine if the coverage has a deductible and if so how much. Therefore, Guidewire
recommends always setting the exposure's coverage attribute.
The following JSON skeleton summarizes these components as they appear in a POST /exposures request payload.

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

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.

240 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
...
}
],
"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"
},
...

Exposures 241
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 403.

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"
},
...

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 and response inclusion” on page 109.
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]

242 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 and response inclusion” on page 109. Depending on the incident type, the new incident can
reference a child object (a location, injured person, or vehicle). This child object could be on the policy, in
ClaimCenter, or also created in the POST /exposures request payload.
If the incident already exists in ClaimCenter, the caller application can reference it by its id.
Note: If the incident already exists in ClaimCenter, always reference the existing incident and use the id field.
Do not create an additional incident through the use of the refid field. Creating the same logical incident twice
results in duplicate data. This can complicate the processing of the claim.
In this example, the incident does not exist and must be created. But, it will reference a vehicle that is already on the
policy. The ID for this vehicle was already retrieved in the first step when the coverage type was identified. The ID is
demo_sample:4. There is no need for an additional request to retrieve additional vehicle information.

Exposure request payload (first four parts)

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

{
"data": {
"attributes": {
"primaryCoverage": {
"code": "PACollisionCov"
},
"coverageSubtype": {
"code": "PACollisionCov"
},
"claimant": {
"id": "cc:32"
},
"vehicleIncident": {
"refid": "newVehicleIncident"
},
...
}
},
"included": {

Exposures 243
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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

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"

244 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}
},
"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}
The GET /claims/{claimId}/exposures endpoint also has special assignedUser and assignedUsername filters.
For more information, see “The assignedUser filters” on page 54.
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.
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:

Exposures 245
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

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
}

246 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}

Deductibles
If an exposure has a deductible, you can do the following through Cloud API:
• Access information about it
• Modify its amount
• Waive it
Note that Cloud API does not have separate endpoints for managing deductibles. All of the actions in the previous list
are executed by specifying information in the related exposure, either in the initial POST or a subsequent PATCH.
User interface behaviors that are not enforced by Cloud API
Be aware that, in the base configuration, ClaimCenter has behaviors and restrictions related to deductibles that are
defined in the user interface layer and not in the domain layer. Given that these behaviors are not declared in the
domain layer, they are not enforced when working with deductibles through Cloud API. The user interface behaviors
include the following:
• If a deductible amount is overridden:
◦ The new amount cannot be greater than the original amount.
◦ The edit reason cannot be null.
• If a deductible is waived:
◦ The edit reason cannot be null.
• If a deductible amount is not overridden and the deductible is not waived:
◦ You cannot change the amount.
◦ You cannot specify an edit reason.
• If a deductible has been partially or entirely applied, it cannot be waived.

Accessing deductible information

The Exposure schema has a Deductible child schema. This schema includes the following fields related to
deductibles. When an exposure has a deductible, this information is returned by default with any call, provided the
field is non-null.
• amount
• amountApplied
• amountRemaining
• editReason
• overridden
• waived
For example, exposure cc:222 on claim cc:111 has a deductible of $500. The following call returns information about
the exposure. This includes information about the exposure's deductible. (editReason does not appear because that
field's value is null.)
Command

GET /claim/v1/claims/cc:111/exposures/cc:222

Exposures 247
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Response

{
"data": {
"attributes": {
...
"deductible": {
"amount": {
"amount": "500.00",
"currency": "usd"
},
"amountApplied": {
"amount": "0.00",
"currency": "usd"
},
"amountRemaining": {
"amount": "500.00",
"currency": "usd"
},
"overridden": false,
"waived": false
},
"id": "cc:222",
...
},
...
}

Modifying a deductible amount

When PATCHing an exposure, you can modify a deductible amount by setting the amount field. Note that you can
modify amount, which is a database-backed value. But, you cannot modify either amountApplied or
amountRemaining, as these are calculated values.

The base configuration user interface has the following behaviors:

• In order to modify a deductible amount, you must first set the Modified field to true. (This value is stored in the
Overridden field.)
• When you set the Modified field to true, the Edit Reason field becomes visible and is required.
Because these behaviors are declared in the user interface, and not as domain-level logic, Cloud API does not enforce
them. Thus:
• You can modify a deductible amount without setting overridden to true. However, if you want to match base
configuration user interface behavior, then set overridden to true.
• You can modify a deductible amount without providing an editReason. However, if you want to match base
configuration user interface behavior, then provide a value for editReason.
For example, the following call sets the deductible for exposure cc:222 on claim cc:111 to $550. It sets overridden to
true and provides an edit reason of "Deductible entered incorrectly in PAS".
Command

PATCH /claim/v1/claims/cc:111/exposures/cc:222

Request

{
"data": {
"attributes": {
"deductible": {
"amount": {
"amount": "550.00",
"currency": "usd"
},
"editReason": "Deductible entered incorrectly in PAS",
"overridden": true
}
}
}
}

248 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Response

{
"data": {
"attributes": {
...
"deductible": {
"amount": {
"amount": "550.00",
"currency": "usd"
},
"amountApplied": {
"amount": "0.00",
"currency": "usd"
},
"amountRemaining": {
"amount": "550.00",
"currency": "usd"
},
"editReason": "Deductible entered incorrectly in PAS",
"overridden": true,
"waived": false
},
"id": "cc:222",
...
},
...
}

Waiving a deductible
You can waive a deductible, either during the initial POST or a subsequent PATCH.
The base configuration user interface has the following behaviors:
• In order to waive a deductible, you must first set the Modified field to true. (This value is stored in the Overridden
field.)
• When you set the Modified field to true, the Edit Reason field becomes visible and is required.
Because these behaviors are declared in the user interface, and not as domain-level logic, Cloud API does not enforce
them. Thus:
• You can waive a deductible without setting overridden to true. However, if you want to match base configuration
user interface behavior, then set overridden to true.
• You can waive a deductible without providing an editReason. However, if you want to match base configuration
user interface behavior, then provide a value for editReason.
For example, the following call waives the deductible for exposure cc:222 on claim cc:111. It sets overridden to true
and provides an edit reason of "Third party at fault".
Command

PATCH /claim/v1/claims/cc:111/exposures/cc:222

Request

{
"data": {
"attributes": {
"deductible": {
"editReason": "Third party at fault",
"overridden": true,
"waived": true
}
}
}
}

Response

{
"data": {
"attributes": {
...

Exposures 249
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"deductible": {
"amount": {
"amount": "500.00",
"currency": "usd"
},
"amountApplied": {
"amount": "0.00",
"currency": "usd"
},
"amountRemaining": {
"amount": "500.00",
"currency": "usd"
},
"editReason": "Third party at fault",
"overridden": true,
"waived": true
},
"id": "cc:222",
...
},
...
}

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 193.

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.

250 Exposures
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 Cloud API.
Similar to a closed claim, a closed exposure can be reopened.

Closing exposures
Use the following endpoint to close an exposure:
• POST /claim/v1/claims/{claimId}/exposures/{exposureId}/close
A request body is not required, but you can include it to specify a closedOutcome, which must be set to a value from
the ExposureClosedOutcomeType typelist (such as completed or duplicate).
For example, the following request closes exposure cc:222 on claim cc:706 with a closed outcome of duplicate.

POST /claim/v1/claims/cc:706/exposures/cc:222/close

{
"data": {
"attributes": {
"closedOutcome": {
"code": "duplicate"
}
}
}
}

Be aware that validation rules can prevent the closing of the exposure. For example, in the base configuration, an
exposure cannot be closed if it has open activities. If you attempt to close an exposure with open activities,
ClaimCenter responds with a message similar to the following.
"message": "There are open activities related to this exposure. To close the exposure, you must
first complete or skip these open activities. Please complete or skip these activities before
closing the exposure.",

Reopening a closed exposure

Use the following endpoint to reopen a closed exposure:
• POST /claim/v1/claims/{claimId}/exposures/{exposureId}/reopen
A request body is not required, but you can include it to specify either of the following:
• A note, which is a string value to explain why the exposure has been reopened
• A reason, which must be set to a value from the ExposureReopenedReason typelist (such as mistake or
paymentdenied).

For example, the following request reopens exposure cc:222 on claim cc:706 (assuming the exposure is closed):

POST /claim/v1/claims/cc:706/exposures/cc:222/reopen

<no request body>

Exposures 251
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

252 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 requests 253

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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:
• 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.

254 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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

Service requests 255

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ 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.

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.

256 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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.

Service requests 257

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

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}/ All service requests for the specified claim
service-requests
This is a "potentially large" endpoint. Cloud API returns an error if you attempt to sort on
this endpoint and the sort cannot be accomplished efficiently. For more information, see
“Potentially large endpoints” on page 56.

GET /claims/{claimId}/ The specified service request.

service-requests/ Note that in order to get information about a specific service request, you must access the
{serviceRequestId} 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)

258 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ 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:
• 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.
Command

POST [Link]

Service requests 259

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Request body

{
"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"
}
},
"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.

260 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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).

Service requests 261

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
}
}

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.

262 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 263

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

264 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 265

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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

266 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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)

Service requests 267

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ A category (a code from the ServiceRequestStatementLineItemCategory typelist)

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"
}
}
}
}

268 Service requests

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Note that ClaimCenter has validation rules that limit the ability to mark an invoice as paid based on the invoice's state.

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 269

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

270 Service requests

chapter 20

Matters

A matter is an object that manages information pertaining to a legal proceeding related to a claim, such as a lawsuit.
Similar to claims, exposures, and activities, a matter can be assigned to a group and a user in that group. This user is
responsible for managing the matter.
After its initial creation, a matter is considered open. An open matter can be closed (indicating no further action is
expected on the matter). A matter is considered closed when its CloseDate is non-null. A closed matter can be
reopened. (This resets CloseDate to null.)
You can create and manage matters through Cloud API.

Query for matters

Use the following endpoints to query for matters related to a given claim:
• GET /claim/v1/claims/{claimId}/matters
• GET /claim/v1/claims/{claimId}/matters/{matterId}
For example, the following request retrieves information about the matters associated with claim demo_sample:1.
GET /claim/v1/claims/demo_sample:1/matters/

{
"count": 1,
"data": [
{
"attributes": {
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31",
"type": "Group",
"uri": "/admin/v1/groups/demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1",
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
},
"assignmentStatus": {
"code": "assigned",
"name": "Assigned"
},
"caseNumber": "34-84982A",
"courtType": {
"code": "state",
"name": "State"
},
"fileDate": "2019-09-06T07:00:00.000Z",
"id": "cc:SKbNseiqKR6rbsdYtA5Qh",

Matters 271
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"matterType": {
"code": "General",
"name": "General"
},
"name": "Ray Newton matter",
"validationLevel": {
"code": "payment",
"name": "Ability to pay"
}
},
...

Creating matters
Use the following endpoint to create a matter for a given claim:
• POST /claim/v1/claims/{claimId}/matters
You can POST matters only on open claims. You cannot POST matters on draft claims.

Minimum creation criteria

The only required field is the matter's name.
For example, the following request creates a matter for claim demo_sample:1 using only the required field.

POST /claim/v1/claims/demo_sample:1/matters/

{
"data": {
"attributes": {
"name": "Claim arbitration"
}
}
}

The following request creates a matter for claim demo_sample:1 using the required field and some of the optional
fields.

POST /claim/v1/claims/demo_sample:1/matters/

{
"data": {
"attributes": {
"caseNumber": "35-00341B",
"fileDate": "2023-02-02",
"matterType": {
"code": "Mediation"
},
"name": "Mediation to determine who was at fault"
}
}
}

PATCHing matters
Use the following endpoint to PATCH a matter:
• PATCH /claim/v1/claims/{claimId}/matters/{matterId}
For example, the following request PATCHes matter cc:99 for claim demo_sample:1.
PATCH /claim/v1/claims/demo_sample:1/matters/cc:99

{
"data": {
"attributes": {
"caseNumber": "35-00109C"
}
}
}

272 Matters
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

There are several fields related to the matter's assignment: assignedGroup, assignedUser, assignmentStatus. These
fields cannot be set directly. They can only be set by assigning the matter. For more information, see “Assigning
matters” on page 273.

Assigning matters
A matter can be assigned to a group and a user in that group. This user has the primary responsible for managing the
matter.
When you create a matter through Cloud API, ClaimCenter automatically executes the matter assignment rules to
initially assign the activity to a group and user. You can use the following endpoint to reassign the activity as needed.
• POST /claim/v1/claims/{claimId}/matters/{matterId}/assign
Matter assignment is similar to activity assignment. For more information on activity assignment, see “Assigning
activities” on page 356. The only fundamental differences between the two is that activities can be assigned to queues
whereas matters cannot.

Assignment options
A matter can be assigned 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 running the activity assignment rules
The root resource for the /{matterId}/assign endpoint is MatterAssignee. This resource specifies assignment
criteria. The MatterAssignee schema has the following fields:

Field Type Description

autoAssign Boolean Whether to assign the matter using
assignment rules
claimOwner Boolean Whether to assign the matter to the claim
owner
groupId string The ID of the group to assign the matter to
userId string The ID of the user to assign the matter to

The MatterAssignee resource must specify an assignment option. It cannot be empty.

Assignment examples
Assigning to a specific group (and user)
The following payload assigns matter cc:99 for claim demo_sample:1 to group demo_sample:31 and user
demo_sample:1. The user must be active and must have the "own matter" system permission.

POST /claim/v1/claims/demo_sample:1/matters/cc:99/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:1"
}
}
}

Matters 273
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

The following payload assigns matter cc:99 for claim demo_sample:1 to group demo-sample:31. Because no user has
been specified, ClaimCenter will execute assignment rules to assign the matter to a user in group demo-sample:31.

POST /claim/v1/claims/demo_sample:1/matters/cc:99/assign

{
"data": {
"attributes" : {
"groupId" : "demo_sample:31"
}
}
}

Assigning to the claim owner

The following payload assigns matter cc:99 for claim demo_sample:1 to the group and user that owns the claim that
the matter is associated with.

POST /claim/v1/claims/demo_sample:1/matters/cc:99/assign

{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}

Using automated assignment

The following payload assigns matter cc:99 for claim demo_sample:1 using automated assignment rules.

POST /claim/v1/claims/demo_sample:1/matters/cc:99/assign

{
"data": {
"attributes" : {
"autoAssign" : true
}
}
}

For more information on assignment rules, see the Gosu Rules Guide.

Closing and reopening matters

Closing matters
Use the following endpoint to close a matter:
• POST /claim/v1/claims/{claimId}/matters/{matterId}/close
A request body is not required, but you can include it to specify either of the following:
• A note, which is a string value to explain why the matter was closed.
• A reason, which must be set to a value from the ResolutionType typelist.
For example, the following request closes matter cc:99 for claim demo_sample:1 with an optional note and optional
reason of "Petition/motion withdrawn (PMW)".

POST /claim/v1/claims/demo_sample:1/matters/cc:99/close

{
"data": {
"attributes": {
"note": "Opposing counsel withdrew petition to reassign fault",
"reason": {
"code": "PMW"
}
}
}
}

274 Matters
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

When you close a matter, the closeDate field is set to the current date and time.

Reopening matters
Use the following endpoint to reopen a matter:
• POST /claim/v1/claims/{claimId}/matters/{matterId}/reopen
A request body is not required, but you can include it to specify either of the following:
• A note, which is a string value to explain why the matter was reopened.
• A reason, which must be set to a value from the MatterReopenedReason typelist.
For example, the following request reopens matter cc:99 for claim demo_sample:1 with an optional reason of
"mistake".

POST /claim/v1/claims/demo_sample:1/matters/cc:99/reopen

{
"data": {
"attributes": {
"reason": {
"code": "mistake"
}
}
}
}

When you reopen a matter, the closeDate field is set to null.

Matters 275
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

276 Matters
chapter 21

Workers' compensation claims

A workers' compensation claim (also referred to as a workers' comp claim) is a claim filed by a company on behalf of
an injured worker. The claim is intended to address losses that result from medical treatment of the injured worker, lost
wages due to the injury, and potentially court costs related to litigation if the worker initiates legal action.
From a processing standpoint, workers' compensation claims have requirements that are unlike claims for any other
line of business. Therefore, ClaimCenter has behaviors that are specific to workers' comp claims. The following topic
summarizes these behaviors. It also describes how to create workers' comp claims through Cloud API.
For more information on the business functionality of workers' comp claims, see the Application Guide.

Workers' comp claims in ClaimCenter

The ClaimWorkComp entity
A large set of claim-level information is relevant only for workers' comp claims. For example, the activity the worker
was performing when injured, and whether the worker required medical attention. This information is not stored on the
Claim entity. Instead, it is stored on the ClaimWorkComp entity. This entity has a one-to-one relationship with Claim. A
given claim has an instance of ClaimWorkComp only when the claim's policy is a workers' comp policy.

Possible exposures for a workers' comp claim

A workers' comp claim must always have one exposure and can have a maximum of three exposures.
• There must always be an injury exposure used to track information related to the injury.
• There can optionally be a lost wages exposure used to track information related to wages the employee has lost as
a result of being injured.
There can optionally be an employer liability exposure used to track information related to legal proceedings initiated
by the employee.

Creating exposures for a workers' comp claim

For most lines of business, exposures get created in one of two ways:
• The exposure may be created automatically by business logic such as Claim presetup rules.
• The exposure may be created manually by the adjuster, either during or after the New Claim wizard.
For workers' comp claims, exposures are always created automatically. Each type of exposure is triggered by the claim
being in a certain state.
Workers' compensation claims 277
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• The injury exposure is created automatically at the end of the New Claim wizard. This is done for all workers'
comp claims.
• The lost wages exposure is created automatically at the end of the New Claim wizard if, on the Loss Details step,
the Lost time from work field is set to Yes.
• The employer liability exposure is created when the Employer Liability? field is set to Yes.
◦ In the base configuration, this field is not exposed in the New Claim wizard. Thus, in the base configuration,
this field can only be set after the claim has been created and assigned. The field is on the Loss Details: General
screen in the Classification section.

Creating incidents for a workers' comp claim

Non-workers' comp claims have incidents. They often appear under some sort of "Incident" label. (For example,
personal auto claims can have exposures with a Vehicle Incident label.)
Workers' comp claims also have incidents. However, the user interface does not call them out as incidents.
The injury exposure
Every workers' comp claim has a "main injury incident". This is an injury incident that stores most of the information
about the injury.
There is also an "additional injury incident". In the base configuration, it is created by ClaimCenter presetup rules
when the injury exposure is created. Note the following:
• The injury exposure is associated with the additional injury incident, not the main injury incident.
• In the base configuration, no information is stored on the additional injury incident. All of the injury information
shown in the user interface and used in the claim process comes from the main injury incident.
Lost wages exposure
If a claim has a lost wages exposure, it also has an incident for lost wages.
• This incident is created automatically by ClaimCenter presetup rules.
• Like the main injury incident, this incident's subtype is injury incident.
Employer liability exposure
If a claim has an employer liability exposure, it also has an incident for employer liability.
• This incident is created automatically by ClaimCenter presetup rules.
• Its subtype is general incident.

Exposures in the user interface

For all claims, there is a list of exposures on the Overview screen.
For non-workers' comp claims, there is also a separate Exposures screen listed in the left-hand side bar. This screen lists
all exposures for the claim. For workers' comp lines of business, there is no separate Exposures screen listed in the left-
hand side bar. Instead, each exposure is given its own screen.
• The injury exposure appears on the Medical Details screen.
• The lost wages exposure appears on the Indemnity screen.
• This screen is hidden if there is no lost wages exposure for the claim.
• The employer liability exposure appears on the Employer Liability screen.
• This screen is hidden if there is no employer liability exposure for the claim.
Each of these screens lists information from the associated incidents. However, the term "Incident" is not used in the
user interface. The information is co-mingled with exposure-level information.

278 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Creating basic workers' comp claims

For the purpose of this discussion, a basic workers' comp claim is defined as a workers' comp claim with a single
exposure for the worker's injury.
In both the user interface and Cloud API, you do not create the injury exposure manually.
• In the user interface, you simply provide information about the injury.
• In Cloud API , you must create an injury incident that is marked as the "main injury incident". You then add
information about the injury to this incident.
When the claim is submitted, ClaimCenter automatically creates the injury exposure.

Create and submit requirements

There are multiple requirements for creating and submitting a workers' comp claim. These requirements come from
different aspects of ClaimCenter.
Requirements to create
In Cloud API, to create a draft workers' comp claim (without necessarily submitting it):
• The claim itself must specify lossDate and policyNumber.
• There must be exactly one injury incident whose mainWorkersCompIncident property is set to true.
• This requirement is configurable. For more information, see “Configuring Cloud API behavior with workers' comp
claims” on page 292.
A workers' comp claim cannot be created without a main injury incident. Therefore, workers' comp claims can be
created only in the context of a composite request.
Requirements to submit
The base configuration of ClaimCenter 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 lossDate, policyNumber and mainWorkersCompIncident, you must also
specify a reporter for the claim and a claimant for the exposure. These requirements are enforced by the "CLV04000 -
ClaimContact Role Configuration" validation rule, which throws an error at the NewLossCompletion level if the claim
reporter or exposure claimant is null.
The additional injury exposure
In the base configuration, the ClaimCenter presetup rules create the injury exposure automatically. They also create an
"additional injury incident". The injury exposure is associated with the additional injury incident, not the main injury
incident. However, no information is stored on the additional injury incident. All of the injury information shown in the
user interface and used in the claim process comes from the main injury incident.
Be aware that after you create a workers' comp claim, the claim has at least two injury incidents:
• The "main injury incident". This stores information about the injury.
• The "additional injury incident". This typically does not store any information of value and can usually be ignored.

Minimal basic workers' comp claim: Example

The following is an example of the minimum amount of information needed to create a workers' comp claim. Note the
following:
• It uses policy 32-300869, which is part of the sample data.
• It specifies two contacts: Susan Sarcosky and Jennifer Albee. These contacts are created solely to pass the base
configuration validation rules for submitting a claim.

Workers' compensation claims 279

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /composite/v1/composite

Request payload

{
"requests": [
{
"body": {
"data": {
"attributes": {
"lossDate": "2024-06-09",
"policyNumber": "32-300869"
}
}
},
"method": "post",
"uri": "/claim/v1/claims",
"vars": [
{
"name": "claimId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Sue",
"lastName": "Sarcosky",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "sueId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Jennifer",
"lastName": "Albee",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "jenniferId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"reporter": {
"id": "${sueId}"
},
"claimant": {
"id": "${jenniferId}"
}
}
}
},
"method": "patch",
"uri": "/claim/v1/claims/${claimId}"
},
{
"body": {
"data": {
"attributes": {
"mainWorkersCompIncident": true
}
}

280 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/injury-incidents"
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
}
]
}

Creating lost wages workers' comp claims

For the purpose of this discussion, a lost wages workers' comp claim is a claim with both an injury exposure and a lost
wages exposure. (It may or may not also have an employer's liability exposure.)
In both the user interface and Cloud API, you do not create the lost wages exposure manually.
• In the user interface, you set the Lost time from work field to Yes.
• In Cloud API, you must add the workersCompInfo object to the claim and set its timeLossReport field to true.
When the claim is submitted, ClaimCenter automatically creates the lost wages exposure.

Create and submit requirements

All of the requirements for a basic workers' comp claim are also requirements for a lost wages claim. For information
on those requirements, see “Creating basic workers' comp claims” on page 279.
In addition to those requirements, the subrequest that creates the claim must include the following:
"data": {
"attributes": {
...
"workersCompInfo": {
"timeLossReport": true
}
...
}
}

Minimal lost wages claim: Example

The following is an example of the minimum amount of information needed to create a workers' comp claim with both
an injury exposure and a lost wages exposure. Note that the only difference between this example and the initial
"minimal basic workers' comp claim" example is the addition of the workersCompInfo object in the body of the first
subrequest. It appears below in bold. The remainder of the composite request is the same.
Command

POST /composite/v1/composite

Request payload

{
"requests": [
{
"body": {
"data": {
"attributes": {
"lossDate": "2024-06-09",
"policyNumber": "32-300869",
"workersCompInfo": {
"timeLossReport": true
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims",
"vars": [
{
"name": "claimId",
"path": "$.[Link]"

Workers' compensation claims 281

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Sue",
"lastName": "Sarcosky",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "sueId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Jennifer",
"lastName": "Albee",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "jenniferId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"reporter": {
"id": "${sueId}"
},
"claimant": {
"id": "${jenniferId}"
}
}
}
},
"method": "patch",
"uri": "/claim/v1/claims/${claimId}"
},
{
"body": {
"data": {
"attributes": {
"mainWorkersCompIncident": true
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/injury-incidents"
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
}
]
}

Creating employer liability workers' comp claims

For the purpose of this discussion, an employer liability workers' comp claim is a claim with both an injury exposure
and an employer liability exposure. (It may or may not also have a lost wages exposure.)
In both the user interface and Cloud API, you do not create the employer liability exposure manually.

282 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• In the user interface, you must create the claim using the New Claim wizard. Then once it has been submitted, you
must navigate to the Lost Details: General screen and, in the Classification section, set the Employer Liability? field
to Yes.
• In Cloud API , you must add the workersCompInfo object to the claim and set its employerLiability field to true.
This can be done either before the claim is submitted as part of the POST /claim call, or after the claim is
submitted as part of a PATCH /claim call.
Note: When the claim is created or updated with the appropriate field set, ClaimCenter automatically creates
the employer liability exposure.

Create and submit requirements

All of the requirements for a basic workers' comp claim are also requirements for an employer liability claim. For
information on those requirements, see “Creating basic workers' comp claims” on page 279.
In addition to those requirements, the subrequest that creates the claim must include the following:
"data": {
"attributes": {
...
"workersCompInfo": {
"employerLiability": true
}
...
}
}

Minimal employer liability claim: Example

The following is an example of the minimum amount of information needed to create a workers' comp claim with both
an injury exposure and an employer liability exposure. Note that the only difference between this example and the
initial "minimal basic workers' comp claim" example is the addition of the workersCompInfo object in the body of the
first subrequest. It appears below in bold. The remainder of the composite request is the same.
Command

POST /composite/v1/composite

Request payload
{
"requests": [
{
"body": {
"data": {
"attributes": {
"lossDate": "2024-06-09",
"policyNumber": "32-300869",
"workersCompInfo": {
"employerLiability_Ext": true
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims",
"vars": [
{
"name": "claimId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Sue",
"lastName": "Sarcosky",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",

Workers' compensation claims 283

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"vars": [
{
"name": "sueId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Jennifer",
"lastName": "Albee",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "jenniferId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"reporter": {
"id": "${sueId}"
},
"claimant": {
"id": "${jenniferId}"
}
}
}
},
"method": "patch",
"uri": "/claim/v1/claims/${claimId}"
},
{
"body": {
"data": {
"attributes": {
"mainWorkersCompIncident": true
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/injury-incidents"
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
}
]
}

Typical basic workers' comp claim: Example

The following is an example of the more typical workers' comp claim. It includes information that is not required but is
often known at FNOI. It also triggers the creation of all three types of exposures: injury, lost wages, and employer
liability. Once again, this example uses policy 32-300869, which is part of the sample data.
Command

POST /composite/v1/composite

Request payload
{
"requests": [
{
"body": {
"data": {
"attributes": {
"accidentType": {
"code": "25"
},
"dateReportedToEmployer": "2024-06-09",
"description": "WC Claim",

284 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"employmentInjury": true,
"lobCode": {
"code": "WorkersCompLine"
},
"reportedDate": "2024-06-09",
"lossCause": {
"code": "fall"
},
"lossDate": "2024-06-09",
"policyNumber": "32-300869",
"lossLocation": {
"addressLine1": "1111 Accident Dr",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"workersCompInfo": {
"timeLossReport": true,
"deathReport": false,
"medicalReport": true,
"employerLiability_Ext": true
},
"employmentData": {
"numberOfDaysWorked": "5.8",
"numberOfHoursWorked": "8.6",
"wageAmount": {
"amount": "748.20",
"currency": "usd"
},
"payPeriod": {
"code": "weekly"
}
},
"examinationDate": "2024-06-09",
"treatmentRendered": "This patient had a very bad fall"
}
}
},
"method": "post",
"uri": "/claim/v1/claims",
"vars": [
{
"name": "claimId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Sue",
"lastName": "Sarcosky",
"contactSubtype": "Person"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "sueId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Jennifer",
"lastName": "Albee",
"contactSubtype": "Person",
"homePhone": {
"countryCode": {
"code": "US"
},
"number": "8184461206"
},
"primaryAddress": {
"addressLine1": "354 Cactus Ln",
"city": "Tucson",
"postalCode": "85716",
"state": {
"code": "AZ"
}
}
}

Workers' compensation claims 285

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "jenniferId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"firstName": "Gregory",
"lastName": "House",
"emailAddress1": "0000@[Link]",
"primaryAddress": {
"addressLine1": "1111 Hospital Rd,",
"city": "Princeton",
"postalCode": "08540",
"state": {
"code": "NJ"
}
},
"contactSubtype": "Doctor",
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "704-434-2008"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"vars": [
{
"name": "doctorId",
"path": "$.[Link]"
}
]
},
{
"body": {
"data": {
"attributes": {
"reporter": {
"id": "${sueId}"
},
"mainContact": {
"id": "${jenniferId}"
},
"claimant": {
"id": "${jenniferId}"
},
"firstIntakeDoctor": {
"id": "${doctorId}"
},
"reportedByType": {
"code": "hrrep"
},
"mainContactType": {
"code": "claimant"
}
}
}
},
"method": "patch",
"uri": "/claim/v1/claims/${claimId}"
},
{
"body": {
"data": {
"attributes": {
"mainWorkersCompIncident": true,
"description": "This was an injury",
"generalInjuryType": {
"code": "specific"
},
"detailedInjuryType": {
"code": "07"
},
"bodyParts": [
{
"primaryBodyPart": {
"code": "head"
},

286 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"detailedBodyPart": {
"code": "10"
},
"sideOfBody": {
"code": "left"
}
}
]
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/injury-incidents"
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/submit"
}
]
}

Managing ICD codes

The International Statistical Classification of Diseases and Related Health Problems (ICD) are medical diagnosis codes
that classify diseases. These are also referred to as ICD codes. ICD codes are used to standardize information about the
causes, symptoms, and diagnoses of medical issues. ClaimCenter provides over 72,000 ICD codes as reference data.
These codes can be attached to claims, such as workers' compensation claims. ClaimCenter also provides a user
interface for searching for, creating, and editing codes. For more information on the business functionality of ICD
codes, refer to the Application Guide.
Cloud API also provides endpoints that you can use to manage ICD codes.

Querying for ICD codes

Use the following endpoint to retrieve all ICD codes loaded into ClaimCenter:
• GET /admin/v1/icd-codes
Note: In the base configuration, there are over 72,000 ICD codes. By default, each GET returns a page of 25
codes. You can modify the default page size using the pageSize query parameter. But given the amount of
codes, it is usually impractical to page through codes to identify a specific code. It is usually more efficient to
search for a code. For more information, see “Searching for ICD codes” on page 288.
For example, the following query returns the first 2 codes.
Command

GET /admin/v1/icd-codes?pageSize=2

Response

{
"count": 2,
"data": [
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"code": "A00.0",
"description": "Cholera due to Vibrio cholerae 01, biovar cholerae",
"edition": {
"code": "ICD10",
"name": "ICD10"
},
"id": "icd10:A00.0"
},
...
},
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},

Workers' compensation claims 287

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"code": "A00.1",
"description": "Cholera due to Vibrio cholerae 01, biovar eltor",
"edition": {
"code": "ICD10",
"name": "ICD10"
},
"id": "icd10:A00.1"
},
...
}
...

Use the following endpoint to retrieve a specific ICD codes:

• GET /admin/v1/icd-codes/{icdCodeId}
For example, the following query returns information about ICD code icd10:A00.0.
Command

GET /admin/v1/icd-codes/icd10:A00.0

Response

{
"data": {
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"code": "A00.0",
"description": "Cholera due to Vibrio cholerae 01, biovar cholerae",
"edition": {
"code": "ICD10",
"name": "ICD10"
},
"id": "icd10:A00.0"
},
...
}
}

Searching for ICD codes

Use the following endpoint to search for ICD codes.
• POST /admin/v1/search/icd-codes
When you call this endpoint, you must provide a body. The body can be empty, in which case all ICD codes are
returned. (This is equivalent to executing GET /admin/v1/icd-codes.)
You can also specify one or more of the following fields:
• activeDate- A date or datetime value, specified as a string, at which the ICD code is active. This returns any ICD
code whose AvailabilityDate is on or after the given datetime and whose ExpiryDate is on or before the given
datetime.
• bodySystem - A typecode from the ICDBodysystem typelist, such as INF (Certain infectious and parasitic diseases
(ICD10 A00-B99)). The search returns only ICD codes whose with that bodySystem code.
• code - A String representing a portion of the ICD 10 code. The search returns only ICD codes whose code contains
the specified String.
• description - A String value. The search returns only ICD codes whose description contains the specified String.
• edition - A typecode from the ICDEdition typelist. The search returns only ICD codes whose with that edition
code.
bodySystem and description example
The following request searches for all ICD codes whose bodySystem code is DIG (Diseases of the digestive system
(K00-K95)) and whose description includes the text "fever". The request returns only the ID, body system, and
description of each code.

288 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /admin/v1/search/icd-codes?fields=id,bodySystem,description

Request

{
"data": {
"attributes": {
"bodySystem": {
"code": "DIG"
},
"description": "fever"
}
}
}

Response

{
"count": 6,
"data": [
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"description": "Typhoid fever, unspecified",
"id": "icd10:A01.00"
}
},
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"description": "Typhoid fever with other complications",
"id": "icd10:A01.09"
}
},
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"description": "Paratyphoid fever A",
"id": "icd10:A01.1"
}
},
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"description": "Paratyphoid fever B",
"id": "icd10:A01.2"
}
},
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"description": "Paratyphoid fever C",
"id": "icd10:A01.3"
}
},
{
"attributes": {
"bodySystem": {
"code": "DIG",
"name": "Diseases of the digestive system (K00-K95)"
},
"description": "Paratyphoid fever, unspecified",
"id": "icd10:A01.4"
}
}
],

Workers' compensation claims 289

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

...
}

activeDate and description example

The following request searches for all ICD codes that are active on September 30, 2024 and whose description includes
the text "fever". The request returns only the ID and description of each code. (Note that, in the base configuration, the
ICD Codes do not have active and expiration dates. So in the base configuration, this would return all ICD Codes with
"fever" in the description.)
Command

POST /admin/v1/search/icd-codes?fields=id,availabilityDate,expirationDate,description

Request

{
"data": {
"attributes": {
"activeDate": "2024-09-30",
"description": "fever"
}
}
}

Response

{
"count": 1,
"data": [
{
"attributes": {
"availabilityDate": "2024-09-15T00:00:00.000Z",
"description": "Typhoid fever, unspecified",
"expirationDate": "2024-10-15T00:00:00.000Z
",
"id": "icd10:A01.00"
}
}
],
...
}

POSTing ICD codes

Use the following endpoint to POST an ICD code:
• POST /admin/v1/icd-codes
The minimum required fields are:
• bodySystem - A typecode from the ICDBodySystem typelist, such as INF (Certain infectious and parasitic diseases
(ICD10 A00-B99))
• code - A String of up to 8 characters representing the ICD 10 code
• description - A String
Th following fields are optional:
• availabilityDate - A date value identifying the first day the ICD code is available
• chronic - A Boolean value which, if not specified, defaults to false
• edition - A typecode from the ICDEdition typelist. In the base configuration, there is only one ICD Edition code:
ICD10. Thus, new codes default to this edition
• expirationDate - A date value identifying the last day the ICD code is available
For example, the following request creates a new ICD code.

290 Workers' compensation claims

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /admin/v1/icd-codes

Request

{
"data": {
"attributes": {
"bodySystem": {
"code": "INF"
},
"code": "AA77.07",
"description": "Cabin fever"
}
}
}

Response

{
"count": 1,
"data": [
{
"attributes": {
"bodySystem": {
"code": "INF",
"name": "Certain infectious and parasitic diseases (ICD10 A00-B99)"
},
"chronic": false,
"code": "AA77.07",
"description": "Cabin fever",
"edition": {
"code": "ICD10",
"name": "ICD10"
},
"id": "cc:Sh8KF2kE94Jt0ZGE91ejL"
},
...
}
}
}

PATCHing ICD codes

Use the following endpoint to PATCH an ICD code:
• PATCH /admin/v1/icd-codes/{icdCodeId}
For example, the following request modifies the code for the ICD Code created in the previous example.
Command

PATCH /admin/v1/icd-codes/cc:Sh8KF2kE94Jt0ZGE91ejL

Request

{
"data": {
"attributes": {
"chronic": true
}
}
}

Response

{
"count": 1,
"data": [
{
"attributes": {
"bodySystem": {
"code": "INF",
"name": "Certain infectious and parasitic diseases (ICD10 A00-B99)"
},
"chronic": true,
"code": "AA77.07",

Workers' compensation claims 291

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"description": "Cabin fever",

"edition": {
"code": "ICD10",
"name": "ICD10"
},
"id": "cc:Sh8KF2kE94Jt0ZGE91ejL"
},
...
}
}
}

Configuring Cloud API behavior with workers' comp claims

Enabling the main injury incident
By default, workers' comp claims must be submitted within the context of a composite request. Also, there must be a
"main" injury incident. This is an injury incident whose mainWorkersCompIncident property is set to true.
This behavior is enforced by the EnableWorkersCompMainInjuryIncidentInCloudAPI application configuration
parameter, which is introduced in the 2024.07.0 (Kufri) release.
• For insurers who enter production with the 2024.07.0 (Kufri) release or a later release, this parameter is set to true
by default.
• For insurers who entered production with a release earlier than the 2024.07.0 (Kufri) release, during the update
process, this parameter is set to false by default to maintain the behavior of previous releases.
When the parameter is set this parameter to false:
• Workers' comp claims can be submitted outside of a composite request.
• The "main" injury incident is not returned by the /injury-incidents endpoint
◦ However, if a caller is able to ascertain the main injury incident's ID, then it can be accessed directly through
the /claim/injury-incident/{incidentId} endpoint
• The InjuryIncident schema's mainWorkersCopIncident property cannot be updated through Cloud API
For more information on setting application configuration parameters, see the Configuration Guide.

Exposing additional fields

As of this release, the base configuration of Cloud API exposes many of the fields used by ClaimCenter to process
workers' comp claims. But it does not expose all of them.
If there are fields that you need for Cloud API to support workers' comp claims, you can configure Cloud API to
expose them. This applies to both base configuration fields and extension fields.
For more information on how to add properties to resources, see the Cloud API Developer Guide.

292 Workers' compensation claims

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 293

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

294 Business flows: Financials

chapter 22

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".
Reserves 295
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ Cost categories are used for financial and business tracking purposes.

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 353.
(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- Retrieve a list of reserve sets
sets
This is a "potentially large" endpoint. Cloud API returns an error if you attempt to
sort on this endpoint and the sort cannot be accomplished efficiently. For more
information, see “Potentially large endpoints” on page 56.
GET /claims/{claimId}/reserve- Retrieve details of a reserve set
sets/{reserveSetId}
GET /claims/{claimId}/reserves The reserves associated with a given claim
This is a "potentially large" endpoint. Cloud API returns an error if you attempt to
sort on this endpoint and the sort cannot be accomplished efficiently. For more
information, see “Potentially large endpoints” on page 56.
GET /claims/{claimId}/reserves/ The details of a specific reserve
{transactionId}

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:

296 Reserves
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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

{
"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"

Reserves 297
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
"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"
}
}
],
"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)
◦ exposure (This must be specified. It can be explicitly set to null, in which case the reserve line is created at the
claim level. For an example,see “Creating a claim-level reserve” on page 300.)
◦ 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

298 Reserves
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 339.

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.

Reserves and exchange rates

ClaimCenter had multiple data models for storing exchange rate information. Each model makes use of a different
schema. If your instance of ClaimCenter supports multicurrency and you are specifying exchange rate information in a
reserve, then the payload must make use of the schema that corresponds to the exchange rate data model that
ClaimCenter is currently using. For more information, see “Exchange rate information for transactions” on page 342.

Example of creating reserves

Creating an exposure-level reserve
The following payload is an example of creating a reserve line for a specific exposure.
• 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.

Reserves 299
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /claims/cc:61/reserve-sets

Request payload

{
"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"
}
}
]
}
}
}

Creating a claim-level reserve

The following payload is an example of creating a claim-level reserve.
• The ID of the claim is cc:61.
• Because this is a claim-level reserve, the exposure is set to null.
• There is only one reserve transaction.
◦ The transaction is for a reserve line whose cost type and cost category is Expense - D&CC / Legal (dccexpense
and legal).
◦ The transaction's currency is USD.
◦ The transaction has a single line item for $5000.
Command

POST /claims/cc:61/reserve-sets

Request payload

{
"data": {
"attributes": {
"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "legal"
},
"costType": {
"code": "dccexpense"
},
"exposure": null,
"reservingCurrency": {
"code": "usd"

300 Reserves
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
},
"lineItems": [
{
"transactionAmount": {
"amount": "5000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

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.
Command

POST /claims/cc:61/reserve-sets

Request payload

{
"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"
}
}
]
}

Reserves 301
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}

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.
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>

302 Reserves
chapter 23

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.
When issuing money for claims, ClaimCenter makes use of several distinct types of objects. This includes payments,
checks, and check sets.

Payments
Within the context of ClaimCenter, a payment transaction (often referred to simply as a payment) is a monetary amount
that is paid to satisfy a claim.
Every payment transaction is associated with exactly one reserve line from one exposure, though a reserve line can be
associated with multiple payment transactions. 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 about 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 whose car and fence were damaged, 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
◦ Description of loss: Ray Newton hit a tree. His car was damaged, and he suffered a broken arm.

Creating checks 303

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ 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 of loss: 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 shop 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
Financial transactions require approval. In some cases, the transaction is sufficiently small and does not meet any
special criteria, and therefore the transaction is automatically approved. In other cases, the amount is large enough that
it exceeds the creator's authority limit, or the transaction meets certain criteria specified in transaction approval rules.
In these cases, the transaction must be approved by another user.
For a given claim, when multiple payment transactions are created at the same time, they 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 in Cloud API, see “Activities” on page 353.
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
(This endpoint is "potentially large". See below.)
GET /claims/{claimId}/check-sets/{checkSetId} Retrieve details of a check set
GET /claims/{claimId}/checks The checks associated with a given claim
(This endpoint is "potentially large". See below.)
GET /claims/{claimId}/checks/{checkId} The details of a specific check
GET /claims/{claimId}/payments The payment transactions associated with a given claim
(This endpoint is "potentially large". See below.)
GET /claims/{claimId}/payments/{transactionId} The details of a specific payment transaction

Some endpoints are "potentially large". Cloud API returns an error if you attempt to sort on this endpoint and the sort
cannot be accomplished efficiently. For more information, see “Potentially large endpoints” on page 56.

304 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
• 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"
}
}
],

Creating checks 305

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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;
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 193. For more information on validating
exposure, see “Validating exposures” on page 250.

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.

306 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
• 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.

Creating checks 307

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 339.

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.

Checks and exchange rates

ClaimCenter had multiple data models for storing exchange rate information. Each model makes use of a different
schema. If your instance of ClaimCenter supports multicurrency and you are specifying exchange rate information in a
check, then the payload must make use of the schema that corresponds to the exchange rate data model that
ClaimCenter is currently using. For more information, see “Exchange rate information for transactions” on page 342.

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".
◦ 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": {

308 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"code": "claimcost"
},
"exposure": {
"id": "cc:58"
},
"reservingCurrency": {
"code": "usd"
}
},
"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
"id": "cc:613"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
}
}

Recurrences
Recurrences in ClaimCenter
A recurrence is a series of one or more checks that ClaimCenter 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

Creating checks 309

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
}

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)

310 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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)

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.

Creating checks 311

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
}
}
]

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"

312 Creating checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
"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.
• 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}

Creating checks 313

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

314 Creating checks

chapter 24

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 315
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

316 Managing the check life cycle

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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"

Managing the check life cycle 317

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.

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

318 Managing the check life cycle

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

When acknowledging a transaction, there is no additional required information. The request can have no body.
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 319

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

320 Managing the check life cycle

chapter 25

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 321
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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
(This endpoint is "potentially large". See below.)
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
(This endpoint is "potentially large". See below.)
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
(This endpoint is "potentially large". See below.)
GET /claims/{claimId}/recovery-sets/{recoverySetId} Retrieve the details for a specific recovery set
GET /claims/{claimId}/recoveries Retrieve the recovery transactions
(This endpoint is "potentially large". See below.)
GET /claims/{claimId}/recoveries/{transactionId} Retrieve the details of a specific recovery

Some endpoints are "potentially large". Cloud API returns an error if you attempt to sort on this endpoint and the sort
cannot be accomplished efficiently. For more information, see “Potentially large endpoints” on page 56.

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"
},

322 Recoveries and recovery reserves

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"reservingAmount": {
"amount": "100.00",
"currency": "usd"
},
"transactionAmount": {
"amount": "100.00",
"currency": "usd"
}
}
],
"reserveLine": {
"costCategory": {
"code": "body",
"name": "Auto body"
},
"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.

Recoveries, recovery reserves, and exchange rates

ClaimCenter had multiple data models for storing exchange rate information. Each model makes use of a different
schema. If your instance of ClaimCenter supports multicurrency and you are specifying exchange rate information in a
recovery or recovery reserve, then the payload must make use of the schema that corresponds to the exchange rate data
model that ClaimCenter is currently using. For more information, see “Exchange rate information for transactions” on
page 342.

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:

Recoveries and recovery reserves 323

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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)
◦ 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": {

324 Recoveries and recovery reserves

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"id": "cc:SB1"
},
"recoveryCategory": {
"code": "salvage"
},
"reservingCurrency": {
"code": "usd"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "5000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

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:

Recoveries and recovery reserves 325

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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.
• 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"
}
}
]
}
}
}

326 Recoveries and recovery reserves

chapter 26

Financial calculations

Cloud API supports the ability to retrieve financial calculations for a claim. This topic describes how to use the
financial calculations endpoints.

Financial calculations in ClaimCenter

In ClaimCenter, the financial management of a claim is tracked through instances of the Transaction entity. Every
Transaction is associated with a claim. Every instance of Transaction is one of the following subtypes: Reserve,
Payment, RecoveryReserve, or Recovery.

Every transaction has four additional values that identify its associated reserve line: CostType, CostCategory,
ReservingCurrency, and Exposure. The first three must be non-null. The fourth one is either non-null (when the
transaction is associated with an exposure), or null (when the transaction is claim-level).
Before any payments are made, the amount of money in a given reserve line is the sum of the appropriate transactions
associated with that reserve line. For example, suppose a claim has the following reserve transactions:

Exposure CostType CostCategory Currency Amount

cc:22 ClaimCost Medical USD $5000
cc:22 ClaimCost Medical USD $7000
cc:333 ClaimCost Auto parts USD $1000
cc:333 ClaimCost Auto parts USD $1000
cc:333 Expense - A&O Vehicle appraisal USD $500
cc:4444 ClaimCost Auto parts USD $1000

For this claim:

• The first exposure (cc:22) has a $12,000 reserve for "ClaimCost - Medical". This is the sum of the first two
transactions.
• The second exposure (cc:333) has a $2000 reserve for "ClaimCost - Auto parts" (the sum of the third and fourth
transaction) and a $500 reserve for "Expense - A&O - Vehicle appraisal" (the fifth transaction).
• The third exposure (cc:4444) has a $1000 reserve for "ClaimCost - Auto parts) (the sixth transaction).
In order to determine certain values, such as the total reserve remaining, one must query the ClaimCenter database for
the correct transactions and then perform the correct calculations against those transactions. It is too unwieldy for an
insurer to execute this type of calculation directly against the database. Therefore, ClaimCenter provides a set of Gosu
classes with methods you can use to retrieve specific calculations for a given claim.

Financial calculations 327

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

For example, the following Gosu expression returns the amount of open reserves for claim thisClaim (expressed in
the claim's currency).
[Link]()
.withClaim(thisClaim)
.Amount

For more information on using these classes directly in ClaimCenter, see the Configuration Guide.

ClaimAmount, ReportingAmount, and ReservingAmount

When you execute a financial calculation in ClaimCenter, there are three types of amounts you can get:
• ClaimAmount - The amount expressed in the claim's currency
• ReportingAmount - The amount expressed in the reporting currency for this instance of ClaimCenter
• ReservingAmount - The amount expressed in the reserve's currency
In a mono-currency instance of ClaimCenter, these fields have the same value.
In a multicurrency instance of ClaimCenter, these fields have the same logical value. But the actual values might be
different for a claim whose claim currency, reporting currency, and/or reserving currency are not the same, as each
logical value is converted to the appropriate currency.
A given calculation can always return ClaimAmount and ReportingAmount. This is because, for any given claim, the
relevant transactions are in a single currency. For a single claim, reserve transactions can be in different currencies.
Therefore, ReservingAmount is available only if the calculation filters out transactions so that the remaining
transactions all share the same currency.

Financial calculations in Cloud API

Financial calculations are exposed to Cloud API through the following endpoints:
• GET /claim/v1/claims/{claimId}/financial-calculations
• POST /claim/v1/claims/{claimId}/financial-calculations/{expression}/get-amount
The first endpoint provides a list of available financial expressions for the claim that can be used to execute
calculations. The second endpoint returns the amount of a specific calculation for a specific claim.

Retrieving the available financial calculations

A caller can retrieve the list of available financial expressions for a given claim by using the following endpoint.
• GET /claim/v1/claims/{claimId}/financial-calculations
This endpoint returns a list of financial expressions that the caller can access on this claim.
• If there are no restrictions placed on the caller, then this is the full set of expressions supported by the given
instance of ClaimCenter.
• If there are restrictions placed on the caller, then this will be the subset of expressions that caller can access on that
claim. For more information, see “Restricting access to financial calculation expressions” on page 337.
The following is an example of executing this endpoint on a sample data claim as super user su.
Request

GET /claim/v1/claims/demo_sample:1/financial-calculations?fields=name

Response

{
"count": 16,
"data": [
{
"attributes": {

328 Financial calculations

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"name": "PendingApprovalErodingPayments"
}
},
{
"attributes": {
"name": "PendingApprovalNonErodingPayments"
}
},
{
"attributes": {
"name": "PendingApprovalPayments"
}
},
...

The base configuration of Cloud API supports the following financial expressions:
• AvailableReserves
• FuturePayments
• GrossTotalIncurred
• OpenRecoveryReserves
• OpenReserves
• PendingApprovalErodingPayments
• PendingApprovalNonErodingPayments
• PendingApprovalPayments
• PendingApprovalReserves
• RemainingReserves
• TotalIncurredNetRecoveries
• TotalIncurredNetRecoveryReserves
• TotalPayments
• TotalRecoveries
• TotalRecoveryReserves
• TotalReserves
You can configure Cloud API to expose additional financial expressions. This includes expressions in the base
configuration of ClaimCenter that are not exposed in the base configuration of Cloud API, as well as custom
expressions. For more information, see the Cloud API Developer Guide.
There is also a GET /claim/v1/claims/{claimId}/financial-calculations/{expression} endpoint. This
endpoint returns only the name of the expression. It must exist for technical reasons, but there is usually no practical
reason for a caller application to use it.

Retrieving financial calculations

Use the following endpoint to retrieve a financial calculation for a claim.
• POST /claim/v1/claims/{claimId}/financial-calculations/{expression}/get-amount
The value of {expression} must be the name of a financial expression returned by the GET /claim/v1/claims/
{claimId}/financial-calculations endpoint.

The response always includes the following:

• The name of the expression
• The result of the calculation in the claim's currency (claimAmount)
• The result of the calculation in the reporting currency (reportingAmount)

Financial calculations 329

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

The response also includes the result of the calculation in the reserve currency (reservingAmount) if the expression is
related to reserves and the request filters out all but one currency.
Additional fields might be included if the response was filtered. For more information, see “Calculations that filter
transactions” on page 330.

Calculations that include all relevant transactions

By default, calls to the /get-amount endpoint execute the calculation over all relevant transactions.
For example, suppose you have claim cc:101 with the following transactions:

Exposure CostType CostCategory Currency Amount

cc:1 ClaimCost Auto body USD $2500
cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

Then, suppose you execute the following request.

Command

POST /claim/v1/claims/cc:101/financial-calculations/AvailableReserves/get-amount

Request

<no request body>

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "3250.00",
"currency": "usd"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "3250.00",
"currency": "usd"
}
},
...

The request was unfiltered. Therefore, all three transactions were included in the calculation.

Calculations that filter transactions

The /get-amount endpoint can optionally have a request body. The body can specify filtering criteria. When a body is
included, the result is based on only the transactions that meet the filtering criteria.
For example, suppose you have claim cc:101 with the following transactions:

Exposure CostType CostCategory Currency Amount

cc:1 ClaimCost Auto body USD $2500
cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

Then, suppose you execute the following request.

Command

POST /claim/v1/claims/cc:101/financial-calculations/AvailableReserves/get-amount

330 Financial calculations

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Request body
{
"data": {
"attributes": {
"costType": {
"code": "claimcost"
}
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "2750.00",
"currency": "usd"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "2750.00",
"currency": "usd"
}
},
...

This request filtered out all transactions except for those whose costType was claimcost. This included the first
($2500) and third ($250), but not the second ($500). Thus, the amount is $2750.

Transaction filtering options

You can filter a financial calculation on the following criteria. You can specify multiple criteria, but you can specify
only one value per criteria. Transactions must meet all criteria in order to be included in the calculation.
• Specific exposure only (or claim-level only)
• Claim cost
• Cost category
• Reserving currency
• Recovery category

Transaction filtering syntax

The complete syntax for specifying the filtering options is as follows.
{
"data": {
"attributes": {
"claimLevel": true,
"exposure": {
"id": "<exposureId>"
},
"costType": {
"code": "<costTypeCode>"
},
"costCategory": {
"code": "<costCategoryCode>"
},
"reservingCurrency": {
"code" : "<currencyCode>"
},
"recoveryCategory": {
"code" : "<recoveryCategoryCode>"
}
}
}
}

For examples of how to use each option, see “Filtering transaction examples” on page 332.

Financial calculations 331

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Filtering transaction examples

The complete syntax for specifying the filtering options is as follows.
{
"data": {
"attributes": {
"claimLevel": true,
"exposure": {
"id": "<exposureId>"
},
"costType": {
"code": "<costTypeCode>"
},
"costCategory": {
"code": "<costCategoryCode>"
},
"reservingCurrency": {
"code" : "<currencyCode>"
},
"recoveryCategory": {
"code" : "<recoveryCategoryCode>"
}
}
}
}

Example: Only claim-level transactions

The claimLevel property can be used to filter out all exposure-level transactions. By default, the claimLevel property
is false. The body needs to include claimLevel only when setting it to true. Also, you cannot set claimLevel to true
if you include the exposure property.
When you explicitly set the claimLevel property, it is included in the response.
Claim cc:202 transactions

Exposure CostType CostCategory Currency Amount

(claim level) ClaimCost Other USD $400
cc:1 ClaimCost Auto body USD $2500
cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

Command

POST /claim/v1/claims/cc:202/financial-calculations/AvailableReserves/get-amount

Request body
{
"data": {
"attributes": {
"claimLevel": true
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "400.00",
"currency": "usd"
},
"claimLevel": true,
"name": "AvailableReserves",
"reportingAmount": {
"amount": "400.00",
"currency": "usd"
}

332 Financial calculations

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
...

Example: Only one exposure

The exposure property can be used to filter out all transactions except for those related to the specified exposure. The
property must be set to the ID of an exposure on the claim.
When you explicitly set the exposure property, information about the exposure is included in the response. If the body
includes the exposure property, it cannot set claimLevel to true.
Claim cc:202 transactions

Exposure CostType CostCategory Currency Amount

(claim level) ClaimCost Other USD $400
cc:1 ClaimCost Auto body USD $2500
cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

Command

POST /claim/v1/claims/cc:202/financial-calculations/AvailableReserves/get-amount

Request body
{
"data": {
"attributes": {
"exposure": {
"id": "cc:1"
}
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "3000.00",
"currency": "usd"
},
"exposure": {
"displayName": "(1) 1st Party Vehicle - Ray Newton",
"id": "cc:1",
"type": "Exposure",
"uri": "/claim/v1/claims/cc:202/exposures/cc:1"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "3000.00",
"currency": "usd"
}
},

Example: Only one CostType

You can use the costType property to filter transactions based on cost type. costType must be set to a valid typecode
from the CostType typelist.
When you explicitly set the costType property, it is included in the response.
Claim cc:202 transactions

Exposure CostType CostCategory Currency Amount

(claim level) ClaimCost Other USD $400

Financial calculations 333

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

cc:1 ClaimCost Auto body USD $2500

cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

Command

POST /claim/v1/claims/cc:202/financial-calculations/AvailableReserves/get-amount

Request body
{
"data": {
"attributes": {
"costType": {
"code": "ClaimCost"
}
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "3150.00",
"currency": "usd"
},
"costType": {
"code": "claimcost",
"name": "Claim Cost"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "3150.00",
"currency": "usd"
}
},

Example: Only one CostCategory

You can use the costCategory property to filter transactions based on cost category. costCategory must be set to a
valid typecode from the CostCategory typelist.
When you explicitly set the costCategory property, it is included in the response.
Claim cc:202 transactions

Exposure CostType CostCategory Currency Amount

(claim level) ClaimCost Other USD $400
cc:1 ClaimCost Auto body USD $2500
cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

Command

POST /claim/v1/claims/cc:202/financial-calculations/AvailableReserves/get-amount

Request body
{
"data": {
"attributes": {
"costCategory": {
"code": "body"
}
}
}
}

334 Financial calculations

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "2500.00",
"currency": "usd"
},
"costCategory": {
"code": "body",
"name": "Auto body"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "2500.00",
"currency": "usd"
}
},

Example: Only one currency

You can use the reservingCurrency property to filter transactions based on reserving currency. reservingCurrency
must be set to a valid typecode from the Currency typelist.
When you explicitly set the reservingCurrency property, it is included in the response.
Claim cc:303 transactions

Exposure CostType CostCategory Currency Amount

(claim level) ClaimCost Other USD $400
cc:1 ClaimCost Auto body EUR $2500
cc:1 Expense - A&O Vehicle inspection EUR $500
cc:22 ClaimCost Medical payments USD $250

Command

POST /claim/v1/claims/cc:303/financial-calculations/AvailableReserves/get-amount

Request body
{
"data": {
"attributes": {
"reservingCurrency": {
"code": "USD"
}
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "650.00",
"currency": "usd"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "650.00",
"currency": "usd"
},
"reservingAmount": {
"amount": "650.00",
"currency": "usd"
},
"reservingCurrency": {
"code": "usd",
"name": "USD"
}
},

Financial calculations 335

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Example: Only one Recovery Category

You can use the recoveryCategory property to filter transactions based on recovery category. recoveryCategory
must be set to a valid typecode from the RecoveryCategory typelist.
When you explicitly set the recoveryCategory property, it is included in the response.
Claim cc:303 transactions

Exposure CostType CostCategory Recovery Category Currency Amount

cc:1 ClaimCost Auto body n/a USD $2500
cc:1 Expense - A&O Vehicle inspection n/a USD $500
cc:1 ClaimCost Auto body Salvage USD $1200

Command
Note that unlike the other examples, which used the AvailableReserves expression, this example is using the
OpenRecoveryReserves expression.

POST /claim/v1/claims/cc:303/financial-calculations/OpenRecoveryReserves/get-amount

Request body
{
"data": {
"attributes": {
"recoveryCategory": {
"code" : "salvage"
}
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "1200.00",
"currency": "usd"
},
"name": "OpenRecoveryReserves",
"recoveryCategory": {
"code": "salvage",
"name": "Salvage"
},
"reportingAmount": {
"amount": "1200.00",
"currency": "usd"
}
},

Example: Multiple filter criteria

A single request can include multiple filter criteria. For example, the following request gets the available reserves for
exposure cc:1 where CostType is claimcost.
Claim cc:202 transactions

Exposure CostType CostCategory Currency Amount

(claim level) ClaimCost Other USD $400
cc:1 ClaimCost Auto body USD $2500
cc:1 Expense - A&O Vehicle inspection USD $500
cc:22 ClaimCost Medical payments USD $250

336 Financial calculations

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /claim/v1/claims/cc:202/financial-calculations/AvailableReserves/get-amount

Request body
{
"data": {
"attributes": {
"exposure": {
"id": "cc:1"
},
"costType": {
"code": "claimcost"
}
}
}
}

Response
{
"data": {
"attributes": {
"claimAmount": {
"amount": "2500.00",
"currency": "usd"
},
"costType": {
"code": "claimcost",
"name": "Claim Cost"
},
"exposure": {
"displayName": "(1) 1st Party Vehicle - Ray Newton",
"id": "cc:1",
"type": "Exposure",
"uri": "/claim/v1/claims/cc:202/exposures/cc:1"
},
"name": "AvailableReserves",
"reportingAmount": {
"amount": "2500.00",
"currency": "usd"
}
},

Restricting access to financial calculation expressions

As is the case with any endpoint, you can control which callers have access to the /financial-calculations
endpoint through endpoint access. You can also control which callers can access a given claim through resource access.
However, once a caller has access to a given claim and the /financial-calculations/{expression}/get-amount
endpoint, you might not want to give them the ability to perform every type of financial calculation that potentially
includes any or all of the claim's transactions. For example, you might have the following requirements:
• An insured can see total payments for a claim, but not access reserve information.
• A third-party claimant can see total payments only for exposures where they are claimant for the exposure.
To enforce these types of requirements, you can specify additional access logic for financial calculations.

The base configuration restrictions

The base configuration includes the following restrictions:
• Internal users and services can access all financial calculations.
• External users using either the contactAuthorizationIDs resource access strategy or the producerCodes resource
access strategy can access only the TotalPayments expression, and only when filtering by a costType of
claimcost. Broadly speaking:

◦ An insured or a producer can see total claimcost payments for the claim without further restrictions.
◦ A claimant who is not an insured can see total claimcost payments only for the exposures where they are the
claimant.

Financial calculations 337

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• External users using any other resource access strategy (such as vendors) cannot access any financial calculations.

Configuring access to financial calculation expressions

For more information on the base configuration restrictions, and for how to modify these restrictions or add additional
ones, see the Cloud API Developer Guide.

338 Financial calculations

chapter 27

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 339
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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",

340 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"currency": "gbp"
},
"transactionAmount": {
"amount": "1000.00",
"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 341
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}
}

Exchange rate information for transactions

In a multicurrency instance of ClaimCenter, ClaimCenter uses foreign exchange rates to convert amounts between the
various currencies a claim may use. Every transaction stores two fundamental pieces of information about the exchange
rates:
• The rate itself (a numeric value, such as 1.2)
• The type of rate (such as market or corporate)

Exchange rate schemas

The ExchangeRate data model
For ClaimCenter releases up to and including 2024.07 (Kufri), ClaimCenter had a single data model for storing
exchange rates - the ExchangeRate data model . This includes the ExchangeRate and ExchangeRateSet entities.
Exchange rates stored in these entities are not part of the Claim graph.
Exchange rates in the ExchangeRate data model could be one of two types. The type of rate is specified on the
ExchangeRateSet entity. It has a MarketRates Boolean field.

• When set to true, the rate to be used is a "market rate". It is fetched automatically.
• When set to false, the rate is a "custom rate". It must be stated explicitly.
The ExchangeRateInUse data model
For ClaimCenter releases 2024.11 (Las Leñas) and after, ClaimCenter has two data models for storing exchange rates.
ClaimCenter continues to have the ExchangeRate data model, and this is used to manage exchange rates created before
Las Leñas. But there is also a second data model, the ExchangeRateInUse data model.
The ExchangeRateInUse data model includes a number of tables whose name ends in "ExchangeRateInUse", such as
ClaimToReportingExchangeRateInUse. All of the entities delegate to the ExchangeRateInUseDelegate delegate,
which implements the FXRate interface. Exchange rates stored in these entities are a part of the Claim graph.
The type of rate is specified in the ExchangeRateInUseDelegate delegate and therefore is part of every entity in the
data model. It is specified by a Market field which is a typekey to the FXRateMarket typelist. In the base configuration,
this typefield includes three typecodes: market, corporate, and manual.
For information on how to configure which data model ClaimCenter uses for newly created exchange rates, refer to the
Configuration Guide.
Cloud API compatibility with exchange rate data models
To support both approaches to storing exchange rate data, as of 2024.11 (Las Leñas), Cloud API for ClaimCenter has
two schemas for exchange rates:
• TransactionExchangeRate, which captures exchange rate type information for exchange rates stored in the
ExchangeRate data model.
• ExchangeRateInUse, which captures exchange rate type information for exchange rates stored in the
ExchangeRateInUse data model.
Both schemas have a rate field to identify the rate and a market field to identify the rate type.
• In the TransactionExchangeRate schema, the market field is a Boolean.
• In the ExchangeRateInUse schema, the market field is a typekey field whose values are set to typecodes from the
FXRateMarket typelist

Both schemas are referenced by the Transaction schema. There are three pairs of fields. The fields start with the same
name, but the fields that use the ExchangeRateInUse schema end in "InUse".

342 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• The following fields use the TransactionExchangeRate schema:

◦ claimToReportingExchangeRate
◦ transToClaimExchangeRate
◦ transToReservingExchangeRate
• The following fields use the ExchangeRateInUse schema:
◦ claimToReportingExchangeRateInUse
◦ transToClaimExchangeRateInUse
◦ transToReservingExchangeRateInUse

Exchange rate schemas and GETs

Whenever you GET transaction information, for each transaction, Cloud API uses the schema that corresponds to the
data model used to store the transaction. For more information on how ClaimCenter determines which model to use,
refer to the Configuration Guide.
Note that it is technically possible for a single claim to have transactions that use different exchange rate schemas.

Exchange rate schemas and POSTs

Whenever you POST transaction information on an instance on or before 2024.07 (Kufri), the request object must
adhere to the TransactionExchangeRate schema.
Whenever you POST transaction information on an instance on or after 2024.11 (Las Leñas), the request object must
adhere to the schema that corresponds to the current setting of the UseDepricatedExchangeRates application
configuration parameter. Thus:
• If UseDepricatedExchangeRates is set to true, the request object must adhere to the TransactionExchangeRate
schema.
• If UseDepricatedExchangeRates is set to false, the request object must adhere to the ExchangeRateInUse
schema.
The following request payload is an example of creating a transaction while UseDepricatedExchangeRates is set to
true. The exchange rate information is in bold.

Command

POST /claims/cc:61/reserve-sets

Request

{
"data": {
"attributes": {
"reservesToWrite": [
{
"claimToReportingExchangeRate": {
"market": true,
"rate": "1.2"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:79"
},
"reservingCurrency": {
"code": "usd"
},
"transToClaimExchangeRate": {
"market": true,
"rate": "1.2"
},
"transToReservingExchangeRate": {

Multicurrency 343
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"market": true,
"rate": "1.2"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "1000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

The following request payload is an example of creating a transaction while UseDepricatedExchangeRates is set to
false. The exchange rate information is in bold.

Command

POST /claims/cc:61/reserve-sets

Request

{
"data": {
"attributes": {
"reservesToWrite": [
{
"claimToReportingExchangeRateInUse": {
"market": {
"code": "market"
},
"rate": "1.2"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:79"
},
"reservingCurrency": {
"code": "usd"
},
"transToClaimExchangeRateInUse": {
"market": {
"code": "market"
},
"rate": "1.2"
},
"transToReservingExchangeRateInUse": {
"market": {
"code": "market"
},
"rate": "1.2"
}
},
"lineItems": [
{
"transactionAmount": {
"amount": "1000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

344 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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).

Multicurrency 345
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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": {

346 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"code": "claimcost"
},
"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"
},

Multicurrency 347
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},
"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.

348 Multicurrency
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ 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.
◦ 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": {

Multicurrency 349
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"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.

350 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
◦ “Activities”
◦ “Documents”
◦ “Notes”
◦ “History events” on page 401
◦ “Typelist metadata” on page 403
• The Admin API
◦ “Users and groups”
◦ “Security zones”
◦ “Geographic zones” on page 399
◦ “Batch processes”
◦ “Database consistency checks”
◦ “Business entity schemas”
◦ “Testing”

Business flows: Framework APIs 351

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

352 Business flows: Framework APIs

chapter 28

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. Additionally, Cloud API can be used to perform
other actions with activities, such as assigning them, approving them, skipping them, and creating notes on them.
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).
Use the following endpoints to GET activities.

Endpoint Returns
/common/v1/activities By default, all activities the caller can access based on the relevant Access Control Lists (ACLs). (For
more information on the default behavior, see the note at the end of this table.) This endpoint also
has special assignedUser and assignedUsername filters. For more information, see “The
assignedUser filters” on page 54.
/common/v1/activities/ The activity with the given ID.
{activityId}

Activities 353
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Endpoint Returns
/claim/v1/claims/ All activities associated with the given claim. This endpoint also has special assignedUser and
{claimId}/activities assignedUsername filters. For more information, see “The assignedUser filters” on page 54.

Note: By default, internal users who are calling the /common/v1/activities endpoint can view all activities
they have permission to access according to their Access Control Lists. This behavior is controlled by the
GiveInternalUsersFullPermissionsInCommonActivitiesApi application configuration parameter, which is
set to true by default. When it is set to false, internal users can view only activities that are explicitly assigned
to them.
Note that the endpoints to retrieve activities exist in different APIs. To get all activities for a claim, you use an endpoint
in the Claim API. But to get information about all activities (regardless of parent), or to get information about a
specific activity, you use endpoints in the Common API.
For example, the following query retrieves the IDs and subjects of all activities for account demo_sample:1. This
endpoint is in the Claim API.
Request

GET claim/v1/claims/demo_sample:1/activities?fields=id,subject

Response

{
"count": 14,
"data": [
{
"attributes": {
"id": "cc:23218",
"subject": "Contact insured"
}
},
{
"attributes": {
"id": "cc:40404",
"subject": "Determine fault rating"
}
},
...

The following query retrieves activity cc:40404 in detail. This endpoint is in the Common API.
Request

GET /common/v1/activities/pc:40404

Response

{
"data": {
"attributes": {
"activityPattern": "general_reminder",
"activityType": {
"code": "general",
"name": "General"
},
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1",
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
},
"assignmentStatus": {
"code": "assigned",
"name": "Assigned"
},
"createTime": "2023-11-18T02:00:20.481Z",
"dueDate": "2023-11-07T00:00:00.000Z",
"escalated": false,
"externallyOwned": false,

354 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"id": "cc:40404",
"importance": {
"code": "notOnCalendar",
"name": "Not On Calendar"
},
"mandatory": false,
"priority": {
"code": "normal",
"name": "Normal"
},
"recurring": false,
"relatedTo": {
"displayName": "Ray Newton",
"id": "cc:SW8RXsrWJZiKa7jfCEAYr",
"type": "ClaimContact",
"uri": "/claim/v1/claims/demo_sample:1/contacts/cc:SW8RXsrWJZiKa7jfCEAYr"
},
"status": {
"code": "open",
"name": "Open"
},
"subject": "Determine fault rating"
},
...

Creating activities
Activities must be created from an existing claim using the following endpoint:
• POST claim/v1/claims/{claimId}/activities

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

Activities 355
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Field Datatype Description Default

subject String The activity's subject Typically comes from the activity
pattern

AutomatedOnly activity patterns

Activity patterns have an AutomatedOnly field. This field designates whether or not a user can create activities through
the user interface using that activity pattern.
• false - users can create activities with this activity pattern through the user interface
• true - users cannot create activities with this activity pattern through the user interface
When a caller attempts to create an activity through Cloud API, the default behavior is to prohibit the use of any
activity pattern whose AutomatedOnly field is set to true.
There is a system permission named restcreateautomatedactivity that can be used to override this behavior. If a
caller has some association with this permission, then that caller can create activities from AutomatedOnly activity
patterns. There are two ways this association can exist.
For more information on how to associate this permission with different types of callers, see Cloud API Developer
Guide.

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.
Command

POST /claim/v1/claims/cc:102/activities

Request

{
"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.
Command

POST /claim/v1/claims/cc:102/activities

Request

{
"data": {
"attributes": {
"activityPattern": "legal_review",
"mandatory": true,
"priority": {
"code": "urgent"
}
}
}
}

Assigning activities
Ultimately, every activity is assigned to a group and a user in that group. This user is primarily responsible for closing
the activity.

356 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
Command

POST /common/v1/activities/xc:1/assign

Request body

{
"data": {
"attributes": {
"groupId": "demo_sample:31",
"userId": "demo_sample:1"
}
}
}

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.

Activities 357
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

POST /common/v1/activities/xc:1/assign

Request body

{
"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.
Command

POST /common/v1/activities/xc:1/assign

Request body

{
"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.
Command

POST /common/v1/activities/xc:1/assign

Request body

{
"data": {
"attributes": {
"queueId": "cc:32"
}
}
}

Using automated assignment

The following payload assigns activity xc:1 using automated assignment rules.
Command

POST /common/v1/activities/xc:1/assign

Request body

{
"data": {
"attributes": {
"autoAssign": true
}
}
}

358 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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
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.
Command

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.

Activities 359
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
Command
POST /common/v1/activities/xc:1/complete

Request body

<no request payload>

The following payload completes activity xc:1 and creates a note.

Command

POST /common/v1/activities/xc:1/complete

Request body

{
"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.
Command

POST /common/v1/activities/xc:1/skip

Request body

<no request payload>

The following payload skips activity xc:1 and creates a note.

Command

POST /common/v1/activities/xc:1/skip

360 Activities
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Request body

{
"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 123.
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.
The following payload approves activity xc:2.
Command
POST /common/v1/activities/xc:2/approve

Request body

<no request payload>

The following payload approves activity xc:2 with an approval rationale.

Command
POST /common/v1/activities/xc:2/approve

Request body

{
"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.

Activities 361
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command
POST /common/v1/activities/xc:2/approve

Request body

{
"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 373.

362 Activities
chapter 29

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 law enforcement agencies,
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 363
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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.

docUIDs and pendingDocUIDs

When a document is stored in a document management system, it is assigned a DOCument Unique IDentifier, or
docUID. This value can be set through Cloud API when the document is POSTed. Some document management
systems may modify the docUID of an existing document. Therefore, Cloud API also supports the ability to change
docUIDs in PATCHes.
In some cases the document is not immediately stored in the document management system. In a document's metadata,
there is an optional field pendingDocUID which indicates if a document is pending storage. It might be generated by
the document management system, or it can be set in the request when the document is POSTed or PATCHed. A
document cannot have both a pendingDocUID and a docUID. For more, see “POSTing documents” on page 365.

Querying for document information

Querying for document metadata
Use the following endpoints to retrieve document metadata.

Endpoint Returns
GET /common/v1/documents/ Metadata for the given document
{documentId}
GET /claim/v1/claims/{claimId}/ Metadata for documents on the given claim
documents
This is a "potentially large" endpoint. Cloud API returns an error if you attempt to sort
on this endpoint and the sort cannot be accomplished efficiently. For more
information, see “Potentially large endpoints” on page 56.
GET /claim/v1/claims/{claimId}/ Metadata for the given document
documents/{documentId}

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.
Command
GET /common/v1/documents/xc:101

Response

{
"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"

364 Documents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
},
...

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.
• GET /common/v1/documents/{documentId}/content
• GET /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.
Command
GET /common/v1/documents/xc:101/content

Response

RESPONSE:
{
"data": {
"attributes": {
"contents": "REVWIEJVSUxEDQoNCklmIHRoZXJlIGlzIG9ubHkgYSB2aXN1YWxp
emVkIHByb2R1Y3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzIGlua
XRpYWxseSBzZXQgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRGlzYW
JsZWQNCiAgVEhFTiB0aGUgcHJvZHVjdCBpcyBpbW1lZGlhdGVseSB1bmF2YWlsYWJsZSB0byB0aGU
gc3lzdGVtIEFQSXMNCg0KSWYgdGhlcmUgaXMgYSB2aXN1YWxpemVkIHByb2R1Y3QgYW5kIGEgZmlu
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:
• POST /claim/v1/claims/{claimId}/documents
• (ContactManager) POST /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 has 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 typically sends 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 has 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)

Documents 365
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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. In some use cases, it can be omitted.

Use cases for POSTing document information

There are several ways that a caller application can POST document information:
• You can POST information about a document that is not yet in the document management system.
• You can POST information about a document that is already in the document management system but is not yet
known to ClaimCenter.
• You can POST information about a document that will never be in the document management system (such as a
physical piece of paper that must be tracked by ClaimCenter).

POSTing a document that is not yet in the document management system

You can POST a document that is not yet in the document management system. In this approach:
• You provide both document content and document metadata.
• 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).
The following is an example of POSTing a "Property Assessment [Link]" file for claim cc:102 that does not yet
exist in the document management system.
Command
POST /claim/v1/claims/cc:102/documents

Request body

METADATA:
{
"data": {
"attributes": {
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}

CONTENTS:
<contents of "Property Assessment [Link]" file>

POSTing a document that is already in the document management system

You can POST a document that is already in the document management system. In this approach:
• You must know the ID assigned to the document in the document management system.
• You provide document metadata only. The metadata must specify the ID from the document management system in
the docUID field.
• The integration point links the new document metadata to the document in the document management system.

366 Documents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

The following is an example of POSTing a "Property Assessment [Link]" file for claim cc:102 that does exist in
the document management system with id "doc:11-31".
Command
POST /claim/v1/claims/cc:102/documents

Request body

METADATA:
{
"data": {
"attributes": {
"docUID": "doc:11-31",
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}

CONTENTS:
<no content specified>

If a POST /documents call needs to specify document metadata only, it can be executed using a request body that is
formatted as JSON (as opposed to FormData). For more information, see “Sending document metadata only using
JSON” on page 370.
POSTing a document that will never be in the document management system
You can POST information about a document that will never be in the document management system (such as a
physical piece of paper that must be tracked by ClaimCenter). In this approach:
• You provide document metadata only.
• There is no information stored in the document management system.
The following is an example of POSTing a "Printout of email from auto dealership" document for claim cc:102 that is a
physical piece of paper that ClaimCenter must track.
Command
POST /claim/v1/claims/cc:102/documents

Request body

METADATA:
{
"data": {
"attributes": {
"name": "Printout of email from auto dealership",
"status": {
"code": "final"
},
"type": {
"code": "letter_received"
}
}
}
}

CONTENTS:
<no content specified>

If a POST /documents call needs to specify document metadata only, it can be executed using a request body that is
formatted as JSON (as opposed to FormData). For more information, see “Sending document metadata only using
JSON” on page 370.
Errors to avoid when POSTing documents
When POSTing documents, note the following guidelines:

Documents 367
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• Sending the content FormData parameter without the metadata FormData parameter results in an error.
• Uploading documents of an unsupported MIME type results in an error.
• When working with the docUID and pendingDocUID fields, avoid the following to prevent errors:
◦ Including both the docUID and the pendingDocUID in a document's metadata
◦ Including the docUID property or the pendingDocUID property when including the content parameter in the
post
◦ Setting the dms property to true and including the pendingDocUID field
◦ Setting the status to final and including the pendingDocUID field

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.

368 Documents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

PATCHing documents
Use the following to PATCH documents:
• PATCH /common/v1/documents/{documentId}
• PATCH /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 only metadata

If you want to PATCH only the metadata of a document, your call must specify the new metadata, but it can omit
information about the content.
You can submit the call as a FormData object. For example, the following call updates the metadata for document xc:
127.
Command
PATCH /common/v1/documents/xc:127

Request body

METADATA:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}

(No contents included with the call)

You can also submit a metadata-only PATCH using a request body that is formatted as JSON (as opposed to
FormData). For more information, see “Sending document metadata only using JSON” on page 370.

PATCHing only content

If you want to PATCH only the content of a document, your call must specify the new content. It must also specify a
metadata key/value, but the value must consist of a body with no specified attributes.

PATCHes to content are destructive, not additive. If you specify content, the new content replaces the previous
content entirely.
For example, the following call updates the entire content for document xc:127 (without changing any of the
metadata).
Command
PATCH /common/v1/documents/xc:127

Request body

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

<contents of "Property Assessment [Link]" file>

Documents 369
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

PATCHing both metadata and content

If you want to PATCH both the metadata and the content of a document, your call must specify the new metadata and
the new content.
PATCHes to content are destructive, not additive. If you specify content, the new content replaces the previous
content entirely.
For example, the following call updates the metadata and the entire content for document xc:127.
Command

PATCH /common/v1/documents/xc:127

Request body

METADATA:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}

<contents of "Property Assessment [Link]" file>

When PATCHing documents, note the following:

• You cannot PATCH documents that have a status of final.
• If a document has a non-null value for pendingDocUID, you cannot specify dms or docUID.

Sending document metadata only using JSON

If a POST /documents or PATCH /documents call needs to specify document metadata only, it can be executed using
a request body that is formatted as JSON. In this case, you do not need to use a FormData object. This applies to the
POST /documents and PATCH /documents endpoints in both ClaimCenter and ContactManager.
For example, the following creates a "Property Assessment [Link]" document for claim cc:102. The document
already exists in the document management system with id "doc:11-31", which means the POST specifies document
metadata only. In this case, the document metadata can be sent in the request body as JSON.
Command
POST /claim/v1/claims/cc:102/documents

Request body
{
"data": {
"attributes": {
"docUID": "doc:11-31",
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}

DELETEing documents
Use the following to DELETE documents:

370 Documents
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• DELETE /common/v1/documents/{documentId}
• DELETE /claim/v1/claims/{claimId}/documents/{documentId}
For example, the following request DELETEs document xc:101:

PATCH /common/v1/documents/xc:101

<no request body>

Documents 371
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

372 Documents
chapter 30

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}/ All notes associated with the given claim
notes
This is a "potentially large" endpoint. Cloud API returns an error if you attempt to sort on
this endpoint and the sort cannot be accomplished efficiently. For more information, see
“Potentially large endpoints” on page 56.
/common/v1/activities/ All notes associated with the given activity
{activityId}/notes

By default, the GET /notes/{noteId} endpoint returns the body field, but the GET /notes endpoints do not. This is
because of the potentially large size of the body field. To prevent overly large payloads, Guidewire recommends that
Notes 373
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

you retrieve the body field only if the body is needed. The body can be retrieved using the ?fields=body query
parameter.
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:
• 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"
}
}
}
}

374 Notes
 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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'.",
"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 375
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

376 Notes
chapter 31

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.
Note: Be aware that Cloud API enforces application constraints specified in internal code, but it does not
enforce constraint specified in the user interface. This is because internal code constraints cannot be modified or
removed, but user interface constraints can. As a result of this, there may be actions you can execute through
Cloud API that you cannot execute through the base configuration user interface.
For example, there is no internal code that requires a user to have a phone number. Therefore, you can create
and modify a user through Cloud API without ever specifying a primary phone number. However, the base
configuration user interface does require you to specify a phone number. Therefore, any user that you modify
through the base configuration user interface must have a phone number, even when that user was created
through Cloud API without a phone number.
If there is a desire to have the constraints of the two environments match, insurers can add constraints to Cloud
API and/or remove them from the user interface.

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).
Users and groups 377
Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Command

GET /admin/v1/users/demo_sample:1

Response

{
"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",
"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"
}
}
}

378 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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"
]
}
}
}
}

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 385.
• For more information on working with authority limit profiles, see “Authority limit profiles” on page 389.

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 381.

Users and groups 379

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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}
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.

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"
}
},

380 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

...
}
}

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
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 381

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:

Users and groups 381

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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
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

382 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

{
"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
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:

Users and groups 383

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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:
• 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
},
...

384 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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
}
}
}

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 356.

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.)

Users and groups 385

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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",
"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"
}
},
...
},
{

386 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"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:
• 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

Users and groups 387

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

{
"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 and
response inclusion” on page 109.
For example, the following call creates a user role with one permission.

POST /admin/v1/roles

{
"data": {
"attributes": {
"roleType": {
"code": "user"
},
"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"
}
}
}

388 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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.
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"
}

Users and groups 389

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
...
}

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": {
"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"
}
}
}
}

390 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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
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.

Users and groups 391

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• 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 and response inclusion” on page 109.
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

{
"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.

392 Users and groups

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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

{
"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 393

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

394 Users and groups

chapter 32

Security zones

A security zone is a set of business objects whose access is restricted to the users in a user group. Security zones are
used to define access to specific sets of business objects.
At a high level, the process of limiting access through security zones is implemented in these steps:
1. A security zone is created.
2. The security zone is associated with a set of business objects, such as accounts, policies, or claims.
3. The security zone is also associated with a user group.
By default, the only users who can view or edit the business objects in the security zone are the users in the group
associated with the security zone.
For example, suppose there is a security zone named "Security Zone A" that contains an account named "Big Lake
Bakery". The "Western Region" group is also added to "Security Zone A". Now, the Big Lake Bakery account can be
viewed and modified only by users who belong to the Western Region group.
The functionality of security zones, including the business objects that can be added to them, varies between
applications. For more information on the business functionality of security zones in ClaimCenter, see the Application
Guide.
The endpoints for working with security zones are available in Cloud API for ClaimCenter, Cloud API for
PolicyCenter, and Cloud API for BillingCenter. They are not available in Cloud API for ContactManager.

Querying for security zones

Use the following endpoints to query for security zones:
• GET /admin/v1/security-zones
• GET /admin/v1/security-zones/{securityZoneId}
For example, the following request retrieves information about security zone "default_data:1".
GET /admin/v1/security-zones/default_data:1

{
"data": {
"attributes": {
"description": "Default Security Zone",
"displayName": "Default Security Zone",
"id": "default_data:1",
"name": "Default Security Zone"
},
...

Security zones 395

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Creating security zones

Use the following endpoint to create a security zone:
• POST /admin/v1/security-zones
The only required field is the zone name.
For example, the following request creates a new security zone named "Cloud API security zone".
POST /admin/v1/security-zones/

{
"data": {
"attributes": {
"name": "Cloud API security zone"
}
}
}

Note that there are differences between security zone functionality in the base configuration of the different
applications.
• In ClaimCenter and BillingCenter, users can create security zones. This is done from the Admin tab's Security Zones
screen in the Users & Security group.
• In PolicyCenter, users cannot create security zones. (There is no Security Zones screen.) However, users can import
security zones through the Import Administrative Data screen in the Utilities group.

Modifying and deleting security zones

Modifying security zones
Use the following endpoints to modify a security zone:
• PATCH /admin/v1/security-zones/{securityZoneId}
For example, the following request modifies security zone xc:111.

PATCH /admin/v1/security-zones/xc:111

{
"data": {
"attributes": {
"description": "Security zone created using Cloud API"
}
}
}

Note that there are differences between security zone functionality in the base configuration of the different
applications.
• In ClaimCenter and BillingCenter, users can edit security zones. This is done from the Admin tab's Security Zones
screen in the Users & Security group.
• In PolicyCenter, users cannot edit security zones.

Deleting security zones

In ClaimCenter, use the following endpoints to delete a security zone:
• DELETE /admin/v1/security-zones/{securityZoneId}
For example, in ClaimCenter, the following request deletes security zone xc:111.

DELETE /admin/v1/security-zones/xc:111

<no request body>

396 Security zones

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

In PolicyCenter and BillingCenter, users cannot delete security zones, either through the user interface or through
Cloud API. The DELETE /security-zones/{securityZoneId} endpoint is exposed in Cloud API for PolicyCenter
and Cloud API for BillingCenter. But if you attempt to use it, Cloud API returns the following error. This is true even
for the super user "su", who is not bound by permissions.

{
"status": 403,
"errorCode": "[Link]",
"userMessage": "You do not have permission to delete this resource"
}

Associating security zones with other objects

To associate a security zone with a business object or group, specify the security zone in either a POST or a PATCH.
For example, the following request PATCHes BillingCenter account bc:101 so that it is associated with security zone
bc:222.
PATCH /billing/v1/accounts/bc:101

{
"data": {
"attributes": {
"securityZone": {
"id": "bc:222"
}
}
}
}

Similarly, the following request PATCHes BillingCenter group bc:555 so that it is associated with security zone bc:222.
PATCH /admin/v1/groups/bc:555

{
"data": {
"attributes": {
"securityZone": {
"id": "bc:222"
}
}
}
}

As a result of the two queries in the previous examples, account bc:101 is now restricted to only users in group bc:555.

Support for security zones in Cloud API business objects

In order to associate a business object with a security zone, the corresponding Cloud API resource must have a
securityZone field. For each InsuranceSuite application, there may be business object that can be associated with
security zones, but the corresponding resource in Cloud API does not have a securityZone field. In these
circumstances, you can extend the resource to include the securityZone field. For information, see the Cloud API
Developer Guide.

Security zones 397

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

398 Security zones

chapter 33

Geographic zones

The geographic zone endpoint is used to retrieve information about a predefined geographic region. That information
can then be associated with InsuranceSuite features where a geographic region is needed.
Geographic zone endpoint:
GET /admin/v1/geographic-zones
GET is the only method available for geographic zones; you cannot add, update, or delete geographic zones through
the Cloud API.
The base configuration of InsuranceSuite includes over 1,000 geographic zones, so Guidewire provides several fields
you can filter on to make retrieving geographic zones more efficient.
Filters:
• id: The unique ID of the zone.
• country: The typecode for the country you want to filter on. Use the Country typekey to find available country
codes:
GET /common/v1/typelists/Country?fields=typeKeys
• zoneType: A typekey that varies by country. For example, if the country is US (United States) the zoneType could
be state, whereas a country value of CA (Canada) could have a zoneType of province. Use the ZoneType typekey
to find available zone types:
GET /common/v1/typelists/ZoneType?fields=typeKeys
• code: A value associated with the zoneType. For example, if the zoneType is state, the code could be OR
(Oregon).
This example retrieves information for the geographic zone that includes the U.S. state of Oregon:

GET /admin/v1/geographic-zones?filter=country:eq:US&filter=zoneType:eq:state&filter=code:eq:OR

{
"count": 1,
"data": [
{
"attributes": {
"code": "OR",
"country": {
"code": "US",
"name": "United States"
},
"displayName": "OR",
"id": "US:S4MEjnBYkBZqD_nWzarTl",
"name": "OR",

Geographic zones 399

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"zoneType": {
"code": "state",
"name": "State"
}
},
...
}

Here’s another example, this time with a broader search. This example will return a list of all provinces in Canada:

GET /admin/v1/geographic-zones?filter=country:eq:CA&filter=zoneType:eq:province

{
"data": [
{
"attributes": {
"code": "BC",
"country": {
"code": "CA",
"name": "Canada"
},
"displayName": "BC",
"id": "CA:SNAwbKcTW2uiIdv0FGcd0",
"name": "BC",
"zoneType": {
"code": "province",
"name": "Province"
}
},
},
{
"attributes": {
"code": "NL",
"country": {
"code": "CA",
"name": "Canada"
},
"displayName": "NL",
"id": "CA:SGVv0UjgB0_EJCt80VU1K",
"name": "NL",
"zoneType": {
"code": "province",
"name": "Province"
}
},
...

400 Geographic zones

chapter 34

History events

When certain events occur in InsuranceSuite they are automatically recorded. Each history event is stored as a
CustomHistory type. You can retrieve these history events by using the history-events endpoint.
• GET /common/v1/history-events/{historyEventId}
• GET /claims/{claimId}/history-events
The following sections provide examples of these endpoints.

Retrieve a single history event

You can retrieve a single history event by using the history-events endpoint in the common API. To use this
endpoint you must first retrieve the historyEventId from the history-events endpoint on the relevant object, such
as the contacts object in the ContactManager Contact API. (For more information on the Contact API, see “History
events” for ContactManager.)
The information retrieved in this example is from an account change history event where the account changed from
pending to active.
Command

GET /common/v1/history-events/S-d_RRz9cG9bhqcfVN2xC

Response

{
"data": {
"attributes": {
"account": {
"displayName": "C000478975",
"id": "SaDgS3XDMmUlTYlw-HNoI",
"type": "Account",
"uri": "/account/v1/accounts/SaDgS3XDMmUlTYlw-HNoI"
},
"customType": {
"code": "acct_changed",
"name": "Account changed"
},
"description": "Pending account became active",
"eventTimestamp": "2024-06-03T23:03:05.992Z",
"historyType": {
"code": "custom",
"name": "Custom"
},
"id": "SJj0sm_oXm7aZUXrKuWxF",
"user": {
"displayName": "Super User",
"id": "default_data:1",
"type": "User",

History events 401

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"uri": "/admin/v1/users/default_data:1"
}
},
…
}

Retrieve claim history events

Claim history events record events associated with a claim, even minor events, such as when a claim is viewed. For
example:
Command

GET /claim/v1/claims/cc:439/history-events

Response

{
"count": 7,
"data": [
{
"attributes": {
"description": "Reserve of $500.00 created",
"eventTimestamp": "2024-11-18T22:00:43.109Z",
"historyType": {
"code": "reservecreated",
"name": "Reserve created"
},
"id": "cc:SHNXJQFrqGjZNWSkZEUC-",
"user": {
"displayName": "Super User",
"id": "default_data:1",
"type": "User",
"uri": "/admin/v1/users/default_data:1"
}
},
...
},
...
}
}

402 History events

chapter 35

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 403
Guidewire ClaimCenter for Guidewire Cloud 2024.11 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]

404 Typelist metadata

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

The /business-line-metadata endpoint

In ClaimCenter, the line of business model is a set of typelists that organizes policies, coverages, and covered losses
into a single hierarchy. Collectively, these typelists define the valid types of coverages, incidents, and exposures for a
given policy and type of loss. For more information on the line of business model, see the Configuration Guide.
A caller application may want to access the metadata for these typelists so that it can determine valid coverage and
exposure values for a given claim. This information can be retrieved using the Claim API's /business-line-
metadata endpoint. This endpoint returns the entire line of business model in the following format:

• policyTypes
◦ coverageTypes
▪ coverageSubtypes
▫ exposureType
▫ incidentType
▫ lossPartyType
◦ internalPolicyType
◦ lobCodes
▪ lossType
▫ lossCauses
For example, the following request executed against the base configuration returns the following edited results.
Command
GET /claim/v1/claims/business-line-metadata

Response
{
"policyTypes": [
{
"code": "BusinessOwners",
"coverageTypes": [
{
"code": "BOPReceivablesCov",
"coverageSubtypes": [
{
"code": "BOPReceivablesCov",
"description": "Accounts Receivable",
"exposureType": {
"code": "GeneralDamage",
...
},
"incidentType": {
"code": "Incident",
...
},
"lossPartyType": {
"code": "insured",
...
},
"name": "Accounts Receivable",
"priority": -1,
"sortOrder": 103
}
],
...
},
...
],
"description": "Business Owners",
"internalPolicyType": {
"code": "commercial",
...
},
"lobCodes": [
{
"code": "BOPLine",
"description": "BusinessOwners",

Typelist metadata 405

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"lossType": {
"code": "GL",
"description": "Liability",
"lossCauses": [
{
"code": "animal_bite",
...
},
...
],
"name": "Liability",
"priority": -1,
"sortOrder": 1
},
...
}
],
"name": "Businessowners",
...
## This is the end of the Businessowners policy metadata
},
{
## This is the start of the policy metadata for the Business Auto policy
"code": "BusinessAuto",
...
},
...
]
}

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

Tutorial: Query for typelist metadata

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” 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.)

406 Typelist metadata

chapter 36

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 407

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Querying for batch process information

There are several endpoints that provide information about batch processes. They are summarized in the table below.

Endpoint Description
GET /systemtools/v1/batch-processes Return a list of batch process types. In other words, this identifies all of the batch
processes that could be run.
GET /systemtools/v1/batch- For a given batch process type, return information about the most recent
processes/{batchProcessType} execution of that batch process, if any.
GET /systemtools/v1/batch- For a given batch process type, return information about all previous runs of that
processes/{batchProcessType}/ batch process.
histories
GET /systemtools/v1/batch- For a given batch process type, return information about the run of that batch
processes/{batchProcessType}/ process with the given processHistoryId, which may or may not be the most recent
histories/{processHistoryId} run.

Getting information about the most recent run of a batch process

You can retrieve information about the most recent run of a given batch process. When you do so, 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 about the most recent run, Yes
such as startDate, 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 containing Only if the batch process is distributed
information on the worker status for the batch process.
processId Deprecated. Do not use.
processHistoryId 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 most recent run of 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

408 Batch processes

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

{
"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"
}
},
...

Response for a running batch process

The following is an example of querying for the most recent run of 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 most recent run of the Activity Escalation batch process, but doing so
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"
}
},
...

Getting information about batch process history

You can also retrieve information about all runs of a given batch process, or a specific run of a given batch process,
even when that specific run was not the most recent. This is done using any of the /batch-process/
{batchProcessType}/histories endpoints.

Batch processes 409

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

For example, the following request returns all runs of the Activity Escalation batch process.
Command

GET /batch-processes/ActivityEsc/histories

Response

{
"count": 2,
"data": [
{
"attributes": {
"dateCompleted": "2024-09-19T23:47:34.321Z",
"dateCreated": "2024-09-19T23:47:34.302Z",
"description": "Activity escalation monitor",
"failedOps": 0,
"id": "ab:Swdab0ToBSDtgSnHcTZZW",
"internalFailure": false,
"leaseId": "b1ac375b-8de1-4241-9da2-c132f487ec6e",
"opsCompleted": 0,
"ranToCompletion": true,
"scheduled": false,
"serverId": "e7fe021f6dfd",
"startDate": "2024-09-19T23:47:34.313Z",
"type": "ActivityEsc"
},
...
},
{
"attributes": {
"dateCompleted": "2024-09-18T03:30:00.033Z",
"dateCreated": "2024-09-18T03:30:00.009Z",
"description": "Activity escalation monitor",
"failedOps": 0,
"id": "ab:SKQcRxTozlLJVCpZZV1x7",
"internalFailure": false,
"leaseId": "efa769b4-6730-4688-8032-4ef13c45df5d",
"opsCompleted": 0,
"ranToCompletion": true,
"scheduled": true,
"serverId": "e7fe021f6dfd",
"startDate": "2024-09-19T03:30:00.024Z",
"type": "ActivityEsc"
},
...
}
}
}

The following request returns the run of the Activity Escalation batch process whose ID is
ab:SKQcRxTozlLJVCpZZV1x7. Note that this was not the most recent run.

Command

GET /batch-processes/ActivityEsc/histories/ab:SKQcRxTozlLJVCpZZV1x7

Response

{
"data": {
"attributes": {
"dateCompleted": "2024-09-18T03:30:00.033Z",
"dateCreated": "2024-09-18T03:30:00.009Z",
"description": "Activity escalation monitor",
"failedOps": 0,
"id": "ab:SKQcRxTozlLJVCpZZV1x7",
"internalFailure": false,
"leaseId": "efa769b4-6730-4688-8032-4ef13c45df5d",
"opsCompleted": 0,
"ranToCompletion": true,
"scheduled": true,
"serverId": "e7fe021f6dfd",
"startDate": "2024-09-19T03:30:00.024Z",
"type": "ActivityEsc"
},
...

410 Batch processes

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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 411.
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.
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,
"processHistoryId": 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.

Batch processes 411

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

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>,
...
}
}
}
}

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.

412 Batch processes

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer 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"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
},
"wasStopped": true,
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},

Batch processes 413

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

414 Batch processes

chapter 37

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 ConsistencyCheckType 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 415

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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": {

416 Database consistency checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 417

Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 418.
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.

418 Database consistency checks

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 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 419

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

420 Database consistency checks

chapter 38

Business entity schemas

For some use cases, it’s necessary to have a schema with detailed graph and entity information. For this purpose,
ClaimCenter provides endpoints that retrieve schema information that can be used to navigate the graph structure for
various purposes and to build out custom user interfaces.
The schema endpoints return metadata about the business entities that are exposed by the API (such as Users and
Contacts) as normal JSON schema documents. In addition to standard JSON Schema properties, the schema endpoints
can also return additional application-specific metadata. This additional metadata is returned in the form of x-gw-*
properties.
The topics in this section describe the endpoints and query parameters for retrieving schemas. They also describe
properties that are specific to entity and graph schemas and not found in the standard business schemas (such as
OpenAPI).

Retrieve a business entity schema

The entity-schemas and graph-schema endpoints both return a JSON representation of business entities. The
information returned is similar to what you would find in the swagger and openapi endpoints, but with additional
metadata. (See Viewing API definitions for information on the swagger and openapi endpoints.)
As a general rule, use graph-schema if you're consuming a graph, such as from AppEvents. Use entity-schemas if
you want a schema for everything in the API, or you want to use one endpoint that works across all InsuranceSuite
applications.

Retrieve an entity schema

The entity-schemas endpoints return one or more complete product schemas. They can also be filtered to target
specific sets of entities. For more information on query parameters, see “Business entity schema query parameters” on
page 422.
Use the following command to retrieve a JSON-formatted entity schema:
GET /common/v1/entity-schemas
To retrieve the schema for a single entity, use the following command:
GET /common/v1/entity-schemas/{entityId}
For example, you can return the schema for the User entity with the following command:

GET /common/v1/entity-schemas/User

Business entity schemas 421

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

The schema returned by the entity-schemas/{entityId} endpoint returns the schema for the specified entity and
other schemas transitively referenced from that entity. In the preceding example, in the base configuration the returned
entity schema would include User, plus related schemas such as UserGroupReference and UserRoleReference.
However, it won’t return the schemas for any child entities. Instead it will return a list of children (if any) in the x-gw-
children property for each entity. (See "Child entities" in “Schema properties usage” on page 426 for more
information.)
To retrieve a specific entity along with the complete schema information for all its children, filter the entity-schemas
endpoint on rootEntity:
GET /common/v1/entity-schemas?filter=rootEntity:eq:{entityId}
Filtering on rootEntity retrieves a more detailed schema than using the entity-schemas/{entityId} endpoint by
traversing the entity graph tree and including all the child entities of the specified entity.

Retrieve a graph schema

The graph-schema endpoint returns a graph schema. A graph schema is a JSON representation of one or more logical
entities and their children.
Use the following command to retrieve a graph schema:
GET /claim/v1/graph-schema
The response returned by the graph-schema endpoint is a JSON Schema Draft-7 document that contains schema
definitions for the primary business object graphs for the application. The schema definitions are similar to the schema
definitions found in the API schemas and entity-schemas endpoints, but will include additional properties that embed
child objects in their parents. For example, an entity accessed through an endpoint as /entity with a child accessed as /
entity/{entityId}/entityChild would be represented in the graph schema as an "Entity" definition with an "entityChild"
property.
The schema returned in the response can contain multiple logical "graphs." However, it does not return all entities. For
example, Admin entities such as User are not included in the graph-schema response. To retrieve all entities, use the
entity-schemas endpoint.

The following command retrieves a graph schema with entities such as Activity, Claim, and InjuryIncident.
Command

GET /claim/v1/graph-schema

Response

{
"$schema": "[Link]
"definitions": {
"Activity": {
"description": "An `Activity` is an assignable item that represents a task to be done, a decision to be made, or
information to be aware of",
"properties": {
"activityPattern": {
…
"Claim": {
"description": "An insurance claim",
"properties": {
"accidentType": {
…
"InjuryIncident": {
"description": "Information about a bodily injury",
"properties": {
…

Business entity schema query parameters

The following table includes query parameters that are specific to business entity schemas. Parameters can be used
with entity-schemas endpoints and the graph-schema endpoint unless noted otherwise. For each parameter, a short

422 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

description is provided along with possible values. Also listed for each parameter are any other parameters that must be
included in order for the given parameter to be used. See below for detailed descriptions of each.

Parameter Description Values Other parameters

required

includeLocalizations Include localization strings in the schema for all • {language code} none
localizable strings for the specified installed
• {language-region code}
languages.
• *all (all installed
Available only for entity-schemas endpoints.
languages)

inlineTypelists Include typelist values in the schema. Boolean none

includeLocalizations
The includeLocalizations query parameter includes localized versions of all strings in the schema response. Any
element that can be localized will include an x-gw-localizations property containing localized versions of the
associated schema property. (If no localized version for a given language exists, the value will be provided in the
default language.)
The localized languages that are displayed depend on the value assigned to the parameter. You can retrieve localized
strings for all installed languages (languages in the LangaugeType typelist) by assigning the *all value to the
parameter.
To retrieve localized strings for only specific languages, include the language code as the value. The language code can
be in any of the following formats:
• Language code, such as fr (French).
• Language and region, such as fr-CA (French, Canada) or fr-FA (French, France).
• Language and region with either a hyphen or an underscore. Both fr-CA and fr_CA will return French (Canada)
localized strings.
Note that the value is case-sensitive; you’ll receive an error if the installed language is en_US and you specify en_us.
Only installed languages can be specified. If you set a value to a language that is not installed you’ll receive an error.
The following examples show different options for calling includeLocalizations:
Retrieve localized values for all installed languages:

GET /common/v1/entity-schemas?includeLocalizations=*all

Retrieve localized values for US English:

GET /common/v1/entity-schemas?includeLocalizations=en_US

Retrieve localized values for all versions of French:

GET /common/v1/entity-schemas?includeLocalizations=fr

Retrieve localized values for English and French (Canada):

GET /common/v1/entity-schemas?includeLocalizations=en,fr_CA

For details on the schema structure, see “Localizations” on page 433.

inlineTypelists
The inlineTypelists query parameter is used to include typelist metadata for each typekey field or term so that
typelist metadata doesn’t need to be fetched separately. Set inlineTypelists to true to enable this feature.

Business entity schemas 423

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

• GET /common/v1/entity-schemas?inlineTypelists=true
• GET /claim/v1/graph-schema?inlineTypelists=true
See “Choice values” on page 427 for more information and schema examples.

ETag support
The business entity schema endpoints support the use of ETags. An ETag response header is returned with every
request. The ETag acts as a checksum of schema content, so it changes depending on which query parameters you use.
Use the ETag with the If-None-Match request header. If this matches the current checksum, you’ll receive a "304 not
modified" response. If it doesn’t match, the request will be processed normally.
ETag is a standard HTTP header. More information can be found by doing an internet search.

Schema properties
The InsuranceSuite business entity schemas are returned as JSON documents using the JSON Schema Draft-7
specification. In addition to standard JSON schema properties, the business entity schemas include a number of
additional schema properties that include metadata about the entities and their representation in APIs and AppEvents.
• “Schema properties overview” on page 424
• “Schema properties usage” on page 426

Schema properties overview

This table provides a list of schema properties specific to business entities. See “Business entity schemas” on page 421
for more information on retrieving these schemas.

Property Description More information

x-gw-actions A list of logical actions that you can take on an entity. This “Cloud API endpoint
encompasses standard HTTP operations on the element or elements” on page 428
collection, as well as custom actions.

x-gw-after Applies to properties of format date or date-time. Indicates a “Date and date-time
date or date-time that the value must be later than. fields” on page 431

x-gw-before Applies to properties of format date or date-time. Indicates a “Date and date-time
date or date-time that the value must be earlier than. fields” on page 431

x-gw- For entities that can be accessed through a Cloud API endpoint, “Cloud API endpoint
canonicalCollectionUri this object contains the URI to the collection endpoint. elements” on page 428

x-gw-canonicalElementUri For entities that can be accessed through a Cloud API endpoint, “Cloud API endpoint
this object contains the URI to the individual element endpoint. elements” on page 428

x-gw-canonicalParent For entities that can be accessed through a Cloud API endpoint, “Cloud API endpoint
this object contains the ID of the parent entity. elements” on page 428

x-gw-calculatedValues An object whose keys represent schema properties that have “Calculated values” on
dynamic values. Dynamic values are calculated based on page 426
evaluation of static values retrieved through JsonLogic.

x-gw-children An object containing information about child objects of an “Child entities” on page
entity. 427

424 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Property Description More information

x-gw-choices This property contains typelist values associated with the entity “Choice values” on page
objects. It is included in the schema response when the 427
inlineTypelists query parameter is set to true.

x-gw-createOnly Indicates that a property can be set when creating the entity “Update restrictions” on
(during an initial POST), but not modified. page 438

x-gw-defaultValues An array of strings that indicate what default views a property “Cloud API responses” on
will appear in. Possible values include detail, summary, and page 429
none.

x-gw-dynamicProperties An object where each key in the map represents a named rule. “Rules” on page 436
The values of such keys have a jsonLogic object defining the
rules.

x-gw-entityId A marker on every schema that corresponds to an entity that “Entity ID” on page 431
contains the id of that entity.

x-gw-filterBy Applies to typekey properties that have typelists that are “Typekey references” on
filtered by categories from other typelists represented on the page 438
same object. This property is an array of schema property
names for the filtering typekey properties.

x-gw-forbidden This property contains an array of one or more values that • “Forbidden fields” on
indicate properties that are forbidden for use in a particular page 432
context. Often used within an x-gw-rules object to identify
fields that cannot be used in certain situations. • “Country-specific
fields” on page 430
x-gw-includedInAppEvents Used to determine whether a property is event safe. Only for “Event safety” on page 432
use when integrating through App Events.
x-gw-localizations When the “Localizations” on page
433
includeLocalizations query parameter is set to true, this
property is included in the schema to show localized versions of
strings for every installed language.
x-gw-maximum Used to represent a maximum value for a property that is not a “Numeric values” on page
standard JSON integer or decimal, such as a gw-bigdecimal 434
or MonetaryAmount object.

x-gw-minimum Used to represent a minimum value for a property that is not a “Numeric values” on page
standard JSON integer or decimal, such as a gw-bigdecimal 434
or MonetaryAmount object.

x-gw-patchOnly Indicates that the value can be set only during updates (PATCH “Update restrictions” on
requests), not during the initial creation (POST request). page 438

x-gw-precision The precision of a fixed-point decimal value (the total number “Numeric values” on page
of digits allowed in a number). 434

x-gw-reference-schema The name of the schema definition associated with a given type “References” on page 435
when a property is a reference (such as SimpleReference).

x-gw-referenceType The name of the referenced entity type when a property is a “References” on page 435
reference (such as SimpleReference).

x-gw-requiredForCreate An array of property names for properties whose values must “Required properties” on
be specified as part of POST requests to create a new entity. page 435

Business entity schemas 425

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Property Description More information

x-gw-requiredForValidation This property identifies fields that are required for a particular • “Required properties”
entity to be valid. A typical use case is to define required fields on page 435
in an address.
• “Country-specific
fields” on page 430
x-gw-resourceReference A marker attached to schema definitions such as “References” on page 435
SimpleReference that indicates that the schema represents a
reference to another entity.

x-gw-rules This property contains a jsonLogic attribute where you can • “Rules” on page 436
apply conditional rules to various schema elements.
• “Country-specific
fields” on page 430
x-gw-scale The scale of a fixed-point decimal value (the number of digits “Numeric values” on page
allowed to the right of the decimal point). 434

x-gw-sortOrder The sequence number of coverables, clauses, covTerms, • “Sort order” on page
questions, modifiers, rate factors, and scheduled item 438
properties defined in APD.
• “Choice values” on
page 427

x-gw-typelist The name of the typelist when the property is a reference to a “Typekey references” on
TypeKeyReference. page 438

Schema properties usage

The following topics provide detailed descriptions and examples that will help in understanding the properties returned
in the business entity schemas. See “Schema properties overview” on page 424 for a list of properties that are specific
to these schemas.

Calculated values
APD supports calculated values for coverage terms on a parent coverage where the minimum or maximum are
calculated based on terms on the child coverages. For example, the parent coverage can have a limit whose minimum
value is the sum of the limits of a set of child coverages. Calculated values can use a sum, min, or max across the child
terms, or be a direct reference to a child term.
The entity schema provides the x-gw-calculatedValues property to support this type of scenario. This property is an
object whose keys represent schema properties that have dynamic values rather than static values. Each schema
property will have a value with a jsonLogic property that can be evaluated, resulting in the concrete value to attach to
that schema property.
The x-gw-calculatedValues property is primarily intended for use by client code that uses schema-based validation.
In order to interpret the calculated values at runtime, a client needs to iterate through each property on the x-gw-
calculatedValues object, evaluate the JsonLogic expression for that property, and then attach the resulting value to
the containing schema definition.
See [Link] for more information on using JsonLogic.
The following is an example of a calculated value. This is a simple example where the value must be retrieved from
another entity:

"x-gw-calculatedValues": {
"x-gw-maximum": {
"jsonLogic": {
"+": {
"uri": "/jobs/{jobId}/lines/TSTLine/test-coverables/{testCoverableId}/coverages/TSTChildCov/
[Link][0].value"

426 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

}
}
}
}

Child entities
An entity can (but doesn’t have to) have child objects. These child objects are returned in the x-gw-children schema
object. The following properties can be included with the x-gw-children object:
• childType: The type related to certain product model metadata. See "Special child types" below.
• description: A description of the children.
• graphProperty: The property used to attach these children in the schema.
• id: The id of the child entity.
• title: The title for the children.
• urlPart: The URL fragment used for the collection of child entities in the API.
The following example shows some of the children for the Account entity in the base configuration:

"x-gw-children": [
{
"id": "Activity",
"urlPart": "activities"
},
{
"id": "Assignee",
"urlPart": "activity-assignees"
},
{
"id": "ActivityPattern",
"urlPart": "activity-patterns"
},

Choice values
For entities that contain choice values, the entity schema returns the x-gw-choices object. You must include the query
parameter inlineTypelists set to true to retrieve this object. The object contains the following properties:

Property Description Used with

code The unique identifier for the choice. • Typelists

• Option/package choices
• Coverage term choices

name The name of the choice. • Typelists

• Option/package choices
• Coverage term choices

description The description of the choice. • Typelists

• Option/package choices
• Coverage term choices

sortOrder The canonical sort order for the choice, relative to other choices in the same list. • Typelists
• Option/package choices
• Coverage term choices

categories A list of strings that indicate the categories the typekey belongs to. Categories are • Option/package choices
presented in the form [Link], such as [Link].
• Coverage term choices

Business entity schemas 427

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Property Description Used with

values An array of additional values relating to coverage terms. • Coverage term choices

Typelist choice values

The x-gw-choices property can contain typelist values associated with the entity objects. For example, in the
PolicyCenter base configuration the Account Status on the Account entity is a typelist of type AccountStatus. The
typekeys in the AccountStatus typelist are Active, Merged, Pending, and Withdrawn. Without inlineTypelists set to
true, the schema endpoint returns the following:

"accountStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The current status of this account",
"readOnly": true,
"title": "Account status",
"x-gw-typelist": "AccountStatus"
},

This example shows that accountStatus is a typelist of type AccountStatus, but the values of that typelist are not
displayed. When you add inlineTypelists=true to the endpoint query string, the individual values are included in
the schema in the x-gw-choices object:

"accountStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The current status of this account",
"readOnly": true,
"title": "Account status",
"x-gw-choices": [
{
"code": "Active",
"description": "The account is fully ready and open, and submissions have been created for it.",
"name": "Active",
"sortOrder": 0
},
{
"code": "Merged",
"description": "The account has been merged into another account and is available for read only access.",
"name": "Merged",
"sortOrder": 1
},
{
"code": "Pending",
"description": "The account is ready for data entry, but data entry is still ongoing and the account is not
considered fully open.",
"name": "Pending",
"sortOrder": 2
},
{
"code": "Withdrawn",
"description": "The account has been withdrawn from consideration for business with the carrier.",
"name": "Withdrawn",
"sortOrder": 3
}
],
"x-gw-typelist": "AccountStatus"

Notice the sortOrder value under each choice. This ordering can be used to ensure the desired order of user interface
elements. See “Sort order” on page 438 for more information.

Cloud API endpoint elements

For schema entities that can be accessed through Cloud API endpoints, the schema includes information on options for
accessing those endpoints:
• x-gw-canonicalParent: The parent entity.
• x-gw-canonicalCollectionUri: The endpoint that accesses a collection of entities.
• x-gw-canonicalElementUri: The endpoint that accesses individual instances of the entity.
• x-gw-actions: An array of actions that can be taken on the endpoints. Each object in the array includes:
◦ httpMethod: A command that can be used with the endpoint.

428 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

◦ actionTarget: Whether the command applies to the individual element endpoint or the collection endpoint.
◦ description: Optional. Describes the action.
◦ urlSuffix: Optional. An additional action that can be taken on the endpoint by using the httpMethod with the
endpoint, followed by the urlSuffix at the end of the endpoint. (See example below.)
For example, here are the endpoint elements available for the RolePermission entity:

"title": "Role permission",

"type": "object",
"x-gw-actions": [
{
"actionTarget": "collection",
"httpMethod": "GET"
},
{
"actionTarget": "collection",
"httpMethod": "POST"
},
{
"actionTarget": "element",
"httpMethod": "DELETE"
},
{
"actionTarget": "element",
"httpMethod": "GET"
}
],
"x-gw-canonicalCollectionUri": "/admin/v1/roles/{roleId}/permissions",
"x-gw-canonicalElementUri": "/admin/v1/roles/{roleId}/permissions/{permissionId}",
"x-gw-canonicalParent": {
"id": "Role"
},

This example shows that you can take the following actions on the RolePermission entity through Cloud API:
• GET a collection of role permissions. (GET /admin/v1/roles/{roleId}/permissions)
• Create a new role permission with the POST command on the permissions collection. (POST /admin/v1/roles/
{roleId}/permissions)
• DELETE a single role permission. (DELETE /admin/v1/roles/{roleId}/permissions/{permissionId})
• GET a single role permission. (GET /admin/v1/roles/{roleId}/permissions/{permissionId})
Note that the x-gw-canonicalParent identifies the Role entity as the canonical parent of RolePermissions.

Cloud API responses

When an element is retrieved with a Cloud API command, it’s possible that not all properties of that element will be
displayed in the response by default. This might be desirable, for example, in cases where retrieving the contents of a
certain property could impact performance if it were to be retrieved for every instance of that element.
You can identify the circumstances under which a property will be displayed based on the x-gw-defaultViews
property. This property is an array with the following possible values:
• detail: This property is in the response when a single instance of the element is retrieved, not when a collection is
retrieved.
• summary: This property is in the response when a collection is retrieved.
• none: This property is in the response only when it is explicitly identified in the fields query parameter.
In this example, the accountContactRoles property is displayed in the response only when a single instance of an
AccountContact is retrieved:

"AccountContact": {
...
"properties": {
"accountContactRoles": {
...
"x-gw-defaultViews": [
"detail"
],

Business entity schemas 429

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

...
},

The following command retrieves a single account contact, and therefore displays the accountContactRoles property:
Command

GET /account/v1/accounts/pc:Su4p27AlTSug_SWq-8koA/contacts/pc:S9rwT9nWtFBArb3GFDwkc

Response

{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
"active": true,
"authorizationID": "S5qmqyeE_7azM0VwejF2r",
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},

However, when the collection of account contacts is retrieved, account contact roles is not included:
Command

GET /account/v1/accounts/pc:Su4p27AlTSug_SWq-8koA/contacts

Response

{
"count": 5,
"data": [
{
"attributes": {
"authorizationID": "S5qmqyeE_7azM0VwejF2r",
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},

Country-specific fields
Entity schemas use JSON logic conditional rules to define whether certain fields are forbidden or required based on the
country. In some cases a field might be forbidden for use in a particular county. In other cases, such as addresses,
required fields differ by country. These rules are specified in the x-gw-rules property.
Note: See “Rules” on page 436 and “Forbidden fields” on page 432 for more information.

In this example, there is a rule on PolicyLocation that makes certain location fields forbidden and others required for
the US:

"x-gw-entityId": "PolicyLocation",
"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
"===": [
{
"var": "country"
},
"US"
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"CEDEX",
"addressLine1Kanji",

430 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"addressLine2Kanji",
"area",
"cityKanji",
"department",
"emirate",
"island",
"oblast",
"parish",
"prefecture",
"province"
],
"x-gw-requiredForValidation": [
"addressLine1",
"city",
"postalCode",
"state"
]
},

In some cases the same set of rules apply to multiple countries. In those cases, all countries are listed in an array using
in logic on the rules, as shown here:

"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
…
},
{
"in": [
{
"var": "country"
},
[
"AS",
"AU",
"FM",
"GU",
"IN",
"MH",
...

Date and date-time fields

Some properties that contain dates have restrictions on the date range allowed. There are instances where a date must
be before or after a certain timeframe. To allow for this, the following attributes can be found on a date or date-time
property when applicable:
• x-gw-before: The date or date-time must be earlier than this value.
• x-gw-after: The date or date-time must be later than this value.
In the following example, dateOfBirth is a date that must have a value before the date the value is entered (now):

"dateOfBirth": {
"description": "The person's date of birth. Only applicable for an `AccountContact` that represents a person.",
"format": "date",
"nullable": true,
"title": "Date of birth",
"type": "string",
"x-gw-before": "now"
},

Entity ID
Every schema that contains an entity has a corresponding entity ID. For example, the User schema has an entity ID of
User:

"x-gw-entityId": "User"

In contrast, the SimpleReference schema is not an entity, and therefore does not have an x-gw-entityId property.
Note that the x-gw-entityId property is available only when a schema is retrieved through the entity-schemas
endpoints.

Business entity schemas 431

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Event safety
When you’re integrating with Guidewire InsuranceSuite through App Events, it’s important to know whether a
property is event safe. You can determine the event safety of a property by looking for the x-gw-
includedInAppEvents property.

If a property is not event safe, it will have an x-gw-includedInAppEvents property with a value of false. If a
property is event safe, x-gw-includedInAppEvents will not be present on the property.
If you are not integrating through App Events, you can ignore the x-gw-includedInAppEvents property.
See App Events for more information on App Events.

Forbidden fields
The schema can include the x-gw-forbidden property. This property is an array used to indicate that one or more
properties are not allowed or available under certain conditions. It is often defined inside JsonLogic decisions that
provide the conditions under which something is forbidden. (See [Link] for more information on using
JsonLogic.)
This example shows a section of the schema that indicates certain properties are forbidden based on a contact subtype:

"x-gw-rules": [
{
"jsonLogic": {
"if": [
…
{
"in": [
{
"var": "contactSubtype"
},
[
"Adjudicator",
"Person",
"PersonVendor",
"UserContact"
]
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"companyName"
]
},
{
"in": [
{
"var": "contactSubtype"
},
[
"LegalVenue",
"Place"
]
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"applicableGoodDriverDiscount",
"cellPhone",
"companyName",
…
]
},

The x-gw-forbidden property is used in several contexts. It is used to designate forbidden fields for things such as:
• Subtype-specific fields.
• Product edition rules that indicate that a given element is unavailable for that edition.
• Choices on options, packages, or typekeys. In these cases, x-gw-forbidden is an array of objects, where each
object has a code and name for the forbidden choice.
See “Country-specific fields” on page 430 for more examples of x-gw-forbidden.

432 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Localizations
When you call the schema retrieval endpoint with the includeLocalizations parameter set to true, the returned
schema will contain localized versions of all localizable strings in the schema. (See “includeLocalizations” on page 423
for information on using this parameter.) If you also specify the inlineTypelists parameter, localized strings will be
included for typelist values. Similarly, if you specify the inlineProductDefinition parameter, localized strings will
be included for localizable product model elements such as coverage names and descriptions.
Localization strings are returned on the x-gw-localizations property on the associated element. The value of x-gw-
localizations is an object with a key for each localized property, such as title or description. The values of those
keys are another object with key/value pairs for each requested language and the localized value for those languages.
For example, suppose you have two languages configured, English (US) and French (France). You also have a schema
object on an entity named username. The object looks like this:

"username": {
"description": "The username for the user",
"maxLength": 30,
"minLength": 1,
"pattern": "\\S",
"title": "Username",
"type": "string",

Retrieve localized values for all installed languages:

Command

GET /common/v1/entity-schemas?includeLocalizations=*all

Schema example

"x-gw-localizations": {
"description": {
"en_US": "The username for the user",
"fr_FR": "Le nom d’utilisateur de l’utilisateur"
},
"title": {
"en_US": "Username",
"fr_FR": "Nom d’utilisateur"
}
}

Retrieve localized values for US English:

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US

Schema example

"x-gw-localizations": {
"description": {
"en_US": "The username for the user"
},
"title": {
"en_US": "Username"
}
}

Retrieve localized values in US English including typelists:

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US&inlineTypelists=true

Schema example

"vacationStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "Indicates whether the user is considered to be on vacation",
"title": "Vacation status",

Business entity schemas 433

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"x-gw-choices": [
{
"code": "atwork",
"description": "The user is at work",
"name": "At work",
"sortOrder": 0,
"x-gw-localizations": {
"description": {
"en-US": "The user is at work"
},
"name": {
"en-US": "At work"
}
}
},
{
"code": "onvacation",
"description": "The user is on vacation",
"name": "On vacation",
"sortOrder": 1,
"x-gw-localizations": {
"description": {
"en-US": "The user is on vacation"
},
"name": {
"en-US": "On vacation"
}
}
},
…
],
"x-gw-localizations": {
"description": {
"en-US": "Indicates whether the user is considered to be on vacation"
},
"title": {
"en-US": "Vacation status"
}
},
"x-gw-typelist": "VacationStatusType"
},

A value will always be included in x-gw-localizations for each installed language. If the value has not been
localized for a language, normal localization fallback rules will apply. If a language code and region are specified, the
first fallback will be to language code, then to the default language. For example, suppose fr_CA (Frech, Canada) is an
installed language. If there is no localization for a particular property for fr_CA, it will fall back to a value specified for
fr (French). If there is no localized value for fr, the value will be the default language (if the default language is not
fr_CA or fr).
Command

GET /common/v1/entity-schemas?includeLocalizations=en_US,fr_FR

Schema example

"x-gw-localizations": {
"description": {
"en_US": "The username for the user",
"fr_FR": "The username for the user"
},
"title": {
"en_US": "Username",
"fr_FR": "Username"
}
}

Numeric values
Properties that are numeric types can have additional defining properties depending on the type of value.
Fixed-point decimal values
Certain decimal values need to be restricted as to the maximum number of digits allowed in the value. This is depicted
in the schema through the x-gw-precision and x-gw-scale properties:
• x-gw-precision: The maximum number of digits allowed for a value.
• x-gw-scale: The scale of the value, such as the maximum number of digits to the right of a decimal point.

434 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

These properties apply only to elements of type gw-bigdecimal and to MonetaryAmount references.
In this example, the cost of a new car can be up to 18 digits, with up to two digits following the decimal point:

"PersonalVehicle": {
"description": "Personal Vehicle",
"properties": {
...
"costNew": {
"$ref": "#/definitions/MonetaryAmount",
"description": "Original retail cost of car.",
"nullable": true,
"title": "Cost New",
"x-gw-precision": 18,
"x-gw-scale": 2,
"x-gw-sortOrder": 6
},

Minimum and maximum values

Numeric properties that are non-standard JSON decimal or integer types (such as MonetaryAmount and gw-
bigdecimal) can have maximum and minimum values defined in the x-gw-maximum and x-gw-minimum properties. In
this example, the maximum amount allowed is 5000, and the minimum is 250:

"amount": {
"$ref": "#/definitions/MonetaryAmount",
"description": "The transaction amount for the effective time",
"readOnly": true,
"title": "Amount",
"x-gw-maximum": 5000,
"x-gw-minimum": 250
},

References
There are some schema definitions that are references to other entities. Examples are entities such as SimpleReference
and GroupReference. When this is the case, the entity has an x-gw-resourceReference property set to true.

"x-gw-resourceReference": true

For properties that are reference types, such as SimpleReference, the name of the referenced entity type is defined in
the x-gw-referenceType property. The name of the schema definition associated with a given type is specified in the
x-gw-reference-schema property. In this example, accountHolder is a SimpleReference associated with the
AccountContact schema, of type AccountContact:

"accountHolder": {
"$ref": "#/definitions/SimpleReference",
"description": "A reference to the `AccountContact` that represents the owner of the policies for this account",
"title": "Account holder",
"x-gw-reference-schema": "AccountContact",
"x-gw-referenceType": "AccountContact"
},

Required properties
Some entities have a required property. This property is an array containing a list of properties that must have values
on instances of the entity. In addition, there are properties that are required only when certain actions, such as creation
or validation, take place on those entities.
• requiredForCreate: The property must have a value for an entity to be created.
• requiredForValidation: The property must have a value for the object to validate.
For example, the following specifies that an address cannot be validated if there are not values for addressLine1,
city, postalCode, and state:

"x-gw-requiredForValidation": [
"addressLine1",
"city",
"postalCode",
"State"
]

Business entity schemas 435

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Rules
The entity schema applies rules to some entities, both conditional and non-conditional. Rules are required for several
different areas of the schema. For details on some of the specific areas of the entity schema where rules are used, see
the following sections:
• “Country-specific fields” on page 430
Rules Overview
In some cases there is schema metadata about a business entity, or associated product model entity, that is conditional
rather than static. To support those use cases, where possible the Guidewire schema APIs translate those rules into
conditions using the JsonLogic format. The JsonLogic expressions, when evaluated, will return a JSON object that
might contain additional JSON Schema properties to apply to the attached schema.
For example, if a direct coverage term has a conditional maximum value, the directValue schema property for the
term's schema will have an x-gw-rules array with an object representing this rule. Evaluating the JsonLogic
expression for the associated rule might return a result such as:

{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-maximum": "500.00"
}

This means that the x-gw-maximum schema property needs to be applied to the term's schema dynamically, replacing
any value that might already be there. If the result returns null or the empty object, it means no changes to the schema
are needed. (The x-gw-dynamicPropertiesMarker property is a marker property that can be ignored at runtime).
JsonLogic expressions need to be evaluated using the associated root API object's attributes as the context for
evaluation.
See [Link] for more information on using JsonLogic.
The following are examples of places where rules can be attached:
• Field existence rules are attached to the containing schema definition.
• Field min/max/default rules are attached to the associated property definition.
• Field typekey existence rules are attached to the associated property definition.
• Clause existence rules are attached to the _Coverages schema definition that defines a container for all coverages
on the coverable.
• Term existence rules are attached to the terms property on the _Coverage schema definition.
• Term min/max/default rules are attached to the Value property for the term, such as directValue.
• Term option/package/typekey existence rules are attached to the choiceValue or typekeyValue property for the
term.
Rules Examples
Conditional rules are provided with JsonLogic. Often (but not always) this logic is nested within the x-gw-rules array.
Here’s an example. (Note that while this example pertains specifically to PolicyCenter, the functionality of x-gw-rules
is the same across all InsuranceSuite products.)

"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
"===": [
{
"uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
},
1002
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-maximum": "500.00"
}

436 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

},
{
"===": [
{
"uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
},
1003
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-maximum": "400.00"
},

In this case, if the property at the specified uri is equal to 1002, the maximum value for this property is 500. But if the
value is 1003, the maximum is 400.
Rules can also exist without conditions. For example, if a direct coverage term always has a maximum of 500.00 for a
particular product edition, fetching the schema in the context of that edition includes the property directly.

"directValue": {
"x-gw-maximum": "500.00",
…
}

The x-gw-rules property is an array of JsonLogic rules. Another property, x-gw-dynamicProperties, is similar to x-
gw-rules, but instead of being an array, it’s an object containing named rules. In this example, there are two named
rules, one for accountHolderCreation and one for primaryLocationCreation:

"x-gw-dynamicProperties": {
"accountHolderCreation": {
"forbiddenError": "Exactly one of either 'accountHolder' or 'initialAccountHolder' is required on creation",
"jsonLogic": {
"if": [
{
"===": [
{
"var": "accountHolder"
},
null
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-requiredForCreate": [
"initialAccountHolder"
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"initialAccountHolder"
]
}
]
},
"requiredError": "Exactly one of either 'accountHolder' or 'initialAccountHolder' is required on creation"
},
"primaryLocationCreation": {
"forbiddenError": "Exactly one of either 'primaryLocation' or 'initialPrimaryLocation' is required on creation",
"jsonLogic": {
"if": [
{
"===": [
{
"var": "primaryLocation"
},
null
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-requiredForCreate": [
"initialPrimaryLocation"
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"initialPrimaryLocation"
]
}
]
},

Business entity schemas 437

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"requiredError": "Exactly one of either 'primaryLocation' or 'initialPrimaryLocation' is required on creation"

}
},

Sort order
Sort order is preserved in various situations and can be used to ensure the desired order of user interface elements.
sortOrder
In this example, the order of Account Status choices has been preserved through the sortOrder on the choice options,
with Active first, Merged second, and so on. Note that counting starts at 0, so the first choice is sortOrder 0.

"accountStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The current status of this account",
"readOnly": true,
"title": "Account status",
"x-gw-choices": [
{
"code": "Active",
"description": "The account is fully ready and open, and submissions have been created for it.",
"name": "Active",
"sortOrder": 0
},
{
"code": "Merged",
"description": "The account has been merged into another account and is available for read only access.",
"name": "Merged",
"sortOrder": 1
},
{
"code": "Pending",
"description": "The account is ready for data entry, but data entry is still ongoing and the account is not
considered fully open.",
"name": "Pending",
"sortOrder": 2
},

See “Choice values” on page 427 above for more information.

Update restrictions
Some properties can be assigned values only when the entity is first created. In those cases, the property will have a
value of x-gw-createOnly set to true.
For example, an initial account holder can be specified only at the time the account is created (POST), and cannot be
modified later.

"Account": {
...
"initialAccountHolder": {
...
"title": "Initial account holder",
"x-gw-createOnly": true
},

In other cases, a property can be assigned a value only when the entity is updated (PATCH). In those cases, the property
will have x-gw-patchOnly set to true:

"x-gw-patchOnly": true

Typekey references
Some properties in the schema are used to identify typekey properties and behaviors.
Typelist
If an element in the schema is a TypeKeyReference, the applicable typelist is specific in the x-gw-typelist property.
In this example, the organizationType property is a TypeKeyReference to the AccountOrgType typelist:

"organizationType": {
"$ref": "#/definitions/TypeKeyReference",

438 Business entity schemas

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

"description": "The type of organization of the company or person represented by this account, such as `individual`
or `corporation`",
"nullable": true,
"title": "Organization type",
"x-gw-typelist": "AccountOrgType"
},

Filter
Some typelists are filtered by categories from other typelists represented on the same object. The x-gw-filterBy
property contains an array of categories on which to filter. For example, a country typelist might include states,
provinces, islands, and so on. Not all of these options apply to all countries. In these cases, the typelist needs to be
filtered by country, as in the following examples:

"province": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The province of the location's address. Only applicable in certain countries.",
"nullable": true,
"title": "Province",
"x-gw-createOnly": true,
"x-gw-filterBy": [
"country"
],
"x-gw-typelist": "State"
},
"state": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The state of the location's address. Only applicable in certain countries.",
"nullable": true,
"title": "State",
"x-gw-createOnly": true,
"x-gw-filterBy": [
"country"
],
"x-gw-typelist": "State"
}

Business entity schemas 439

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

440 Business entity schemas

chapter 39

The Test Util API

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. The API is also sometime referred to by its internal name (testutil).
By default, the Test Util API is not enabled.

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.

Learn more about the Test Util API and some of the available endpoints:
• “Enabling the Test Util API” on page 441
• “View the Test Util API in Swagger UI” on page 442
• “Test Util API endpoints” on page 442

Enabling the Test Util API

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.

To enable the Test Util API, you must do two things:

1. Enable the Test Util API itself.
2. Set the IPolicySearchAdapter plugin to use a mock plugin designed specifically for Test Util API.
Both of these steps are accomplished using substitution placeholders. A substitution placeholder is a variable that
determines the setting of a specific server property. The value is stored outside of the Guidewire application. During
server start-up, the Guidewire application looks for the property's value in the following places in this order. It uses the
first value it finds.
1. Guidewire Property Services
2. Guidewire Cloud Console environment variables
3. The application's [Link] file
The syntax for a substitution variable varies slightly based on where the value is being set.

The Test Util API 441

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Setting the values in Guidewire Property Services

To set the values in Guidewire Property Services, specify the following:

published-apis.PUBLISHEDAPIS_testutil_publish = true
plugin.PLUGIN_IPOLICYSEARCHADAPTER_PROFILE = testutil-api

Then, you must start (or restart) the server.

Setting the values in Guidewire Cloud Console environment variables

To set the values in Guidewire Cloud Console, specify the following:

PUBLISHEDAPIS_testutil_publish = true
PLUGIN_IPOLICYSEARCHADAPTER_PROFILE = testutil-api

Then, you must start (or restart) the server.

Setting the values in the application's [Link] file

To set the values in the application's [Link] file, specify the following:

published-apis.PUBLISHEDAPIS_testutil_publish = true
plugin.PLUGIN_IPOLICYSEARCHADAPTER_PROFILE = testutil-api

Then, you must start (or restart) the server.

View the Test Util API in Swagger UI

About this task

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.

After you enable Test Util, you can use Swagger UI to view the Test Util API definition. (See “Enabling the Test Util
API” on page 441 for instructions on enabling Test Util.)

Procedure
1. Start ClaimCenter.
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]
ui/
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.

Test Util API endpoints

The Test Util API provides endpoints that help with development and testing.

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.

The following table lists the endpoints in the Test Util API that are used most often, and where you can go to get more
information about them.

442 The Test Util API

 Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

Description Endpoint More information

Create a test policy POST /test-util/v1/policies “Creating test policies” on page 149

The Test Util API 443

Guidewire ClaimCenter for Guidewire Cloud 2024.11 Cloud API Consumer Guide

444 The Test Util API