CloudAPI Consumer

Guidewire ClaimCenter™
for Guidewire Cloud
Cloud API Consumer Guide

Release: 2023.06
© 2023 Guidewire Software, Inc.
For information about Guidewire trademarks, visit https://www.guidewire.com/legal-notices.
Guidewire Proprietary & Confidential — DO NOT DISTRIBUTE
Product Name: Guidewire ClaimCenter for Guidewire Cloud

Product Release: 2023.06
Document Name: Cloud API Consumer Guide
Document Revision: 01-December-2023
Guidewire ClaimCenter for Guidewire Cloud 2023.06 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............................................................................................................................................45
Overview of query parameters........................................................................................................................ 45
Viewing query parameter definitions.......................................................................................................46
The fields query parameter.............................................................................................................................. 46
Contents 3
Tutorial: Send a GET with the fields parameter........................................................................................49

The filter query parameter............................................................................................................................... 49
Endpoints with default filters................................................................................................................... 51
Tutorial: Send a GET with the filter parameters....................................................................................... 51
The sort query parameter................................................................................................................................ 52
Tutorial: Send a GET with the sort query parameter................................................................................53
The pagination query parameters.................................................................................................................... 54
pageSize limits the number of resources per page.................................................................................. 54
The self link returns a single resource in a page.......................................................................................55
pageOffset pages through resources........................................................................................................55
includeTotal retrieves the total number of resources.............................................................................. 56
Tutorial: Send a GET with the pageSize and totalCount parameters........................................................ 56
Query parameters for included resources........................................................................................................57
Specifying query parameters that apply to an included resource............................................................57
Summary of query parameters for included resources............................................................................ 58
Tutorial: Send a GET with query parameters for included resources....................................................... 59
Query parameters for POSTs and PATCHes.......................................................................................................60
4 POSTs............................................................................................................................................................... 61
Overview of POSTs........................................................................................................................................... 61
Standardizing payload structures..................................................................................................................... 62
Viewing request schemas......................................................................................................................... 63
View a request schema in Swagger UI......................................................................................................63
Designing a request payload............................................................................................................................ 63
Request payload structure....................................................................................................................... 63
Determining the minimum creation criteria............................................................................................ 64
Specifying scalar values............................................................................................................................ 64
Specifying compound values.................................................................................................................... 65
Setting values and objects to null.............................................................................................................66
Sending POSTs.................................................................................................................................................. 66
Send a POST using Postman..................................................................................................................... 66
Tutorial: Create a new note that specifies required fields only................................................................67
Tutorial: Create a new note that specifies optional fields........................................................................ 68
Responses to a POST........................................................................................................................................ 69
Postman behavior with redirects..................................................................................................................... 69
Business action POSTs...................................................................................................................................... 69
Improving POST performance.......................................................................................................................... 70
5 PATCHes........................................................................................................................................................... 73
Overview of PATCHes....................................................................................................................................... 73
The PATCH payload structure........................................................................................................................... 73
Designing a request payload.................................................................................................................... 74
PATCHes and arrays.......................................................................................................................................... 74
Sending PATCHes.............................................................................................................................................. 74
Send a PATCH using Postman................................................................................................................... 74
Tutorial: PATCH an activity........................................................................................................................ 75
Responses to a PATCH...................................................................................................................................... 76
PATCHes and lost updates................................................................................................................................ 76
Postman behavior with redirects..................................................................................................................... 76
6 DELETEs............................................................................................................................................................ 77
Overview of DELETEs........................................................................................................................................ 77
Tutorial: DELETE a note............................................................................................................................ 77
DELETEs and lost updates.................................................................................................................................78
4 Contents
7 Request headers.............................................................................................................................................. 79
HTTP headers................................................................................................................................................... 79
Overview of Cloud API headers................................................................................................................ 79
Send a request with a Cloud API header using Postman..........................................................................81
Language and locale......................................................................................................................................... 82
Preventing duplicate database transactions.................................................................................................... 83
Sticky sessions in clustered environments....................................................................................................... 83
Warming up an endpoint................................................................................................................................. 85
Handling a call with unknown elements.......................................................................................................... 85
Validating response payloads against additional constraints........................................................................... 85
Part 2
Optimizing calls.......................................................................................................................................87
8 Reducing the number of calls.......................................................................................................................... 89

Features that execute multiple requests at once............................................................................................. 89
Comparing features that execute multiple requests................................................................................ 89
Determining which feature to use............................................................................................................90
9 Composite requests......................................................................................................................................... 91
Constructing composite requests.....................................................................................................................91
The requests section................................................................................................................................ 92
Using variables to share information across subrequests........................................................................ 93
Responses to the subrequests..................................................................................................................94
The selections section.............................................................................................................................. 96
Composite request limitations................................................................................................................. 98
Composite request examples................................................................................................................... 99
Administering composite requests...................................................................................................................99
Error handling...........................................................................................................................................99
Logging................................................................................................................................................... 100
Configuring the maximum number of subrequests............................................................................... 101
Complete composite request syntax.............................................................................................................. 101
10 Request inclusion.......................................................................................................................................... 103
Syntax for simple parent/child relationships.................................................................................................. 103
Syntax for named relationships...................................................................................................................... 105
Additional behaviors with write inclusion...................................................................................................... 106
Additional behaviors with read inclusion....................................................................................................... 107
11 Batch requests............................................................................................................................................... 109
Batch request syntax...................................................................................................................................... 109
Optional subrequest attributes.............................................................................................................. 110
Batch request examples................................................................................................................................. 110
Simple batch requests............................................................................................................................ 110
Batch requests with query parameters.................................................................................................. 111
Batch requests with request payloads................................................................................................... 111
Batch requests with distinct operations................................................................................................. 112
Administering batch requests........................................................................................................................ 112
Specifying subrequest headers.............................................................................................................. 112
Specifying onFail behavior......................................................................................................................113
Configuring the maximum number of subrequests............................................................................... 113
12 Lost updates and checksums......................................................................................................................... 115
Lost updates................................................................................................................................................... 115
Checksums..................................................................................................................................................... 116
Contents 5
Checksums for PATCHes and business action POSTs...................................................................................... 117

Tutorial: PATCH an activity using checksums.......................................................................................... 117
Tutorial: Assign an activity using checksums.......................................................................................... 118
Checksums for DELETEs..................................................................................................................................119
Send a checksum in a request header using Postman........................................................................... 119
Tutorial: DELETE a note using checksums...............................................................................................119
13 Asynchronous calls........................................................................................................................................ 123
Overview of asynchronous calls..................................................................................................................... 123
Determining when the call has been processed.................................................................................... 125
Retrieving the response using /requests/{asyncRequestId}...................................................................126
Retrieving the response from /requests/{asyncRequestId}/response................................................... 127
Sending a request asynchronously................................................................................................................. 128
Tutorial: Send a request asynchronously................................................................................................129
Retrieving the response to the original request.............................................................................................129
Response information in the /requests response.................................................................................. 129
Response information using the /response endpoint............................................................................ 130
Tutorial: Retrieve information about an asynchronous request.............................................................130
Waiting for a response synchronously........................................................................................................... 131
Tutorial: Send a request asynchronously with a wait time.....................................................................131
Asynchronous request administration........................................................................................................... 132
Part 3
Business flows: FNOL and adjudication.....................................................................................135
14 Executing FNOL.............................................................................................................................................. 137

The FNOL process in ClaimCenter.................................................................................................................. 137
Draft claims and open claims................................................................................................................. 137
Verified and unverified policies.............................................................................................................. 138
The FNOL process in Cloud API...................................................................................................................... 138
The Cloud API FNOL process.................................................................................................................. 138
FNOL use cases by policy state............................................................................................................... 139
Composite request limitations with claims............................................................................................ 140
Canceling claims..................................................................................................................................... 141
Claim modes........................................................................................................................................... 141
The Test Util API............................................................................................................................................. 141
Enabling the Test Util API....................................................................................................................... 141
View the Test Util API in Swagger UI...................................................................................................... 142
Creating test policy data.........................................................................................................................142
Tutorial: Creating a policy using the Test Util API................................................................................... 146
Creating test data for related objects.....................................................................................................146
POSTing a minimal draft claim....................................................................................................................... 146
Tutorial: POSTing a minimal draft claim for personal auto.....................................................................147
PATCHing a draft claim....................................................................................................................................148
Tutorial: PATCHing a draft claim for personal auto................................................................................. 148
POSTing a typical draft claim.......................................................................................................................... 149
Tutorial: POSTing a typical draft claim for personal auto....................................................................... 149
Creating claims with unverified policies......................................................................................................... 150
Minimum criteria for an unverified policy and claim............................................................................. 150
Contacts on an unverified policy............................................................................................................ 151
Locations on an unverified policy........................................................................................................... 152
Risk units on an unverified policy........................................................................................................... 154
6 Contents
Coverages on unverified policies............................................................................................................ 155

PATCH an unverified policy..................................................................................................................... 158
Retrieving information about an unverified policy.................................................................................158
Submitting a draft claim................................................................................................................................. 159
Minimum criteria for submitting a claim with an unverified policy....................................................... 160
Tutorial: Submitting a draft claim........................................................................................................... 161
Canceling a draft claim................................................................................................................................... 161
Sample payload addendum............................................................................................................................161
Sample policy payload............................................................................................................................ 162
Sample draft claim payload.................................................................................................................... 163
Sample composite claim payload........................................................................................................... 164
Sample composite first-and-final........................................................................................................... 171
15 Claims.............................................................................................................................................................175
Querying for claims associated with you........................................................................................................175
Querying for a claim by claim ID.................................................................................................................... 177
Searching for active and archived claims....................................................................................................... 177
Request payload for a claim search........................................................................................................ 178
Response payload for a claim search..................................................................................................... 180
Retrieving policy information......................................................................................................................... 182
Summary of the policy endpoints.......................................................................................................... 182
Assigning claims............................................................................................................................................. 184
Validating claims.............................................................................................................................................185
ClaimCenter validation levels................................................................................................................. 185
Validating a claim through Cloud API..................................................................................................... 186
Retrieving claims from archive....................................................................................................................... 188
Closing claims................................................................................................................................................. 188
16 ClaimContacts................................................................................................................................................ 191
Overview of ClaimContacts in Cloud API........................................................................................................ 192
ClaimContact roles......................................................................................................................................... 194
Querying for ClaimContacts........................................................................................................................... 195
Creating new ClaimContacts.......................................................................................................................... 196
Creating a new ClaimContact with a reserved role................................................................................ 196
Creating a new ClaimContact with a non-reserved role.........................................................................199
Working with contacts from the policy.......................................................................................................... 200
Copying vendor contacts from ContactManager........................................................................................... 201
PATCHing ClaimContacts................................................................................................................................ 202
Assigning roles to existing ClaimContacts...................................................................................................... 202
Deleting ClaimContacts.................................................................................................................................. 204
Additional behaviors...................................................................................................................................... 204
Masking the taxID field...........................................................................................................................204
Role constraint endpoints...................................................................................................................... 205
Role owners endpoint............................................................................................................................ 206
17 Incidents........................................................................................................................................................ 209
Overview of incidents in ClaimCenter............................................................................................................ 209
Overview of incidents in Cloud API................................................................................................................ 210
Fixed property incidents.................................................................................................................................212
Managing fixed property incidents........................................................................................................ 213
Managing dwelling incidents..................................................................................................................213
Managing other structure incidents.......................................................................................................214
General incidents........................................................................................................................................... 215
Injury incidents...............................................................................................................................................216
Contents 7
Living expenses incidents............................................................................................................................... 217

Mobile property incidents..............................................................................................................................217
Baggage incidents...................................................................................................................................217
Property contents incidents................................................................................................................... 219
Vehicle incidents.................................................................................................................................... 221
Trip incidents.................................................................................................................................................. 222
Overview of trip incidents...................................................................................................................... 222
Managing trip incidents......................................................................................................................... 222
Managing trip accommodations............................................................................................................ 223
Managing trip segments.........................................................................................................................223
18 Exposures....................................................................................................................................................... 225
Overview of exposures in ClaimCenter.......................................................................................................... 225
Overview of exposures in Cloud API.............................................................................................................. 227
Creating exposures......................................................................................................................................... 228
Minimum creation criteria..................................................................................................................... 228
Building an exposure payload................................................................................................................ 229
Step 1: Identify the coverage type......................................................................................................... 229
Step 2: Identify the coverage subtype....................................................................................................230
Step 3: Create or identify the claimant.................................................................................................. 230
Step 4: Create or identify the incident................................................................................................... 231
Step 5: Identify the coverage................................................................................................................. 232
Querying for and modifying exposures.......................................................................................................... 233
Assigning exposures....................................................................................................................................... 233
Additional exposure endpoints...................................................................................................................... 235
Deleting draft exposures........................................................................................................................ 235
Validating exposures.............................................................................................................................. 235
Closing exposures................................................................................................................................... 235
19 Service requests.............................................................................................................................................237
Overview of service requests in ClaimCenter.................................................................................................237
Service request kinds............................................................................................................................. 238
The service request lifecycle.................................................................................................................. 238
Invoices for service request....................................................................................................................240
Overview of service requests in the Cloud API.............................................................................................. 240
Service request APIs and vendor portals................................................................................................240
Required service request data model.................................................................................................... 241
Service request numbers........................................................................................................................241
Support for each service request kind................................................................................................... 241
Composite request limitations with service requests............................................................................ 242
Querying for service requests........................................................................................................................ 242
Creating service requests............................................................................................................................... 242
Minimum creation criteria..................................................................................................................... 242
Modifying existing service requests............................................................................................................... 244
PATCHing service requests......................................................................................................................244
Assigning service requests to users........................................................................................................ 245
Advancing a service request in its lifecycle.................................................................................................... 246
Submitting, accepting, and declining service requests.......................................................................... 247
Completing and canceling service requests........................................................................................... 248
Service request quotes................................................................................................................................... 249
Service request invoices................................................................................................................................. 251
Querying for invoices............................................................................................................................. 251
Creating invoices for service requests.................................................................................................... 251
8 Contents
Approving service request invoices........................................................................................................ 252

Marking invoices as paid........................................................................................................................ 252
Withdrawing service request invoices....................................................................................................253
20 Matters.......................................................................................................................................................... 255
Query for matters........................................................................................................................................... 255
Creating matters.............................................................................................................................................256
PATCHing matters........................................................................................................................................... 256
Assigning matters........................................................................................................................................... 257
Assignment options................................................................................................................................ 257
Assignment examples............................................................................................................................. 257
Closing and reopening matters...................................................................................................................... 258
Part 4
Business flows: Financials...............................................................................................................261
21 Reserves......................................................................................................................................................... 263
Overview of reserves in ClaimCenter............................................................................................................. 263
Querying for reserves..................................................................................................................................... 264
Creating reserves............................................................................................................................................266
Example of creating reserves................................................................................................................. 267
Example of adding to reserves............................................................................................................... 268
Acknowledging reserve transactions..............................................................................................................268
22 Creating checks.............................................................................................................................................. 271
Querying for check sets and checks............................................................................................................... 272
POSTing checks...............................................................................................................................................274
Check creation in ClaimCenter............................................................................................................... 274
Check creation through Cloud API..........................................................................................................274
Example of creating a minimal check set............................................................................................... 276
Recurrences....................................................................................................................................................277
Recurrences in ClaimCenter................................................................................................................... 277
Recurrences in Cloud API....................................................................................................................... 277
Sending checks every X months on the Nth day.................................................................................... 277
Sending checks every X months on the Nth dayOfWeek....................................................................... 278
Sending checks every X weeks on dayOfWeek....................................................................................... 278
Deductible handling....................................................................................................................................... 279
Deductible handling in ClaimCenter.......................................................................................................279
Deductible handling in Cloud API........................................................................................................... 279
Underpaying and overpaying deductibles.............................................................................................. 281
PATCHing checks............................................................................................................................................. 281
DELETEing checks........................................................................................................................................... 281
23 Managing the check life cycle....................................................................................................................... 283
The check life cycle prior to submission......................................................................................................... 283
Advancing a check to submission through Cloud API.............................................................................284
The check life cycle after submission............................................................................................................. 284
Advancing a check beyond submission through Cloud API.................................................................... 286
Acknowledging payment transactions........................................................................................................... 286
24 Recoveries and recovery reserves................................................................................................................. 289
Querying for recoveries and recovery reserves............................................................................................. 290
Creating recoveries and recovery reserves.................................................................................................... 291
Creating a recovery reserve....................................................................................................................291
Creating a recovery reserve set.............................................................................................................. 292
Contents 9
Acknowledging a recovery reserve.........................................................................................................293

Creating a recovery................................................................................................................................ 293
25 Multicurrency................................................................................................................................................ 295
Multicurrency overview................................................................................................................................. 295
Multicurrency in ClaimCenter................................................................................................................ 295
Multicurrency in Cloud API.....................................................................................................................295
Retrieving multicurrency information............................................................................................................ 296
Multicurrency reserves.......................................................................................................................... 296
Multicurrency checks............................................................................................................................. 297
POSTing multicurrency information............................................................................................................... 298
POSTing a reserve with multiple currencies........................................................................................... 298
POSTing a reserve with a custom exchange rate....................................................................................298
POSTing a check set with multiple currencies........................................................................................ 299
POSTing a check set with a custom exchange rate................................................................................. 300
Specifying multicurrency line items....................................................................................................... 301
Additional exchange rate schema fields................................................................................................. 303
Part 5
Business flows: Framework APIs.................................................................................................. 305
26 Activities........................................................................................................................................................ 307
Querying for activities.................................................................................................................................... 307
Creating activities........................................................................................................................................... 309
Assigning activities......................................................................................................................................... 310
Assignment options................................................................................................................................ 310
Assignment examples............................................................................................................................. 311
Retrieving recommended assignees.......................................................................................................312
Closing activities............................................................................................................................................. 313
Additional activity functionality..................................................................................................................... 315
27 Documents..................................................................................................................................................... 317
Overview of documents................................................................................................................................. 317
Querying for document information.............................................................................................................. 318
Querying for document metadata..........................................................................................................318
Querying for document content.............................................................................................................318
POSTing documents....................................................................................................................................... 319
POSTing documents using Postman....................................................................................................... 321
PATCHing documents..................................................................................................................................... 322
Sending document metadata only using JSON...............................................................................................323
DELETEing documents.................................................................................................................................... 323
28 Notes.............................................................................................................................................................. 325
Querying for notes......................................................................................................................................... 325
Creating claim notes.......................................................................................................................................326
Additional notes functionality........................................................................................................................ 327
29 Users and groups........................................................................................................................................... 329
Users.............................................................................................................................................................. 329
Querying for user information............................................................................................................... 329
Creating users.........................................................................................................................................330
Updating users....................................................................................................................................... 331
Deleting users.........................................................................................................................................331
Groups............................................................................................................................................................ 332
Querying for groups............................................................................................................................... 332
10 Contents
Creating groups...................................................................................................................................... 332

Assigning users to groups....................................................................................................................... 333
Updating groups..................................................................................................................................... 335
Deleting groups...................................................................................................................................... 335
Queues........................................................................................................................................................... 335
Working with queues............................................................................................................................. 336
User roles....................................................................................................................................................... 337
Querying for user roles...........................................................................................................................337
Creating user roles................................................................................................................................. 339
Updating user roles................................................................................................................................ 340
Authority limit profiles................................................................................................................................... 341
Retrieving information about authority limit profiles............................................................................ 341
Creating authority limit profiles............................................................................................................. 342
Adding limits to the profile.....................................................................................................................343
Updating authority limit profiles............................................................................................................ 344
30 Security zones................................................................................................................................................ 347
Querying for security zones........................................................................................................................... 347
Creating security zones.................................................................................................................................. 348
Modifying and deleting security zones.......................................................................................................... 348
Associating security zones with other objects............................................................................................... 349
31 Geographic zones.......................................................................................................................................... 351
32 Typelist metadata.......................................................................................................................................... 353
The /typelists endpoints.................................................................................................................................353
Querying with typekey filters......................................................................................................................... 353
Tutorial: Query for typelist metadata............................................................................................................. 355
33 Batch processes............................................................................................................................................. 357
Overview of batch processes......................................................................................................................... 357
Querying for batch process information........................................................................................................ 358
Managing batch processes............................................................................................................................. 359
Starting a batch process......................................................................................................................... 359
Starting a batch process with arguments............................................................................................... 360
Stopping a batch process....................................................................................................................... 361
34 Database consistency checks........................................................................................................................ 363
Overview of database consistency checks (DBCCs)........................................................................................363
Running DBCCs............................................................................................................................................... 364
Running a previously run DBCC.............................................................................................................. 365
Querying for DBCC run information............................................................................................................... 366
Contents 11
12 Contents
Support
For assistance, visit the Guidewire Community.
Guidewire customers
https://community.guidewire.com
Guidewire partners
https://partner.guidewire.com
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

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:

Admin API for administration objects, such as users and groups /admin/v1
Introduction to Cloud API 17


API List API for listing the available APIs /apis
Async API for retrieving responses to asynchronously processed /async/v1
calls
Common API for common InsuranceSuite platform objects, such as /common/v1
activities and notes
Contact API for contacts /contact/v1
Note: The /apis endpoint returns all REST APIs for ContactManager. This includes some APIs that are not
part of Cloud API, such as /system/v0/database and /system/v0/maintenance. The only APIs that are part
of Cloud API are the ones listed in the previous table. These are the only APIs that have access to Cloud API
features, such as request inclusion and authentication.
You can use the API path to view metadata about the API. This is discussed in detail in the following section.
Version numbers for major and minor releases

The following section defines what a minor release is. Minor releases are not expected to have "breaking changes".
The types of changes that do and do not fall into the definition of "breaking change" are described in the Schema
Backwards Compatibility Contract. To access a copy of this contract, consult your Guidewire representative.
Release numbers
Every release of Cloud API has a three-digit version number. The first digit is the version's major release number. The
second digit is the version's minor release number. For example, suppose the latest release of Cloud API has a version
number of 1.5.0. This release is major release 1 and minor release 5.
The release number can be seen in the API definition. For example, in Swagger UI, when you view an API, the version
number appears in a gray bubble next to the API name. (Note that individual APIs do not have distinct version
numbers. The version numbers that appear in the API definition are for the entire Cloud API release.)
For every API, the major release number is also part of the endpoint path. It is the number that appears after the "/v".
For example, the first major release of the Admin API has a path of /admin/v1. If there was a theoretical ninth major
release of the Admin API, its path would be /admin/v9.
Minor and major releases

In future releases, Cloud API functionality is expected to change. To define and control these changes, Guidewire
defines the scope of change that can be added to each release.
• In a minor version release, the functionality is either identical to the previous release or additive.
• In a major version release, the functionality has changed from the previous release.
A given release of ClaimCenter can have multiple major versions of Cloud API. For example, suppose that in a given
year there were the following releases:
• The January release is the first new major release.
• The April release is 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

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

View definitions using Swagger UI

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “List of APIs in Cloud API” on page 17.)
2. Start ClaimCenter.
3. In a web browser, enter the URL for Swagger UI. This loads the Swagger UI tool.
• The format of the URL is <applicationURL>/resources/swagger-ui/
• For example, for a local instance of ClaimCenter, use: http://localhost:8080/cc/resources/swagger-
ui/
4. In the text field at the top of the Swagger UI interface, enter the URL that points to the desired API's
swagger.json file. Then, click Explore.
• The format of the URL is <applicationURL>/rest<APIpath>/swagger.json.
• For example, to view the common API, enter: <applicationURL>/rest/common/v1/swagger.json
Results
The following screenshot shows the top of the Swagger UI display of the Common API.
Information in Swagger UI
The Cloud API version number at the top in a gray bubble after the API name. (Note that individual APIs do not have
distinct version numbers. The version numbers that appear in Swagger UI are for the entire Cloud API release.)
Every endpoint in the API appears in a list. For each API, the following information is shown by default:
• The endpoint's operation (such as GET)
• The endpoint's path (such as /activities)
• An endpoint summary (such as "Returns a list of activities assigned to the current user")
If you click the operation button, additional information about the endpoint appears. This includes:

• A more detailed endpoint description

• A list of query parameters supported by the endpoint
• A hierarchical list of resources and schemas used by the endpoint (This appears in the Responses section on the
Model tab.)
The API definition endpoints and Postman

In some situations, it is useful to view the raw API definition information. In Cloud API, every API includes two
endpoints that return the API definition: /openapi.json and /swagger.json.
• /openapi.json returns the API definition using the OpenAPI 3.0 specification, often referred to as "OpenAPI 3.0"
• /swagger.json 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 /swagger.json endpoint) or the OpenAPI 3.0
specification (using the /openapi.json 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 /openapi.json endpoint. For example, Guidewire-
proprietary tags (such as x-gw-typelist) are listed in the /openapi.json response, but not in the /swagger.json
response. However, some tools used to render API metadata may not be robust enough to process information using the
OpenAPI 3.0 specification. The /swagger.json 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 https://www.postman.com/.
View definitions using Postman
Before you begin
Install Postman. For more information and to download the tool, see https://www.postman.com/.
About this task
This task does not involve authentication information. This is because every type of caller can request API metadata,
including unauthenticated callers.

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “List of APIs in Cloud API” on page 17.)
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>/openapi.json (or
<applicationURL>/rest<APIpath>/swagger.json). For example, to view the Common API on a local instance
of ClaimCenter, enter the following:
• http://localhost:8080/cc/rest/common/v1/openapi.json (OR http://localhost:8080/cc/rest/common/v1/
swagger.json)
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 openapi.json 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 /openapi.json endpoints

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

For example, the following HTTP request retrieves the metadata for the Admin API. It also enables filterByUser and
prettyPrint.
http://localhost:8080/cc/rest/admin/v1/openapi.json?filterByUser=true&prettyPrint=true
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.
http://localhost:8080/cc/rest/admin/v1/openapi.json?enablePolymorphism=false
(For more information on openapi-generator, see https://github.com/OpenAPITools/openapi-generator/.)
The Guidewire API References site

Guidewire Documentation hosts copies of the API references at the following URL:
https://docs.guidewire.com/apiReferences/
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 /openapi.json
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 https://docs.guidewire.com/apiReferences/. 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 /openapi.json
endpoint. This endpoint returns the API definition using the OpenAPI 3.0 specification.
Every endpoint in the API appears in the left-hand pane. To view information about a specific endpoint, click the
endpoint name. This causes information about the endpoint to be shown in the center pane.
The middle pane shows general information about the endpoint, such as:
• The endpoint's operation (such as GET)
• The endpoint's path (such as /activities)

• An endpoint summary (such as "Returns a list of activities assigned to the current user")
The right pane shows Response samples. You can expand the data.attributes 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.

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",
},
"dueDate": "2020-11-16T08:00:00.000Z",
"id": "xc:20",
"priority": {
"code": "urgent",
"name": "Urgent"
"subject": "Contact claimant"
}
Note that a field can store:

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

Endpoints
Every API consists of a set of endpoints. An endpoint is a command that a caller application can use to request data
from or trigger action in ClaimCenter. For example, the /common/v1/activities endpoint can be used to either
request data about ClaimCenter activities or trigger actions related to ClaimCenter activities. When referenced in
documentation, endpoints start with a slash (/), such as the /activities endpoint. Endpoints are defined in Swagger
schema files.
In Cloud API, the endpoint path (the full name of the endpoint) includes the API and the version. For convenience
sake, the documentation often refers to endpoints using only the last part of the endpoint path. For example, the /rest/
common/v1/activities endpoint is often referred to simply as "the /activities endpoint".
Endpoints in Cloud API have four fundamental components: root resources, child resources, methods, and paths.
Root resources
Every endpoint has a root resource. The root resource is the resource which the endpoint creates, updates, deletes, or
queries for. Every call to an endpoint makes use of the root resource.
For example, the root resource for the /common/v1/activities endpoint is Activity. This endpoint is used to
potentially create, update, delete, or queries for activities.
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.
• 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.
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:
https://iap:8880/xc/rest/common/v1/activities/xc:207?fields=assignedGroup
\__________________/\______________________________/\___________________/
application URL endpoint path query parameters
• Application URL - The URL to the InsuranceSuite application.

◦ This value is required.
• Endpoint path - The path to the specific endpoint that the request is requesting.
◦ This value is required.
◦ Endpoint paths end either with a resource name (such as .../activities) or the ID of a specific element (such
as .../activities/xc:207 in the example above). The ID of a specific element is also referred to as a path
parameter.
• Query parameters - This is a set of query parameters that further defines the data that is desired in the response.
For most endpoints, query parameters are optional.
◦ For example, when you add ?fields=assignedGroup, you are specifying that the only field you want returned
in the response is the assignedGroup field.
Some requests require a payload. The payload is a block of JSON-formatted text that contains information about one or
more resources associated with the operation. Typically:

• GETs and DELETEs do not require request payloads.

◦ For a GET, you only need to identify the resource you want information about, and this is done in the URL.
◦ For a DELETE, you only need to identify the element to delete, and this is done in the URL.
• POSTs and PATCHes do require request payloads.
◦ For a POST, you must specify data about the element to create.
◦ For a PATCH, you must specify the data about the element that must be updated.
Responses
A response is the set of information returned by an API endpoint for a request to the caller application.
Some responses include a payload. The payload contains information about one or more resources that are returned by
the operation. For example, for a request to get all open activities assigned to a given user, the response includes a
payload with information about the open activities. For more information about the payload structure, see “GETs” on
page 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 https://www.postman.com/.
Note: Swagger UI also has the capability to send requests to a working endpoint and observe responses.
However, Guidewire recommends using Swagger UI only to view API definitions. The APIs in Cloud API are
significantly robust. When sending requests using Swagger UI, the performance time for getting responses can
be unacceptably long. Also, if you attempt to send calls from Swagger UI and log into the ClaimCenter user
interface on the same machine, the two systems may attempt to share the same session, and either or both may
stop working. For more information on recommended request tools, see “Requests and responses” on page 28.
Tutorial: Set up your Postman environment

The Cloud API documentation contains a set of tutorials that guide you through examples of how to send requests and
review the responses. All of these tutorials assume the following base environment:
• A default instance of ClaimCenter installed on your machine that contains only the Demo sample data set.

• An instance of Postman.
This tutorial walks you through the process of setting up this environment.
If your instance of ClaimCenter is installed on a different machine, you will need to adjust the endpoint URLs provided
in the tutorials. Also, if you create data in addition to the Demo sample data, then your responses may differ from the
ones described in the tutorials.
Tutorial steps
1. Install Postman. (For more information, refer to https://www.postman.com/.)
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.
5. In the Enter request URL field, enter the following URL: http://localhost:8080/cc/rest/common/v1/
activities
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": {
},
"assignedUser": {
},
...
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 http://localhost:8080/cc/rest/common/v1/activities.

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": "gw.api.rest.exceptions.NotFoundException",
"userMessage": "No resource was found at path /common/v1/activities"


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 45.
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 straight-forward. The
call may require query parameters, but GETs do not require a request payload. The majority of the work lies in parsing
the response payload. The remainder of this topic discusses how response payloads are structured and how developers
can learn about response payload formats.
Standard payload structures

The endpoints in Cloud API have standard structures for both request payloads and response payloads. The structures
are defined by data envelopes, and by request and response schemas.
Standard information common to all endpoints

A data envelope is a wrapper that wraps JSON sent to or returned from a REST API. To maintain a standard payload
structure, Cloud API uses two data envelopes: DataEnvelope and DataListEnvelope.
GETs 33
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 },
...
],
"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
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
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
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.
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.
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 http://localhost:8080/cc/rest/common/v1/
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": {
"assignedGroup": {
},
"assignedUser": {
},
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
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
... },
"links": { ... } # Resource 2 links
... ], # 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 46.
GETs 37
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:ss.fffZ
• 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 46.
Broadly speaking, there are four types of inlined resources: typelists, monetary amount values, simple references, and
complex references.
38 GETs
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": {
},
"assignedUser": {
},
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 115.
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
"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
• Details about the included resources appear at the end of the payload in a section called included.
The ids of included objects appear in both the related section and the included section. You can use these ids to
match a primary resource with details about its included resources.
Contrasting included resources and inlined resources

A response payload can contain two types of resources that have a relationship to the root resources: inlined resource
and included resources. The following table contrasts the two types of resources.
Resource How many related resources Where do their fields When do they appear?
type for each primary resource? appear?
Inlined Typically one. (For example, Entirely in the attributes If the query does not use the fields query
resource every activity has only one section of the root resource parameter, then each inlined resource appears only if
related assignedUser.) it is one of the default attributes.
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

Tutorial steps
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 http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:1?include=contacts
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 http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:1?include=mainContact
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
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
... },
"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
] } }
"attributes": { # Recourse 2 name/value pairs
... },
"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
] } }
... ], # 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
"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",
},
"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
Including either a collection or a specific resource

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

For each endpoint, you can determine the resources that can be included by referring to the API definition for the
endpoint. There will be a data envelope in the model whose name ends with ...Inclusions. This data envelope lists
all the resources that can be included when querying for that type of resource.
For example, in the Common API, the model for GET /activities references an ActivityResponseInclusions
element. This element has a single child element - Note. This means that the only type of element you can include on
an activity query is notes.
If you attempt to include a resource type that a given endpoint does not support for inclusion, the API returns a 400
error code and message. For example, the following is the message if you attempt to do a GET /activities?
include=users:
"userMessage": "Bad value for the 'include' query parameter - The requested
inclusions '[users]' are not valid for this resource. The valid options are [notes]."
44 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.
• “Tutorial: Send a GET with the fields parameter” on page 49
• “Tutorial: Send a GET with the filter parameters” on page 51
• “Tutorial: Send a GET with the sort query parameter” on page 53
• “Tutorial: Send a GET with the pageSize and totalCount parameters” on page 56
• “Tutorial: Send a GET with query parameters for included resources” on page 59
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 45
• 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 57.
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 57.
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".
46 Query parameters
• *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": {
Query parameters 47
"assignedGroup": {
},
"assignedUser": {
},
"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": {
},
"assignedUser": {
}
}
You can also specify specific subfields using the following syntax:
fields=inlinedResourceName.fieldName
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=assignedGroup.id,assignedUser.id
This would return:
"attributes": {
"assignedGroup": {
},
"assignedUser": {
}
}
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.
48 Query parameters
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 57.
Tutorial: Send a GET with the fields parameter

Tutorial steps
2. Enter the following and click Send:
GET http://localhost:8080/cc/rest/common/v1/activities
3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
GET http://localhost:8080/cc/rest/common/v1/activities?fields=id,subject
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 49
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
Determining which values you can filter on

For a given endpoint, you can identify the attributes that are filterable by reviewing the schema definition. If a field is
filterable, then the schema definition of the field includes the text: "filterable": true.
For example, the following is the schema description from Swagger UI for two fields returned by the Common API's /
activities endpoint.
escalated boolean
readOnly: true
x-gw-extensions: OrderedMap { "filterable": true, "sortable": true }
escalationDate string($date-time)
x-gw-nullable: true
Note that the escalated field includes the "filterable": true expression, but the escalationDate field does not.
This means that you can filter on escalated, but not escalationDate.
50 Query parameters
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
Endpoints with default filters

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

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

Query parameters 51
Tutorial steps
3. Specify Basic Auth authorization using user aapplegate and password gw.
GET http://localhost:8080/cc/rest/common/v1/activities?filter=priority:eq:high
Checking your work

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

For endpoints that return collections, you can sort the elements in the collection. To do this, use:
sort=propertiesList
where propertiesList is a comma-delimited list of properties that support sorting for that endpoint.
For example, the following query returns all activities and sorts them by due date:
GET /activities?sort=dueDate
You can specify multiple sort properties. Resources are sorted based on the first property. Any resources with the same
value for the first property are then sorted by the second property, and so on. For example, the following query returns
all activities assigned to the current caller and sorts them first by escalation status and then by due date:
GET /activities?sort=escalated,dueDate
You can also use the sort query for related resources added through the include parameter. For more information, see
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
52 Query parameters
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-1.0.apiconfig.yaml. Custom default sorts
(which could either be overrides of base configuration sort orders or sort orders for custom endpoints) are defined in
shared_ext-1.0.apiconfig.yaml. Both of these apiconfig.yaml 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-1.0.apiconfig.yaml where the default sort order for Activities is defined.
resources:
...
Activities:
resource: gw.rest.core.pc.common.v1.activity.ActivitiesCoreResource
defaultSort:
- priority
- subject
In the defaultSort section, every field is preceded by a hyphen and a space (- ). This first hyphen does not indicate
descending order. If a field has a default descending order, then the field name is preceded by a second hyphen and
surrounded by quotation marks. For example, a default sort on priority in descending order would appear as - "-
priority".
As discussed in the previous section, you can use the sort query parameter to override the default sort for a collection.
You can also remove the default sort order by specifying ?sort=*none. When you do this, results are sorted based on
their id value. This may improve performance when you are retrieving a large amount of information from an endpoint
with a default sort order and the column that the sort is based on is not indexed.
For example:
• GET /common/v1/activities returns activities using the default sort (priority and then subject).
• GET /common/v1/activities?sort=priority returns activities sorted by priority only.
• 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
Tutorial: Send a GET with the sort query parameter

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
GET http://localhost:8080/cc/rest/common/v1/activities?fields=id,dueDate
Query parameters 53
GET http://localhost:8080/cc/rest/common/v1/activities?fields=id,dueDate&sort=dueDate
Checking your results

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

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

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

GET /activities?pageSize=20
Every resource type has a default pageSize. This value is used when the query does not specify a pageSize. You can
specify a pageSize less than or greater than the default pageSize.
Also, every resource has a maximum pageSize, and you cannot execute a query with a pageSize larger than the
maximum.
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 apiconfig.yaml file. (For example, in claim-1.0.apiconfig.yaml, 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
54 Query parameters
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"
Query parameters 55
]
}
}
To access a collection that starts with a specific resource, Cloud API uses a pageOffset parameter. This parameter is
used in the prev and next links for a collection. The pageOffset index starts with 0, so a theoretical pageOffset=0
would start with the first element and pageOffset=5 skips the first 5 elements and starts with the sixth.
There can be some complexity involved in determining how to construct a link with the correct pageOffset value.
Therefore, Guidewire recommends that you use the prev and next provided in response payloads and avoid
constructing pageOffset queries of your own.
includeTotal retrieves the total number of resources

When querying for data, you can get the total number of resources that meet the criteria. To get this number, use the
following syntax:
includeTotal=true
When you submit this query parameter, the payload includes an additional total value that specifies the total. For
example:
"total": 72
When the includeTotal query parameter is used, the response payload contains two counting values:
• count - The number of resources returned in this page.
• total - The total number of resources that meet the query's criteria.
If the total number of resources that meet the criteria is less than or equal to the pageSize, then count and total are
the same. If the total number of resources that meet the criteria is greater than the pageSize, then count is less than
total. count can never be greater than total.
For performance reasons, Guidewire will count the total number of items up to 1000 only. When the total value is
stated as 1000, the actual count could be 1000 or some number greater than 1000.
Note: If the number of resources to total is sufficiently large, using the includeTotal parameter can affect
performance. Guidewire recommends you use this parameter only when there is a need for it, and only when
the number of resources to total is unlikely to affect performance.
In some situations, you may be interested in retrieving only the total number of resources that meet a given criteria,
without needing any information from any specific resource. However, a GET cannot return only an included total. If
there are resources that meet the criteria, it must return the first N set of resources and at least one field for each
resource. For calls that are sent to retrieve only the total number of resources, Guidewire recommends using a call with
query parameters that return the smallest amount of resource information, such as GET ...?
includeTotal=true&fields=id&pageSize=1.
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 57.
Tutorial: Send a GET with the pageSize and totalCount parameters

Tutorial steps
56 Query parameters
GET http://localhost:8080/cc/rest/common/v1/activities?pageSize=10&includeTotal=true
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
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
Most query parameters that can be used on primary resources can also be used on included resources.
Specifying query parameters that apply to an included resource

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

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

Query expressions for each included resource are also independent of query expressions for other included resources. If
a given GET includes multiple included resources and you want to apply a given query expression to all included
resources, you must specify the query expression for each included resource.
For example, suppose you want to GET all claims. But you want the response payload to include only the main contact
and reporter, and you want only the id, primary phone, and work phone for these contacts. To get this response, you
must send the following:
GET /claims?include=mainContact,reporter
&fields=mainContact,reporter
&fields=mainContact:id,primaryPhone,workPhone
&fields=reporter:id,primaryPhone,workPhone
Note that, in this example, the logic to restrict the returned fields to only id, primary phone, and work phone needs to
be specified for each included resource.
Summary of query parameters for included resources

The 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:
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:
include=activities&
sort=activities:dueDate
• Returns: Claim demo_sample:1 and its included activities, sorted by their due date.
58 Query parameters
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:
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:
include=activities&
includeTotal=activities:true
• Returns: Claim demo_sample:1, its included activities, and the total number of included activities for
demo_sample:1.
Tutorial: Send a GET with query parameters for included resources

Tutorial steps
GET http://localhost:8080/cc/rest/claim/v1/claims?include=activities
GET http://localhost:8080/cc/rest/claim/v1/claims?
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.
• For activities, all activities are returned.
In the second payload:
• For claims, only the id and claimNumber fields are returned.
• For activities, only the escalated activities are returned.
Query parameters 59
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).
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.
60 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 89.
• “Tutorial: Create a new note that specifies required fields only” on page 67
• “Tutorial: Create a new note that specifies optional fields” on page 68
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 61
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": [
...
],
"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.
62 POSTs
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
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 63
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.",
"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 307.
• The minimum required fields for activities are documented in “Documents” on page 317.
• The minimum required fields for activities are documented in “Notes” on page 325.
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
64 POSTs

Datetime "fieldName" : "value" "createdDate": Expressed using the format
"2020-04-09T18:24:57.
YYYY-MM-DDT
256Z"
hh:mm:ss.fffZ
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:
"amount": "500.00",
POSTs 65
"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 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
2. Specify the appropriate authorization information.
3. Under the Untitled Request label, make sure that POST is selected.
66 POSTs
• For example, to create a new note for activity cc:2 on an instance of ClaimCenter on your machine, enter:
http://localhost:8080/cc/rest/common/v1/activities/cc:2/notes
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

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
2. Enter the following call and click Send:
3. Identify the id of the first activity in the payload. This value is referenced below as <activityId>.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
POST http://localhost:8080/cc/rest/common/v1/activities/<activityId>/notes
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"
}
}
}
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
relatedTo.displayName field.)
b. Log on to ClaimCenter as aapplegate.
POSTs 67
c. On the Claim tab, click the drop-down arrow. Enter the claim number in the Claim # field and press Enter.
d. In the left-hand sidebar, click Notes.
The API tutorial note should be listed as one of the notes.
Tutorial: Create a new note that specifies optional fields

In this tutorial, you will create a note whose subject is "API tutorial note 2" for an existing activity. You will also
specify values for two optional fields: confidential (set to true) and subject (set to "Litigation").
Tutorial steps
POST http://localhost:8080/cc/rest/common/v1/activities/<activityId>/notes
{
"data":
{
"attributes": {
"body": "API tutorial note 2",
"confidential": true,
"topic": {
"code": "litigation"
}
}
}
}
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
relatedTo.displayName field.)
c. On the Claim tab, click the drop-down arrow. Enter the claim number in the Claim # field and press Enter.
d. In the left-hand sidebar, click Notes.
The API tutorial note should be listed as one of the notes. This note is confidential and it has the category specified in
the request payload.
68 POSTs
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.

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 http://) may get automatically redirected to a secure URL (one starting with https://).
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 69
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 115.
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
70 POSTs
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 85.
POSTs 71
72 POSTs
chapter 5
PATCHes
This topic discusses the PATCH method, which modifies existing data.
• “Tutorial: PATCH an activity” on page 75
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 62.
PATCHes 73
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 63.
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
3. Under the Untitled Request label, make sure that PATCH is selected.
• 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
• 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.
74 PATCHes
• Paste the request payload into the text field underneath the radio buttons.
Tutorial: PATCH an activity

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
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 http://localhost:8080/cc/rest/common/v1/activities?filter=subject:sw:Get%20police
%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
5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
a. PATCH http://localhost:8080/cc/rest/common/v1/activities/<activityID>
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"
}
}
}
}
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 75
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.

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

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.
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 http://) may get automatically redirected to a secure URL (one starting with https://).
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.
76 PATCHes
chapter 6
DELETEs
This topic provides an overview of DELETEs, which are used to delete resources.
• Tutorial: “Tutorial: DELETE a note” on page 77
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

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 77
Tutorial steps
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab tab.
a. On the Authorization tab, select Basic Auth using user elee and password gw.
a. POST http://localhost:8080/cc/rest/common/v1/activities/<activityId>/notes
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted"
}
}
}
7. Click Send. In the response payload, identify the note's id.

8. Open a third request tab and right-clicking the second tab and selecting Duplicate Tab tab.
a. Because it is a duplicate of the second tab, this tab also uses user elee.
9. Change the operation to DELETE, enter the following URL, but do not click Send yet:
a. DELETE http://localhost:8080/cc/rest/common/v1/notes/<noteID>
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

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.
78 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 115.
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 79

be globally unique across all clients, APIs, and web
services.
For more information, see “Preventing duplicate
database transactions” on page 83.
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 85.
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 82.
GW-Locale String This sets the locale for the response.
For more information, see “Language and locale” on
page 82.
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 85.
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 85.
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 85.
x-gwre-session String This controls how related calls are routed on instances of
ClaimCenter running in a cluster.
80 Request headers

(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 83.
Prefer String This gives the caller the ability to specify a wait time.
(Note: This is a standard HTTP header. Cloud API supports
the following standard values for this header: respond-
async and respond-async, wait=T. It also supports
one Guidewire-specific value, respond-async, wait-
ms=T.)
For more information, see “Asynchronous calls” on page
123.
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
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 81
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 config.xml 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 /openapi.json and /swagger.json 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.
82 Request headers
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
gw.api.webservice.exception.AlreadyExecutedException 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. 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 Cloud Operations.
Request headers 83
Using session IDs

Within the context of Cloud API calls in a clustered environment, a session ID is an arbitrary string generated by the
caller application to identify related API calls. The ID is passed in the header of each request. Every request that uses a
given session ID will be routed to the same node in the cluster. The header key for a session ID is x-gwre-session.
For example, suppose that a caller application makes the following calls to ClaimCenter cluster:
1. A POST to create an activity.
2. A PATCH to update the activity.
3. A POST to create a note on the activity.
All three calls include the following header:
x-gwre-session: 09d0fbf0-243c-4337-a582-725df8d33e39
Because all three calls specify the same session ID, all three calls will be routed to the same node.
Session IDs is the default behavior of the Guidewire Cloud Platform. If you wish to use this option, you do not need to
make any special request to Guidewire Cloud Operations.
Using cookies
Within the context of Cloud API calls in a clustered environment, a cookie is an arbitrary string generated by
Guidewire Cloud Platform that can be used to identify subsequent related API calls.
If a request header does not contain an x-gwre-session header key, the Guidewire Cloud Platform generates a cookie
and returns it in the response header with a Set-Cookie header key. Subsequent calls can include this cookie in the
request header using the Cookie header key. Every request that uses a given cookie will be routed to the same node in
the cluster that generated the cookie.
For example, suppose that a caller application makes the following calls to ClaimCenter cluster:
1. A POST to create an activity
• The request header contains no x-gwre-session header key.
• The response header contains the following: Set-Cookie: gwre=ccd37ca0-f8d3-4a8e-
b278-83274d82b355; Path=/
2. A PATCH to update the activity.
• The request header contains the following: Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355
3. A POST to create a note on the activity
• The request header contains the following: Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355
Because the second and third call specify the cookie returned by the first call, the second and third call are routed to the
same node that processed the first call.
Cookies are not the default behavior of the Guidewire Cloud Platform. If you wish to use this option, you must request
this from Guidewire Cloud Operations.
Comparing session IDs and cookies

Under most circumstances, it may be easier to use session IDs.
• Session IDs are generated by the caller application.
• Session IDs do not require the caller application to identify information in a response header and then manage the
storage that information for later use.
• Session IDs are the default behavior for Guidewire Cloud Platform.
If you wish to use cookies, you must request this from Guidewire Cloud Operations.
84 Request headers
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 dummy data
downstream.
Handling a call with unknown elements

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

Serialization of the HTTP response is one of the final steps in handling a request. Both the response body and response
headers need to be serialized, with the response body written to the HttpServletResponse output stream and the
Request headers 85
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.
86 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 87
88 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 91.
Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:
• A single parent request that creates or modifies a resource
• One or more child requests that create or modify resources related to the parent resource
If either the parent request or any child request fails, the entire request fails.
For details about request inclusion, see “Request inclusion” on page 103.
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 109.
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 89

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.
90 Reducing the number of calls

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

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

A composite request can have up to two sections:
• A requests section, which contains the subrequests that commit data.
• A selections section, which contains the subselections that query for data. These are executed after the
subrequests, and only if all the subrequests commit data successfully.
Composite requests 91
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>",
...
}
}
}
},
{
<next subrequest>
},
...
{
<final subrequest>
}
]
}
For example, the following simple composite request creates two notes for activity xc:202.
POST <applicationURL>/rest/composite/v1/composite
{
"requests": [
{
"method": "post",
"uri": "/common/v1/activities/xc:202/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
},
{
"method": "post",
"body": {
"data": {
"attributes": {
}
}
}
}
92 Composite requests
]
}
For the complete syntax that includes all composite request features, see “Complete composite request syntax” on page
101.
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": "$.data.attributes.id"
}
]
This creates a variable named newActivityId, which is set to the value of the data section's attributes section's id
field (which would typically be the id of the newly created activity).
Referencing variables
To reference a variable, use the following syntax:
${<varName>}
You can use variables anywhere in the body of a subrequest. The most common uses for variable values are:
• In an attributes field
• Within the path of a uri
• As part of a query parameter
For example, suppose there is a subrequest that creates an activity, and it is followed by a subrequest that creates a
note. The first subrequest creates a newActivityId variable as shown previously. The uri for the second subrequest is:
"uri": "/common/v1/activities/${newActivityId}/notes"
This would create the new note as a child of the first subrequest's activity.
The following is the complete code for the previous examples.
{
"requests": [
{
"method": "post",
"uri": "/claim/v1/claims/cc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"vars": [
{
}
]
},
{
"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
}
}
}
}
]
}
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": {
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
},
...
},
"checksum": "0",
"links": {
"assign": {
"href": "/common/v1/activities/cc:403/assign",
"methods": [
"post"
]
},
...
}
}
},
"headers": {
"GW-Checksum": "0",
"Location": "/common/v1/activities/xc:403"
},
"status": 201
},
Fields whose values are generated when data is committed

The individual subresponses to each subrequest specify data that has technically not been committed yet. However,
some fields contain values that are not generated until the data is committed.
When a subresponse includes a value that is generated as part of the commit, Cloud API makes effort to match the data
that will be committed as closely as possible. For example, the composite request reserves id values so that these ids
can be provided in subresponses and committed to the database.
But, there are some fields for which Cloud API cannot match the value. For example, the values for createTime and
updateTime cannot be determined prior to the commit. Fields of this type are always omitted from a subrequest's
subresponse. But, they can be retrieved through a subselection.
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",
"body": {
"data": {
"attributes": {
}
}
},
},
...
The composite response still includes a subresponse for the subrequest. But instead of providing the endpoint's default
response, the subresponse appears as:
{
"responseIncluded": false
},
The responseIncluded field defaults to true. If you want a detailed response for a given subrequest, simply omit the
responseIncluded reference.
Using query parameters in subrequests

For a POST or PATCH subrequest, you can also refine which fields are returned. To do this, use the fields query
parameter. The syntax for this is:
{
"requests": [
{
"method": "<post/patch>",
"uri": "<path>",
"body": {
"data": {
"attributes": {
...
}
}
},
"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",
"body": {
"data": {
"attributes": {
}
}
},
"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 /openapi.json call. If a query parameter is available to composite requests, the OpenAPI output will
include the following line: "x-gw-allowForCompositeApi": true.
The selections section

The selections section contains subselections that query for data. These are executed after the subselections in the
requests section, and only if all the subrequests commit data successfully.
The basic syntax for the selections section is shown below. You do not need to specify a method for each subselection,
as the only valid method in the selections section is GET.
"selections": [
{
"uri": "<pathForFirstSubselection>"
},
{
"uri": "<pathForSecondSubselection>"
},
....
]
For example, the following code creates a new activity and a note for that activity. It then queries for the newly created
activity.
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
}
}
},
"vars": [
{
}
]
},
{
"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
}
}
}
}
],
"selections": [
{
"uri": "/common/v1/activities/${newActivityId}"
}
]
}
For the complete syntax that includes all composite request features, see “Complete composite request syntax” on page
101.
Using query parameters in the selections section

You can use certain query parameters for each subselection. This includes:
• fields
• filter
• includeTotal
• pageOffset
• pageSize
• sort
Each subselection is independent from the others. You can use different query parameters for each subselection, and
you can have some subselections with query parameters and others without query parameters.
The syntax for adding query parameters to a subselection is as follows:
"selections": [
{
"uri": "<pathForFirstQuery>",
"parameters" : {
"fields" : "<value>",
"filter" : [<value>],
"includeTotal" : <value>,
"pageOffset" : <value>,
"pageSize" : <value>,
"sort" : [<value>]
}
},
....
]
Note the following:

• fields is specified as a single string of one or more fields, delimited by commas. The entire string is surrounded by
quotes.
◦ For example, "assignedUser,dueDate,priority,subject"
• filter and sort are stringified arrays consisting of one or more expressions. Each individual expression is
surrounded by quotes. The list of expressions is then surrounded by [ and ].
◦ For example: ["dueDate:gt:2022-12-20","status:in:open,complete"]
• includeTotal , pageOffset, and pageSize are either Boolean or integer values, and therefore do not use quotes.
For example, when querying for activities, to return only the assigned user, due date, priority and subject fields:
{
"uri": "/common/v1/activities",
"parameters" : {
"fields" : "assignedUser,dueDate,priority,subject"
}
To return only open and complete activities with due dates after 2022-12-20:
{
"parameters" : {
"filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"] }
To return activities based on multiple criteria:
{
"parameters" : {
"fields" : "assignedUser,dueDate,priority,subject",
"filter" : ["dueDate:gt:2022-12-20","status:in:open,complete"],
"includeTotal" : true,
"pageSize" : 5,
"sort" : ["dueDate"]
}
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 /openapi.json call. If a query parameter is available to composite requests, the OpenAPI output will
include the following line: "x-gw-allowForCompositeApi": true.
Composite requests that execute only queries

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

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

Composite requests have the following general limitations:
• The number of subrequests and subselections in a single composite request must be less than or equal to the value
of the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. (In the base configuration, this
is set to 100.)
• The subrequests can make use of other endpoints that are part of Cloud API. However, they cannot make use of
endpoints outside of Cloud API, such as custom endpoints created by an insurer.
• You cannot use request inclusion in composite requests.
◦ For more information on request inclusion, see “Request inclusion” on page 103.
• 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)
• There is no mechanism for iterating over a set of things.
◦ For example, you cannot start with a list of elements and include related resources for each item in that list.
There may be some business requirements where you are required to use a composite request. For example, when
creating a new claim with an unverified policy, you must create the policy and claim in a composite request.
There are also specific business requirements where you cannot use a composite request. For example:
• You cannot have a single composite request operate on more than one claim.
• For service requests that are Quote Only, Quote and Service, or Service Only, you can create and submit a service
request in a single composite request. But you cannot advance these types of service requests to any other stage in
its life cycle (such as in progress, declined, or canceled at the vendor’s or insurer’s request) in the same composite
request.
• Within a composite request, the only financial object you can create or modify is final non-recurring check sets.
You otherwise cannot create or modify financial objects. This includes reserve sets and reserve transactions,
recurring check sets and payment transactions, and the check life cycle endpoints (such as POST /mark-issued).
However, within a composite request, you can GET information on financial objects.
Many of the examples in the previous list pertain to situations where there must be an intermediate data commit, which
composite requests do not allow by design. However, the previous list is not intended to be exhaustive. Refer to the
section of the documentation that discusses each business requirement for more information on requirements or
limitations related to composite requests.
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 164
• Creating, closing, and paying out a claim: “Sample composite first-and-final” on page 171
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": [
{
},
{
},
{
"requestError": {
"details": [
{
"message": "Schema definition 'ext.common.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": "gw.api.rest.exceptions.BadInputException",
"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[ GW.PL ]> 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="ext.common.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="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="",
devMessage="", elapsedTimeMs=4, message="Composite API subrequest
succeeded", eventType="STATUS", serverID="server-id-207"}

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

Composite requests are limited to a maximum number of subrequests and subselections. The maximum is specified by
the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. In the base configuration, this
parameter is set to 100. Composite requests with more than the maximum number fail with a BadInputException.
(The maximum applies to the sum of the number of subrequests and the number of subselections.)
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": {
...
}
}
},
"parameters" : {
"fields" : "<value>"
},
"vars": [
{
"name": "<name>",
"path": "<path-starting-with-$>"
},
<next variable>,
...
],
},
{
<next subrequest>
},
...
{
<final subrequest>
}
],
"selections": [
{
"uri": "<pathForFirstQuery>",

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

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

In most cases, the relationship between the root resource and an included resource is a simple parent/child relationship.
Examples of this include:
• An activity and its notes
• A claim and its incidents
When using request inclusion for simple parent/child relationships, the JSON has the following structure:
{
"data" : {
"attributes": {
...
}
},
"included": {
"<resourceType>": [
{
"attributes": {
...
},
Request inclusion 103

"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".
The uri must also specify the id of the root resource. When the root resource and the included resources are being
created at the same time, the root resource does not yet have an id. Therefore, the keyword this is used in the uri to
represent the root resource's id.
Example of request inclusion for simple parent/child relationships

The following payload is an example of creating a claim and a note for the claim. The payload assumes there is an
existing policy whose number is "FNOL-POLICY". For more information on creating policies, see “Executing FNOL”
on page 137.
POST http://localhost:8080/cc/rest/claim/v1/claims
{
"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"
}
104 Request inclusion

]
}
}
Syntax for named relationships

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

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

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

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

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

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

The following payload is an example of creating a claim and a ClaimContact for the claim whose relationship is
"reporter". The payload assumes there is an existing policy whose number is "FNOL-POLICY". For more information
on creating policies, see “Executing FNOL” on page 137.
POST http://localhost:8080/cc/rest/claim/v1/claims
{
"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",
}
]
}
}
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 exposure would have a value such as "/
claim/v1/claims/this/notes".
From a syntax perspective, you could attempt to attach an included resource not to the root resource, but rather to some
other existing resource. For example, instead of referencing the root resource, the uri for the note could reference an
existing claim, such as "/claim/v1/claims/cc:200/notes". This uri says "create a note and attach it not to the root
resource of this POST, but rather to the existing claim cc:200".
Cloud API will not allow this. Any attempt to POST or PATCH an included resource to something other than the root
resource will cause the operation to fail.
Request inclusion 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 91.
Additional behaviors with read inclusion

Using query parameters 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
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.
You can also use query parameters with included resources. For example, the following call GETs all activities
assigned to the current user and includes any related notes. The number of notes returned 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


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 113.
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 http://localhost:8080/cc/rest/claim/v1/batch
Batch request payload syntax

The basic syntax for a batch request payload is:
{
"requests": [
{
"method": "<method>",
"path": "<path>",
"query": "<queryParameters>",
"data":
{
Batch requests 109

"attributes": {
...
}
}
},
{
"method": "<method>",
"path": "<path>",
"query": "<queryParameters>",
"data":
{
"attributes": {
...
}
}
},
...
]
}
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: http://localhost:8080/cc/
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-1.0.schema.json 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",
110 Batch requests

"path": "/claims/demo_sample:1"
},
{
"method": "get",
},
{
"method": "get",
}
]
}
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",
}
]
}
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",
"data":
{
"attributes": {
"body": "Batch note 2"
}
}
}
]
}
Batch requests 111

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",
"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",
"headers": [
112 Batch requests

{
"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",
"body": {
"data": {
"attributes": {
"subject": "PATCH body 1"
}
}
},
"onFail": "abort"
},
{
"method": "patch",
"body": {
"data": {
"attributes": {
}
}
},
"onFail": "abort"
},
{
"method": "patch",
"body": {
"data": {
"attributes": {
}
}
}
}
]
}
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 113

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.
114 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.
• “Tutorial: PATCH an activity using checksums” on page 117
• “Tutorial: Assign an activity using checksums” on page 118
• “Tutorial: DELETE a note using checksums” on page 119
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 115

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.
116 Lost updates and checksums

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

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
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:
%20report

3. Note the ID, subject, and checksum of the first activity returned in the response payload. (These values are
referred to in later steps as "<ActivityID>", "<originalSubject>", and "<originalChecksum>".)
5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
a. PATCH http://localhost:8080/cc/rest/common/v1/activities/<ActivityID>
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

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
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:
%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>".)
a. POST http://localhost:8080/cc/rest/common/v1/activities/<ActivityID>/assign
6. The POST /{activityId}/assign endpoint requires a request payload that specifies how the assignment is to
be done. Specify the request payload.

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


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
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab tab.
a. On the Authorization tab, select Basic Auth using user elee and password gw.
a. POST http://localhost:8080/cc/rest/common/v1/activities/<activityId>/notes
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted with a checksum"
}
}
}
7. Click Send. In the response payload, identify the note's id.

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

14. Click Send a second time. Now, the checksum value in the header matches the checksum value for the note
calculated by ClaimCenter. So, the DELETE is successful. (The response to a successful DELETE is "204 - No
content".)


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

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.
124 Asynchronous calls

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",
"responseStatus": 202,
"startTime": "2022-07-12T16:53:12.365Z",
"status": {
"code": "Accepted",
"name": "Accepted"
}
}
}
}
Example response for a call that is complete

The following is a portion of the /requests response for a asynchronous call that is complete.
{
"data": {
"attributes": {
"completionTime": "2022-07-12T16:53:16.073Z",
"requestMethod": "POST",
"requestPath": "/admin/v1/users",
"responseBodyJson": {
"data": {
"attributes": {
...
"username": "asyncUser99",
"vacationStatus": {
"code": "atwork",
"name": "At work"
}
},
"checksum": "321dff263827cbbd772c26676398d8ae",
"links": {
...
}
}
},
"responseHeaders": {
"Cache-Control": [
"must-revalidate",
"post-check=0",
"pre-check=0",
"max-age=0",
"no-store",

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

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.
6. The caller application sends a GET /async/v1/requests/{asyncRequestId}/response request to Cloud API.

7. The Cloud API response includes the original response, as if the request had been executed synchronously.
When the original call is complete, the response to GET /async/v1/requests/{asyncRequestId}/response has the
same status code, response body (if any), and response headers as if the caller were getting a synchronous response to
the original request.

For example, if the original request was a POST that created a new activity, the GET request to retrieve the response
might return a 201 response code and have a Location header. If the original request failed because of a validation
error, the GET request to retrieve the response might have a 400 status code and a response body with details of the
errors.
Sending a request asynchronously

To send a request asynchronously, include the following header with the request:
• Key: Prefer
• Value: respond-async
The caller application can also specify an amount of time it is willing to wait for a response. If the call can be
processed within the specified time, Cloud API returns the results as if the call had been executed synchronously. For
more information, see “Waiting for a response synchronously” on page 131.
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
131.
• If the application is overloaded and unable to process or queue the request, it will return a 503 response.

Tutorial: Send a request asynchronously

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
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 http://localhost:8080/cc/rest/admin/v1/users
{
"data": {
"attributes": {
"username": "asyncUser"
}
}
}
4. Add the asynchronous request to the header.

a. In the first row of tabs, click Headers.
i. KEY: Prefer
ii. VALUE: respond-async
5. Click Send.
Results
The response should be "202 Accepted". To view the value for GW-Async-Location header, click the Headers tab in
the response object pane. (This Headers tab is in a row of tabs that starts with Body and Cookies.) This value is used in
the next tutorial.
Retrieving the response to the original request

There are multiple ways to retrieve the response to the initial request.
Response information in the /requests response

The response to the initial call includes a GW-Async-Location header. This header uses the following syntax:
/async/v1/requests/<asyncRequestId>
You can execute a GET on this endpoint to retrieve information about the original request.

The response status

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

There is also a /requests/{asyncRequestId}/response endpoint. Calls to this endpoint use the following syntax:
/async/v1/requests/<asyncRequestId>/response
If the original request is complete, this endpoint returns the response to the original request as if the call had been
executed synchronously. This endpoint is useful when:
• 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 129.
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. GET http://localhost:8080/cc/rest/<Async-Location>, where <Async-Location> is the value of
the GW-Async-Location response header from the initial asynchronous request.
3. Ensure that, for this request, you do not have Prefer/respond-async header specified in your request.
(Although you can submit the /requests call asynchronously, you typically would not want to.)
4. Click Send.
5. Send a second request that uses the /response endpoint to retrieve only the response.
a. Right-click the current tab and choose Duplicate Tab.
b. In the new tab, add "/response" to the end of the existing URL.
6. Click Send.

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

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

In this tutorial, you will submit two requests asynchronously to create a new user. Both will specify a wait time.
Tutorial steps
1. In Postman, start a new request by:

a. Clicking the + to the right of the Launchpad tab

b. Specifying Basic Auth authorization using user su and password gw.
a. POST http://localhost:8080/cc/rest/admin/v1/users
{
"data": {
"attributes": {
"username": "asyncUserNoWait"
}
}
}
4. Add the asynchronous request to the header.

a. In the first row of tabs, click Headers.
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.

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
config.xml. For example, if you wanted request information to be purged when it is 6 days old, you would add the
following to config.xml:
<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.


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

136 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.
• “Tutorial: Creating a policy using the Test Util API” on page 146
• “Tutorial: POSTing a minimal draft claim for personal auto” on page 147
• “Tutorial: PATCHing a draft claim for personal auto” on page 148
• “Tutorial: POSTing a typical draft claim for personal auto” on page 149
• “Tutorial: Submitting a draft claim” on page 161
For sample FNOL payloads, see the “Sample payload addendum” on page 161.
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 137
All open claims initially start as draft claims, regardless of how they are created. However, the New Claim Wizard hides
most of the distinction between draft and open claims. For example, in the base configuration, draft claim numbers are
not shown in the New Claim Wizard during claim creation.
Prior to finishing a draft claim in the New Claim Wizard, you can cancel the draft claim by clicking the Cancel button.
This discards the claim information from the database. This action can be taken only on draft claims. Once the New
Claim Wizard is finished, the claim cannot be canceled.
Verified and unverified policies

When a claim is created, ClaimCenter creates a copy of the relevant policy and attaches it to the claim. This can be
either a verified policy or an unverified policy.
Verified policies
A verified policy is a copy of the policy based on information retrieved from the Policy Administration System (PAS).
In a production system, verified policies are the most common types of policies.
Every claim has its own copy of the policy. If two claims are created from the same policy, they will each have their
own copy.
Verified policies can be used in either a test or production system. However, they require a PAS (or test PAS) and an
integration point to that PAS.
Unverified policies
An unverified policy is a policy that is created during the FNOL process based on information supplied by an adjuster
or by the caller application. This information may or may not correctly correspond to information in a PAS. Unverified
policies let adjusters start the FNOL process without information from the PAS. This could be necessary if the reporter
does not know or cannot recall enough information to find the policy.
Eventually, the unverified policy must be refreshed with data from the PAS, thereby converting it to a verified policy.
You cannot complete the claims process and make payments on a claim while the policy is still unverified.
Unverified policies can be used in either a test or production system. In a test system, unverified policies may be a
useful way to create policies without having an integration point to a PAS and without needing to enable the Test Util
API.
The FNOL process in Cloud API

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

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

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 139

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 164.
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.
140 Executing FNOL

Canceling claims
You can cancel a draft claim through Cloud API. This is done using the /claim/{claimId}/cancel endpoint. This has
the same effect as when a user clicks the Cancel button in the New Claim Wizard.
You cannot cancel a claim after it has been submitted and therefore promoted to being an open claim. Once a claim has
been submitted, the only way to discontinue processing of it is to close it.
Claim modes
In the base configuration, some lines of business let you create claims in different "modes". For example, for personal
auto, you can create a "regular" claim, a "quick" claim, or a "first and final" claim. These modes are distinctions that
exist primarily in the user interface. Each mode may require a greater or lesser amount of information, and some modes
may assist in executing tasks beyond simply reporting the claim. But from a technical standpoint, the claims created in
each mode are not fundamentally different from one another.
Thus, Cloud API does not have an analog for "modes". When you create a claim through Cloud API, as long as you
provide the minimum required information, you can provide whatever amount of information is appropriate for the use
case.
The Test Util API

To create a claim, you must have information from a Policy Administration System. 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.
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.
Enabling the Test Util API

To enable the Test Util API for FNOL development, 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 config.properties file
To enable the Test Util API and set the correct policy search adapter plugin, you must specify two values. The syntax
for these values varies slightly based on where the values are being set.
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
Executing FNOL 141

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
Setting the values in the application's config.properties file

To set the values in the application's config.properties file, specify the following:
View the Test Util API in Swagger UI

About this task
Once the Test Util has been enabled, you can use Swagger UI to view the Test Util API definition.
Procedure
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: http://localhost:8080/cc/resources/swaggerui/
3. In the text field at the top of the Swagger UI interface, enter the following URL:
• <applicationURL>/rest/test-util/v1/swagger.json
4. Click Explore.
Creating test policy data

The TestSupportPolicyPlugin class
At the beginning of the FNOL process, the user or service that is executing FNOL must identify the relevant policy.
Once identified, ClaimCenter copies information about that policy to its own policy graph. These processes are referred
to as policy search and policy retrieval. The details for how to execute these processes are specified by the
IPolicySearchAdapter plugin.
The base configuration includes an implementation of the IPolicySearchAdapter plugin that points to a Gosu class
named TestSupportPolicyPlugin. This implementation is used only when ClaimCenter is started in the ci-test
environment.
The Test Util endpoints

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

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 162.
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",
"verifiedPolicy": true
}
}
}
Common typekey fields

The following code block creates a personal auto policy that is in force. (In other words, the policy has not been
canceled.)
{
"data": {
"attributes": {
"policyType": {
"code": "PersonalAuto"
},
"status": {
"code": "inforce"
}
}
}
Executing FNOL 143

Policy contacts
The following code block creates a policy where the insured is a person named Ray Newton who lives at 287
Kensington Rd. #1A, South Pasadena, CA. The ID in the Policy Administration for this contact is ab:0001-1.
When creating test policies, policy contacts are specified using request inclusion. For more information on this
approach, see “Request inclusion” on page 103.
{
"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": {
"state": {
"code": "CA"
}
}
}
]
}
}
}
144 Executing FNOL

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"
}
}
]
}
Executing FNOL 145

]
}
}
}
Tutorial: Creating a policy using the Test Util API

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 config.properties.
b. Add the following to the end of the file:
• POST http://localhost:8080/cc/rest/test-util/v1/policies
d. Paste the text in the “Sample policy payload” on page 162 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:
146 Executing FNOL

"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
In this tutorial, you will create a draft claim for a personal auto policy using the minimum amount of information
needed.
• POST http://localhost:8080/cc/rest/claim/v1/claims
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.
Executing FNOL 147

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 149.)
Tutorial: PATCHing a draft claim for personal auto

• “Tutorial: POSTing a minimal draft claim for personal auto” on page 147
◦ 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.
• PATCH http://localhost:8080/cc/rest/claim/v1/claims/{TutorialClaimID}
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.
the Basic Info step of the New Claim Wizard. The How Reported field should be set to Internet.
state.
148 Executing FNOL

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 91.
• For an example of a draft claim created in a composite request, see “Sample composite claim payload” on page
164.
Request inclusion is a technique you can use with POSTs where you specify a root resource (such as a claim), one or
more related child resource (such as one or more ClaimContacts), and the relationship between the root and the
children.
• For more information on request inclusion, see “Request inclusion” on page 103.
• For an example of a draft claim created using request inclusion, see “Sample draft claim payload” on page 163.
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 191
• “Incidents” on page 209
• “Exposures” on page 225
• “Service requests” on page 237
Tutorial: POSTing a typical draft claim for personal auto

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.
• POST http://localhost:8080/cc/rest/claim/v1/claims
d. Paste the text in the “Sample draft claim payload” on page 163 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.
Executing FNOL 149

Checking your work

1. View the new draft claim in ClaimCenter.
b. Log on to ClaimCenter as su.
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.
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 91.
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 164.
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)
150 Executing FNOL

• 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": {
}
}
}
}
},
{
"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.
Executing FNOL 151

Command
Request body
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-contact",
"policyType": {
}
}
}
},
"vars": [
{
"name": "policyId",
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/contacts",
"body": {
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Ray",
"lastName": "Newton"
}
}
}
},
{
"method": "post",
"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.
152 Executing FNOL

The following example creates an unverified policy with a location as part of a composite request.
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-location",
"policyType": {
}
}
}
},
"vars": [
{
"name": "policyId",
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/locations",
"body": {
"data": {
"attributes": {
}
}
},
"vars": [
{
"name": "locationId",
}
]
},
{
"method": "post",
"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",
Executing FNOL 153

"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",
}
]
},
{
"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.
154 Executing FNOL

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
Request body
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-vehicle-risk-unit",
"policyType": {
}
}
}
},
"vars": [
{
"name": "policyId",
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units",
"body": {
"data": {
"attributes": {
}
}
}
},
{
"method": "post",
"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.
Executing FNOL 155

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
Request body
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-policy-coverage",
"policyType": {
}
}
}
},
"vars": [
{
"name": "policyId",
}
]
},
{
"method": "post",
"uri": "/claim/v1/unverified-policies/${policyId}/coverages",
"body": {
"data": {
"attributes": {
"coverageType" : {
}
}
}
}
},
{
"method": "post",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-with-policy-coverage"
}
156 Executing FNOL

}
}
}
]
}
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
Request body
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-with-risk-unit-coverage",
"policyType": {
}
}
}
},
"vars": [
{
"name": "policyId",
}
]
},
{
"method": "post",
"body": {
"data": {
"attributes": {
}
}
},
"vars": [
{
"name": "riskUnitId",
}
]
},
{
"method": "post",
Executing FNOL 157

"uri": "/claim/v1/unverified-policies/${policyId}/vehicle-risk-units/${riskUnitId}/coverages",
"body": {
"data": {
"attributes": {
"coverageType" : {
}
}
}
}
},
{
"method": "post",
"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}
{locationBasedRiskUnitId}/coverages
{locationBasedRiskUnitId}/coverages/{coverageId}
158 Executing FNOL

• 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. Each rule can throw an error that is tied to a specific
level of claim maturity. The two lowest levels are LoadSave and NewLossCompletion. The /submit endpoint will not
succeed if the claim violates any rule at either of these levels.
In the base configuration, in addition to policy number and loss date, you must also specify a reporter. The requirement
to include a reporter is implemented by the "CLV04000 - ClaimContact Role Configuration" validation rule, which
throws an error at the NewLossCompletion level if the reporter is null. For an example of a payload that creates a
minimum base-configuration-submittable claim, see the “Sample payload addendum” on page 161.
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.
Executing FNOL 159

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
Request body
{
"requests": [
{
"method": "post",
"body": {
"data": {
"attributes": {
"policyNumber": "unverified-minimum-submittable",
"policyType": {
}
}
}
}
},
{
"method": "post",
"body": {
"data": {
"attributes": {
"lossDate": "2021-03-04T07:00:00.000Z",
"policyNumber": "unverified-minimum-submittable"
}
}
},
"vars": [
{
"name": "claimId",
}
]
},
{
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts",
"body": {
"data": {
"attributes": {
"firstName": "Ray",
}
}
},
"vars": [
{
"name": "contactId",
}
]
},
{
160 Executing FNOL

"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

• “Tutorial: POSTing a typical draft claim for personal auto” on page 149
◦ 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.
• POST http://localhost:8080/cc/rest/claim/v1/claims/{TutorialClaimID}/submit
Checking your work

1. View the open claim in ClaimCenter.
starts with "000-00-".)
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.
Executing FNOL 161

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",
"verifiedPolicy": true,
"policyType": {
},
"status": {
"code": "inforce"
},
"policyContacts": [
{
"contact": {
"refid": "rayNewton"
},
"roles": [
{
"code": "insured"
}
]
}
],
"policyLocations": [
{
"address": {
"state": {
"code": "CA"
}
}
}
],
"policyCoverages": [
{
"coverageType": {
},
"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": {
},
"covTerms": [
{
"covTermPattern": {
},
"amount": "500.00",
"currency": "usd"
}
}
],
"incidentLimit": {
162 Executing FNOL

"amount": "15000.00",
"currency": "usd"
}
}
]
}
]
}
},
"included": {
"TestUtilContact": [
{
"attributes": {
"firstName": "Ray",
"primaryAddress": {
"country": "US",
"state": {
"code": "CA"
}
},
"subtype": {
"code": "Person"
},
},
"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",
"lossCause": {
"code": "vehcollision"
},
"mainContact": {
},
"reporter": {
}
}
},
"included": {
"ClaimContact": [
{
"attributes": {
"firstName": "Robert",
"lastName": "Farley",
},
"method": "post",
"refid": "robertFarley",
}
],
"VehicleIncident": [
{
"attributes": {
"collision": true,
"damageDescription": "Minor collision",
"driver": {
},
"lossParty": {
"code": "insured"
},
"vehicle": {
"policySystemId": "pcveh:0001-1"
}
},
"method": "post",
"uri": "/claim/v1/claims/this/vehicle-incidents"
Executing FNOL 163

},
{
"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": {
}
}
}
},
"method": "post",
"vars": [
{
"name": "policyId",
}
]
},
{
"body": {
"data": {
"attributes": {
"coverageType": {
},
"covTerms": [
{
"covTermOrder": 1,
"covTermPattern": {
"code": "PALiability"
},
"modelAggregation": {
"code": "pi"
},
"modelRestriction": {
"code": "acc"
},
"amount": "50000.00",
"currency": "usd"
}
},
{
"covTermSubtype": "ClassificationCovTerm",
"covTermOrder": 2,
"code": "Classification Code - 1",
164 Executing FNOL

"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@email.com",
"firstName": "Ray",
"primaryAddress": {
"country": "US",
"state": {
"code": "CA"
}
},
"primaryPhoneType": {
"code": "work"
},
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "818-446-1206"
}
}
}
},
"method": "post",
"vars": [
{
"name": "insuredId",
}
]
},
{
"body": {
"data": {
"attributes": {
"insured": {
"id": "${insuredId}"
}
}
}
},
"method": "patch",
"uri": "/claim/v1/unverified-policies/${policyId}"
},
{
"body": {
"data": {
"attributes": {
"addressBookUID": "UID-HelenNewton-001",
"emailAddress1": "HelenNewton@email.com",
"firstName": "Helen",
"primaryAddress": {
"country": "US",
"state": {
Executing FNOL 165

"code": "CA"
}
},
"code": "work"
},
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "818-446-1206"
}
}
}
},
"method": "post",
"vars": [
{
"name": "coveredContactId",
}
]
},
{
"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",
"vars": [
{
"name": "vehicleId",
"path": "$.data.attributes.vehicle.id"
},
{
"name": "vehicleRUId",
},
{
"name": "RUNumber",
"path": "$.data.attributes.RUNumber"
}
]
},
{
"body": {
"data": {
"attributes": {
"claimAggLimit": {
"amount": "7000.00",
"currency": "usd"
},
166 Executing FNOL

"personAggLimit": {
"amount": "8000.00",
"currency": "usd"
},
"coverageType": {
},
"covTerms": [
{
"covTermOrder": 1,
"covTermPattern": {
},
"modelAggregation": {
"code": "pi"
},
"modelRestriction": {
"code": "acc"
},
"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",
"state": {
"code": "CA"
}
},
"policyNumber": "composite-FNOL-example",
"reporter": {
}
}
}
},
"method": "post",
"vars": [
{
"name": "claimId",
}
]
},
{
"body": {
"data": {
"attributes": {
"body": "Test note body"
}
}
},
"method": "post",
Executing FNOL 167

"uri": "/claim/v1/claims/${claimId}/notes"
},
{
"body": {
"data": {
"attributes": {
"collision": true,
"collisionPoint": {
"code": "03"
},
"damageDescription": "Damaged front bumper",
"driver": {
},
"lossParty": {
"code": "insured"
},
"severity": {
"code": "major-auto"
},
"vehicle": {
"id": "${vehicleId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/vehicle-incidents",
"vars": [
{
"name": "vehicleIncidentId",
},
{
"name": "driverUri",
"path": "$.data.attributes.driver.uri"
}
]
},
{
"body": {
"data": {
"attributes": {
"coverageSubtype": {
},
"claimant": {
},
"primaryCoverage": {
},
"vehicleIncident": {
"id": "${vehicleIncidentId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/exposures",
"vars": [
{
"name": "exposureId",
}
]
},
{
"body": {
"data": {
"attributes": {
"cellPhone": {
"countryCode": {
"code": "US"
},
"number": "555-555-5555"
},
"dateOfBirth": "1928-11-18",
"emailAddress1": "MitchMochizuki@email.com",
"firstName": "Mitch",
"homePhone": {
"countryCode": {
"code": "US"
},
"number": "555-555-5556"
},
"lastName": "Mochizuki",
"licenseNumber": "ABCDE12345",
"licenseState": {
"code": "CA"
168 Executing FNOL

},
"primaryAddress": {
"addressLine1": "1313 Albian Dr.",
"city": "Anaheim",
"country": "US",
"county": "Orange County",
"state": {
"code": "CA"
}
},
"primaryLanguage": {
"code": "en_US"
},
"primaryLocale": {
"code": "en_US"
},
"code": "home"
},
}
}
},
"method": "post",
"vars": [
{
"name": "mitchMochizukiId",
}
]
},
{
"body": {
"data": {
"attributes": {
"addressBookUID": "DOCTOR-12345",
"dateOfBirth": "1959-06-11",
"emailAddress1": "DanaEdwards@email.com",
"firstName": "Dana",
"lastName": "Edwards",
"primaryAddress": {
"addressLine1": "1000 Hospital Dr.",
"city": "Princeton",
"country": "US",
"state": {
"code": "NJ"
}
},
"primaryLanguage": {
"code": "en_US"
},
"primaryLocale": {
"code": "en_US"
},
"code": "work"
},
"contactSubtype": "Doctor",
"workPhone": {
"countryCode": {
"code": "US"
},
"number": "666-666-6666"
}
}
}
},
"method": "post",
"vars": [
{
"name": "danaEdwardsId",
}
]
},
{
"body": {
"data": {
"attributes": {
"ambulanceUsed": true,
"bodyParts": [
{
"detailedBodyPart": {
"code": "57"
},
"detailedBodyPartDesc": {
Executing FNOL 169

"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": {
},
"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": {
},
"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": "#(args.name)",
"editableRoles": [
{
"active": true,
"relatedTo": {
"id": "${claimId}",
"type": "Claim"
},
"role": {
"code": "repairshop"
170 Executing FNOL

}
}
],
"contactSubtype": "AutoRepairShop"
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/contacts"
},
{
"method": "post",
}
],
"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.
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).
Executing FNOL 171

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 ",
"country": "US",
"county": "San Mateo",
"state": {
"code": "CA"
}
},
"mainContact": {
"policySystemId": "pc:contact_1"
},
"policyNumber": "POLICY-ID",
"reportedByType": {
"code": "self"
},
"reporter": {
}
}
}
},
"method": "post",
"vars": [
{
"name": "claimId",
}
]
},
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",
}
]
},
172 Executing FNOL

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"
},
"code": "PAComprehensiveCov"
},
"claimant": {
},
"code": "PAComprehensiveCov"
},
"id": "${firstPartyVehicleIncidentId}"
}
}
}
},
"method": "post",
"uri": "/claim/v1/claims/${claimId}/exposures",
"vars": [
{
"name": "exposureId",
}
]
},

{
"body": {
"data": {
"attributes": {
"initialAssignment": {
"groupId": "#(args.groupId)",
"userId": "#(args.adjusterId)"
}
}
}
},
"method": "post",
},
5. POST a payment to the insured.

{
"body": {
"data": {
"attributes": {
"primaryCheckToWrite": {
"paymentsToWrite": [
{
"lineItems": [
{
"amount": "500",
"currency": "usd"
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "${exposureId}"
},
"reservingCurrency": {
"code": "usd"
}
},
Executing FNOL 173

"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
},
"payeeType": {
"code": "other"
}
}
],
"paymentMethod": {
"code": "check"
},
"mailTo": "Ray Newton",
"payTo": "Ray Newton",
"mailingAddress": {
"addressLine1": "2850 S Delaware St ",
"country": "US",
"county": "San Mateo",
"state": {
"code": "CA"
}
}
}
}
}
},
"method": "post",
"uri": "#('/claim/v1/claims/${claimId}/check-sets')",
"vars": [
{
"name": "checkId",
"path": "$.data.attributes.checks[0].id"
}
]
}
]
}
174 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 137.
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": {
}
},
{
"attributes": {
}
},
{
Claims 175
"attributes": {
}
}
],
...
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": {
}
},
{
"attributes": {
}
},
{
"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.
176 Claims
Querying for a claim by claim ID

The GET /claim/v1/claims/{claimId} endpoint returns information on the given claim, assuming the caller's
resource access permits the caller to view the claim.
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,
"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 177
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
• policyNumber
• taxID
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",
}
}
}
178 Claims
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": "com.guidewire.pl.modules.rest.framework.v1.exceptions.OperationNotCurrentlyAllowedException",
"userMessage": "The operation is not currently allowed for this resource"
}
Searching by name and tax ID

When the payload includes either the firstName , lastName , companyName, or taxID, the default behavior is to search
for claims where there is a claimant with that first, last, company name, or tax ID.
You can also use the nameSearchType parameter to execute searches where the named person is either the insured, an
additional insured, or has any role on the claim. To do this, provide one of the following codes for the
ClaimSearchNameSearchType code:
• addinsured (additional insured)

• any (any role on the claim, including the roles beyond additional insured, claimant, and insured)
• claimant (this is the default behavior)
• insured
For example, the following payload will search for all claims where the insured has a first name of "Ray" and a last
name of "Newton". The nameSearchType uses a field from the ClaimSearchNameSearchType code:
Command
POST /claim/v1/search/claims-v2
Request body
{
"data": {
"attributes": {
"firstName": "Ray",
Claims 179
"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"
}
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": {
180 Claims
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 45.
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 181
}
},
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.
182 Claims
• 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 183
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.
184 Claims
Command
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
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 137.
Claims 185
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. (validationLevelReached.code 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": {
{
186 Claims
"code": "newloss",
},
{
"code": "loadsave",
}
],
"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",
"code": "iso",
"name": "Valid for ISO"
}
}
],
"validationLevelReached": {
"code": "newloss",
}
}
}
}
From this payload, you can determine the following information:

• The claim is at the "new loss completion" level (validationLevelReached.code 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": {
{
"code": "payment",
"name": "Ability to pay"
},
{
"code": "external",
"name": "Send to external system"
},
{
"code": "iso",
"name": "Valid for ISO"
},
{
"code": "newloss",
},
{
"code": "loadsave",
}
],
"hasErrors": false,
"validationLevelReached": {
"code": "payment",
}
}
}
}
Claims 187
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.
188 Claims
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 189
190 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 191
◦ 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 195
to an existing ClaimContact
• “Assigning roles to
When deleting a ClaimContact
existing ClaimContacts”
on page 202
• “Deleting ClaimContacts”
on page 204
refid A temporary reference ID When POSTing or PATCHing a • “Creating a new

ClaimContact using request
ClaimContact with a
inclusion
192 ClaimContacts
Identifier Description Use case More information
reserved role” on page

196
• “Creating a new
ClaimContact with a non-
reserved role” on page
199
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
200
• “Assigning roles to
existing ClaimContacts”
on page 202
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 201
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
External user authorization for ClaimContacts

Cloud API supports authorization for different types of callers. One of the supported caller types is external users. An
external user is a person who is known to the insurer but who is not listed as a user in the operational database. For
ClaimCenter, one of the external user types is policyholders. They are users who want to interact with information
about claims on their policies. For example, Ray Newton, who is a policyholder and wants to check on the status of a
claim filed against his personal auto policy. For more information on external user authorization, see the Cloud API
Developer Guide.
In the base configuration, external users have the ability to view and edit ClaimContact information on claims related
to their policies. But, they can view and edit only the ClaimContacts that are related to the policy with the role of
Insured. They cannot view information about ClaimContacts that are not related to the policy (such as a third-party
ClaimContact or vendor), or that are related to the policy but without this role of Insured (such as an agent).
For example, suppose Ray Newton files a claim for an accident involving himself and another driver, David Preston.
Ray's vehicle is repaired by Sam's Towing and Auto Service.
• Ray Newton can do the following.
◦ View information about himself, as this ClaimContact is related to the policy with the role of Insured.
◦ Create new ClaimContacts (who may or may not be related to the policy with the role of Insured).
ClaimContacts 193
• Ray Newton cannot do the following

◦ View or edit information about David Preston.
◦ View or edit information about Sam's Towing.
◦ View or edit information about any ClaimContacts he created that are not related to the policy with the role of
Insured.
There is a similar type of restricted access for incidents and exposures. For more information, see:
• “External user authorization for incidents” on page 212
• “External user authorization for exposures” on page 227
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.
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 ReservedContactRoles.yaml 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
ReservedContactRoles.yaml 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:
194 ClaimContacts
• 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:
Command
GET /claim/v1/claims/demo_sample:1/contacts?fields=displayName,id,roles
Response
{
"count": 7,
"data": [
{
"attributes": {
"displayName": "Mike's Auto detailing shop",
"id": "cc:5",
"roles": [
{
"active": true,
"relatedTo": {
"displayName": "235-53-365870",
"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",
"type": "Policy",
"uri": "/claim/v1/claims/demo_sample:1/policy"
ClaimContacts 195
},
"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

When you create a ClaimContact, you must specify the following:
• contactSubtype (a subtype of Contact)
• Either:
◦ firstName and 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 inclusion” on page 103 and “Composite requests” on page 91.
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
196 ClaimContacts
Request
{
"data": {
"attributes": {
"reporter": {
"refid": "newContact"
}
}
},
"included": {
"ClaimContact": [
{
"refid": "newContact",
"attributes": {
"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": [
{
"method": "post",
"uri": "/claim/v1/claims/cc:402/contacts",
"body": {
"data": {
"attributes": {
"firstName": "Carol",
"lastName": "Daniels"
}
}
},
"vars": [
{
"name": "newContactId",
}
]
},
{
"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
ClaimContacts 197
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 73.
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
Request
{
"data": {
"attributes": {
"witnesses": [
{
"contact": {
"id": "newContact"
}
}
]
}
},
"included": {
"ClaimContact": [
{
"refid": "newContact",
"attributes": {
"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": {
"firstName": "Matt",
"lastName": "Capaldi"
}
}
},
"vars": [
{
"name": "newContactId",
}
]
},
{
"method": "patch",
198 ClaimContacts
"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
ReservedContactRoles.yaml 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
• 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 http://localhost:8080/cc/rest/claim/v1/claims/cc:610/contacts/cc:777
Request body
{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "altcontact"
},
"relatedTo": {
"type": "Claim",
"id": "cc:610"
}
}
]
ClaimContacts 199
}
}
}
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
Request body
{
"data": {
"attributes": {
"editableRoles": [
{
"role": {
"code": "incidentowner"
},
"relatedTo": {
"type": "vehicleIncident",
"id": "cc:102"
}
}
]
}
}
}
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",
"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
200 ClaimContacts
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
Request: Version 1 (using id)
{
"data": {
"attributes": {
"maincontact": {
"id": "cc:3131"
}
}
}
}
Request: Version 2 (using policySystemId)
{
"data": {
"attributes": {
"maincontact": {
"policySystemId": "pc:2000-acme-12445"
}
}
}
}
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 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"
}
ClaimContacts 201
}
]
}
}
}
Shared vendors and reserved roles

In the Cloud API schemas, the only place that syncAddressBookUID field is declared is in the ClaimContact's
editableRoles array. This array can be used only for setting non-reserved roles.
There are a small number of vendor roles that are reserved roles, such as Primary Doctor. The schemas for these roles
do not specify a syncAddressBookUID field.
Thus, if you want to copy a ContactManager contact to a claim and assign it a reserved role, you must do it in two
calls:
• In the first call, copy the contact and assign it a dummy role, such as "other".
• In the second call, PATCH the claim by removing the dummy role and assigning the desired reserved role.
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@email.com"
}
}
}
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 202.
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
Request body
{
"data": {
202 ClaimContacts
"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
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
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 73.
ClaimContacts 203
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
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.
204 ClaimContacts
• 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 entityroleconstraints-config.xml. For more
information, refer to the Configuration Guide.
Role constraint endpoints

You can use the following endpoints to retrieve information about role constraints.
Operation Endpoint Description

GET /role-constraints Retrieve a list of all contact role constraints for the given
instance of ClaimCenter
GET /role-constraints/{contactRoleId} Retrieve information for the given contact role. Note
that contactRoleId is the contact role's code, such as
reporter.
These are metadata endpoints. They return information about the configuration of the given instance of ClaimCenter,
not about any of its business resources.
Role constraint example: Doctor

This is a portion of the payload when GET /role-constraints/doctor is executed on the base configuration:
{
"data": {
"schemaConstraints": [
{
"constraints": [
{
"constraintType": "ZeroToMore"
}
],
"schema": "Claim"
},
{
"constraints": [
{
ClaimContacts 205
}
],
"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": [
{
}
],
"schema": "Exposure"
}
]
From this payload, you can determine the following about reporter:
• It can be used as a role for a ClaimContact that is associated with a claim.
◦ The role is "exclusive". (There can be at most one ClaimContact on a Claim with this role.)
◦ The role is "required". (There must be at least one ClaimContact on a Claim with this role.)
◦ Taken together, these two constraints mean there must be exactly one reporter on a Claim.
• It can be used as a role for a ClaimContact that is associated with an Exposure.
◦ There can be any number of reporters on an exposure, including 0.
• There is no subtype restriction. Therefore, the role of reporter can be used with any ClaimContact, regardless of the
subtype of its associated contact.
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
206 ClaimContacts
• 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.
ClaimContacts 207
208 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 209
▪ 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 191.
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 225.
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}
210 Incidents
• 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 211
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,
"userMessage": "No resource was found at path /claim/v1/claims/cc:34/dwelling-incidents"
}
External user authorization for incidents

Developer Guide.
In the base configuration, external users have the ability to view and edit incident information on claims related to their
policies. But, they can view and edit only the incidents that are related to a ClaimContact that is related to the policy
with the role of Insured. They cannot view information about any other type of incident (such as a third-party incident).
The claim has two vehicle incidents: one for Ray Newton's vehicle and one for David Preston's vehicle.
◦ View information about his vehicle incident, as this incident is related to himself, and he is related to the policy
with the role of Insured.
◦ Create new incidents (that may or may not be related to a ClaimContact that is an Insured on the policy).
◦ View or edit information about David Preston's vehicle incident.
◦ View or edit information about any incidents he created that are not related to a ClaimContact that is an Insured
on the policy.
There is a similar type of restricted access for ClaimContacts and exposures. For more information, see:
• “External user authorization for ClaimContacts” on page 193
• “External user authorization for exposures” on page 227
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).
212 Incidents
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.
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.
Incidents 213
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}
• 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": {
214 Incidents
"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.
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/
• DELETE /claims/{claimId}/general-incidents/{incidentId}/assessment-content-items/
Incidents 215
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:
• 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": {
},
"lostWages": true,
"severity": {
"code": "major-injury"
},
"treatmentType": {
216 Incidents
"code": "hospital"
}
}
}
}
Living expenses incidents

A living expenses incident is an object that captures loss information about expenses incurred as a result of the loss of
use of a property. (For example, staying in a hotel while a damaged home is repaired.)
Endpoints for managing living expense incidents

Use the following endpoints to manage living expense incidents:
• GET /claims/{claimId}/living-expense-incidents
• POST /claims/{claimId}/living-expense-incidents
• GET /claims/{claimId}/living-expense-incidents/{incidentId}
• PATCH /claims/{claimId}/living-expense-incidents/{incidentId}
• DELETE /claims/{claimId}/living-expense-incidents/{incidentId}
For example, the following request creates a living expense incident for cc:5433.
POST /claim/v1/claims/cc:5433/living-expenses-incidents
{
"data": {
"attributes": {
"description": "7-day hotel stay during flood damage repair",
"lossParty" : {
"code" : "insured"
},
"startDate" : "2020-08-31T07:00:00.000Z"
}
}
}
Mobile property incidents

A mobile property incident is an incident that tracks information about lost or damaged items that are moveable, such
as:
• Lost baggage covered by a travel policy
• Stolen jewelry covered by a home owner's policy
• A damaged vehicle covered by a personal auto policy
In ClaimCenter, there is a MobilePropertyIncident entity. But incidents are typically not created at this level. They
are created at one of the child levels: BaggageIncident, PropertyContentsIncident, or VehicleIncident.
Some mobile property incidents make use of assessment content items. An assessment content item is an individual
item covered by the policy, such as a laptop in lost baggage or jewelry stored in a house safe.
Baggage incidents
A baggage incident is an object that captures loss information about a piece of baggage that was lost or damaged
during a covered trip. Travel policies may also cover individual items within the baggage. Each covered item is an
assessment content item.
In ClaimCenter, baggage incidents are stored in the BaggageIncident entity, which is a subtype of
MobilePropertyIncident. Assessment content items are stored in the AssessmentContentItem entity.
In Cloud API, the Claim API has multiple sets of endpoints for baggage incident information:
Incidents 217
• 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/
• PATCH /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items/
• DELETE /claims/{claimId}/baggage-incidents/{incidentId}/assessment-content-items/
For example, the following request retrieves the assessment content items for baggage incident cc:443 on claim cc:76.
GET /claim/v1/claims/cc:76/baggage-incidents/cc:443/assessment-content-items
RESPONSE:
{
"count": 2,
"data": [
{
"attributes": {
"contentCategory": {
"code": "computers",
"name": "Computers"
},
"contentSchedule": {
"code": "travel",
"name": "Travel"
},
"description": "iPad Pro",
"id": "cc:SxxdfwnGPPus1JO9lUrPh",
"incidentOrder": 1,
"numberOfItems": 1,
218 Incidents
"purchaseCost": {
"amount": "760.00",
"currency": "usd"
}
},
...
},
{
"attributes": {
"code": "cameras",
"name": "Cameras"
},
"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
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:
• GET /claims/{claimId}/property-contents-incidents
• POST /claims/{claimId}/property-contents-incidents
Incidents 219
• 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/
• PATCH /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items/
• DELETE /claims/{claimId}/property-contents-incidents/{incidentId}/assessment-content-items/
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": {
"code": "jewelry"
},
"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
• GET /claims/{claimId}/property-contents-incidents/{incidentId}/scheduled-items/
{scheduledItemId}
220 Incidents
• 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": {
"attributes": {
"collisionPoint": {
"code": "front"
},
Incidents 221
"damageDescription": "Damage to bumper and front panels",

"driver": {
"id": "cc:102"
},
"severity": {
"code": "moderate-auto"
},
"vehicle": {
"licensePlate": "7FDG745",
"make": "Mercury",
"model": "Sable",
"state": {
"code": "CA",
"name": "California"
},
"vin": "6GYF54637HD645370",
"year": 1993
}
}
}
}
Trip incidents
Overview of trip incidents
A trip incident is an incident that captures loss information related to a covered trip on a travel policy, such as a
Personal Travel policy.
Trip incidents in ClaimCenter

Trip incidents are managed using the TripIncident entity. This entity has two arrays:
• An array of TripAccommondations
◦ Members of this array track the original and changed accommodation on the travel schedule
• An array of TripSegments
◦ Members of this array track the original and changed segments on the travel schedule
Trip incidents in Cloud API

In Cloud API, the Claim API has multiple sets of endpoints for trip incident information:
• One set for the trip incident itself
• One set for trip accommodations
• One set for trip segments
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
222 Incidents
{
"data": {
"attributes": {
"description": "Flight cancelled due to airline strike",
"tripRiskUnit": {
"id": "cc:SHEXDGWJHfyVMKSxBLFZ9"
}
}
}
}
Managing trip accommodations

Use the following endpoints to manage a trip incident's trip accommodations:
• GET /claims/{claimId}/trip-incidents/{incidentId}/trip-accommodations
• POST /claims/{claimId}/trip-incidents/{incidentId}/trip-accommodations
• GET /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-accommodations/
{accommodationId}
• PATCH /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-accommodations/
{accommodationId}
• DELETE /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-accommodations/
{accommodationId}
For example, the following request creates a trip accommodation for trip incident cc:9811 on claim cc:411.
POST /claim/v1/claims/cc:411/trip-incidents/cc:9811/trip-accommodations
{
"data": {
"attributes": {
"cancelOnly": false,
"paidAmount": {
"amount": "508.00",
"currency": "aud"
},
"propertyName": "Yotel Syndey"
}
}
}
Managing trip segments

Use the following endpoints to manage a trip incident's trip segments:
• GET /claims/{claimId}/trip-incidents/{incidentId}/trip-segments
• POST /claims/{claimId}/trip-incidents/{incidentId}/trip-segments
• GET /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-segments/{segmentId}
• PATCH /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-segments/{segmentId}
• DELETE /claims/{claimId}/trip-incidents/{incidentId}/{incidentId}/trip-segments/{segmentId}
For example, the following request creates a trip segment for trip incident cc:9811 on claim cc:411.
POST /claim/v1/claims/cc:411/trip-incidents/cc:9811/trip-segments
{
"data": {
"attributes": {
"arrivalDateTime": "2022-10-16T00:00:00.000Z",
"cancelOnly": false,
"carrierName": "Jetstar",
"carrierNumber": "607",
"departureDateTime": "2022-10-16T00:00:00.000Z",
"otherFees": {
"amount": "50.00",
"currency": "usd"
},
"portOfDisembarkation": "Brisbane",
"portOfEmbarkation": "Sydney",
Incidents 223
"transportType": {
"code": "airline"
}
}
}
}
224 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 225
covers damage to a vehicle owned by the insured. PALiabilityCov covers damages to vehicles owned by a third party
where the damage was caused by the insured.
Every exposure is indirectly linked to an exposure type. An exposure type is a set of information to gather for an
exposure. For example, VehicleDamage is an exposure type. It consists of information to gather about a damaged
vehicle, such as where on the vehicle is the damage, who was the driver, and were the airbags deployed.
Two exposures can be linked to the same exposure type, even if the coverages are different. For example,
PACollisionCov and PALiabilityCov are different coverages, but they can both involve damaged vehicles. The same
set of information needs to be gathered about a damaged vehicle, regardless of which coverage is involved. Therefore,
the two coverages are mapped to a single exposure type - the VehicleDamage exposure type. This exposure type is
used to determine the information to gather during the claims process.
Some coverages link to multiple exposure types. Therefore, ClaimCenter does not link coverage types directly to
exposure types. Instead, ClaimCenter links them through coverage subtypes. A coverage subtype is a value that links a
coverage type to an exposure type. For example:
• PACollisionCov is a coverage subtype that links the PACollisionCov coverage to the VehicleDamage exposure
type. (In this case, the coverage type and coverage subtype have the same name.)
• PALiabilityCov_vd is a coverage subtype that links the PALiabilityCov coverage to the VehicleDamage
exposure type.
When you create an exposure, you must specify both its coverage and coverage subtype.
Exposures and reserve lines

When an exposure is created, ClaimCenter also creates a reserve line for the exposure. A reserve line is an amount of
money set aside for expected payments related to a given exposure. Insurers are often legally required to create reserve
lines to ensure that they maintain financial solvency.
Reserve lines can be created:
• Automatically by business rules
• Manually by adjusters
When a payment is made from an exposure, the money comes from this reserve line.
For more information on reserve lines, see “Reserves” on page 263.
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 137.
226 Exposures
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 191.
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 209.
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
External user authorization for exposures

Developer Guide.
In the base configuration, external users have the ability to view exposure information on claims related to their
policies. But, they can view only the exposure where the claimant is a ClaimContact with the role of Insured. They
cannot view information about any other exposures (such as exposures where the claimant does not have the role of
Insured). They also cannot edit information on any exposure.
The claim has two vehicle incidents: one for Ray Newton's vehicle and one for David Preston's vehicle. There is one
exposure for each vehicle.
Exposures 227

◦ View information about the exposure for his vehicle incident, as he is the claimant on this exposure and he has
the role of Insured.
◦ View or edit information about David Preston's exposure. (David Preston is the claimant for that exposure, and
David Preston does not have the role of Insured.
◦ Edit information on either exposure.
There is a similar type of restricted access for ClaimContacts and incidents. For more information, see:
• “External user authorization for ClaimContacts” on page 193
• “External user authorization for incidents” on page 212
Creating exposures
Use the POST /claims/{claimId}/exposures endpoint to create new exposures.

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": {
"code": "..."
},
"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:
228 Exposures
◦ id, if the claimant already exists on the claim

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

To build an exposure payload, you must:
1. Identify the coverage type
2. Identify the coverage subtype
3. Create or identify the claimant
4. Create or identify the incident
5. Identify the coverage
Note that each item in the previous list does not necessarily map to a single block of code. When it is time to create the
exposure, the caller application may already have the required information. Also, the caller application may be able to
query ClaimCenter for multiple pieces of information in a single call.
Example creation of an exposure payload

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

If the caller application does not know the coverage type, it can use the GET /claims/{claimId}/policy endpoint to
determine the coverages attached to the Honda Civic.
Request to determine the coverage type
GET http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:8037/policy/vehicle-risk-units?fields=*all
Response payload (snippet)
"RUNumber": 1,
"coverages": [
{
...
"coverageType": {
"code": "PACollisionCov",
"name": "Collision"
}
...
}
],
"id": "cc:9",
"vehicle": {
...
Exposures 229
"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": {
},
...
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 353.
Request to determine the coverage subtype
GET http://localhost:8080/cc/rest/common/v1/typelists/CoverageSubtype
?typekeyFilter=category:cn:CoverageType.PACollisionCov
"description": "Subtype of coverage, filtered by CoverageType",

"name": "CoverageSubtype",
"typeKeys": [
{
"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": {
},
},
...
Step 3: Create or identify the claimant

If the claimant exists on the policy, the payload can identify the claimant by its policySystemId. If necessary, the
caller application can query the Policy Administration System for the policySystemId.
If the claimant does not already exist, the caller application can create a new ClaimContact in the POST /exposures
request payload and then reference that ClaimContact using a refid. This technique is referred to as request inclusion.
For more information, see “Request inclusion” on page 103.
230 Exposures
If the claimant exists in ClaimCenter, the payload can identify the claimant by its id. If necessary, the caller application
can query ClaimCenter for the id.
Note: If the claimant already exists in ClaimCenter, always reference the existing ClaimContact and use the id
field. Do not create an additional ClaimContact through the use of the refid field. Creating the same logical
ClaimContact twice results in duplicate data. This can complicate the processing of the claim.
In this example, the claimant has already been copied over to ClaimCenter. Therefore, the payload will identify the
claimant by ClaimCenter id.
Request to determine the claimant ID
GET http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:8037/contacts
{
"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": {
},
},
"claimant": {
"id": "cc:32"
},
...
Step 4: Create or identify the incident

An incident is a collection of information that typically represents an item that was lost or damaged. Incidents may
reference objects on a policy. (For example, a vehicle incident can reference a vehicle on the policy.) But, incidents
never appear on policies. Incidents exist solely in ClaimCenter.
If the incident does not already exist, the caller application can create a new incident in the POST /exposures request
payload and then reference that incident using a refid. This technique is referred to as request inclusion. For more
information, see “Request inclusion” on page 103. 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.
Exposures 231
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": {
},
},
"claimant": {
"id": "cc:32"
},
"refid": "newVehicleIncident"
},
...
}
},
"included": {
{
"attributes": {
"vehicle": {
}
},
"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 http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:8037/
policy/vehicle-risk-units/cc:121

{
"attributes": {
"coverages": [
{
"coverageType": {
},
"id": "cc:7007",
...
232 Exposures
Exposure request payload (complete)

The complete POST /exposures request payload looks like this:
{
"data": {
"attributes": {
},
},
"claimant": {
"id": "cc:32"
},
"refid": "newVehicleIncident"
},
"coverage": {
"id": "cc:7007"
}
}
},
"included": {
{
"attributes": {
"vehicle": {
}
},
"refid": "newVehicleIncident",
"method": "post",
"uri": "/claim/v1/claims/demo_sample:8037/vehicle-incidents"
}
]
}
}
Querying for and modifying exposures

You can query for exposures using:
• GET /claims/{claimId}/exposures
• GET /claims/{claimId}/exposures/{exposureId}
You can modify an exposure using:
• PATCH /claims/{claimId}/exposures/{exposureId}
Assigning exposures
Every exposure is assigned to a group and a user in that group. The assigned user has the primary responsible for
managing the exposure.
Most exposures are assigned to the same user and group that owns the claim. However, exposures occasionally require
special expertise that require assignment to a different user and group than that of the claim. For example, suppose
there is a personal auto claim that includes three exposures: two exposures for damaged vehicles and one exposure for
medical payments related to a fatal injury. The claim and the vehicle exposures are routine and can all be assigned to
the same group and user. But the injury exposure is likely to involve a significant payment or litigation. This exposure
is assigned to a group and user that specialize in fatalities.
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.
Exposures 233
Assignment options
An exposure can be assigned through the system APIs in the following ways:
• 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:

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.

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" : {
}
}
}
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.
{
"data": {
"attributes" : {
}
}
}
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.
234 Exposures
"data": {
"attributes" : {
"claimOwner" : true
}
}
}

The following assigns exposure cc:48 (from claim cc:34) using automated assignment rules.
{
"data": {
"attributes": {
"autoAssign" : true
}
}
}
Additional exposure endpoints

The system APIs provide additional endpoints to interact with exposures.
Deleting draft exposures

During the FNOL process, the claim passes through two states: draft and open.
• A draft claim is a claim that has been saved to the ClaimCenter database, but there is not yet enough information
for the claim to enter the adjudication process. Draft claims are not assigned to any user.
• An open claim is a claim that has been saved to the ClaimCenter database with enough information to enter the
adjudication process. Once a claim becomes open, it is assigned to an adjuster.
A draft exposure is an exposure on a draft claim. While a claim is in a draft state, you can delete any exposures created
on the claim using the DELETE /claims/{claimId}/exposures/{exposureId} endpoint.
Executing a POST /claims/{claimId}/submit on a draft claim promotes the claim and all of its exposures to open
status. Once a claim has been submitted, you can no longer delete its exposures.
Validating exposures
Similar to claim validation, the POST /claim/{claimId}/exposures/{exposureId}/validate endpoint returns
allvalidation levels reached for the given exposure. It can also be used to determine what conditions must be met for
the exposure to advance to a given validation level.
Checking an exposure's validation level can be useful in the following situations:
• You want to determine whether the exposure has enough information to be assigned to an adjuster. You can use
the /validate endpoint to determine if the exposure has reached the "new loss completion" level. If the exposure is
below the "new loss completion" level, the payload identifies the conditions needed to reach "new loss completion".
• You want to execute a payment for an exposure. You can use the /validate endpoint to determine if the exposure
has reached the "ability to pay" level, as well as all levels before “ability to pay”. If the exposure is below the
"ability to pay" level, the payload identifies the conditions needed to reach "ability to pay".
• Your instance of ClaimCenter has custom validation levels. You can use the /validate endpoint to determine all
the levels the exposure has reached in its lifecycle, including those custom levels.
For more information on validation through system APIs, see “Validating claims” on page 185.
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.
Exposures 235
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 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>
236 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 237

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 vendorservicedetails.xml 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.
238 Service requests

A service request that is fully executed goes through the following stages:
1. Draft
• The service request has been created in ClaimCenter but not yet submitted to the vendor.
2. Requested
• The service request has been submitted to the vendor, but not yet accepted.
3. In Progress
• The vendor has accepted the service request and started the work.
• For a Quote Only service request, the "work" consists of generating a quote.
• For a Quote and Service service request, the "work" consists of generating a quote and then, once the quote is
approved, providing the services.
• For all other service request kinds, the "work" consists of directly providing the services.
4. Work Complete
• The work (the quote or the set of services) is complete.
• At this point, the vendor may or may not have submitted invoices for the work.
• At this point, the invoices may or may not have been paid.
There are additional stages that a service request could reach:
• Declined
◦ A service request can reach this stage if the vendor decides to not accept a service request. For example, this
could happen if the service request is for a rental car and the vendor has no available cars.
◦ A service request can reach this stage if the vendor accepts a service request, but then later states they cannot
complete it. For example, this could happen if the vendor experiences an unexpected reduction in available
mechanics.
• Canceled
◦ A service request can reach this stage when the insurer decides the service request is no longer needed. For
example, the insured could decide to buy a new car instead of fixing the damaged car.
• Vendor Waiting

◦ A service request can reach this stage when the vendor cannot take action on the service without further input
from ClaimCenter. For example, the vendor could have submitted a quote that requires approval from an
adjuster.
Invoices for service request

For all service requests whose kind is Quote and Service, Service Only, or Unmanaged, once the work is complete, the
vendor typically submits one or more invoices. These invoices are attached to the service request. They are paid using
money from one of the claim's reserve lines. Depending on the nature of the service request, they may also require
adjuster approval.
Straight-through invoice processing

Straight-through invoice processing is a configurable ClaimCenter behavior in which invoices that meet certain criteria
are automatically approved and paid. Straight-through invoice processing is frequently used with Unmanaged service
requests, as these service requests are designed to involve minimal processing.
Overview of service requests in the Cloud API
Service request APIs and vendor portals

In previous releases of ClaimCenter, service requests were primarily managed by two systems: ClaimCenter and a
vendor portal. The vendor portal is an application used by a vendor to manage information about service requests from
ClaimCenter. In this paradigm:
ClaimCenter is responsible for actions such as:
• Creating the service request
• Submitting the service request to the vendor
• Paying the vendor.
The vendor is responsible for actions such as:
• Accepting the service request
• Quoting the service request
• Submitting invoices for the service request
Cloud API provides a wider range of options for processing service requests. The service request APIs can be used by
a vendor portal. But they can also be used by:
• An alternate front-end application for adjusters who specialize in service requests
• A service that submits or pays for vendor invoices in bulk
• A vendor management system that manages service requests for multiple vendors
Thus, the service request functionality exposed by Cloud API is not limited to only the functionality that would be used
by vendor portals. Rather, it exposes the service request functionality needed to manage the entire service request
process.
Lifecycle management
Cloud API provides a number of endpoints to manage the lifecycle of a service request. This includes both endpoints
for actions taken by the insurer (such as submitting a service request) and endpoints for actions taken by the vendor
(such as accepting a service request).
As of this release, there are endpoints to advance a service request to most stages in the lifecycle. However, there are
currently no endpoints to move a service request to the "Vendor Waiting" status.

Required service request data model

ClaimCenter includes two service requests data models: the "legacy model" and the Core Service Request data model.
Each instance of ClaimCenter can use only one of these models. In the base configuration, the Core Service Request
data model is enabled by default. In general, Guidewire recommends insurers use the Core Service Request data model.
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.
POST /service-requests Draft "Submit request"
POST /{serviceRequestId}/submit Requested "Agree to perform service"
POST /{serviceRequestId}/accept In Progress "Finish the work"
POST /{serviceRequestId}/complete- Work Complete "Add invoice"
work
POST /{serviceRequestId}/invoices Work Complete "Pay invoice"
As of this release, there are no endpoints to pay invoices. However, invoices can be paid through the user interface.

Unmanaged service requests

The following table lists the stages that an Unmanaged service request can advance to through the system APIs. It
identifies which system API action advances the service request to the next stage, and the value of the service's Next
Action column in the ClaimCenter Services list.
POST /service-requests Work Complete "Add invoice"
POST /{serviceRequestId}/invoices Work Complete "Pay invoice"
As of this release, there are no endpoints to pay invoices. Unmanaged service requests are expected to make use of
straight-through invoice processing to automatically approve and pay invoices. However, if required, invoices can be
paid through the user interface.
Composite request limitations with service requests

For service requests that are Quote Only, Quote and Service, or Service Only, you can create and submit a service
request in a single composite request. But you cannot advance these types of service requests to any other stage in its
life cycle (such as in progress, declined, or canceled at vendor or insurer request) in the same composite request.
Querying for service requests

The following Claim API endpoints can be used to request information about service requests:
Endpoint Response
GET /service-requests All service requests
By default, the payload in the response includes the ID of each service request and
each claim the service request belongs to.
GET /claims/{claimId}/service- All service requests for the specified claim
requests
GET /claims/{claimId}/service- The specified service request.
requests/{serviceRequestId} Note that in order to get information about a specific service request, you must
access the service request through its parent claim.
Creating service requests

To create a service request, use the following endpoint:
• POST /claims/{claimId}/service-requests
Once a service request has been created, its Progress field is set to Draft.

At a minimum, a service request must specify:
• The service request kind, such as Service Only or Unmanaged (in the kind field)
• The vendor (in the specialist field)
• A service instruction (in the instruction field), which at a minimum must contain:
◦ The customer (in the customer field)
◦ The location where the service is being performed (in the serviceAddress field)
◦ The set of services being performed (in the services array)

• A requested quote completion date, if the service request is Quote Only or Quote and Service
• A requested service completion date, if the service request is Service Only
Additional details on each required field

A service request must specify the service request kind. This is specified in the kind field, and it must be set to a
typecode from the ServiceRequestKind typelist, such as:
• 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 vendorservicetree.xml 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 vendorservicedetails.xml file, which you can also access through Studio.
If the service request's kind is quoteonly or quoteandservice, you must also specify a requested quote completion
date in the requestedQuoteCompletionDate.
If the service request's kind is serviceonly, you must also specify a requested service completion date in the
requestedServiceCompletionDate.
Sample Service Only service request

The following payload shows an example of a minimal Service Only service request for claim 235-53-365889 in the
sample data (whose ID is cc:33). The service request will be performed by Joe's Auto Body Shop (ClaimContact cc:16)
at 1313 Mockingbird Lane in Arcadia, California, for Robert Farley (ClaimContact cc:13). There is one service to be
performed: Salvage (autoothersalvage). The service is requested to be completed by March 3, 2021.
POST http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:20/service-requests
{
"data": {
"attributes": {
"kind": {
"code": "serviceonly"
},
"specialist": {
"id": "cc:16"

},
"instruction": {
"customer": {
"id": "cc:13"
},
"serviceAddress": {
"addressLine1": "1313 Mockingbird Lane",
"city": "Arcadia",
"country": "US",
"state": {
"code": "CA",
}
},
"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 http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:20/service-requests
{
"data": {
"attributes": {
"kind": {
"code": "unmanaged"
},
"specialist": {
"id": "cc:16"
},
"instruction": {
"customer": {
"id": "cc:13"
},
"serviceAddress": {
"addressLine1": "1313 Mockingbird Lane",
"city": "Arcadia",
"country": "US",
"state": {
"code": "CA",
}
},
"services": [
{
"code": "autoothertowing"
}
]
}
}
}
}
Modifying existing service requests

Use the following endpoints to modify a service request without advancing it through its lifecycle.
PATCHing service requests

To PATCH a service request, use:
• PATCH /claims/{claimId}/service-requests/{serviceRequestId}

You cannot PATCH any field in the base configuration, as all of them can be set during creation only. But, if your
instance includes extension fields on ServiceRequest or a related entity, you could use this endpoint to update those
fields.
Specifying the reason for change

In ClaimCenter, the ServiceRequest entity has a History array which contains a set of ServiceRequestChange
instances. The ServiceRequestChange entity has a Description field, which is used to capture the reason for the
change.
Whenever a service request is modified through a PATCH, the Description field is set using the following display
key:
Rest.Claim.V1.ServiceRequest.PropertiesChanged = 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:
• 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:

autoAssign Boolean Whether to assign the service request using assignment rules
claimOwner Boolean Whether to assign the service request to the claim owner
groupId string The ID of the group to assign the service request to
userId string The ID of the user to assign the service request to
The Assignee resource cannot be empty. It must specify a single assignment option (group and user, group only, claim
owner, or automatic assignment).
For more information on how assignment rules execute assignment, see the Gosu Rules Guide.


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" : {
}
}
}
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.
{
"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).
{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}

The following assigns service request cc:102 (from claim demo_sample:20) using automated assignment rules.
{
"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.

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.

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.

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.

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

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

An invoice must have the following information:
• A description
• A set of one of more line items. Each line item must specify:
◦ A monetary amount (with amount and currency values)

◦ A category (a code from the ServiceRequestStatementLineItemCategory typelist)

The following creates an invoice for service request cc:9. The invoice contains two line items: a $150 USD charge for
labor, and a $50 USD charge for parts. It also includes an optional reference number for the invoice, and optional
descriptions for each line item.
POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices
{
"data": {
"attributes": {
"description": "Invoice submitted using system APIs",
"referenceNumber": "771-DX5667",
"lineItems": [
{
"amount": {
"amount": "150.00",
"currency": "usd"
},
"category": {
"code": "labor"
},
"description": "Invoiced labor"
},
{
"amount": {
"amount": "50.00",
"currency": "usd"
},
"category": {
"code": "parts"
},
"description": "Invoiced parts"
}
]
}
}
}
Approving service request invoices

To approve an invoice, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/approve
The POST invoices/{invoice-id}/approve endpoint does not require a request body.
The following approves invoice cc:06 for service request cc:9.
POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/approve
(no request body)
Marking invoices as paid

To mark an invoice as paid, use:
• POST /claims/{claimId}/service-requests/{serviceRequestId}/invoices/{invoice-id}/mark-as-paid
When an invoice is marked as paid, there must be an associated check (which was presumably used to pay the invoice).
In the /mark-as-paid request payload, you must include a check attribute with the ID of the associated check. For
example, the following payload marks invoice cc:6 (for service request cc:9 on claim demo_sample:20) as paid. The
associated check is cc:413.
POST /claim/v1/claims/demo_sample:20/service-requests/cc:9/invoices/cc:6/mark-as-paid
{
"data": {
"attributes": {
"check": {
"id": "cc:413"
}
}
}
}

Note that ClaimCenter has validation rules that limit the ability to mark an invoice as paid based on the invoice's state.
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"
}
}
}


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": {
"type": "Group",
"uri": "/admin/v1/groups/demo_sample:31"
},
"assignedUser": {
"type": "User",
},
"code": "assigned",
"name": "Assigned"
},
"caseNumber": "34-84982A",
"courtType": {
"code": "state",
"name": "State"
},
"fileDate": "2019-09-06T07:00:00.000Z",
"id": "cc:SKbNseiqKR6rbsdYtA5Qh",
Matters 255
"matterType": {
"code": "General",
"name": "General"
},
"name": "Ray Newton matter",
"code": "payment",
}
},
...
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.

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"
}
}
}
256 Matters
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 257.
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 310. 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:
• 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:

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" : {
}
}
}
Matters 257
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.
{
"data": {
"attributes" : {
}
}
}
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.
{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}
Using automated assignment

The following payload assigns matter cc:99 for claim demo_sample:1 using automated assignment rules.
{
"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 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"
}
}
}
}
258 Matters
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 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 259
260 Matters
part 4
Business flows: Financials
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 261

262 Business flows: Financials

chapter 21
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 263
◦ 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 307.
(When the reserve set is submitted through Cloud API, the user whose authority limits are checked is the session user.
For more information on how the session user is determined, refer to the Cloud API Authentication Guide.)
Reserve transactions and acknowledgment

ClaimCenter is typically integrated with several downstream systems, including a general ledger system. When
ClaimCenter executes financial activity, it typically informs the general ledger. At some later point, the general ledger
may acknowledge that the information about the activity has been received.
When a reserve transaction is created and approved, its status is initially set to "submitting". Once the transaction has
been acknowledged, its status is changed to "submitted".
Querying for reserves

You can use the following endpoints to query for reserve-related information.
Endpoint Description
GET /claims/{claimId}/reserve-sets Retrieve a list of reserve sets
GET /claims/{claimId}/reserve-sets/{reserveSetId} Retrieve details of a reserve set
GET /claims/{claimId}/reserves The reserves associated with a given claim
GET /claims/{claimId}/reserves/{transactionId} The details of a specific reserve
Sample response for a reserve set

For example, the ClaimCenter sample data includes a claim whose ID is demo_sample:1. This claim has one reserve
set. The following is the call to get that reserve set, and the response. The response has been edited for clarity. Note the
following:
• The reserve set includes 9 transactions, three of which are shown in the output below.
• The reserve set was approved on 2021-08-08.
• The reserve set was submitted by Andy Applegate.
• The first three transactions in the reserve set are as follows:
◦ A reserve for the first exposure, with a cost type of "Claim cost" and a cost category of "Auto body".
◦ A reserve for the first exposure, with a cost type of "Expense - A&O" and a cost category of "Other".
264 Reserves
◦ 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": {
},
"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": {
"name": "Collision"
},
"currency": {
"code": "usd",
"name": "USD"
},
"id": "cc:22",
"lineItems": [
{
"claimAmount": {
"amount": "500.00",
"currency": "usd"
},
"comments": "Repairs",
"id": "cc:56",
"lineCategory": {
"code": "other",
"name": "Other"
},
"reportingAmount": {
"amount": "500.00",
"currency": "usd"
},
"reservingAmount": {
"amount": "500.00",
"currency": "usd"
Reserves 265
},
"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",
},
"code": "usd",
"name": "USD"
}
},
"status": {
"code": "submitted",
"name": "Submitted"
},
"type": {
"code": "Reserve",
"name": "Reserve"
}
},
..
}
Creating reserves
When creating reserves from Cloud API, there is no POST endpoint whose root resource is a reserve line or a reserve
transaction. Reserve lines and reserve transactions are created within the context of a reserve set.
To create a reserve set, use the following endpoint:
• POST /claims/{claimId}/reserve-sets
When you create a reserve set, you must specify the reservesToWrite. This is reserve set which consists of an array
of reserve transactions. For each member of the array, you must specify:
• The reserveLine for the reserve. To identify this, you must specify:
◦ costCategory (a value from the CostCategory typelist)
◦ costType (a value from the CostType typelist)
◦ The id of the parent exposure (This can also be explicitly set to null, in which case the reserve line is created at
the claim level.)
◦ reservingCurrency
• An array of one or more transaction lineItems, each of which must specify:
◦ A transactionAmount (specified as an amount and a currency)
• The reserve transaction currency
Currencies in the POST reserve-sets payload

Every reserve transaction consists of one of more line items. Reserve transactions and line items are stored in different
database tables. However, for a given reserve transaction, the currency of every line item in the reserve transaction
must match the currency of the reserve transaction.
This distinction may not be evident when using the user interface. The user chooses a currency for the transaction, and
all line items automatically default to that transaction. This hides the fact that they are technically distinct values.
266 Reserves
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 295.
Approval status
When a reserve set is submitted, ClaimCenter checks the corresponding user's authority limits.
• If the amount is at or below the user's authority limit, the reserve set is approved. The appropriate amount is added
to the reserve line, and the response object's approvalStatus field is set to approved.
• If the amount is above the user's authority limit, the reserve set requires approval. An approval activity is created
and sent to a user with sufficient approval authority. No amount is added to the reserve line, and the response
object's approvalStatus field is set to unapproved.
A given user can have an authority limit for "claim total reserves", "exposure total reserves", or both. For more
information on authority limits, see the Application Guide.
When the reserve set is submitted through Cloud API, the user whose authority limits are checked is the session user.
For more information on how the session user is determined, see the Cloud API Developer Guide.
Reserves and composite requests

Within a composite request, you cannot create or modify financial objects. This includes reserve sets and reserve
transactions. However, within a composite request, you can GET information on financial objects.
Example of creating reserves

The following payload is an example of creating a reserve line.
• The ID of the claim is cc:61.
• The ID of the exposure is cc:79.
• There is only one reserve transaction.
◦ The transaction is for a reserve line whose cost type and cost category is Claim Cost / Auto Body (claimcost
and body).
◦ The transaction's currency is USD.
◦ The transaction has a single line item for $1000.
POST /claims/cc:61/reserve-sets
{
"data": {
"attributes": {
"reservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:79"
},
"code": "usd"
}
},
"lineItems": [
{
"amount": "1000.00",
"currency": "usd"
Reserves 267
}
}
],
"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.
POST /claims/cc:61/reserve-sets
{
"data": {
"attributes": {
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:79"
},
"code": "usd"
}
},
"lineItems": [
{
"amount": "250.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}
Acknowledging reserve transactions

ClaimCenter is typically integrated with a general ledger system. When ClaimCenter executes financial activity, it
typically informs the general ledger. At some later point, the general ledger may acknowledge that the information
about the activity has been received.
268 Reserves
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>
Reserves 269
270 Reserves
chapter 22
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 271

◦ 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 307.
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.
GET /claims/{claimId}/check-sets Retrieve a list of check sets
GET /claims/{claimId}/check-sets/{checkSetId} Retrieve details of a check set
GET /claims/{claimId}/checks The checks associated with a given claim
GET /claims/{claimId}/checks/{checkId} The details of a specific check
GET /claims/{claimId}/payments The payment transactions associated with a given claim
GET /claims/{claimId}/payments/{transactionId} The details of a specific payment transaction
Sample response for a check set

For example, the ClaimCenter sample data includes a claim whose ID is demo_sample:1. This claim has one check set.
The following is the call to get that check set, and the response. The response has been edited for clarity. Note the
following:
• The check set has one check.
272 Creating checks

• 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"
}
}
],
"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;
Creating checks 273

Claim Cost/Medical; Submitted"

},
{
Claim Cost/Medical; Submitted"
},
{
"displayName": "(1) 1st Party Vehicle - Ray Newton;
Expense - A&O/Other; Submitted"
},
{
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 185. For more information on validating
exposure, see “Validating exposures” on page 235.
Checks and payment types

When a check is created, each underlying payment can have one of three types:
• Final - This applies to open claims and exposures. This indicates that no additional payments are expected to be
made from the corresponding reserve line.
• Partial - This applies to open claims and exposures. This indicates that additional payments may be made from the
corresponding reserve line.
• Supplement - This is used to make payments on closed claims and exposures.
Check creation through Cloud API

When creating checks from Cloud API, there is no POST endpoint whose root resource is a check or a payment
transaction. Checks and payment transactions are created within the context of a check set. Keep in mind that check
sets can be created only for claims at or above "Ability to pay" and using only exposures at or above "Ability to pay".
To create a check set, use the following endpoint:
• POST /claims/{claimId}/check-sets
Prior to creating the check set, you will need the following:
274 Creating checks

• 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:
◦ 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:
◦ The id of the parent exposure
◦ The reservingCurrency
• The payment transaction currency
You must also specify an array of payees. For each payee you must specify:
• An ID for the payee
◦ If the contact already exists on the claim, you can reference it by its id.
◦ If the contact does not exist on the claim, you can create it in the same call using request inclusion and reference
it using a refid.
• The payeeType (a value from the ContactRole typelist filtered by payee, such as insured, claimant, vendor, or
other)
You must also specify the paymentMethod. This is a value from the PaymentMethod typelist, such as check or eft.
Currencies in the POST check-sets payload

Every payment transaction consists of one of more line items. Payment transactions and line items are stored in
different database tables. However, for a given payment transaction, the currency of every line item in the payment
transaction must match the currency of the payment transaction.
This distinction may not be evident when using the user interface. The user chooses a currency for a check set, and all
line items automatically default to that currency. This hides the fact that they are technically distinct values.
However, this distinction must be taken into consideration when writing a check set payload. There is no mechanism
for the line items to inherit the payment transaction's currency. Therefore, the currency of the payment transaction and
each line item must be explicitly stated, and they must be the same.
There is a third field that is set to a currency value, reservingCurrency. This must always be specified. In an instance
of ClaimCenter that makes use of multicurrency, this can be set to a currency other than the reserve transaction's
currency. For more information, see “Multicurrency” on page 295.
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.
Creating checks 275

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": {
{
"lineItems": [
{
"amount": "75.50",
"currency": "usd"
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:58"
},
"code": "usd"
}
},
"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
"id": "cc:613"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
276 Creating checks

}
}
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
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:
• 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).
Creating checks 277

• 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
• 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
◦ recurrenceWeek.code - Set to a typecode from the RecurrenceWeek typelist (first, second, third, fourth,
or last)
• recurrenceDay
◦ recurrenceDay.code - Set to a typecode from the RecurrenceDay typelist (mon, tue, weds, thurs, fri, sat, or
sun)
For example, the following recurrence could be used to send 7 checks, once every month, on the first Thursday. The
first check will be sent January 7 (the first Thursday in January). The next check will be sent February 4 (the first
Thursday in February), and so on.
"recurrence": {
"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
278 Creating checks

• 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
◦ recurrenceDay.code - 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": {
"numChecks": 12,
"recurrenceDay": {
"code": "thurs"
},
"subtype": {
"code": "WeeklyCheckRecurrence"
},
"weeklyFrequency": 1
}
Deductible handling
Deductible handling in ClaimCenter
A deductible is an amount of money associated with a specific coverage that the insured must pay out of pocket for a
loss before the coverage takes effect. The insurer provides payment only for the amount above and beyond the
deductible. For example, suppose there is a personal auto policy with a collision coverage that has a deductible of
$2000. The associated vehicle is involved in a collision, and the repairs cost $6000. The insured is responsible for
paying the first $2000. The insurer pays the remaining $4000.
ClaimCenter provides functionality to handle deductibles during check creation. This includes keeping track of the
total amount, the amount applied, and the amount remaining to be applied.
For more information on deductible handling, see the Application Guide.
Deductible handling in Cloud API

For Cloud API, deductible handling is part of check creation. A check set has one or more checks, and each check has
one or more payments. A payment is comprised of one or more line items. For an exposure with a deductible,
payments typically have at least two line items.
• One or more line items that represent the total amount of the service or reimbursement.
◦ These line items have a transaction amount, which is typically positive.
• One line item that represents the deductible.
◦ The line item has a transaction amount, which is typically negative.
◦ The line item also has a lineCategory object with a code property set to deductible.
For example, suppose that you are writing the payload for a check the previous example in which a car needs $6000 of
repairs, and there is a $2000 deductible. The lineItems array for the check would have two members:
• The $6000 line item (for the repair service)
• The -$2000 line item with a lineCategory.code of deductible (for the deductible)
Creating checks 279

The lineItems portion of the POST /check-sets payload would appear as follows:
"lineItems": [
{
"amount": "6000.00",
"currency": "usd"
}
},
{
"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": {
{
"lineItems": [
{
"amount": "6000.00",
"currency": "usd"
}
},
{
"amount": "-2000.00",
"currency": "usd"
},
"lineCategory": {
}
}
],
"paymentType": {
"code": "final"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:SFaWbxZwJOCFh_UWbbC_8"
},
"code": "usd"
}
},
"currency": {
"code": "usd"
}
}
],
"payees": [
{
"contact": {
"id": "cc:SHLpehV4HdCDJSJhilgCA"
},
"payeeType": {
"code": "insured"
}
}
],
"paymentMethod": {
"code": "eft"
}
}
}
280 Creating checks

}
}
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}
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.
Creating checks 281

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.
282 Creating checks

chapter 23
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 283
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.
284 Managing the check life cycle

Note the following:

• When a "Requesting" check is managed entirely by APIs, it most commonly moves to "Requested" using the
POST /acknowledge-submission endpoint. There are endpoints that can move a "Requesting" check directly to
"Pending stop" or "Pending void", but these are less common routes.
• Once a check is "Requested", the three most common outcomes are:
◦ The check moves to "Issued" (the check is sent) and then "Cleared" (the check is cashed).
◦ The check moves to "Pending stop" and then "Stopped".
◦ The check moves to "Pending void" and then "Voided".
The previous diagram does not exhaustively list every possible transition. For example, a check that is "Issued" can
move to "Pending stop", and a check that is "Pending stop" can moved to "Issued". This diagram identifies only the
most common paths. For a complete discussion of all possible transitions, see the Application Guide.
Also, there are some life cycle statuses that you cannot advance a check to through Cloud API. This includes:
• Denied
• Pending transfer
• Transferred
If you attempt to advance a check from one status to another in a way that is not possible, the call fails and Cloud API
returns an error message indicating the operation is not possible. For example, if you attempt to call POST /mark-
cleared on a check that is "Requesting", Cloud API returns the following message:
"The 'mark-cleared' operation is not currently available for this check"

Advancing a check beyond submission through Cloud API

To advance a check to a given status, use the corresponding endpoint as described in the following table.
Status To Advance To Endpoint

Requested POST /claims/{claimId}/checks/{checkId}/acknowledge-submission
Issued POST /claims/{claimId}/checks/{checkId}/mark-issued
Cleared POST /claims/{claimId}/checks/{checkId}/mark-cleared
Pending stop POST /claims/{claimId}/checks/{checkId}/request-stop
Stopped POST /claims/{claimId}/checks/{checkId}/mark-stopped
Pending void POST /claims/{claimId}/checks/{checkId}/request-void
Voided POST /claims/{claimId}/checks/{checkId}/mark-voided
When using these endpoints, you do not need to provide a request body.
For example, suppose check cc:601 on claim cc:400 has a status of "Requesting". The following payload advances the
check to the "Requested" status.
POST claim/v1/claims/cc:400/checks/cc:601/acknowledge-submission
<no request body>
Then, the following payload advances the check to the "Issued" status.
POST claim/v1/claims/cc:400/checks/cc:601/mark-issued
<no request body>
Finally, the following payload advances the check to the "Cleared" status.
POST claim/v1/claims/cc:400/checks/cc:601/mark-cleared
<no request body>
You can also view the status of a given check through the ClaimCenter user interface. Navigate to the claim and then,
in the left-hand side bar, click Financials > Checks. This shows a list of checks for the claim and the status of each
check.
The check life cycle and composite requests

Within a composite request, you cannot create or modify financial objects. This includes use of the check life cycle
endpoints (such as POST /mark-issued). However, within a composite request, you can GET information on financial
objects.
Acknowledging payment transactions

ClaimCenter is typically integrated with one or more downstream financial systems. When ClaimCenter executes
financial activity, it typically informs the downstream systems. At some later point, one of these systems may
acknowledge that the information about the activity has been received.
Checks have associated payments. When a check set has been approved, the associated checks and payment
transactions have a status of "submitting". When you acknowledge a check, the status of the check and its associated
payments changes to "submitted". Thus, there is typically no need to explicitly acknowledge payments. they are
automatically acknowledged when the check is acknowledged. However, Cloud API does provide an endpoint to
acknowledge payments in the unusual circumstance where explicit acknowledgment is required.
To acknowledge a payment transaction, use the following endpoint:
• POST /claims/{claimId}/payments/{transactionId}/acknowledge-submission

When acknowledging a transaction, there is no additional required information. The request can have no body.
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>


chapter 24
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 289
Querying for recoveries and recovery reserves

You can use the following endpoints to query for recovery-related information.
GET /claims/{claimId}/recovery-reserve-sets Retrieve a list of recovery reserve sets
GET /claims/{claimId}/recovery-reserve-sets/{recoveryReserveSetId} Retrieve details of a recovery reserve set
GET /claims/{claimId}/recovery-reserves Retrieve a list of recovery reserves
GET /claims/{claimId}/recovery-reserves/{transactionId} Retrieve the details from a specific recovery reserve
GET /claims/{claimId}/recovery-sets Retrieve a list of recovery sets
GET /claims/{claimId}/recovery-sets/{recoverySetId} Retrieve the details for a specific recovery set
GET /claims/{claimId}/recoveries Retrieve the recovery transactions
GET /claims/{claimId}/recoveries/{transactionId} Retrieve the details of a specific recovery
Sample response for a recovery reserve

You can query for all recovery reserves created in a recovery reserve set by performing a GET on recovery reserves.
The following call gets the recovery reserve. Note the following:
• The recovery reserve was created automatically from a recovery.
• The reserve amount and the transaction amount are equal because the recovery amount was already received.
• The recovery offsets costs paid out for Karen Egertson’s collision policy, which uses the exposure for Karen
Egertson’s first policy vehicle.
• The recovery reserve was created in the expectation of subrogation for the claim.
GET rest/claim/v1/claims/demo-sample:1/recovery-reserves
{
"data": {
"attributes": {
"comments": "Automatically created due to recovery for $100.00 on (1) 1st Party Vehicle - Karen Egertson; Claim
Cost/Auto body; USD; Subrogation",
"coverage": {
"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",
"amount": "100.00",
"currency": "usd"
},
"amount": "100.00",
"currency": "usd"
},
"amount": "100.00",
"currency": "usd"
}
}
],
"reserveLine": {
"costCategory": {
"code": "body",
290 Recoveries and recovery reserves

"name": "Auto body"

},
"costType": {
},
"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"
},
"code": "usd",
"name": "USD"
}
},
"status": {
"code": "submitting",
"name": "Submitting"
},
"subtype": {
"code": "RecoveryReserve",
"name": "RecoveryReserve"
}
}
}
}
Creating recoveries and recovery reserves

Recovery and recovery reserve dependency criteria
A recovery reserve is an object that defines the amount of money you anticipate receiving for a claim, such as for
subrogation or salvage. A recovery can reference a recovery reserve to specify the amount of money received going
towards the recovery reserve total, whether that be a partial amount of the recovery reserve’s total amount of money
received.
You can also create a recovery without a referenced recovery reserve, in which case the recovery automatically creates
the recovery reserve. The recovery reserve is created for the recovery; creating a recovery without a recovery reserve
assumes that the full amount the money received in the reserve is the total expected amount of the recovery reserve.
Creating a recovery reserve

When creating recovery reserve from Cloud API, there is no POST endpoint whose root resource is a recovery reserve.
Recovery reserves are created in the context of a recovery reserve set.
To create a recovery reserve, use the following endpoint:
• POST /claims/{claimId}/recovery-reserve-sets
Prior to creating the recovery reserve set, you need the following information:
• Cost type
• Cost category
• Currency
The recoveryReservesToWrite object

When you create a recovery reserve set, you must specify the recoveryReservesToWrite. At a minimum, it must
consist of the following items:
• The reserveLine specifies where the money is coming from. To identify this, you must specify:


◦ The recovery category (a value from the RecoveryCategory typelist)
An array of one or more transaction lineItems, each of which must specify:
• The transactionAmount, including the amount and currency
• The currency (a value from the currency typelist)
Note that transactions do not automatically inherit the reserveLine’s currency, such as in the ClaimCenter application.
Therefore, the currency must be defined three times in the request payload.
Recovery reserve and composite requests

Within a composite request, you cannot create or modify financial objects. This includes recoveries and recovery
reserves. However, within a composite request, you can GET information on financial objects.
Creating a recovery reserve set

The following payload is an example of creating a recovery reserve set.
• The reserveLine offsets money coming from a single exposure:
◦ The exposure’s ID is cc:SB1
• The cost type is claimcost.
• The cost category is Auto Body (body).
• The recovery category is salvage.
• The reserving currency is USD.
◦ The transactionAmount is for 5000.00.
POST /claims/cc:76b/recovery-reserve-sets
{
"data": {
"attributes": {
"recoveryReservesToWrite": [
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimCost"
},
"exposure": {
"id": "cc:SB1"
},
"code": "salvage"
},
"code": "usd"
}
},
"lineItems": [
{
"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:
◦ The recovery category (a value from the RecoveryCategory typelist)
◦ The transactionAmount, including the amount and currency
◦ Currency (a value from the currency typelist)
If you want your recovery to reference a recovery reserve, and have its transaction amount go toward the total of the
expected recovery reserve, you must duplicate the following information from the recovery reserve:
• costCategory (a value from the CostCategory typelist)
• costType (a value from the CostType typelist)
• The recovery category (a value from the RecoveryCategory typelist)
• The id of the parent exposure
• The reservingCurrency
The currency in the lineItem object must also be the same.
Note: If you create a recovery with a transaction amount in excess of its referenced recovery reserve,
ClaimCenter creates an additional recovery reserve to make up for the difference.
Example of creating a recovery

The following payload is an example of creating a recovery that references the previous example recovery reserve:

• The reserveLine offsets money coming from a single exposure:

◦ The exposure’s ID is cc:SB1
• The cost type is claimcost.
• 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"
},
"code": "salvage"
},
"code": "usd"
}
},
"lineItems": [
{
"amount": "3000.00",
"currency": "usd"
}
}
],
"currency": {
"code": "usd"
}
}
]
}
}
}

chapter 25
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 295
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 reportingAmount.currency field.
• The claim's currency is US dollars (usd).
◦ This is specified in the claimAmount.currency field.
• The reserving currency is British pounds (gbp).
◦ This is specified in the reservingAmount.currency 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 lineItems.transactionAmount.currency
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",
"amount": "1920.82",
"currency": "usd"
},
"amount": "1000.00",
296 Multicurrency
"currency": "gbp"
},
"amount": "1000.00",
"currency": "gbp"
}
}
],
"reserveLine": {
"costCategory": {
"code": "body",
"name": "Auto body"
},
"costType": {
},
"exposure": {
"displayName": "(1) 1st Party Vehicle - Allen Robertson",
"id": "cc:SfXS3Pey0Al29PI13KC5C",
},
"code": "gbp",
"name": "GBP"
}
}
}
}
}
There is also a currency value specified in the reserveLine.reservingCurrency 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 reportableAmount.currency 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 grossAmount.currency 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 297
}
}
}
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 http://localhost:8080/cc/rest/claim/v1/claims/cc:202/reserve-sets
{
"data": {
"attributes": {
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
"id": "cc:SfXS3Pey0Al29PI13KC5C"
},
"code": "eur"
}
},
"lineItems": [
{
"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.)
298 Multicurrency
• A decimal rate value.

the payload, the claim currency for cc:202 is US dollars (usd).
• 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.)
{
"data": {
"attributes": {
{
"transToReservingExchangeRate": {
"description": "Custom exchange rate",
"market": false,
"rate": "4.0"
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
},
"code": "usd"
}
},
"lineItems": [
{
"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 currency for the check (and any associated payment transaction) is Canadian dollars (cad).
POST http://localhost:8080/cc/rest/claim/v1/claims/cc:202/check-sets
{
"data": {
"attributes": {
{
"lineItems": [
{
"amount": "75.00",
"currency": "cad"
}
}
],
"paymentType": {
"code": "final"
Multicurrency 299
},
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
},
"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 payload, the claim currency for cc:202 is US Dollars (usd).
• 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.)
{
"data": {
"attributes": {
{
"lineItems": [
{
"amount": "50.00",
"currency": "cad"
}
}
],
"paymentType": {
"code": "partial"
},
"reserveLine": {
300 Multicurrency
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
},
"code": "gbp"
}
},
"currency": {
"code": "cad"
},
"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.
Multicurrency 301
◦ claimAmount is set to the transactionAmount if the claim currency is the same as the transaction currency.
Otherwise, the claimAmount is set to the converted value.
◦ reportingAmount is set to the transactionAmount if the reporting currency is the same as the transaction
currency. Otherwise, is transactionAmount is set to the converted value.
• The reservingAmount field, if specified, cannot have the same currency as the transaction currency.
◦ 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.
{
"market": false,
"rate": "1.9998"
},
"lineItems": [
{
"amount": "600",
"currency": "gbp"
},
"amount":"-250.02",
"currency": "gbp"
},
"claimAmount": {
"amount": "-500.00"
"currency": "USD"
},
"lineCategory": {
}
}
],
...
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:
302 Multicurrency
{
"data": {
"attributes": {
{
"reserveLine": {
"costCategory": {
"code": "body"
},
"costType": {
"code": "claimcost"
},
"exposure": {
},
"code": "eur"
}
},
"lineItems": [
{
"amount": "100.00",
"currency": "jpy"
},
"amount":"1.01",
"currency": "eur"
}
}
],
"currency": {
"code": "jpy"
}
}
]
}
}
}
Additional exchange rate schema fields

Response payloads can also include the following exchange rate fields:
• claimToReportingExchangeRate
• transToClaimExchangeRate
Note that these fields are read-only. When POSTing reserves and check sets, custom exchange rates are always
specified using the transToReservingExchangeRate field.
Multicurrency 303
304 Multicurrency
part 5
Business flows: Framework APIs
The following topics discuss how caller applications can initiate business flows related to the Common API and the
Admin API. This includes:
• The Common API
◦ Working with activities
◦ Working with documents
◦ Working with notes
• The Admin API
◦ Working with users and groups
Business flows: Framework APIs 305

306 Business flows: Framework APIs

chapter 26
Activities
An activity is an action related to the processing of a claim that a user must attend to or be aware of. Activities are
ultimately assigned to a group and a user in that group. This user has the primary responsibility for closing the activity.
Activities are typically created by users or by automatic ClaimCenter processes, and they are typically closed by users.
But, activities can be both created and closed by Cloud API calls.
For a complete description of the functionality of activities in ClaimCenter, see the Application Guide.
Note: Activities exist in all core InsuranceSuite applications. To ensure that activities behave in a common way
across all applications, some activity endpoints, such as the endpoints for querying for or assigning activities,
are declared in the Common API. Activities can also belong to claims, which do not exist in all InsuranceSuite
applications. This means that other activity endpoints, such as the endpoint for creating an activity for a claim,
are declared in the Claim API. This topic always identifies the API in which each endpoint is declared.
Note: ContactManager for Cloud API includes the Common API and its endpoints for working with activities.
However, in the base configuration of the ContactManager application, there is no user interface or business
rule support for activities. The activities endpoints have been included in Cloud API for ContactManager
primarily for the sake of consistency, and also to support any insurer who wishes to configure ContactManager
so that it can work with activities.
Querying for activities

Activities cannot exist on their own. They must be attached to a parent object. In ClaimCenter, activities can be
attached only to claims (directly or indirectly).
You can use the following endpoints to GET activities.
Endpoint Returns
/common/v1/activities All activities
/common/v1/activities/{activityId} The activity with the given ID
/claim/v1/claims/{claimId}/activities All activities associated with the given claim
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 the 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 claim demo_sample:1. This
endpoint is in the Claim API.
Activities 307
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": {
},
"assignedUser": {
"type": "User",
},
"code": "assigned",
"name": "Assigned"
},
"createTime": "2023-11-18T02:00:20.481Z",
"dueDate": "2023-11-07T00:00:00.000Z",
"escalated": false,
"externallyOwned": false,
"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"
},
...
308 Activities
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
subject String The activity's subject Typically comes from the activity
pattern
automate-only activity patterns

Activity patterns have an automate-only field. This field designates whether or not a user can create activities through
the user interface using that activity pattern. By default, when an activity pattern's automate-only field is set to true,
any caller creating an activity through Cloud API cannot use the activity pattern either.
You can override the behavior for individual callers by granting them the restcreateautomatedactivity system
permission. Callers with this permission are able to creating activities using activity patterns whose automate-only
field is set to true.
To assign this permission:
• For internal user callers, add this permission to one of the user roles assigned to the caller.
• For external users and services, add this permission to the user role assigned to the proxy user.
For more information on proxy users, see Cloud API Developer Guide.
Activities 309
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 has the primary responsible for
closing the activity.
Activities can be temporarily assigned to queues. A queue is a repository belonging to a group which contains activities
assigned to the group but not yet to any user in that group. Users in the group can then take ownership of activities
manually as desired.
When you create an activity through Cloud API, ClaimCenter automatically executes the activity assignment rules to
initially assign the activity to a group and user. You can use the /{activityId}/assign endpoint to reassign the
activity as needed.
Assignment options
An activity can be assigned through Cloud API in the following ways:
• To a specific group and queue
• 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.
310 Activities
The root resource for the /{activityId}/assign endpoint is Assignee. This resource specifies assignment criteria.
The Assignee schema has the following fields:

autoAssign Boolean Whether to assign the activity using assignment rules
claimOwner Boolean Whether to assign the activity to the claim owner
groupId string The ID of the group to assign the activity to
queueId string The ID of the queue to assign the activity to
userId string The ID of the user to assign the activity to
The Assignee resource must specify an assignment option. It cannot be empty.
Assignment examples
When assigning activities to users, the user must be active and must have the "own activity" system permission.
Assigning to a specific group (and user)

The following payload assigns activity xc:1 to group demo_sample:31 and user demo_sample:1.
POST /common/v1/activities/xc:1/assign
{
"data": {
"attributes" : {
}
}
}
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.
{
"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.
{
"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.
Activities 311
{
"data": {
"attributes" : {
"claimOwner" : true
}
}
}
Using automated assignment

The following payload assigns activity xc:1 using automated assignment rules.
{
"data": {
"attributes": {
"autoAssign" : true
}
}
}
For more information on assignment rules, see the Gosu Rules Guide.
Retrieving recommended assignees

When ClaimCenter users are assigning activities manually, the user interface includes a drop-down list of
"recommended assignees". Typically, this list includes:
• The option to use assignment rules
• The option to assign the activity to the user who owns the activity's claim
• Users in the group the activity is currently assigned to.
• Any queues belonging to the group the activity is currently assigned to.
The contents of this drop-down list are generated by an application-specific SuggestedAssigneeBuilder class. You
can access the same contents by executing a GET with one of the following /assignees endpoints:
Endpoint Returns
/common/v1/activity/{activityId}/assignees The list of suggested assignees for this activity
/claim/v1/claims/{claimId}/activity-assignees The list of suggested assignees for activities on this claim
The following is a portion of an example response from the Common API's /assignees endpoint.
GET /common/v1/activities/cc:301/assignees
RESPONSE:
{
"count": 16,
"data": [
{
"attributes": {
"autoAssign": true,
"name": "Use automated assignment"
}
},
{
"attributes": {
"claimOwner": true,
"name": "Claim/Exposure Owner"
}
},
{
"attributes": {
"groupId": "demo_sample:31",
"name": "Sue Smith (Auto1 - TeamA)",
"userId": "demo_sample:2"
}
},
{
"attributes": {
"groupId": "demo_sample:31",
"name": "Andy Applegate (Auto1 - TeamA)",
"userId": "demo_sample:1"
312 Activities
}
},
...
{
"attributes": {
"name": "FNOL - Acme Insurance",
"queueId": "default_data:1"
}
}
],
...
Closing activities
A general activity is closed either by completing it or skipping it. In order to be closed, the activity must be opened and
assigned to a user. (Approval activities, which are discussed later in this topic, are closed in a different way.)
When closing an activity, there are two options for the request payload:
• An empty payload
• A payload with an included note. (This option is used when you want to create a note while you close the activity.
The payload has no data section, but it does have an included section.)
All endpoints for closing activities are in the Common API.
Completing an activity
Completing an activity indicates that the corresponding action has been taken or the assignee is aware of the
corresponding issue.
The following payload completes activity xc:1.
POST /common/v1/activities/xc:1/complete
<no request payload>
The following payload completes activity xc:1 and creates a note.
POST /common/v1/activities/xc:1/complete
{
"included": {
"Note": [
{
"attributes": {
"body": "This activity was completed through a system API call."
},
"method": "post",
"uri": "/common/v1/activities/xc:1/notes"
}
]
}
}
Skipping an activity
Skipping an activity indicates that there is no longer a need to take the action that the activity originally identified.
Activities have a mandatory Boolean field. If this is set to true, the activity cannot be skipped.
The following payload skips activity xc:1.
POST /common/v1/activities/xc:1/skip
The following payload skips activity xc:1 and creates a note.
POST /common/v1/activities/xc:1/skip
{
"included": {
"Note": [
Activities 313
{
"attributes": {
"body": "This activity was skipped by a system API call."
},
"method": "post",
}
]
}
}
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 115.
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.
POST /common/v1/activities/xc:2/approve
The following payload approves activity xc:2 with an approval rationale.
{
"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.
{
"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",
}
]
314 Activities
}
}
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 325.
Activities 315
316 Activities
chapter 27
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 317
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
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.
Querying for document information
Querying for document metadata

Use the following endpoints to retrieve document metadata.
Endpoint Returns
/common/v1/documents/{documentId} Metadata for the given document
/claim/v1/claims/{claimId}/documents Metadata for documents on the given claim
/claim/v1/claims/{claimId}/documents/{documentId} Metadata for the given document
ContactManager also has its own /contact/v1/contacts/{contactId}/documents endpoint.

The following is a portion of an example response from the Common API's /documents/{documentId} endpoint.
GET /common/v1/documents/xc:101
{
"data": {
"attributes": {
"author": "Sue Smith",
"dateModified": "2020-12-07T23:40:23.534Z",
"docUID": "2020/11/7/235-53-425892/Legal Ownership of Property",
"id": "xc:101",
"inbound": false,
"mimeType": "text/plain",
"name": "Legal Ownership of Property",
"obsolete": false,
"section": {
"code": "legal",
"name": "Legal"
},
"status": {
"code": "final",
"name": "Final"
},
"type": {
"code": "other",
"name": "Other"
}
},
...
Querying for document content

You can use the following to GET document contents. However, these contents are base64 encoded and therefore are
not human-readable until they are decoded.
• /common/v1/documents/{documentId}/content
• /claim/v1/claims/{claimId}/documents/{documentId}/content
318 Documents
The following is a portion of an example response from the Common API's /documents/{documentId}/content
endpoint.
GET /common/v1/documents/xc:101/content
RESPONSE:
{
"data": {
"attributes": {
"contents": "REVWIEJVSUxEDQoNCklmIHRoZXJlIGlzIG9ubHkgYSB2aXN1YWxp
emVkIHByb2R1Y3QNCiAgQU5EIHRoZSAiRW5hYmxlZCBmb3IgUmVzdCBBUEkiIGZpZWxkIGlzIGlua
XRpYWxseSBzZXQgdG8gRW5hYmxlZA0KICBBTkQgeW91IGNoYW5nZSB0aGUgZmllbGQgdG8gRGlzYW
JsZWQNCiAgVEhFTiB0aGUgcHJvZHVjdCBpcyBpbW1lZGlhdGVseSB1bmF2YWlsYWJsZSB0byB0aGU
gc3lzdGVtIEFQSXMNCg0KSWYgdGhlcmUgaXMgYSB2aXN1YWxpemVkIHByb2R1Y3QgYW5kIGEgZmlu
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)

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.
Documents 319
• 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 Report.pdf" file for claim cc:102 that does not yet
exist in the Document Management System.
POST /claim/v1/claims/cc:102/documents
METADATA:
{
"data": {
"attributes": {
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}
CONTENTS:
<contents of "Property Assessment Report.pdf" 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.
The following is an example of POSTing a "Property Assessment Report.pdf" file for claim cc:102 that does exist in
the Document Management System with id "doc:11-31".
METADATA:
{
"data": {
"attributes": {
"docUID": "doc:11-31",
"status": {
"code": "draft"
},
"type": {
}
}
}
}
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 323.
320 Documents
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.
METADATA:
{
"data": {
"attributes": {
"name": "Printout of email from auto dealership",
"status": {
"code": "final"
},
"type": {
}
}
}
}
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 323.
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.
3. Under the Untitled Request label, select POST.
• 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.
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.
Documents 321
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.
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.
PATCH /common/v1/documents/xc:127
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 323.
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).
METADATA:
{
"data": {
"attributes": {
}
322 Documents
}
}
}
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.
METADATA:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}
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. (As of this release,
this functionality is supported for ClaimCenter and ContactManager only.)
For example, the following creates a "Property Assessment Report.pdf" 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.
{
"data": {
"attributes": {
"docUID": "doc:11-31",
"status": {
"code": "draft"
},
"type": {
}
}
}
}
DELETEing documents
Use the following to DELETE documents:
• /common/v1/documents/{documentId}
• /claim/v1/claims/{claimId}/documents/{documentId}
Documents 323
For example, the following request DELETEs document xc:101:
<no request body>
324 Documents
chapter 28
Notes
A note is a free-form record of the actions or thinking of a user or process. Notes are typically used to capture
information that cannot be easily captured in some other way on some other business object. Notes are typically
created by users, but they can be created by batch processes or other system behavior within ClaimCenter. They can
also be created by caller applications using Cloud API.
Through Cloud API, a note can be attached to a claim. It can also optionally be attached to an exposure, a
ClaimContact, or a service request on that claim. Notes can also be attached to activities.
For a complete description of the functionality of notes in ClaimCenter, see the Application Guide.
Note: Notes exist in all core InsuranceSuite applications. To ensure that notes behave in a common way across
all applications, some note endpoints, such as the endpoint for querying for a note with a given ID, are declared
in the Common API. Notes can also belong to claims, which do not exist in all InsuranceSuite applications.
This means that other note endpoints, such as the endpoint for querying for notes related to a given claim, are
declared in the Claim API. This topic always identifies the API in which each endpoint is declared.
Note: ContactManager for Cloud API includes the Common API and its endpoints for working with notes.
However, in the base configuration of the ContactManager application, there is no user interface or business
rule support for notes. The notes endpoints have been included in Cloud API for ContactManager primarily for
the sake of consistency, and also to support any insurer who wishes to configure ContactManager so that it can
work with notes.
Querying for notes

Use the following endpoints to query for notes:
Endpoint Returns
/common/v1/notes/{noteId} The note with the given ID (see below)
/claim/v1/claims/{claimId}/notes All notes associated with the given claim
/common/v1/activities/{activityId}/notes All notes associated with the given activity
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
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.
Notes 325
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.
{
"data": {
"attributes": {
"body": "The insured's last name, Cahill, is pronounced 'KAH-hill', not 'KAY-hill'." ,
"securityType": {
"code": "public"
},
"subject": "Pronunciation note",
"topic": {
"code": "general"
}
}
}
}
Notes attached to child objects

By default, every note is attached only to the parent claim. You can attach a note to one of the claim's child objects
using the relatedTo field. This field has the following syntax:
"relatedTo": {
"id": "<childObjectId>",
"type": "<childObjectType>"
326 Notes
For example, the following creates a note on claim cc:102 for the exposure with id cc:48:
{
"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 327
328 Notes
chapter 29
Users and groups
Cloud API provides endpoints in the Admin API to support several of the tasks associated with user and group
management.
Users
In most cases, a user is a person who is known to ClaimCenter and who is listed in the ClaimCenter database (such as
policy underwriters, claims adjusters, and billing clerks). Within the context of Cloud API authentication, this is also
referred to as an internal user.
In some cases, a user can represent a service. This occurs for caller applications which are services which are mapped
to user accounts for the purpose of managing access.
Do not confuse internal users with external users. External users are users known to ClaimCenter but who are not listed
in the ClaimCenter database (such as account holders, policy holders, and service vendors).
For information on working with services and external users, see the Cloud API Developer Guide.
Querying for user information

To retrieve information about a user, you can use the following endpoints:
• GET /admin/v1/users
• GET /admin/v1/users/{userId}
For example, the following is the snippet of the response payload when retrieving the information for user
demo_sample:1 (Andy Applegate).
GET /admin/v1/users/demo_sample:1
{
"data": {
"attributes": {
"active": true,
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},
"displayName": "650-333-3333",
"number": "6503333333"
},
"employeeNumber": "1000001",
"externalUser": false,
"firstName": "Andy",
Users and groups 329

"lastName": "Applegate",
"roles": [
{
"displayName": "Adjuster",
"id": "adjuster",
"type": "Role"
},
{
"displayName": "Trusted for Sensitive Claims",
"id": "sensitive_claims",
"type": "Role"
}
],
"username": "aapplegate",
"vacationStatus": {
"code": "atwork",
"name": "At work"
},
"workPhone": {
"displayName": "213-555-8164",
"number": "2135558164"
}
}
}
}
Creating users
To create a user, use the following endpoint:
• POST /admin/v1/users
Note: When a user is created through Cloud API, the user's password is set to a value that cannot be used for
authentication. (The password is set to a value that is not a valid Base64 string, but the authentication
framework can authenticate passwords only when they are valid Base64 strings.) In order for the new user to
authenticate, the password must first be changed to a valid Base64 string through some other method, such as
through the user interface.
Create a minimal user

The minimum creation criteria for a user is the username. For example, the following request creates a user with the
user name "amartin".
{
"data": {
"attributes": {
"username": "amartin"
}
}
}
The following is the response payload.
{
"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"
]
}
}
330 Users and groups

}
}
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)
{
"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 337.
• For more information on working with authority limit profiles, see “Authority limit profiles” on page 341.
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 333.
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.
You cannot create groups through Cloud API. However, you can retrieve information about groups, and you can assign
users to groups and unassign them from groups.
Querying for groups

To retrieve information about a group, use the following endpoints:
• GET /admin/v1/groups
• GET /admin/v1/groups/{groupId}
For example, the following is the snippet of the response payload when retrieving the information for group
demo_sample:31.
GET /admin/v1/users/demo_sample:31
{
"data": {
"attributes": {
"displayName": "Alexandria Branch",
"groupType": {
"code": "branch",
"name": "Branch office"
},
"name": "Alexandria Branch",
"parent": {
"displayName": "Eastern Region",
"type": "Group",
"uri": "/admin/v1/groups/demo_sample:29"
},
"securityZone": {
"displayName": "Auto and Property",
"id": "default_data:1"
},
"supervisor": {
"displayName": "Sue Smith",
"type": "User",
}
},
...
}
}
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
As of this release, there is no endpoint for retrieving information about security zones. To identify the ID of the desired
security zone, you must use some other method.
The user who is designated as the supervisor of the group is not required to be a member of the group. Also, designated
a user as the supervisor does not automatically add the user to the group as a member.
For example, the following request creates a new group:
POST /admin/v1/groups
{
"data": {
"attributes": {
"groupType": {
"code": "general"
},
"name": "Cloud API Group 1",
"parent": {
"id": "systemTables:1"
},
"securityZone": {
"id": "default_data:1"
},
"supervisor": {
}
}
}
}
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 333
Assigning users to groups

The GroupUser entity
In ClaimCenter, users and groups are tracked as separate User and Group entities. There is a third entity, GroupUser,
whose purpose is to track information about one assignment of a user to a group. For example, if an instance of
GenericCenter has two groups and three users and every user belongs to every group:
• There would be two instances of Group
• There would be three instances of User
• There would be six instances of GroupUser (user 1 to group A, user 1 to group B, user 2 to group A, and so on)
In addition to tracking a single user assignment to a group, the GroupUser entity also tracks information about the
user’s capabilities within the group. This includes the following fields:
• manager - Boolean indicating whether the user has permission to view the activity of others in the group
• member - Boolean indicating whether the user is a working member of the group (for purposes of work assignment),
as opposed to simply being associated with the group as a manager or other auxiliary person
• loadFactor - Percent of work that can be assigned to the user
Querying for group/user information

To retrieve information about user assignments for a group, use the following endpoints:
• GET /admin/v1/groups/{groupId}/users
◦ Returns a collection of user assignments for the group
• GET /admin/v1/groups/{groupId}/users/[groupUserId}

◦ Returns information about a specific user assignment to the group

For example, the following is the snippet of the response payload when retrieving the information for the GroupUser
assignments in group demo_sample:31. Note that the count is 12, which means the group has 12 users. Information is
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": {
"type": "User",
}
},
...
},
{
"attributes": {
"id": "cc:SZPhG_CUIA3E1sO2AiZ_s",
"manager": false,
"member": true,
"user": {
"displayName": "Betty Baker",
"type": "User",
}
},
...
},
...
Adding a user to a group

To add a user to a group, use the following endpoint:
• POST /admin/v1/groups/{groupId}/users
In the request, you must specify the user to be added to the group. You can optionally specify other attributes. If you do
not, the following default values are used:
• member: true
• manager: false
• loadFactor: null
For example, the following request adds user demo_sample:18 to group demo_sample:31.
POST /admin/v1/groups/demo_sample:31/users
{
"data": {
"attributes": {
"user": {
}
}
}
}
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": {
}
}
}
}
Deleting groups
Use the following endpoint to delete an existing group:
• DELETE /admin/v1/groups/{groupId}
For example, the following request deletes group xc:202:
DELETE /admin/v1/groups/xc:202
<no request body>
Queues
A queue is a named repository that belongs to a specific group and that contains activities assigned to the group but not
yet to any user in the group. Users who belong to the group can assign activities in a queue to themselves. Queues are
often used to allow users in a group to take ownership of activities as their workload or expertise permits.

In the data model, queues are managed using the AssignableQueue data model entity.
In order to work with queues in the base configuration, the following must exist:
• Support for queues in the data model
• Assignment methods that let activities be assigned to queues
• Rules that create queues automatically, and/or user interface controls that let administrators create queues manually
• User interface screens to let users view queues and the activities assigned to them, and to take ownership of
activities in the queue
The base configuration of ClaimCenter has all of the above items. Thus, the base configuration of ClaimCenter
supports queues.
The base configuration of PolicyCenter and BillingCenter have the first two items only. PolicyCenter and BillingCenter
can support queues, but further configuration is required.
Queues in Cloud API

Cloud API provides a set of endpoints for managing queues. These endpoints exist for ClaimCenter, PolicyCenter, and
BillingCenter.
• In ClaimCenter, users can readily work with queues created through Cloud API.
• In PolicyCenter and BillingCenter, additional user interface configuration is required to provide users with access to
any queues created through Cloud API.
Working with queues

Querying for queues
To query for information about queues, use the following endpoints:
• GET /admin/v1/groups/{groupId}/queues
• GET /admin/v1/groups/{groupId}/queues/{queueId}
For example, the following request retrieves information about queue cc:790 for group cc:118:
GET /admin/v1/groups/cc:118/queues/cc:790
{
"data": {
"attributes": {
"description": "Auto-created FNOL queue for group",
"id": "xc:790",
"name": "FNOL",
"subGroupVisible": false
},
...
Creating queues
Use the following endpoint to create queues:
• POST /admin/v1/groups/{groupId}/queues
When creating queues, the only required values are:
• name - A string
• subGroupVisible - A Boolean indicating whether the queue is visible from sub-groups of the group to which it
belongs
For example, the following request creates a new queue for group cc:118:
POST /admin/v1/groups/cc:118/queues

"data": {
"attributes": {
"name": "Damaged vehicle evaluations",
"subGroupVisible": true
}
}
}
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 310.
User roles
A system permission is a granular permission that identifies something a user can view, edit, create, or otherwise work
with.
A user role is a named group of system permissions. User roles simplify the work of granting access by allowing a set
of related system permissions to be assigned to a user. (Note that in most Guidewire documentation, user roles are
referred to simply as "roles". The Cloud API documentation uses the term "user role" to help distinguish them from
"API roles", which is a feature with a similar purpose but different underlying functionality.)
Querying for user roles

To retrieve information about user roles, use the following endpoints:
• GET /admin/v1/roles
• GET /admin/v1/roles/{roleId}
For example, the following is the snippet of the response payload when retrieving the first four roles in the base
configuration.
GET /admin/v1/roles?pageSize=4
{
"count": 5,
"data": [
{
"attributes": {
"carrierInternal": true,
"description": "Permissions for account admin",
"displayName": "Account Manager",

"id": "account_manager",
"name": "Account Manager"
}
},
{
"attributes": {
"description": "All permissions related to activity rules",
"displayName": "Activity Rules Admin",
"id": "activity_rules_admin",
"name": "Activity Rules Admin"
}
},
{
"attributes": {
"description": "Permissions to edit activity rules",
"displayName": "Activity Rules Editor",
"id": "activity_rules_editor",
"name": "Activity Rules Editor"
}
},
{
"attributes": {
"description": "Permissions to view activity rules",
"displayName": "Activity Rules Viewer",
"id": "activity_rules_viewer",
"name": "Activity Rules Viewer"
}
}
]
}
Querying for permissions in a user role

To retrieve information about the permissions in a given user roles, use the following endpoints:
• GET /admin/v1/roles/{roleId}/permissions
• GET /admin/v1/roles/{roleId}/permissions/{permissionId}
For example, the following is the snippet of the response payload when retrieving the first three permissions associated
with a "claims_adjuster" role:
GET /admin/v1/roles/claims_adjuster/permissions
{
"count": 25,
"data": [
{
"attributes": {
"id": "sample_data:213",
"permission": {
"code": "lvprint",
"name": "Print listviews"
}
},
...
},
{
"attributes": {
"permission": {
"code": "searchpols",
"name": "Search related policies"
}
},
...
},
{
"attributes": {
"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
{
"data": {
"attributes": {
"permission": {
"code": "notecreate"
}
}
}
}
There is no way to specify multiple permissions in a single call to the /permissions endpoint. You must invoke the /
permissions endpoint once for each permission to be added to a role.
Creating user roles with permissions in a single call

You can create a user role and one or more permissions for the role in a single call using request inclusion. In this case,
the name of the included resource is RolePermission. For more information on request inclusion, see “Request
inclusion” on page 103.

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.
PATCH /admin/v1/roles/{roleId} Modify attributes about the role, such as its name or description
DELETE /admin/v1/roles/{roleId}/permissions/ Remove a permission from a role
{permissionId}
DELETE /admin/v1/roles/{roleId} Delete a role
Example of PATCHing a role

The following request modifies the name and description of role xc:222.
PATCH /admin/v1/roles/xc:222
{
"data": {
"attributes": {
"name": "Finance Administrator",
"description": "User role for finance administrators"
}
}
}
Example of removing a permission

The following request removes the permission with id xc:515 (notecreate) from role xc:222.
DELETE /admin/v1/roles/xc:222/permissions/xc:515
<no request body>
Example of DELETEing a role

The following request deletes role xc:222.
DELETE /admin/v1/roles/xc:222
<no request body>
You cannot a delete a role if it is associated with one or more users.

Authority limit profiles

In ClaimCenter, an authority limit is a restriction placed upon a user that limits the types of transactions that user can
make. It can also determine whether these new transactions require approval from someone with greater authority. An
authority limit profile is a named collection of authority limits. Through Cloud API, you can create, modify, delete, and
retrieve information about authority limit profiles.
Note that there are two types of authority limit profiles: assignable and custom. The information used by an authority
profile limit changes based on its type.
• An assignable authority limit profile is created outside of the context of any user and it can be assigned to multiple
users. Assignable authority limit profiles capture logic that is needed by a large group of users.
• A custom authority limit profile is created for a specific user. Custom authority limit profiles are a convenient way
of specifying authority limits for a user whose needs are unlikely to be shared by any other user. Custom authority
limit profiles cannot be shared across users.
Retrieving information about authority limit profiles

To retrieve information about an authority limit profile and its limits, use the following endpoints.
Endpoint Retrieves
GET /admin/v1/authority-limit-profiles A list of all authority limit profiles
GET /admin/v1/authority-limit-profiles/ Information about a specific authority limit profile
{authorityLimitProfileId}
GET /admin/v1/authority-limit-profiles/ A list of limits for a specific authority limit profile
{authorityLimitProfileId}/limits
GET /admin/v1/authority-limit-profiles/ Information about a specific limit in a specific authority
{authorityLimitProfileId}/limits/{limitId} limit profile
For example, the following request retrieves information about authority profile limit "default_data:1".
GET /admin/v1/authority-limit-profiles/default_data:1
{
"data": {
"attributes": {
"currency": {
"code": "usd",
"name": "USD"
},
"custom": false,
"description": "Adjuster default authority",
"displayName": "Adjuster",
"id": "default_data:1",
"name": "Adjuster"
}
}
...
}
The following request retrieves information about the limits for authority profile limit "default_data:1". There are two
limits, one limiting claim payments to date to $15,000 USD and one limiting claim total reserves to $15,000 USD.
GET /admin/v1/authority-limit-profiles/default_data:1/limits
{
"count": 2,
"data": [
{
"attributes": {
"limitAmount": {
"amount": "15000.00",
"currency": "usd"
},
"limitType": {
"code": "cptd",
"name": "Claim payments to date"

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

"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.
• The limitAmount, which must specify an amount and a currency
For example, the following adds the claims total reserves limit (ctr) to authority limit profile cc:1208. The amount is
15,000 USD.
POST /admin/v1/authority-limit-profiles/cc:1208/limits
{
"data": {
"attributes": {
"limitType": {
"code": "ctr"
},
"limitAmount": {
"currency": "usd",
"amount": "15000"
}
}
}
}

Creating authority limit profiles and grants in a single call

You can create an authority limit profile and one or more limits for the profile in a single call using request inclusion.
In this case, the name of the included resource is AuthorityLimit. For more information on request inclusion, see
“Request inclusion” on page 103.
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).
{
"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.
PATCH /admin/v1/authority-limit-profiles/ Modify attributes about the given authority limit profile
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
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.


chapter 30
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",
"name": "Default Security Zone"
},
...
Security zones 347

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>
348 Security zones

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": "gw.api.rest.exceptions.NotAuthorizedException",
"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 349

350 Security zones

chapter 31
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 351

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

chapter 32
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 353
The typekeyFilter query parameter

When using the /typelists/{typelistName} endpoint, if the typelist is associated with a typekey filter, you can limit
the results to only those typecodes that have a given relationship with the typekey filter. You can specify three types of
criteria:
• /typelists/{typelistName}?typekeyFilter=category:in:typecodeList
◦ Returns all typekeys whose categories array contains at least one of the listed typecodes
• /typelists/{typelistName}?typekeyFilter=category:cn:typecodeList
◦ Returns all typekeys whose categories array contains all of the listed typecodes
• /typelists/{typelistName}?typekeyFilter=category:ni:typecodeList
◦ Returns all typekeys whose categories array does not contain any of the listed typecodes
The typecode list must be specified as:
relatedTypelist1.Typecode1,relatedTypelist2.Typecode2,...
where:
• relatedTypelistX is the name of the Nth related typelist.
• TypecodeX is the Nth typecode to use as a filter
Examples
No filter parameter
This call does not use the typekeyFilter query parameter. Therefore, it retrieves all typecodes in the
ActivityCategory typelist:
GET /common/v1/typelists/ActivityCategory
Associated with one category
This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of
General:
GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general
Associated with any of the listed categories
either General or Approval:
GET /common/v1/typelists/ActivityCategory?
typekeyFilter=category:in:ActivityType.general,ActivityType.approval
Associated with all of the listed categories

both General and Approval: (Note that, in the base configuration, there are no typecodes that meet this criteria.)
typekeyFilter=category:in:ActivityType.general,ActivityType.approval
Associated with none of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are not associated with either the
ActivityType of General or the ActivityType of Approval:
typekeyFilter=category:ni:ActivityType.general,ActivityType.approval
354 Typelist metadata

Tutorial: Query for typelist metadata

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
2. Specify Basic Auth authorization using user su and password gw.
• GET http://localhost:8080/cc/rest/common/v1/typelists/ClaimantType
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:LossType.PR
6. The response payload now contains only claimant types relevant to property claims. Verify that the first three
codes in the payload are now: insured, householdmember, propertyowner. (veh_ins_driver no longer appears
because it is not a valid claimant type for a property claim.)
Typelist metadata 355

356 Typelist metadata

chapter 33
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 357

Querying for batch process information

Use the following endpoints to retrieve information about batch processes:
• GET /systemtools/v1/batch-processes
• GET /systemtools/v1/batch-processes/{batchProcessType}
When querying for information on a specific batch process, you must include the batch process type as defined in the
BatchProcessType typelist. This value is case-sensitive. For example, to query for information on the Activity
Escalation batch process, use the following:
GET /systemtools/v1/batch-processes/ActivityEsc
The BatchProcess resource

Cloud API manages batch process information using the BatchProcess resource. This resource contains the following
fields:
Field Description Returned By Default?

type The batch process's BatchProcessType. Yes
status An inline object with status information, such as startDate, Yes
dateCompleted, opsCompleted, and failedOps.
distributed A Boolean indicating whether the batch process is distributed. Yes
workQueueStatus If the batch process is distributed, this is an inline object Only if the batch process is distributed
containing information on the worker status for the batch process.
processId The ID for a newly created process. Only in the response to the /start
endpoint, and only if the call to the /
start endpoint started the batch
process
wasStopped A Boolean indicating whether the batch process was stopped. Only in the response to the /stop
endpoint
The information in the response varies based on whether the batch process has completed, is running, or has never been
run.
Response for a completed batch process

The following is an example of querying for the Activity Escalation batch process after the batch process has been run.
Note that the status object includes the dateCompleted field, and there is no opsExpected field.
{
"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"
}
},
...
358 Batch processes

Response for a running batch process

The following is an example of querying for the Activity Escalation batch process while the batch process is running.
Note that the status object includes the opsExpected field, and there is no dateCompleted field.
{
"data": {
"attributes": {
"status": {
"dateCreated": "2022-09-19T17:30:00.003Z",
"failedOps": 0,
"opsCompleted": 0,
"opsExpected": 0,
"progress": "1 out of 3",
"startDate": "2022-09-19T17:30:00.011Z",
},
"type": {
}
},
...
Response for a batch process that has never been run

The following is an example of querying for the Activity Escalation batch process before the first iteration of the batch
process. Note that the status object includes only the failureReason field and the type field.
{
"data": {
"attributes": {
"status": {
"failureReason": "This batch process type has never run",
},
"type": {
}
},
...
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 360.
The response to the /start endpoint includes the processId field. This value serves two purposes:
• It verifies that the batch process was started as a result of the call to the /start endpoint. If the batch process could
not be started, such as when the process is already running, then this value does not appear in the response.
• This value may be required by other tools, such as the Guidewire SOAP-based MaintenanceToolsAPI, which needs
the process ID to get batch process status or request batch process termination.
Batch processes 359

A batch process can be categorized as MaintenanceOnly, which means the batch process is not available if the server's
run level is above NODAEMONS mode. The /start endpoint is not available for MaintenanceOnly batch processes
when the server's run level is above NODAEMONS mode.
Batch processes can also be categorized as APIRunnable. This setting impacts whether the batch process can be run
from the Guidewire SOAP-based MaintenanceToolsAPI. It does not impose any limitation on whether Cloud API can
start the batch process.
Example of starting a batch process

The following is an example of the response to starting the Activity Escalation batch process.
POST /systemtools/v1/batch-processes/ActivityEsc/start
RESPONSE:
{
"data": {
"attributes": {
"distributed": true,
"processId": 4055,
"status": {
"dateCreated": "2022-09-19T17:54:19.929Z",
"failedOps": 0,
"opsCompleted": 0,
},
"type": {
},
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},
...
Starting a batch process with arguments

In ClaimCenter, some batch processes let you specify arguments when you run the batch process. These arguments
perform the function of input parameters, and they can change the way the batch process runs.
For example, the Purge Async API Requests batch process removes stale information about API requests that were
executed asynchronously. By default, the batch process removes information for asynchronous requests that are more
than 7 days old. However, when running this batch process, you can specify a different number of days.
In Cloud API, for some batch processes, the /start endpoint supports arguments. For these batch processes, you can
submit a request with no body, which is equivalent to starting the batch process without arguments. Or, you can submit
a request with a body that specifies arguments and their values.
Determining which arguments the /start endpoint supports

The root resource for the /start endpoint is BatchProcessArguments. This resource has one JSON object for each
base configuration batch process for which arguments are supported. To determine if you can submit arguments for a
given batch process, you must check the schema to see if a JSON object exists for that batch process.
For example, the BatchProcessArguments resource has a PurgeAsyncApiRequests object. This means that, when
using the /start endpoint to start the Purge Async API Requests batch process, you can submit arguments.
Syntax for the request body

When specifying arguments, the syntax for the request body is as follows:
{
"data": {
"attributes": {
"<batchProcessFieldName>": {
"<argument1>": <values>,
"<argument2>": <values>,
...
}
360 Batch processes

}
}
}
For example, the PurgeAsyncApiRequests object has one integer field, purgeDaysOld. The following request starts
the Purge Async API Requests batch process and passes in a purgeDaysOld value of 3.
POST /systemtools/v1/batch-processes/PurgeAsyncApiRequests/start
{
"data": {
"attributes": {
"purgeAsyncApiRequests": {
"purgeDaysOld": 3
}
}
}
}
Note that the structure of the JSON object varies based on the datatype of the arguments. For example, the following is
an example of starting the Database Consistency Check batch process with arguments. Note that one of the arguments,
tableNames, is an array, whereas the other, description, is a string.
POST /systemtools/v1/batch-processes/DBConsistencyCheck/start
{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
],
"description": "Start of Q1 maintenance"
}
}
}
}
If the attributes section contains any property with an unexpected name, Cloud API returns a 400 error.
Custom batch processes with arguments

Insurers can also create custom batch processes that have arguments. Starting custom batch processes with arguments
requires additional configuration. For more information, see the Cloud API Developer Guide.
Stopping a batch process

Use the following endpoint to stop a batch process:
• POST /systemtools/v1/batch-processes/{batchProcessType}/stop
The POST does not require a request body.
The response to the /stop endpoint includes the wasStopped field. This field is set to true if the batch process was
stopped while the batch process was executing. It is set to false if the batch process was not running when the /stop
request was made.
For example, the following request stops the Activity Escalation batch process:
POST /systemtools/v1/-batch-processes/ActivityEsc/stop
RESPONSE:
{
"data": {
"attributes": {
"distributed": true,
"status": {
"dateCompleted": "2022-09-19T18:00:51.304Z",
"dateCreated": "2022-09-19T18:00:51.291Z",
"failedOps": 0,
"opsCompleted": 0,
"startDate": "2022-09-19T18:00:51.298Z",
},
Batch processes 361

"type": {
},
"wasStopped": true,
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},
362 Batch processes

chapter 34
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 363

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.
<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.
{
"data": {
"attributes": {
"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.
{
"data": {
364 Database consistency checks

"attributes": {
"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".
{
"data": {
"attributes": {
}
}
}
}
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".
{
"data": {
"attributes": {
"tableNames": [
"cc_activity",
"cc_address"
],
" checkTypes ": [
"0lengthstringcheck",
"assignmentcheck"
],
}
}
}
}
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-

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

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


CloudAPI Consumer

Uploaded by

CloudAPI Consumer

Uploaded by

Guidewire ClaimCenter™

for Guidewire Cloud

Cloud API Consumer Guide

Product Name: Guidewire ClaimCenter for Guidewire Cloud

1 Introduction to Cloud API................................................................................................................................ 17

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

8 Reducing the number of calls.......................................................................................................................... 89

Checksums for PATCHes and business action POSTs...................................................................................... 117

14 Executing FNOL.............................................................................................................................................. 137

Coverages on unverified policies............................................................................................................ 155

Living expenses incidents............................................................................................................................... 217

Approving service request invoices........................................................................................................ 252

Acknowledging a recovery reserve.........................................................................................................293

Creating groups...................................................................................................................................... 332

For assistance, visit the Guidewire Community.

Basic REST operations

Basic REST operations 15

16 Basic REST operations

Introduction to Cloud API

List of APIs in Cloud API

API Name Description Path

API Name Description Path

Introduction to Cloud API 17

API Name Description Path

Version numbers for major and minor releases

Minor and major releases

18 Introduction to Cloud API

Viewing API definitions

Introduction to Cloud API 19

View definitions using Swagger UI

20 Introduction to Cloud API

• A more detailed endpoint description

The API definition endpoints and Postman

View definitions using Postman

Before you begin

About this task

Introduction to Cloud API 21

Information in the output of API definition endpoints

Additional options for the /openapi.json endpoints

22 Introduction to Cloud API

Converting schema metadata into SDKs

The Guidewire API References site

View definitions using the API References site

Information on the API References site

Introduction to Cloud API 23

REST API fundamentals

Cloud API calls

Making Cloud API calls

24 Introduction to Cloud API

Cloud API and InsuranceSuite logic

Note that a field can store:

Introduction to Cloud API 25

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

Inline and included resources

26 Introduction to Cloud API

• The notes/{noteId} endpoint supports GET, PATCH, and DELETE.

Method mapping to elements and collections

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

Contrasting endpoints and methods

The PUT method

Introduction to Cloud API 27

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

Requests and responses

• Application URL - The URL to the InsuranceSuite application.

28 Introduction to Cloud API

• GETs and DELETEs do not require request payloads.

Status code Category Meaning

Testing requests and responses

Tutorial: Set up your Postman environment

Introduction to Cloud API 29

Checking your work

There was an error connecting to http://localhost:8080/cc/rest/common/v1/activities.

30 Introduction to Cloud API

Introduction to Cloud API 31

32 Introduction to Cloud API

Standard payload structures