Guidewire PolicyCenter™

for Guidewire Cloud

Cloud API Consumer Guide

Release: 2024.02
© 2024 Guidewire Software, Inc.
For information about Guidewire trademarks, visit https://www.guidewire.com/legal-notices.
Guidewire Proprietary & Confidential — DO NOT DISTRIBUTE

Product Name: Guidewire PolicyCenter for Guidewire Cloud

Product Release: 2024.02
Document Name: Cloud API Consumer Guide
Document Revision: 24-June-2024
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Contents
Support.......................................................................................................................................................... 15

Part 1
Basic REST operations........................................................................................................................ 17

1 Introduction to Cloud API................................................................................................................................ 19

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

Contents 3
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The fields query parameter.............................................................................................................................. 51

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

4 Contents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Tutorial: DELETE a note............................................................................................................................ 83

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

Part 2
Optimizing calls.......................................................................................................................................93

8 Reducing the number of calls.......................................................................................................................... 95

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

Contents 5
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

12 Lost updates and checksums......................................................................................................................... 125

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

Part 3
Business flows: Accounts................................................................................................................ 145

14 Creating accounts.......................................................................................................................................... 147

Creating an account....................................................................................................................................... 147
The account holder................................................................................................................................ 147
The primary location.............................................................................................................................. 148
The producer code................................................................................................................................. 150
Creating an account example payload................................................................................................... 151
Name clearance and account status.............................................................................................................. 151
Child objects for an account........................................................................................................................... 152
Creating accounts as an anonymous user...................................................................................................... 152
15 Managing accounts........................................................................................................................................153
Querying for accounts.................................................................................................................................... 153
Searching for accounts................................................................................................................................... 154
Modifying accounts........................................................................................................................................ 156
Account contacts............................................................................................................................................ 157
Querying for account contacts............................................................................................................... 157
Creating account contacts...................................................................................................................... 158
Modifying account contacts................................................................................................................... 158
Linking account contact addresses......................................................................................................... 159
Account contact roles.....................................................................................................................................162
Account locations........................................................................................................................................... 164
Querying for account locations.............................................................................................................. 164
Creating account locations..................................................................................................................... 164
Modifying account locations.................................................................................................................. 164
Account jobs and policies............................................................................................................................... 165

6 Contents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

16 Managing bound policies.............................................................................................................................. 167

Querying for policies...................................................................................................................................... 167
Searching for policies..................................................................................................................................... 168
Moving policies between accounts................................................................................................................ 170
Policy producers............................................................................................................................................. 170
The producer data model....................................................................................................................... 170
Changing a policy's producer................................................................................................................. 172
Policy jobs...................................................................................................................................................... 173
Policy contacts................................................................................................................................................173
Policy locations............................................................................................................................................... 176
Policy questions..............................................................................................................................................176
Prior policies...................................................................................................................................................179
Querying for prior policy information.................................................................................................... 180
Creating prior policy information........................................................................................................... 180
Updating prior policy information.......................................................................................................... 181
Loss history.....................................................................................................................................................181
Loss history in PolicyCenter.................................................................................................................... 181
Loss history in Cloud API........................................................................................................................ 182
Querying for loss history information.................................................................................................... 183
PATCHing policy-level loss history information.......................................................................................185
Working with loss history entries........................................................................................................... 185
Pre-renewal directions................................................................................................................................... 186
Retrieving pre-renewal directions.......................................................................................................... 187
Setting pre-renewal directions............................................................................................................... 187
Clearing pre-renewal directions............................................................................................................. 189
Additional actions for bound policies.............................................................................................................189

Part 4
Business flows: Job types................................................................................................................191

17 Submissions................................................................................................................................................... 193
Initiating a submission................................................................................................................................... 194
Modifying the submission.............................................................................................................................. 195
Quoting the submission................................................................................................................................. 195
Completing the submission............................................................................................................................ 196
Binding and issuing a submission at the same time............................................................................... 196
Binding a submission without issuing.................................................................................................... 196
Issuing a previously bound policy...........................................................................................................196
Withdrawing and rejecting submissions................................................................................................ 198
Copying submissions...................................................................................................................................... 199
Additional features for submissions............................................................................................................... 200
Composite request submission example for Personal Auto........................................................................... 200
18 Renewals........................................................................................................................................................ 205
Overview of policy transaction management................................................................................................ 205
Initiating a renewal.........................................................................................................................................206
Modifying the renewal................................................................................................................................... 206
Quoting the renewal...................................................................................................................................... 207
Completing the renewal................................................................................................................................. 208
19 Audits............................................................................................................................................................. 209
Audit policy endpoints................................................................................................................................... 209
Audit job endpoints........................................................................................................................................216

Contents 7
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

20 Policy changes................................................................................................................................................221
Overview of policy transaction management................................................................................................ 221
Initiating a policy change................................................................................................................................222
Modifying the policy change.......................................................................................................................... 222
Quoting the policy change............................................................................................................................. 222
Completing the policy change........................................................................................................................ 223
Issues specific to policy changes.................................................................................................................... 223
Changing producers................................................................................................................................223
Preemptions........................................................................................................................................... 223
21 Cancellations and reinstatements.................................................................................................................231
Overview of policy transaction management................................................................................................ 231
Cancellations.................................................................................................................................................. 232
Initiating a cancellation.......................................................................................................................... 232
Modifying and requoting the cancellation............................................................................................. 232
Completing the cancellation.................................................................................................................. 232
Reinstatements.............................................................................................................................................. 233
Initiating a reinstatement....................................................................................................................... 233
Modifying and quoting the reinstatement............................................................................................. 234
Completing the reinstatement............................................................................................................... 234
22 Rewrite and Rewrite New Account............................................................................................................... 235
Overview of policy transaction management................................................................................................ 235
Rewrite transaction........................................................................................................................................ 236
Rewrite new account transaction...................................................................................................................237

Part 5
Business flows: Job policies...........................................................................................................239

23 Overview of modifying jobs.......................................................................................................................... 241

24 Lines of business............................................................................................................................................ 243
Overview of lines of business......................................................................................................................... 243
Lines............................................................................................................................................................... 245
Additional LOB-specific endpoints................................................................................................................. 246
Contrasting job, policy, product, and line of business....................................................................................246
25 Coverables and coverages............................................................................................................................. 249
Overview of coverables.................................................................................................................................. 249
Adding coverables.......................................................................................................................................... 250
Overview of coverages................................................................................................................................... 251
Adding coverages........................................................................................................................................... 252
Coverage terms.............................................................................................................................................. 254
Scheduled items............................................................................................................................................. 255
Scheduled item endpoints......................................................................................................................256
Resources for scheduled items...............................................................................................................256
Querying for scheduled items................................................................................................................ 259
Creating scheduled items....................................................................................................................... 260
Coverage validation........................................................................................................................................ 262
26 Modifiers........................................................................................................................................................265
Product and product line modifiers............................................................................................................... 265
Line-level and object-level modifiers............................................................................................................. 268
Modifier validation......................................................................................................................................... 271
27 Questions....................................................................................................................................................... 273
Overview of questions................................................................................................................................... 273

8 Contents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Answering questions...................................................................................................................................... 274

Specifying answers................................................................................................................................. 276
Question validation........................................................................................................................................ 277
28 Exposures, exclusions, and conditions.......................................................................................................... 279
Overview of exposures, exclusions, and conditions....................................................................................... 279
Adding exposures, exclusions, and conditions............................................................................................... 280
29 Synchronization and deferred validation......................................................................................................283
Out-of-sync policy data.................................................................................................................................. 283
The /sync endpoints....................................................................................................................................... 285
The /sync-coverages endpoints.............................................................................................................. 285
The /sync-fields endpoints..................................................................................................................... 285
The /sync-modifiers endpoints...............................................................................................................286
The /sync-questions endpoints.............................................................................................................. 286
When to call a /sync endpoint................................................................................................................287
Deferring validation........................................................................................................................................287
The deferValidation query parameter.................................................................................................... 287
Authorization to defer validation........................................................................................................... 288
Limitations to deferred validation.......................................................................................................... 289
Default value creation.................................................................................................................................... 289
The createDefaultCoverages query parameter...................................................................................... 289
The createCoveredLocationForPrimaryLocation query parameter........................................................ 290
30 Policy contacts............................................................................................................................................... 291
Overview of policy contacts........................................................................................................................... 291
Working with all policy contacts on a job.......................................................................................................292
Querying for all policy contacts on a job................................................................................................ 292
Adding a policy contact.......................................................................................................................... 293
Updating and deleting policy contacts................................................................................................... 294
Linking policy contact addresses............................................................................................................ 295
Primary and secondary named insured contacts........................................................................................... 299
Additional named insured contacts............................................................................................................... 300
Querying for additional named insureds................................................................................................300
Adding additional named insureds.........................................................................................................301
Updating additional named insureds..................................................................................................... 301
LOB-specific additional insured contacts........................................................................................................302
Location named insureds............................................................................................................................... 304
31 Policy locations.............................................................................................................................................. 307
Overview of policy locations.......................................................................................................................... 307
Querying for a policy's locations.................................................................................................................... 308
Creating policy locations................................................................................................................................ 308
PATCHing policy locations...............................................................................................................................309
DELETEing policy locations............................................................................................................................. 309
32 Job user role assignment............................................................................................................................... 311
Overview of job user role assignment............................................................................................................311
Retrieving job user roles.................................................................................................................................312
Assigning job user roles..................................................................................................................................312
PATCHing job user roles.................................................................................................................................. 312
33 Working with product definitions................................................................................................................. 315
Product definitions for audit schedule patterns.............................................................................................315
Product definitions for lines........................................................................................................................... 317
Product definitions for products.................................................................................................................... 317
Product definitions for reference code data.................................................................................................. 318

Contents 9
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

34 PATCHing jobs................................................................................................................................................ 321

Read-only fields.............................................................................................................................................. 321
Fields you can modify using PATCH /{jobId}................................................................................................... 321
Fields you can modify using specific endpoints............................................................................................. 322

Part 6
Business flows: Job support...........................................................................................................325

35 Affinity groups............................................................................................................................................... 327

Working with affinity groups.......................................................................................................................... 328
Working with affinity group producer codes..................................................................................................329
36 Comparing jobs.............................................................................................................................................. 331
Comparing a job to its base policy................................................................................................................. 331
Structure of the JobReviewDiffs resource.............................................................................................. 331
Example of a /review-diffs response...................................................................................................... 332
Comparing two jobs on the same policy........................................................................................................ 335
Structure of the CompareJobAttributes resource.................................................................................. 335
Example of a /compare-jobs response................................................................................................... 336
37 Contingencies................................................................................................................................................ 339
Querying for contingencies............................................................................................................................ 339
Creating contingencies................................................................................................................................... 340
Closing contingencies..................................................................................................................................... 342
38 Form patterns................................................................................................................................................ 343
Form patterns information............................................................................................................................. 343
Form patterns lookups................................................................................................................................... 347
Form patterns with lookups........................................................................................................................... 349
Policy and job forms....................................................................................................................................... 350
39 Job search...................................................................................................................................................... 351
40 Out-of-sequence conflicts............................................................................................................................. 353
Identifying out-of-sequence conflicts.............................................................................................................353
Resolving out-of-sequence conflicts...............................................................................................................354
Example: Identifying and resolving out-of-sequence conflicts.......................................................................355
41 Policy archiving.............................................................................................................................................. 359
Determine whether archiving is enabled....................................................................................................... 359
List archived policies...................................................................................................................................... 360
Set policies to Do Not Archive........................................................................................................................ 361
Retrieve an archived policy............................................................................................................................ 362
Bulk policy archive retrieval........................................................................................................................... 362
42 Policy holds.................................................................................................................................................... 365
Working with policy holds.............................................................................................................................. 365
Querying for policy holds....................................................................................................................... 365
Creating policy holds............................................................................................................................. 366
Modifying policy holds........................................................................................................................... 367
Deleting policy holds.............................................................................................................................. 368
Policy hold components......................................................................................................................... 368
Policy hold rules............................................................................................................................................. 368
Querying for policy hold rules................................................................................................................ 369
Adding policy hold rules......................................................................................................................... 370
Modifying policy hold rules................................................................................................................... 372
Deleting policy hold rules...................................................................................................................... 373
Policy hold geographic zones......................................................................................................................... 373

10 Contents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Example: Policy hold setup........................................................................................................................... 375

Create policy hold details...................................................................................................................... 375
Add rules to the policy hold.................................................................................................................. 376
Add geographic zones to the policy hold............................................................................................... 377
43 Quoting.......................................................................................................................................................... 379
Costs and transactions................................................................................................................................... 379
Multi-version quoting.....................................................................................................................................381
Job version properties............................................................................................................................ 381
Creating a new job version..................................................................................................................... 382
Selecting a job version............................................................................................................................382
Working with job versions...................................................................................................................... 382
Rating overrides............................................................................................................................................. 383
Rating overrides in Cloud API................................................................................................................. 383
44 Reinsurance risks........................................................................................................................................... 387
45 Streamlined account and submission creation.............................................................................................389
Understanding the Graph API........................................................................................................................ 389
The Graph API........................................................................................................................................ 389
Graph vs Account and Job APIs.............................................................................................................. 390
Using Graph API endpoints in a composite request............................................................................... 390
Order of operations................................................................................................................................ 391
Adding Ref IDs........................................................................................................................................ 391
Additonal Graph API functionality..........................................................................................................392
Example account and submission creation............................................................................................ 393
Example: Creating a policy using the graph endpoints.................................................................................. 393
46 Underwriting issues....................................................................................................................................... 407
Underwriting issues in PolicyCenter...............................................................................................................407
Querying for underwriting issues................................................................................................................... 408
Creating underwriting issues..........................................................................................................................408
Minimum creation criteria..................................................................................................................... 408
Examples of creating an underwriting issue...........................................................................................410
Managing underwriting issue approval.......................................................................................................... 411
Approval underwriting issues................................................................................................................. 411
Rejecting underwriting issues................................................................................................................ 412
Reopening underwriting issues.............................................................................................................. 413
Job locks......................................................................................................................................................... 413
Locking jobs............................................................................................................................................ 413
Releasing locks....................................................................................................................................... 413
Requesting approval.......................................................................................................................................414
Requesting approval through Cloud API.................................................................................................414
Referral reasons............................................................................................................................................. 415
Querying for referral reasons................................................................................................................. 415
Creating referral reasons........................................................................................................................ 415
Closing and reopening referral reasons..................................................................................................416

Part 7
Business flows: Framework APIs.................................................................................................. 419

47 Activities........................................................................................................................................................ 421
Querying for activities.................................................................................................................................... 421
Creating activities........................................................................................................................................... 423
Assigning activities......................................................................................................................................... 424

Contents 11
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Assignment options................................................................................................................................ 424

Assignment examples.............................................................................................................................425
Retrieving recommended assignees.......................................................................................................426
Closing activities............................................................................................................................................. 427
Additional activity functionality..................................................................................................................... 428
48 Documents..................................................................................................................................................... 429
Overview of documents................................................................................................................................. 429
Querying for document information.............................................................................................................. 430
Querying for document metadata..........................................................................................................430
Querying for document content.............................................................................................................430
POSTing documents....................................................................................................................................... 431
POSTing documents using Postman....................................................................................................... 433
PATCHing documents..................................................................................................................................... 434
Sending document metadata only using JSON...............................................................................................435
DELETEing documents.................................................................................................................................... 435
49 Notes.............................................................................................................................................................. 437
Querying for notes......................................................................................................................................... 437
Creating account, job, and policy notes......................................................................................................... 438
Additional notes functionality........................................................................................................................ 439
50 Users and groups........................................................................................................................................... 441
Users.............................................................................................................................................................. 441
Querying for user information............................................................................................................... 441
Creating users.........................................................................................................................................442
Updating users....................................................................................................................................... 444
Deleting users.........................................................................................................................................444
Groups............................................................................................................................................................ 444
Querying for groups............................................................................................................................... 445
Creating groups...................................................................................................................................... 445
Assigning users to groups....................................................................................................................... 446
Updating groups..................................................................................................................................... 448
Deleting groups...................................................................................................................................... 448
Queues........................................................................................................................................................... 448
Working with queues............................................................................................................................. 449
User roles....................................................................................................................................................... 450
Querying for user roles...........................................................................................................................450
Creating user roles................................................................................................................................. 451
Updating user roles................................................................................................................................ 453
Authority profiles........................................................................................................................................... 453
Retrieving information about underwriting authority profiles.............................................................. 454
Assigning authority profiles to users...................................................................................................... 455
Creating authority profiles..................................................................................................................... 456
Modifying authority profiles.................................................................................................................. 456
Authority profile grants.................................................................................................................................. 456
Querying for grants................................................................................................................................ 456
Creating grants....................................................................................................................................... 457
Modifying grants.................................................................................................................................... 460
51 Producers....................................................................................................................................................... 463
Organizations................................................................................................................................................. 463
Querying for organizations..................................................................................................................... 463
Creating organizations............................................................................................................................ 464
Updating organizations.......................................................................................................................... 465

12 Contents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Producer codes...............................................................................................................................................465
Querying for producer codes................................................................................................................. 465
Creating producer codes........................................................................................................................ 467
Updating producer codes....................................................................................................................... 467
Managing producer codes for users and groups.................................................................................... 468
Exposing producer codes to external users............................................................................................ 470
52 Security zones................................................................................................................................................ 471
Querying for security zones........................................................................................................................... 471
Creating security zones.................................................................................................................................. 472
Modifying and deleting security zones.......................................................................................................... 472
Associating security zones with other objects............................................................................................... 473
53 Geographic zones.......................................................................................................................................... 475
54 Typelist metadata.......................................................................................................................................... 477
The /typelists endpoints.................................................................................................................................477
Querying with typekey filters......................................................................................................................... 477
Tutorial: Query for typelist metadata............................................................................................................. 479
55 Batch processes............................................................................................................................................. 481
Overview of batch processes......................................................................................................................... 481
Querying for batch process information........................................................................................................ 482
Managing batch processes............................................................................................................................. 483
Starting a batch process......................................................................................................................... 483
Starting a batch process with arguments............................................................................................... 484
Stopping a batch process....................................................................................................................... 485
56 Database consistency checks........................................................................................................................ 487
Overview of database consistency checks (DBCCs)........................................................................................487
Running DBCCs............................................................................................................................................... 488
Running a previously run DBCC.............................................................................................................. 489
Querying for DBCC run information............................................................................................................... 490
57 Personal data destruction............................................................................................................................. 493
API entity destruction overview..................................................................................................................... 493
System configuration......................................................................................................................................494
Obfuscating user data.................................................................................................................................... 494
Destroying a contact...................................................................................................................................... 495
Destroying an account....................................................................................................................................496
Destroying a policy......................................................................................................................................... 497
Preventing data destruction........................................................................................................................... 497
58 Business entity schemas................................................................................................................................499
Retrieve an entity schema..............................................................................................................................499
Business entity schema query parameters.................................................................................................... 500
ETag support...................................................................................................................................................502
CreateSubmissionAttributes schema............................................................................................................. 502
Schema properties......................................................................................................................................... 503
Schema properties overview.................................................................................................................. 503
Schema properties usage....................................................................................................................... 506
59 The Test Util API.............................................................................................................................................527
Enabling the Test Util API............................................................................................................................... 527
View the Test Util API in Swagger UI.............................................................................................................. 528
Test Util API endpoints................................................................................................................................... 528

Contents 13
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

18 Basic REST operations

chapter 1

Introduction to Cloud API

InsuranceSuite Cloud API for PolicyCenter is a set of RESTful system APIs that caller applications can use to request
data from or initiate action within PolicyCenter. 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 26 section provides a brief overview of how REST APIs work in Cloud API.

List of APIs in Cloud API

Cloud API for PolicyCenter consists of the following APIs:

API Name Description Path

Account API for accounts and account-specific objects /account/v1
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
Common API for common InsuranceSuite platform objects, such as /common/v1
activities and notes
Composite API for composite requests /composite/v1
Graph API for operating on entire graphs of objects /graph/v1
Job API for jobs and job-specific objects /job/v1
Policy API for policies and policy-specific objects /policy/v1
Product Definition API for PolicyCenter product definition metadata /productdefinition/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 PolicyCenter. 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.
Introduction to Cloud API 19
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Cloud API for ContactManager consists of the following APIs:

API Name Description Path

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

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

Version numbers for major and minor releases

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

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

Minor and major releases

In future releases, Cloud API functionality is expected to change. To define and control these changes, Guidewire
defines the scope of change that can be added to each release.
• In a minor version release, the functionality is either identical to the previous release or additive.
• In a major version release, the functionality has changed from the previous release.
A given release of PolicyCenter 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.

20 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Viewing API definitions

An API definition is a technical description of the behavior of an API. The API definition typically includes the
following:
• The endpoints in the API
• The schemas used by each endpoint, which dictate how resources in the payload are structured
• The fields available in each resource
• The properties that apply to each field
There are several different ways you can view API definitions for Cloud API. This includes:
• Swagger UI
• Calling the /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 PolicyCenter.
Swagger UI can be helpful when viewing schema information. Swagger UI presents this information hierarchically.
Child schemas are indented with respect to parent schemas, and individual nodes of the hierarchy can be expanded and
collapsed. Searching through a complex schema is relatively straightforward in Swagger UI.
However, Swagger UI strips out some of the metadata that is present in the source files. For example, Guidewire-
proprietary tags are not rendered in Swagger UI. When you need access to all the metadata for an API, it may be better
to call the /openapi.json endpoint directly.
Swagger UI also requires access to a running instance of PolicyCenter. 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 PolicyCenter 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
30.

Introduction to Cloud API 21

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

View definitions using Swagger UI

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “List of APIs in Cloud API” on page 19.)
2. Start PolicyCenter.
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 PolicyCenter, use: http://localhost:8180/pc/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:

22 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• A more detailed endpoint description

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

The API definition endpoints and Postman

In some situations, it is useful to view the raw API definition information. In Cloud API, every API includes two
endpoints that return the API definition: /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 PolicyCenter. 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.

Introduction to Cloud API 23

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Procedure
1. Identify the path for the API. (For a list of paths for each API, see “List of APIs in Cloud API” on page 19.)
2. Start PolicyCenter.
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 PolicyCenter, enter the following:
• http://localhost:8180/pc/rest/common/v1/openapi.json (OR http://localhost:8180/pc/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.

24 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following HTTP request retrieves the metadata for the Admin API. It also enables filterByUser and
prettyPrint.

http://localhost:8180/pc/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:8180/pc/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 PolicyCenter.

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

Introduction to Cloud API 25

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

26 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Cloud API and InsuranceSuite logic

In the software industry, some RESTful APIs are configured to interact directly with the database. Cloud API is not
configured to behave this way. Cloud API interacts with operational data only through the layer of the application's
business logic. Therefore, Cloud API always leverages the existing business logic of the application.
For example:
• Suppose an internal user does not have permission to create an activity. If the internal user attempts to create an
activity through Cloud API, the attempt results in an insufficient permissions error.
• Suppose there is a validation rule that requires an activity's due date to be set in the future. If an external system
attempts to create an activity with a due date in the past, the attempt results in a validation error.
• Suppose there is a pre-update rule that creates an approval activity whenever a document is marked as "Final". If an
external system creates a "Final" document through Cloud API, the pre-update rule will create an approval activity.

Resources
The primary mechanism for passing information between the caller application and PolicyCenter 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
AccountContact resource maps to three data model entities in PolicyCenter: AccountContact, Contact, and
AccountContactRole.

Resources contain a set of fields. Each field stores information about the resource. Depending on the context, fields are
also referred to as properties or attributes.
Resources are exchanged in the payloads of the request and response objects. The payload is a block of JSON-
formatted text that contains fields from the relevant resources and their values. The following is a portion of the
response payload for an Activity resource.

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

Note that a field can store:

• A scalar value, such as the subject field.
• A set of values, such as the assignedUser field. This is referred to as an inline object.
• An array of objects. (There is no example of this in Activity. If there were, the field name would be followed by
square braces ([ and ]) delimiting the array. Each array member would be listed in curly braces ({ and }).
Every resource can be uniquely defined by its resource ID. This is stored in the resource's id field. For example, the
activity in the previous example has a resource ID of xc:20. For most endpoints, the id field maps to the data model
entity's PublicID field. (However, there are some endpoints that map id to a different field. For example, in
PolicyCenter, the resource ID for a line is its line prefix. This means that the line resource on a personal auto policy
has an id value of something similar to PersonalAutoLine, and not pc:114567.)

Introduction to Cloud API 27

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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 PolicyCenter. For example, the /common/v1/activities endpoint can be used to either
request data about PolicyCenter activities or trigger actions related to PolicyCenter 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 35.

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.

28 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Introduction to Cloud API 29

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For Cloud API, every path consist of the following pattern:

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

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

• common is the name of the API to which the endpoint belongs.
• v1 is the major version number of the API
• activities is the endpoint name
The major version number provides information about the backwards compatibility of the endpoint. For more
information, see “Version numbers for major and minor releases” on page 20.
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 /accounts/{accountId}/activity-patterns endpoint is ActivityPattern)
◦ In some cases, the endpoint name may differ from the root resource name (for example, the root resource for
the /accounts/{accountId}/contacts endpoint is AccountContact)

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.

30 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ There are a small number of endpoints that require a query parameter. For example, to prevent resource-
intensive calls, the Job API's /graph-schema endpoint requires a product parameter.
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 35.
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 PolicyCenter 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 30.

Introduction to Cloud API 31

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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 PolicyCenter installed on your machine that contains only the Large sample data set.
• An instance of Postman.
This tutorial walks you through the process of setting up this environment.
If your instance of PolicyCenter 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 Large 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 PolicyCenter and load the Large sample data set.
You can test your environment by sending your first Postman request.
1. Open Postman.
2. Start a new request by clicking the + to the right of the Launchpad tab.
3. Every request in Postman requires some form of authorization:
a. Click the Authorization tab.
b. For the Type drop-down list, select Basic Auth.
c. In the Username field, enter aapplegate.
d. In the Password field, enter gw.
4. Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
5. In the Enter request URL field, enter the following URL: http://localhost:8180/pc/rest/common/v1/
activities
6. Click the Send button to the right of the request field.

Checking your work

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

{
"count": 11,
"data": [
{
"attributes": {
"activityPattern": "uw_review_contingency",
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
"displayName": "Alice Applegate",
"id": "pc:105"
},
...

Troubleshooting: No response
Requests can be sent only to running applications. All of the tutorials in this documentation require that PolicyCenter 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:8180/pc/rest/common/v1/activities.

32 Introduction to Cloud API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

"status": 404,
"errorCode": "gw.api.rest.exceptions.NotFoundException",
"userMessage": "No resource was found at path /common/v1/activities"

Introduction to Cloud API 33

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

34 Introduction to Cloud API

chapter 2

GETs

This topic discusses how the GET method queries for data and the structure of the response payload. For information
on how you can add query parameters to a GET URL to refine the response, see “Query parameters” on page 49.
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 38
• “Tutorial: Send a Postman request with included resources” on page 43

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

Standard payload structures

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

Standard information common to all endpoints

A data envelope is a wrapper that wraps JSON sent to or returned from a REST API. To maintain a standard payload
structure, Cloud API uses two data envelopes: DataEnvelope and DataListEnvelope.
GETs 35
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

DataEnvelope standardizes the format of information for a single element. It specifies a data property with the
following child properties:
• checksum
• id
• links (for a single element)
• method
• refid
• related
• type
• uri
The format of a payload for a single element has the following structure:

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

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

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

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

Standard information specific to a given endpoint

DataEnvelope and DataListEnvelope provide a standard format for information that is applicable to all request and
response payloads. But, different endpoints interact with different types of resources. For each endpoint, some portion
of the payload must provide information about a specific type of resource.

36 GETs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

To address this, Cloud API also uses request schemas and response schemas. A request schema is a schema that is used
to define the valid structure of a request payload for a specific set of endpoints. Similarly, a response schema is a
schema that is used to define the valid structure of a response payload for a specific set of endpoints.
Request and response schemas are hierarchical. For example, for responses, the GET /activity/{activityId}
endpoint uses the ActivityResponse schema. This schema has two child schemas: ActivityData and
ActivityResponseInclusions.

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

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

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

View a response schema in Swagger UI

Procedure
1. Start PolicyCenter.
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 22.
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 30.

GETs 37
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Send a GET using Postman

Procedure
1. Start PolicyCenter and Postman.
2. Start a new request by clicking the + to the right of the Launchpad tab.
3. Under the Untitled Request label, make sure that GET is selected. (This is the default operation.)
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to do a GET /activities on an instance of PolicyCenter on your machine, enter: http://
localhost:8180/pc/rest/common/v1/activities
5. On the Authorization tab, provide sufficient authorization information to execute the request. For example, to set
up basic authentication for aapplegate:
a) Click the Authorization tab.
b) For the Type drop-down list, select Basic Auth.
c) In the Username field, enter aapplegate.
d) In the Password field, enter gw.
6. Click the Send button to the right of the request field.

Tutorial: Send a basic Postman request

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.

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:8180/pc/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": 11,
"data": [
{
"attributes": {
"activityPattern": "uw_review_contingency",
"activityType": {
"code": "general",
"name": "General"
},
"assignedByUser": {
"displayName": "Alice Applegate",
"id": "pc:105"
},

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

38 GETs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Structure of a basic response

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

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

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

The count property

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

The data section

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

The attributes section

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

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

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

GETs 39
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

"subject": "Verify which coverage is appropriate"

ID properties
Every resource has an id field. This has the same value as the Public ID of the object in PolicyCenter. 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",

Be aware that, for some fields, Cloud API requires a date value as an input. But, PolicyCenter stores the value as a
datetime value, and therefore the value in response payloads is a datetime value. This behavior is an attempt to closely
model the PolicyCenter behavior of adding a time value to entered date values. For example, the JobEffectiveDate
field is specified in the CreateSubmissionAttributes schema as a date value. But once the submission has been
created, the JobEffectiveDate field in the response payload will have a datetime value.

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

40 GETs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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 51.
Broadly speaking, there are four types of inlined resources: typelists, currency amount values, simple references, and
complex references.
Typelists are listed with a code field and a name field. They use the TypeCodeReferences schema. For example:

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

Currency amount values have a currency field and an amount field. For example:

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

Simple references are references to a related object that use the SimpleReferences schema. This schema includes
only the following fields: displayName, id, refId, type, and uri. By default, most endpoints return only
displayName and id.

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

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

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

Fields with null values are omitted

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

The checksum field

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

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.

GETs 41
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, suppose that a given caller application gets activity xc:20. This application has sufficient permission to
assign this activity and to view the notes associated with this activity. The following would appear in the links section
for activity xc:20:

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

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

The self link is a link to the resource itself. The self link is useful when a caller application receives a list of
resources and wants to navigate to a specific resource in the list.
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 /policies?include=contacts,locations returns all policies assigned to the current user, and all
contacts and locations associated with those policies.

42 GETs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

When you execute a call with include, the response payload contains information about the primary resources and the
included resources. However, most of the information about the included resources do not appear inline with the
primary resources. Rather:
• Every primary resource has a related section. This section lists the ids (and types) of included resources related to
that resource. However, each related section does not include any other details about those resources.
• Details about the included resources appear at the end of the payload in a section called included.
The ids of included objects appear in both the related section and the included section. You can use these ids to
match a primary resource with details about its included resources.

Contrasting included resources and inlined resources

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

Resource How many related resources Where do their fields When do they appear?
type for each primary resource? appear?
Inlined Typically one. (For example, Entirely in the attributes If the query does not use the fields query
resource every activity has only one section of the root resource parameter, then each inlined resource appears only if
related assignedUser.) it is one of the default attributes.
If the query does use the fields query parameter,
then each inlined resource does or does not appear
based on whether it is specified in that query
parameter.
Included One to many. (For example, ids appear in the related When the query parameter includes the ?
resource every activity can have section of the root resource. include=resourceName query parameter
several related notes.) The remaining attributes
appear in the included
section at the bottom of the
payload.

Tutorial: Send a Postman request with included resources

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In order to look at a policy in detail, you need to know the policy's public ID. Enter this URL in Postman to
retrieve the ID of the first policy, and click Send:
GET http://localhost:8180/pc/rest/policy/v1/policies?fields=id&pageSize=1
The ID of the policy is in the response payload at or around line 6. This value is referenced in the next steps as
<policyID>.
3. 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 policy and all of its contacts. The following GET retrieves the first policy and its contacts. Enter this
URL in Postman and click Send:
GET http://localhost:8180/pc/rest/policy/v1/policies/<policyId>?include=contacts
Note the following in the response payload:
• The data section starts at line 2. It includes information about the policy.

GETs 43
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• The included section includes an array of contacts for this policy. The start of the included section depends
on the amount of data for the policy. For example, for policy P000143542, the included section starts at line
254.
4. You can use a GET to retrieve a resource and a single related resource. For example, in a single GET you can
retrieve a policy and its primary insured. The following GET retrieves the first policy and its primary insured.
Enter this URL in Postman and click Send:
GET http://localhost:8180/pc/rest/policy/v1/policies/<policyId>?include=primaryInsured
Note the following in the response payload:
• The data section starts at line 2. It includes information about the policy. At or around line 35, there is
information about the policy's primary insured. However, the only meaningful information is the main
contact's display name and ID.
• The included section includes a single contact for this policy (the primary insured). In this section, there is
detailed information about the contact beyond just the display name and ID.

Structure of a response with included resources

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

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

44 GETs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

] }
}

The related section (for a resource)

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

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

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

"related": {
"notes": {
"count": 0,
"data": []
}
}

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

The included section (for a response)

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

"included": {
"Note": [
{
"attributes": {
"author": {
"displayName": "Betty Baker",
"id": "demo_sample:8"
},
"bodySummary": "Main contact is on vacation 03/20",
"confidential": false,
"createdDate": "2020-03-30T23:11:33.346Z",
"id": "xc:55",
"securityType": {
"code": "unrestricted",
"name": "Unrestricted"
},
"subject": "Main contact is on vacation 03/20",
"topic": {
"code": "general",
"name": "General"

GETs 45
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
"updateTime": "2020-03-30T23:12:08.892Z"
},
"checksum": "0",
"links": {
"self": {
"href": "/common/v1/notes/xc:55",
"methods": [
"get",
"patch"
]
}
}
}
]
},

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

Including either a collection or a specific resource

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

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

Determining which resources can be included

For each endpoint, there are several ways to determine the resources that can be included.
For most endpoints, you can refer to the API definition for the endpoint to find the includable resources. There is a data
envelope in the model whose name ends with ...Inclusions. This data envelope lists all the resources that can be
included when querying for that type of resource.
For example, in the Common API, the model for GET /activities references an ActivityResponseInclusions
element. This element has two child elements: Assignee and Note. This means that the only types of element you can
include on an activity query are assignees and notes.
For some endpoints, this method of determining inclusion resources doesn’t work. For example, in the Account API
(available in PolicyCenter), the model for GET /accounts references an AccountIncludes element. This element
shows many child elements, such as AccountContact. However, if you add ?include=AccountContact to your GET
query you’ll receive an error with a message similar to the following:

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

In cases such as this, the error message will specify which elements are allowed in the include.
Other than creating an error and viewing the results, there are a couple of general rules that can help determine which
elements are allowed in an include for a given endpoint: child endpoints and response payload references. (Note that
these are general guidelines, and don’t necessarily apply in all cases.)

46 GETs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Child endpoints
Suppose you have the following set of endpoints:
• /api/v1/endpoint
• /api/v1/endpoint/child1
• /api/v1/endpoint/child1/child2
In most cases, you can include child2 on any calls to endpoint or endpoint/child1:

GET /api/v1/endpoint?include=child2

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

Response payload references

Suppose once again that you have the following endpoint:
• /api/v1/endpoint
Doing a GET on this endpoint returns the following response:

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

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

GET /api/v1/endpoint?include=foreignKeyEntity

GETs 47
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

48 GETs
chapter 3

Query parameters

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

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:
• Retrieving an effective-dated resource "as of" a certain date
• 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:
Query parameters 49
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET /common/v1/activities?fields=*all
• 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 62.

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 asOfDate query parameter

In some situations, a Cloud API call may need to retrieve an effective-dated resource as of a specific date. For example,
a GET may need to retrieve policy pc:10 not as it exists today but as it existed on January 1, 2019. To achieve this,
several job and policy endpoints support an asOfDate parameter. You can use this parameter to retrieve data about a
resource as it existed at a given point in time. The syntax is:

asOfDate=dateValue

For example, the following query returns policy pc:10 as it existed on January 1, 2019:
GET /policy/v1/policies/pc:10?asOfDate=2019-01-01

50 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

If you query for a policy at a point in time before its effective date or after its expiration date, you will get a
BadInputException with the user message similar to the following: "Bad value for the 'asOfDate' query
parameter - No branch found for date 01/01/2019 12:00 AM".

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 62.
The fields parameter can be set to one or more of the following values:
• *all - Return all fields
Note: *all is not recommended for production environments. For more information, see the following
section on "Returning all fields".
• *default - Return the default fields (typically used in conjunction with an additional field list)
• fieldList - Return one or more fields specified as a comma-delimited list

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 contact resource (for example, the default fields for
the /accounts/{accountId}/contacts/{contactId} endpoint) and the summary list fields returned for a contact
collection (for example, the default fields for the /accounts/{accountId}/contacts endpoint). Fields included in the
detail list only are in bold:
• Detail list: companyName, contactSubtype, displayName, emailAddress1, emailAddress2, id, industryCode,
primaryPhoneType, subtype, taxId
• Summary list: companyName, contactSubtype, displayName, emailAddress1, id, industryCode, subtype,
taxId

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

Query parameters 51
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Returning a specific set of properties

To return a specific set of fields, use:

fields=fieldList

where fieldList is a comma-delimited list of fields.

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

Returning a specific set of properties on inlined resources

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

"attributes": {
"activityPattern": "contact_claimant",
"assignedGroup": {
"displayName": "Auto1 - TeamA",
"id": "demo_sample:31"
},
"assignedUser": {
"displayName": "Andy Applegate",
"id": "demo_sample:1"
},
"closeDate": "2020-04-06T07:00:00.000Z",
"dueDate": "2020-04-06T07:00:00.000Z",
"escalated": false,
"id": "cc:20",
...
}

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

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

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

You can also specify specific subfields using the following syntax:
fields=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": {
"id": "demo_sample:31"
},
"assignedUser": {
"id": "demo_sample:1"
}
}

52 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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.

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

Tutorial: Send a GET with the fields parameter

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following and click Send:
GET http://localhost:8180/pc/rest/common/v1/activities
3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
4. Enter the following and click Send:
GET http://localhost:8180/pc/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.

Query parameters 53
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The filter query parameter

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

filter=field:op:value

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

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

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

54 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Determining which fields you can filter on

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

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

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

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

Note that the escalated field includes the "filterable": true expression, but the escalationDate field does not.
This means that you can filter on escalated, but not escalationDate.
The limitation to the preceding option is that it won't display custom filters. You might have to look at the Gosu
resource files to determine whether a customization has been added to make a field filterable. See Cloud API
Developer Guide for information on custom filters and where to find them.

Filtering on multiple values

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

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

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

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

Filtering included resources

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

Query parameters 55
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Endpoints with default filters

Default filters
The following endpoints have default filters:
• GET /admin/v1/users - By default, returns users only in the requester’s organization.
• GET /account/v1/accounts/ - By default, it filters out accounts whose status is withdrawn.
• GET /account/v1/accounts/{accountId}/jobs - By default, it filters out jobs that are not open.
• GET /account/v1/accounts/{AccountId}/activities, GET /job/v1/jobs/{jobId}/activities, and GET /
policy/v1/policies/{policyId}/activities - By default, they filter out activities that are not open.
• GET /job/v1/jobs/{jobId}/uw-issues and GET /policy/v1/policies/{policyId}/uw-issues - By default,
they filter out underwriting issues that are not active or where the blocking user is not the caller.
• The LOB-specific GET /.../coverages endpoints - By default, they filter out coverages that are not selected.

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 /accounts/{AccountId}/jobs?filter=*none returns all jobs for the account, whether
they are open or not.
• You can override the default filter by specifying your own filter.
◦ For example, GET /accounts/{AccountId}/jobs?filter=jobType:eq:Renewal returns all renewal jobs for
the account, whether they are open or not.
If you want the response payload to reflect both the default filter and a custom filter, you must specify both filters
explicitly.

Tutorial: Send a GET with the filter parameters

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Specify Basic Auth authorization using user aapplegate and password gw.
4. Enter the following and click Send:
GET http://localhost:8180/pc/rest/common/v1/activities
5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
6. Enter the following and click Send:
GET http://localhost:8180/pc/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.

56 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The sort query parameter

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

sort=propertiesList

where propertiesList is a comma-delimited list of properties that support sorting for that endpoint.
For example, the following query returns all activities and sorts them by due date:
GET /activities?sort=dueDate
You can specify multiple sort properties. Resources are sorted based on the first property. Any resources with the same
value for the first property are then sorted by the second property, and so on. For example, the following query returns
all activities assigned to the current caller and sorts them first by escalation status and then by due date:
GET /activities?sort=escalated,dueDate
You can also use the sort query for related resources added through the include parameter. For more information, see
“Query parameters for included resources” on page 62.

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

Determining which values you can sort on

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

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

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

Overriding default sorts

Some collections have default sorts. For example, by default, Activities collections are sorted by priority and then
by subject.
Default sorts in the base configuration are defined in shared_core-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

Query parameters 57
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

Sorting included resources

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

Tutorial: Send a GET with the sort query parameter

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will execute two requests to GET activities. The first does not sort the responses. The second does.
To make it easier to compare the order of activities, each request retrieves only the ID and due date of each activity.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Specify Basic Auth authorization using user aapplegate and password gw.
4. Enter the following and click Send:
GET http://localhost:8180/pc/rest/common/v1/activities?fields=id,dueDate
5. Open a second request tab by right-clicking the first tab and selecting Duplicate Tab.
6. Enter the following and click Send:
GET http://localhost:8180/pc/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:

58 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• 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 shared_ext-1.0.apiconfig.yaml, the
AccountActivityPatterns resource overrides the default values and uses defaultPageSize=100 and
maxPageSize=500.)

Specifying page size for included resources

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

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

Query parameters 59
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

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

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

60 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Tutorial: Send a GET with the pageSize and totalCount parameters

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Specify Basic Auth authorization using user aapplegate and password gw.
4. Enter the following and click Send:
GET http://localhost:8180/pc/rest/common/v1/activities
5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
6. Enter the following and click Send:
GET http://localhost:8180/pc/rest/common/v1/activities?pageSize=10&includeTotal=true

Query parameters 61
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Checking your work

Compare the two payloads. In the first payload, the count of activities included in the payload is 11. 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 11. (This appears at
the end of the payload.)

Query parameters for included resources

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

?include=<resourceName>

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

Syntax for query parameters for included resources

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

<queryParameter>=<includedResource>:<queryValue>

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

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

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

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

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 policy/v1/policies/pc:10?include=contacts
&fields=contacts:licenseState,licenseNumber

• Returns: Policy pc:10 and its included contacts. For the contacts, return only licenseState and licenseNumber.

The filter parameter

You can filter out included resources that do not meet a given criteria.

62 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Syntax: filter=resource:field:op:value
• Example:
GET policy/v1/policies/pc:10?include=contacts
&filter=contacts:maritalStatus:eq:S

• Returns: Policy pc:10 and its included contacts that have a marital status of "S" (single)

The sort parameter

You can sort the included resources. This sorting is reflected in both the payload's related sections and the included
section.
• Syntax: sort=resource:properties_list
• Example:
GET policy/v1/policies/pc:10?include=locations
&sort=locations:locationNum

• Returns: Policy pc:10 and its included locations, sorted by their location number.

The pageSize parameter

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

• Returns: Policy pc:10 and up to 5 of its included contacts.

The includeTotal parameter

You can include the total number of included resources.
• Syntax: includeTotal=resource:true
• Example:
GET policy/v1/policies/pc:10?include=contacts
&includeTotal=contacts:true

• Returns: Policy pc:10, its included contacts, and the total number of included contacts for pc:10.

Specifying query parameters at different levels

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

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

Query parameters 63
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

Specifying query parameters for multiple types of included resources

You can also specify multiple types of included resources and specify different query parameters for each resource.
For example, suppose you want to GET all accounts, with the account holder and other contacts included. For the
account, you want the id and account number fields. For the account holder, you want the id and the display name. For
the other contacts, you want only the display name field. To get this response, you must send the following:

GET /accounts?include=accountHolder,contacts
&fields=id,accountNumber
&fields=accountHolder:id,displayName
&fields=contacts:displayName

Tutorial: Send a GET with query parameters for included resources

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. Enter the following and click Send:
GET http://localhost:8180/pc/rest/policy/v1/policies?include=contacts
3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
4. Enter the following and click Send:
GET http://localhost:8180/pc/rest/policy/v1/policies?
include=contacts&fields=id,policyNumber&filter=contacts:contactSubtype:eq:company

Checking your results

Compare the two payloads. Note the following differences:
In the first payload:
• For policies, the default claim fields are returned.
• For contacts, all contacts are returned.
In the second payload:
• For policies, only the id and policyNumber fields are returned.
• For policies, only the company contacts are returned (and not the person contacts).
In the first payload:
• For accounts, the default account fields are returned.
• For contacts, all contacts are returned.
In the second payload:
• For accounts, only the id and the accountNumber fields are returned.

64 Query parameters
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• For contacts, only the contacts that are marked as primary payers are returned.

Query parameters for POSTs and PATCHes

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

POST /admin/v1/users

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

POST /admin/v1/users?fields=id

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

Query parameters 65
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

66 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 95.
If you want to interact directly with the concepts in this topic, go to the following tutorials:
• “Tutorial: Create a new note that specifies required fields only” on page 73
• “Tutorial: Create a new note that specifies optional fields” on page 74

Overview of POSTs
A POST is a REST API method that creates a resource in PolicyCenter. 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 PolicyCenter, 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 67
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Standardizing payload structures

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

Standardizing information common to all endpoints

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

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

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

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

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

Standardizing information specific to a given endpoint

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

68 POSTs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

Viewing request schemas

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

View a request schema in Swagger UI

Procedure
1. Start PolicyCenter.
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 22.
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 69
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

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

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

Determining the minimum creation criteria

For most types of business objects, there are a set of fields that you must specify when creating that type of object. For
example:
• To create an activity, the only required field is activityPattern.
• To create a document, the required fields are name, status, and type.
• To create a note, the only required field is body.
It is typically not possible to determine the minimum required fields from the API definition. This is because the
minimum required fields are often enforced not by Cloud API but rather by PolicyCenter. 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 421.
• The minimum required fields for activities are documented in “Documents” on page 429.
• The minimum required fields for activities are documented in “Notes” on page 437.
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

70 POSTs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Field value type Pattern Example Notes

Datetime "fieldName" : "value" "createdDate": Expressed using the format
"2020-04-09T18:24:57.
YYYY-MM-DDT
256Z"
hh:mm: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 PolicyCenter. Therefore, you cannot specify an id for an object that is being created.
However, you can specify ids when identifying an existing object that the new object is related to.

Specifying compound values

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

Typekeys
Typekeys use the following format:

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

For example:

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

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

Monetary amounts
Monetary amounts use the following format:

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

For example:

"transactionAmount": {
"amount": "500.00",

POSTs 71
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"currency": "usd"
}

Spatial points
Spatial points use the following format:

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

For example:

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

Setting values and objects to null

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

Field value type Pattern Example Notes

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

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

"homePhone": null

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

"language": null

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

"transactionAmount": null

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

Send a POST using Postman

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify the appropriate authorization information.
3. Under the Untitled Request label, make sure that POST is selected.
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to create a new note for activity pc:101 on an instance of PolicyCenter on your machine, enter:
http://localhost:8180/pc/rest/common/v1/activities/pc:101/notes

72 POSTs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

5. Specify the request payload.

a) In the first row of tabs (the one that starts with Params), click Body.
b) In the row of radio buttons, select raw.
c) At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d) Paste the request payload into the text field underneath the radio buttons.
6. Click Send. The response payload appears below the request payload.

Tutorial: Create a new note that specifies required fields only

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will create a note whose subject is "API tutorial note 1" for an existing activity. The other fields
will not be specified and will be assigned default values by the application (such as not being confidential and having a
subject of "General").

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

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

Checking your work

1. View the new note in PolicyCenter.
a. Log on to PolicyCenter as aapplegate and click My Activities.
b. Click the Subject header to sort the activities by subject.
c. Find the first activity with the "Review submission", and click the subject. PolicyCenter opens an Activity
Detail worksheet in the bottom pane.
d. Click View Notes.

POSTs 73
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The API tutorial note is listed as one of the notes. If the note is not present, check the second "Review submission"
activity.

Tutorial: Create a new note that specifies optional fields

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will create a note whose subject is "API tutorial note 2" for an existing activity. You will also
specify values for two optional fields: confidential (set to true) and topic (set to "Legal").

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. Alice Applegate has two "Review submission" activities. Enter the following call and click Send to retrieve them:
GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:eq:Review
%20submission
3. Identify the id of the first activity in the payload. This value is referenced below as <activityId>.
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
POST http://localhost:8180/pc/rest/common/v1/accounts/<accountId>/notes
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note 2",
"confidential": true,
"topic": {
"code": "legal"
}
}
}
}

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

Checking your work

1. View the new note in PolicyCenter.
a. Log on to PolicyCenter as aapplegate and click My Activities.
b. Click the Subject header to sort the activities by subject.
c. Find the first activity with the "Review submission", and click the subject. PolicyCenter opens an Activity
Detail worksheet in the bottom pane.
d. Click View Notes.
The API tutorial note is listed as one of the notes. This note is confidential and it has the category specified in the
request payload. If the note is not present, check the second "Review submission" activity.

74 POSTs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Responses to a POST
Every successful POST generates a response object with a response payload. This payload may contain values
generated by PolicyCenter 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 policy number
• Values generated by a business flow, such as:
◦ The user and group that the resource was assigned to
◦ Activities generated to process the resource
Similarly to request schemas, response schemas follow certain patterns around using data envelopes to wrap the
resource schema. In many instances, the request and response schemas will match.

Fields with null values are omitted

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

POSTs and query parameters

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

Postman behavior with redirects

Some servers automatically redirect incoming calls to different URLs. For example, a call that uses a non-secure URL
(one starting with 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 PolicyCenter. 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 75
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

executed through a PATCH because the caller application cannot always determine how to set the assignedUser and
assignedGroup fields.

In standard REST architecture, there is no operation for this type of business action. Therefore, Cloud API has adopted
the following conventions:
• Endpoints that execute business actions use the POST method.
• Endpoints that execute business actions have paths the end in verbs (such as "assign" or "complete").
Examples of endpoints that execute business actions include:
• POST /common/v1/activities/{activityId}/assign, which assigns the corresponding activity
• POST /common/v1/activities/{activityId}/complete, which marks the corresponding activity as complete
• POST /job/v1/jobs/{jobId}/quote, which quotes the job
• POST /job/v1/jobs/{jobId}/bind-and-issue, which bind and issues the job

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

Improving POST performance

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

76 POSTs
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

POSTs 77
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

78 POSTs
chapter 5

PATCHes

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

Overview of PATCHes
A PATCH is a REST API method that modifies an existing resource in PolicyCenter.
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 68.

PATCHes 79
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Designing a request payload

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

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 Jobs API, the JobRoles resource has a roles array. This is an array of users on the job and the role
of each user (such as Creator or Underwriter). The following PATCH payload will set the roles array to a single user
(user default_data:1) with the role of Auditor. If there were user/role pairs in this array before the PATCH, those pairs
will be removed and the only user/role pair will be user default_data:1/Auditor.

{
"data":
{
"attributes": {
"roles": [
{
"group": "systemTables:1",
"role": {
"code": "Auditor"
},
"user": "default_data:1"
}
]
}
}
}

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

Send a PATCH using Postman

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify Basic Auth authorization using user aapplegate and password gw.
3. Under the Untitled Request label, select PATCH.
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to patch activity pc:2 on an instance of PolicyCenter on your machine, enter: http://
localhost:8180/pc/rest/common/v1/activities/cc:2
5. Specify the request payload.
• In the first row of tabs (the one that starts with Params), click Body.
• In the row of radio buttons, select raw.

80 PATCHes
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Tutorial: PATCH an activity

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will find an open activity from the sample data. You will then update the activity's subject and
priority.
Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by
entering the following call and clicking Send:
a. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
3. For the activity in the response payload that is assigned to Andy/Alice Applegate, note the following information:
a. Activity ID
b. Priority
c. Subject
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
a. PATCH http://localhost:8180/pc/rest/common/v1/activities/<activityID>
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons. Note that the subject has an additional
"!" at the end.
{
"data": {
"attributes": {
"subject" : "Review Risk informaton!",
"priority": {
"code": "low"
}
}
}
}

7. Click Send. The response payload appears below the request payload.
Checking your work
1. View the modified activity in PolicyCenter.
a. Log on to PolicyCenter as the user aapplegate. In the left-hand side bar, click My Activities. PolicyCenter
shows the My Activities screen, which shows the open activities assigned to Alice.
b. Click the Priority column to sort the activities in ascending priority order.
The PATCHed activity (whose priority is now Low) should be at or near the top of the list. The patched activity will
have a subject ending with an "!".

PATCHes 81
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Fields with null values are omitted

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

PATCHes and query parameters

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

PATCHes and lost updates

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

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.

82 PATCHes
chapter 6

DELETEs

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

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
PolicyCenter. What it means to "remove" the resource depends on the resource type. The DELETE operation federates
to the PolicyCenter 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, PolicyCenter does not support the removal of data. Several business objects
can be approved, canceled, completed, closed, declined, rejected, retired, skipped, or withdrawn. But only a few can be
deleted.
A DELETE call consists of the DELETE method and the endpoint, such as DELETE /notes/{noteId}. Similar to
GETs, DELETEs are not permitted to have a request payload.
The response to a DELETE includes an HTTP code indicating success or failure. DELETE responses do not have a
response payload.

Tutorial: DELETE a note

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will send calls as Amy Clinton (user name aclinton). In the base configuration, Amy Clinton is an
underwriting supervisor who has permission to delete notes. As Amy Clinton, 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 83
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by
entering the following call and clicking Send:
a. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
3. Identify the id of the activity in the payload. This value is referenced below as <activityId>.
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
a. On the Authorization tab, select Basic Auth using user aclinton and password gw.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST http://localhost:8180/pc/rest/common/v1/activities/<activityId>/notes
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted"
}
}
}

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

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

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

84 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 PolicyCenter.
For more information, see “Lost updates and
checksums” on page 125.
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 PolicyCenter database and must

Request headers 85
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Header Datatype Description

be globally unique across all clients, APIs, and web
services.
For more information, see “Preventing duplicate
database transactions” on page 89.
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 91.

GW-FailOnValidationWarnings Boolean This can cause certain Job actions to fail if the action
throws any validation warnings.
If set to true on a request to quote, bind-only, or bind-
and-issue a Job, this will cause the action to fail if there
are any validation warnings. (Normally, these actions fail
only if there are validation errors.) The default is false.
For more information on Job actions, see “Submissions”
on page 193.
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 88.
GW-Locale String This sets the locale for the response.
For more information, see “Language and locale” on
page 88.
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 91.
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 91.
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.

86 Request headers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Header Datatype Description

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 92.
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
133.
x-gwre-session String This controls how related calls are routed on instances of
PolicyCenter running in a cluster.
(Note: This header is not exclusive to Cloud API and
therefore does not follow the convention of using "GW-"
at the start of header names.)
For more information, see “Sticky sessions in clustered
environments” on page 89.
X-Correlation-ID String This permits a customer to trace a request from its initial
reception through all of the subsequent applications that
were invoked to handle that request.
The actual traceability ID present in the MDC and logs
(and returned in the response) is dependent on the
implementation of the TraceabilityIDPlugin plugin.
The default implementation uses this value, if specified, or
a generated UID. However, another implementation may
always generate a unique ID and log the relationship
between these incoming values and the generated UID.
This header can be repeated, but the resulting string will
just be the comma separated values.
(Note: This header predates the REST API Framework and
was created prior to the convention of using "GW-" at the
start of header names.)

Send a request with a Cloud API header using Postman

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

Procedure
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify authorization as appropriate.
3. Add the header and header value.
• In the first row of tabs (the one that starts with Params), click Headers.
• Scroll to the bottom of the existing key/value list.

Request headers 87
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• In the blank row at the bottom of the key/value list, enter the header name in KEY column and its value in the
VALUE column.
4. Enter the request operation and URL.
5. Click Send.

Language and locale

When you send a request to Cloud API, the default behavior is to present data in the response using the default
language and locale specified in PolicyCenter. 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 PolicyCenter 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.

88 Request headers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

If the request does not contain either a GW-Language header or GW-Locale header, and the caller is not an authenticated
user with a preferred language, then the Accept-Language header is used.

How are the response language and locale determined?

What is specified What is language set to? What is locale set to?
Both GW-Language and GW- The GW-Language header value. The GW-Locale header value.
Locale
Only GW-Language The GW-Language header value. The caller's preferred locale, if any. Otherwise,
the PolicyCenter default locale.
Only GW-Locale The caller's preferred language, if any. Otherwise, The GW-Locale header value.
the PolicyCenter default language.
Neither GW-Language nor The caller's preferred language, if any. Otherwise, The caller's preferred locale, if any. Otherwise,
GW-Locale the Accept-Language header, if any. Otherwise, the PolicyCenter default locale.
the PolicyCenter 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 PolicyCenter servers in a configuration known as a
cluster. A PolicyCenter cluster distributes client connections among multiple PolicyCenter 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 PolicyCenter is running in a cluster, it is possible for related Cloud API calls to be routed to different nodes. This
can cause problems, such as Concurrent Data Change Exceptions.
Typically, multiple related Cloud API calls need to be routed to the same node. This behavior is sometimes referred to
as sticky sessions (or pod affinity). API Gateway provides two ways that you can implement sticky sessions with Cloud
API: session IDs (which is the default behavior) and cookies.

Request headers 89
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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
PolicyCenter. For more information, contact Guidewire.

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 PolicyCenter cluster:
1. A POST to create an activity.
2. A PATCH to update the activity.
3. A POST to create a note on the activity.
All three calls include the following header:

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

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

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

Comparing session IDs and cookies

Under most circumstances, it may be easier to use session IDs.
• Session IDs are generated by the caller application.
• Session IDs do not require the caller application to identify information in a response header and then manage the
storage that information for later use.

90 Request headers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Session IDs are the default behavior for Guidewire Cloud Platform.
If you wish to use cookies, you must request this from Guidewire.

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 account, and then a submission for the account,
which you then quote and bind. This would include POSTs to other child objects as well, such as contacts, locations,
coverages, and documents.
When executing a GW-DoNotCommit request, the response code will be the same as normal, such as 200 or 201, even
though no data is committed. Caller applications need to be careful to ensure that there are no other undesired side
effects from the warm-up request, such as integration points that might inadvertently send the placeholder data
downstream.

Handling a call with unknown elements

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

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

Request headers 91
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Validating response payloads against additional constraints

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

92 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 93
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

94 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 97.
Request inclusion is a technique for POSTs and PATCHes in which the call consists of the following:
• A single parent request that creates or modifies a resource
• One or more child requests that create or modify resources related to the parent resource
If either the parent request or any child request fails, the entire request fails.
For details about request inclusion, see “Request and response inclusion” on page 111.
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 119.
The Graph API provides endpoints that allow you to create all the elements of an account or a submission, including
all child elements, with a single command. The endpoints return complete account and submission graphs.
For more on the Graph API, see “Streamlined account and submission creation” on page 389.

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)

Reducing the number of calls 95

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Composite requests Request inclusion Batch requests

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)
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.
• Use a composite request with the Graph API endpoints to create a complete account and submission and then quote
and bind the submission.

96 Reducing the number of calls

chapter 9

Composite requests

From a Cloud API perspective, a composite request is a set of requests that are executed in a single InsuranceSuite
bundle (which corresponds to a single database transaction).
• A composite request can include one or more subrequests that create or modify data. Either all of the subrequests
succeed, or none of them are executed. Each subrequest is a separate unit of work.
• A composite request can also include one or more subselections that query for data.
◦ If the composite request has one or more subrequests, the subselections can retrieve data created or modified by
those subrequests.
◦ A composite request can also have no subrequests. In this case, the subselections merely execute multiple
queries to retrieve existing data.
Subrequests and subresponses are executed serially, in the order they are specified in the composite request payload.
PolicyCenter then gathers the response to each subrequest and subselection and returns them in a single response
payload. The responses to each subrequest and subselection appear in the same order as the original composite request.
Composite requests can make use of variables. This allows data created by the execution of one subrequest to be used
by later subrequests.
Composite requests can consist entirely of subrequests that merely retrieve data. For more information, see “Composite
requests that execute only queries” on page 104.
Composite requests support the use of most endpoints, but not all of them. They also support many query parameters,
but not all of them. For more information, see “Composite request limitations” on page 105.
Composite requests can be submitted asynchronously. For more information, see “Asynchronous calls” on page 133.
Composite requests are limited to a maximum number of subrequests. For more information, see “Configuring the
maximum number of subrequests” on page 107.

Constructing composite requests

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

Composite requests 97
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The syntax for the composite request call is:

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

Sections of a composite request

A composite request can have up to two sections:
• A requests section, which contains the subrequests that commit data.
• A selections section, which contains the subselections that query for data. These are executed after the
subrequests, and only if all the subrequests commit data successfully.
At a high level, the syntax for these sections is as follows:

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

The requests section

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

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

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

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

{
"requests": [
{
"method": "post",
"uri": "/common/v1/activities/xc:202/notes",
"body": {

98 Composite requests
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

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

Composite requests 99
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"method": "post",
"uri": "/account/v1/accounts/pc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"vars": [
{
"name": "newActivityId",
"path": "$.data.attributes.id"
}
]
},
{
"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
}
]
}

Responses to the subrequests

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

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

100 Composite requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Fields whose values are generated when data is committed

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

Subresponse values can be out of date

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

Suppressing subresponse details

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

"includeResponse": false

For example:

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

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

{
"responseIncluded": false
},

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

Composite requests 101

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Using query parameters in subrequests

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

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

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

{
"requests": [
{
"method": "post",
"uri": "/account/v1/accounts/pc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"parameters" : {
"fields" : "id,assignedUser"
}
},
...

For a given API, you can see a complete list of all query parameters that can be used in composite requests by
executing a GET /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 (if any), and only if all the subrequests commit data successfully.
The basic syntax for the selections section is shown below. You do not need to specify a method for each
subselection, as the only valid method in the selections section is GET.

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

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

{
"requests": [

102 Composite requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"method": "post",
"uri": "/account/v1/accounts/pc:34/activities",
"body": {
"data": {
"attributes": {
"activityPattern": "contact_insured",
"subject": "Cloud API activity"
}
}
},
"vars": [
{
"name": "newActivityId",
"path": "$.data.attributes.id"
}
]
},
{
"method": "post",
"uri": "/common/v1/activities/${newActivityId}/notes",
"body": {
"data": {
"attributes": {
"body": "Cloud API note #1."
}
}
}
}
],
"selections": [
{
"uri": "/common/v1/activities/${newActivityId}"
}
]
}

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

Using query parameters in the selections section

You can use certain query parameters for each subselection. This includes:
• fields
• filter
• includeTotal
• pageOffset
• pageSize
• sort
Each subselection is independent from the others. You can use different query parameters for each subselection, and
you can have some subselections with query parameters and others without query parameters.
The syntax for adding query parameters to a subselection is as follows:

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

Note the following:

• fields is specified as a single string of one or more fields, delimited by commas. The entire string is surrounded by
quotes.

Composite requests 103

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ For example, "assignedUser,dueDate,priority,subject"

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

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

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

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

To return activities based on multiple criteria:

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

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

Composite requests that execute only queries

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

Responses to the selections subrequests

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

Composite request examples

This documentation includes examples of composite requests for common business tasks. This includes the following:
• Creating and quoting a submission for the base configuration Personal Auto product: “Composite request
submission example for Personal Auto”
◦ Note that this example requires that also generate the LOB-specific endpoints for the base configuration
Personal Auto product.)

104 Composite requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Composite request limitations

General capabilities and limitations
Capabilities
Composite requests have the following general capabilities:
• The subrequests can make use of the following types of endpoints:
◦ Endpoints that are part of the base configuration
◦ Extension endpoints that have been created through the REST endpoint generator
• For base configuration endpoints, the subrequests can make use of extension fields added to the endpoints through
schema configuration, as described in the topic on Adding Properties to Resources in the Cloud API Developer
Guide)
Limitations
Composite requests have the following general limitations:
• The subrequests cannot make use of the endpoints that have been created outside of Cloud API, such as custom
endpoints created directly on the REST API Framework
• The number of subrequests and subselections in a single composite request must be less than or equal to the value
of the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. (In the base configuration, this
is set to 100.)
• You cannot use request inclusion in composite requests.
◦ For more information on request inclusion, see “Request and response inclusion” on page 111.
• You cannot include a subrequest that uses a content type other than application/json.
◦ For example, you cannot work with document resources in composite requests, as documents use multipart/
form-data.
• You cannot use any POST /search/... endpoint in a composite request (such as the ClaimCenter POST /
claim/v1/search/claims-v2 or the PolicyCenter POST /policy/v1/search/policies endpoint). This is
primarily because there is no way to guarantee that a POST /search/... endpoint will return a single result.
• There is no mechanism for iterating over a set of things.
◦ For example, you cannot start with a list of elements and include related resources for each item in that list.

Supported endpoints and query parameters

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

Business-specific limitations
There are also specific business requirements where you cannot use a composite request. For example:
• You cannot quote a job unless that job is created and quoted in the same composite request.
• You cannot bind-only or bind-and-issue in a composite request.
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

Composite requests 105

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

section of the documentation that discusses each business requirement for more information on requirements or
limitations related to composite requests.

Administering composite requests

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

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

{
"requestFailed": true,
"responses": [
{
"responseIncluded": false
},
{
"responseIncluded": false
},
{
"requestError": {
"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"
},

106 Composite requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Composite requests 107

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Complete composite request syntax

The following is the complete syntax for a composite request:

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

108 Composite requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

]
}

Composite requests 109

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

110 Composite requests

chapter 10

Request and response inclusion

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

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

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

Syntax for simple parent/child relationships

In most cases, the relationship between the root resource and an included resource is a simple parent/child relationship.
Examples of this include:
Request and response inclusion 111
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• An activity and its notes

• An account and its AccountLocations
When using request inclusion for simple parent/child relationships, the JSON has the following structure. This
structure is used when the root resource and the included resource are being POSTed. If the root resource is being
PATCHed, the structure may differ slightly. For more information, see “PATCHes in request inclusion” on page 115.

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

The data section

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

The included section

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

The method and uri fields

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

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

This specifies that in order to create the note, use the POST /common/v1/activities/{activityId}/notes endpoint.
The uri must start with the API name, such as "/common/v1".
If the included resource is being POSTed, the uri must specify the ID of the root resource. When the root resource and
the included resources are being created at the same time, the root resource does not yet have an ID. Therefore, the
keyword this is used in the uri to represent the root resource's ID. If the root resource is being PATCHed, the URI
field does not use this. For more information, see “PATCHes in request inclusion” on page 115.

112 Request and response inclusion

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Example of request inclusion for simple parent/child relationships

The following payload is an example of creating an activity on account pc:10, and a note for that activity.

POST http://localhost:8180/pc/rest/account/v1/accounts/pc:10/activities

{
"data": {
"attributes": {
"activityPattern": "general_reminder"
}
},
"included": {
"Note": [
{
"attributes": {
"subject": "Initial phone call",
"body": "Initial phone call with claimant"
},
"method": "post",
"uri": "/common/v1/activities/this/notes"
}
]
}
}

Syntax for named relationships

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

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

The data section

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

The included section

The included section consists of one or more subsections of included resources. Each subsection starts with the
resource type name. Then, one or more resources of that type can be specified. For each resource, you must specify:

Request and response inclusion 113

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• The resource's attributes

• The method and uri to create or modify the resource.

The refid field

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

The method and uri fields

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

"included": {
"AccountContact": [
{
"attributes": {
...
},
"refid": "...",
"method": "post",
"uri": "/account/v1/accounts/this/contacts"
}
]
}

This specifies that in order to create the AccountContact, use the POST /account/v1/{accountId}/contacts
endpoint.
The uri must start with the API name, such as "/account/v1".
If the included resource is being POSTed, the uri must specify the ID of the root resource. When the root resource and
the included resources are being created at the same time, the root resource does not yet have an ID. Therefore, the
keyword this is used in the uri to represent the root resource's ID. If the root resource is being PATCHed, the URI
field would not use this. For more information, see “PATCHes in request inclusion” on page 115.

Example of request inclusion for named relationships

The following payload is an example of creating an account and an AccountContact for the account whose relationship
is "accountHolder". (Accounts also require a primary location, so the payload also creates an AccountLocation whose
relationship is "primaryLocation".) For more information on creating accounts, see “Creating an account” on page
147.

POST http://localhost:8180/pc/rest/account/v1/accounts

{
"data": {
"attributes": {
"accountHolder": {
"refid": "newperson"
},
"organizationType": {
"code": "individual"
},
"preferredCoverageCurrency": {
"code": "USD"
},
"preferredSettlementCurrency": {
"code": "USD"
},
"primaryLocation": {
"refid": "newloc"
},
"producerCodes": [
{
"id": "pc:6"
}
]

114 Request and response inclusion

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
},
"included": {
"AccountContact": [
{
"attributes": {
"contactSubtype": "Person",
"firstName": "Bill",
"lastName": "Preston",
"primaryAddress": {
"addressLine1": "2850 S Delaware St #400",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"method": "post",
"refid": "newperson",
"uri": "/account/v1/accounts/this/contacts"
}
],
"AccountLocation": [
{
"attributes": {
"locationCode": "0001",
"locationName": "Location 0001",
"nonSpecific": true,
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"method": "post",
"refid": "newloc",
"uri": "/account/v1/accounts/this/locations"
}
]
}
}

PATCHes in request inclusion

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

PATCHing parent and POSTing child

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

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

Request and response inclusion 115

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

PATCHing parent and PATCHing child

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

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

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

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 an account and an AccountContact. The uri for the AccountContact would
have a value such as "/account/v1/accounts/this/contacts".
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 AccountContact could
reference an existing account, such as "/account/v1/accounts/pc:20/contacts". This uri says "create an
AccountContact and attach it not to the root resource of this POST, but rather to the existing account pc:20".

116 Request and response inclusion

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Request inclusion can use endpoints from different APIs

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

"uri": "/account/v1/accounts/<accountid>/notes"

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

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

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

"uri": "/account/v1/accounts/<accountid>/contacts"

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

"uri": "/account/v1/accounts/<accountid>/contacts/<contactid>"

Additional behaviors with read inclusion

Some endpoints support the ability to query for a given type of resource and for related resource types. For example,
the default behavior of the GET /activities endpoint is to return only activity resources. However, you can use the
include query parameter to include any notes related to the returned activities in the response payload. These types of
resources are referred to as included resources. The technique of adding included resources to a GET is sometimes
referred to as response inclusion or read inclusion. For more information on how to construct a GET with included
resources, see “Payload structure for a response with included resources” on page 42.
You can also use query parameters to filter included resources. For example, the following call retrieves all activities
assigned to the current user and includes any related notes. The number of notes returned in this example is limited to
5.

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

Request and response inclusion 117

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

118 Request and response inclusion

chapter 11

Batch requests

From a Cloud API perspective, a batch request is a set of requests that are executed in a non-transactional sequence.
Each call within the batch request is referred to as a subrequest. The object that contains all of the subrequests is
referred to as the main request.
Subrequests are executed serially, in the order they are specified in the request payload. PolicyCenter 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 123.

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 Policy API batch from an instance of PolicyCenter on your local machine, the
call would be:

POST http://localhost:8180/pc/rest/policy/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 119

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

where:
• <method> is the method in lower case, such as "get", "post", "patch", or "delete".
• <path> is the endpoint path.
◦ This path starts as if it was immediately following the API path (including the major version, such as "/v1").
For example, suppose the path for a command when executed in isolation is: http://localhost:8180/pc/
rest/policy/v1/policies/pc:22/activities/pc:55. The path within a batch is: /policies/pc:22/
activities/pc: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, PolicyCenter 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 policy.

{
"requests": [
{
"method": "get",

120 Batch requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Batch requests with query parameters

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

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

Batch requests with request payloads

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

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

Batch requests 121

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Batch requests with distinct operations

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

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

Administering batch requests

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

Specifying subrequest headers

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

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

122 Batch requests

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Specifying onFail behavior

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

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

Configuring the maximum number of subrequests

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

Batch requests 123

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

124 Batch requests

chapter 12

Lost updates and checksums

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

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 125

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Checksums
A checksum is a string value that identifies the "version" of a particular resource. Cloud API calculates checksums as
needed based on information about the underlying entities in the PolicyCenter 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, PolicyCenter calculates the checksum and compares that value to the
submitted checksum value.
• If the values match, PolicyCenter 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, PolicyCenter determines the resource has been changed since the caller application last
acquired the data. The request is not executed, and PolicyCenter 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.

126 Lost updates and checksums

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

Checksums for PATCHes and business action POSTs

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

"checksum": "<value>"

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

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

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

Tutorial: PATCH an activity using checksums

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will attempt to PATCH an activity twice. Both PATCHes will include a checksum value. The first
PATCH will succeed, and the second will fail.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by
entering the following call and clicking Send:
a. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
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>".)

Lost updates and checksums 127

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to PATCH and enter the following URL, but do not click Send yet:
a. PATCH http://localhost:8180/pc/rest/common/v1/activities/<ActivityID>
6. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons. For subject, specify the original subject
with an additional "-1".
{
"data": {
"attributes": {
"subject" : "<originalSubject>-1"
},
"checksum": "<originalChecksum>"
}
}

7. Click Send. The checksum value in the payload matches the checksum value for the activity stored in
PolicyCenter. 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 PolicyCenter. So, the second PATCH is unsuccessful and an error message appears.

Tutorial: Assign an activity using checksums

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will attempt to execute a business action (assigning an activity) twice. Both attempts will include a
checksum value. The first attempt will succeed, and the second will fail.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by
entering the following call and clicking Send:
a. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
3. Note the ID and checksum of the first activity returned in the response payload. (These values are referred to in
later steps as "<ActivityID>", and "<originalChecksum>".)
4. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
5. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST http://localhost:8180/pc/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.
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.

128 Lost updates and checksums

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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
PolicyCenter. 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 PolicyCenter. (The successful POST /assign from the previous step will have modified
the checksum value.) So, the second POST /assign is unsuccessful and an error message appears.

Checksums for DELETEs

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

Send a checksum in a request header using Postman

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

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

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

Tutorial: DELETE a note using checksums

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will send calls as Amy Clinton (user name aclinton). In the base configuration, Amy Clinton is an
underwriting supervisor who has permission to delete notes. As Amy Clinton, you will create a note. You will then

Lost updates and checksums 129

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

attempt to DELETE the note twice. Both DELETEs will include a checksum value. The first DELETE will fail, and the
second will succeed.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
a. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
2. The sample data includes one "Review risk information" activity for Alice Applegate. Query for that activity by
entering the following call and clicking Send:
a. GET http://localhost:8180/pc/rest/common/v1/activities?filter=subject:sw:Review%20risk
3. Identify the id of the activity in the payload. This value is referenced below as <activityId>.
4. Identify the id of the account in the payload. This value is referenced below as <accountId>.
5. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab tab.
a. On the Authorization tab, select Basic Auth using user aclinton and password gw.
6. Change the operation to POST and enter the following URL, but do not click Send yet:
a. POST http://localhost:8180/pc/rest/common/v1/activities/<activityId>/notes
7. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data":
{
"attributes": {
"body": "API tutorial note to be deleted with a checksum"
}
}
}

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

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

130 Lost updates and checksums

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Lost updates and checksums 131

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

132 Lost updates and checksums

chapter 13

Asynchronous calls

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

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 133

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

1. The caller application sends a request to Cloud API. In the diagram, the request is a POST for a resource named
someResource. The request has a set of request headers and may have a payload.
2. Cloud API processes the request synchronously.
3. Assuming the request is successful, Cloud API provides the response. The response also has a set of response
headers and may have a payload.

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

Submitting the call

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

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

134 Asynchronous calls

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Determining when the call has been processed

After the call has been submitted, the caller application uses the Async API /requests path from the initial response to
retrieve information about the original request. This path takes the form of /async/v1/requests/<asyncRequestId>.
The response to the /requests call always includes the following information:
• The requestMethod and requestPath of the original request
• The status of the original request, which can be set to:
◦ Accepted - The request is still waiting to be processed.
◦ InProgress - The request is being processed, but processing is not yet complete.
◦ Complete - The request has been processed.
• The startTime of the original request
If the original request has been completed, then the following information is also included:
• The completionTime of the original request
• The responseStatus and responseHeaders
• If the response's format is application/json, then the response itself is included in the responseBodyJson field

Example response for a call that has not been completed

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

{
"data": {
"attributes": {
"requestMethod": "POST",
"requestPath": "/admin/v1/users",
"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",

Asynchronous calls 135

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"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.
This is depicted in the following diagram.

136 Asynchronous calls

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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

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

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

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

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

Asynchronous calls 137

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Sending a request asynchronously

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

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

138 Asynchronous calls

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Tutorial: Send a request asynchronously

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will submit a request asynchronously to create a new user. (The work needed to create a user is
minimal, and one would not normally need to execute this type of request asynchronously. User is used here to
simplify the tutorial. User requires no parent entity, has only one required field, and has the same behavior across all
InsuranceSuite applications.)

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

4. Add the asynchronous request to the header.

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

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

Retrieving the response to the original request

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

Response information in the /requests response

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

/async/v1/requests/<asyncRequestId>

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

Asynchronous calls 139

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The response status

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

Response information using the /response endpoint

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

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

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

Tutorial: Retrieve information about an asynchronous request

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

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

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab
a. On the Authorization tab, select Basic Auth using user su and password gw.
2. Enter the following call, but do not click Send yet:
a. GET http://localhost:8180/pc/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.

140 Asynchronous calls

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Waiting for a response synchronously

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

Specifying wait time in seconds

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

Specifying wait time in milliseconds

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

Specifying a 0 wait time

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

Tutorial: Send a request asynchronously with a wait time

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will submit two requests asynchronously to create a new user. Both will specify a wait time.

Tutorial steps
1. In Postman, start a new request by:

Asynchronous calls 141

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

b. Specifying Basic Auth authorization using user su and password gw.
2. Enter the following call, but do not click Send yet:
a. POST http://localhost:8180/pc/rest/admin/v1/users
3. Specify the request payload.
a. In the first row of tabs (the one that starts with Params), click Body.
b. In the row of radio buttons, select raw.
c. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
d. Paste the following into the text field underneath the radio buttons.
{
"data": {
"attributes": {
"username": "asyncUserNoWait"
}
}
}

4. Add the asynchronous request to the header.

a. In the first row of tabs, click Headers.
b. Scroll to the bottom of the existing key/value list.
c. In the blank row at the bottom of the key/value list, enter the following:
i. KEY: Prefer
ii. VALUE: respond-async, wait=1
5. Create a second tab by duplicating the first tab. To do this, right-click the tab and select Duplicate Tab.
6. Modify the second tab so that it executes with a wait time.
a. In the request body, change the username value to asyncUserWithWait.
b. Change the Prefer header so its wait time is "wait-ms=1" instead of "wait=1":
i. KEY: Prefer
ii. VALUE: respond-async, wait-ms=1
7. On both tabs, click Send.

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

Asynchronous request administration

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

142 Asynchronous calls

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The AsyncApiRequest data model entity

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

The PurgeAsyncAPIRequests batch process

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

• The value of X is 7.
• The batch process is scheduled to run once a day at 3:30 am.
You can configure the value of X by manually adding an AsynchApiRequestPurgeDaysOld configuration parameter to
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.

Asynchronous calls 143

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

144 Asynchronous calls

part 3

Business flows: Accounts

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in PolicyCenter so that caller
applications can request data from or initiate action within PolicyCenter.
The following topics discuss how caller applications can initiate specific PolicyCenter business flows related to
accounts. This includes:
• Creating accounts
• Managing accounts
• Managing an account's bound policies

Business flows: Accounts 145

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

146 Business flows: Accounts

chapter 14

Creating accounts

An account is a person or organization which has or may have one or more policies. You can view, create, and modify
accounts through Cloud API. This topic focuses on account creation. For information on viewing and modifying
accounts, see “Managing accounts” on page 153.

Creating an account
To create a new account, use the following endpoint:
• POST /account/v1/accounts

Minimum creation criteria

The minimum amount of information you must provide is:
• An account holder
• A primary location
• A producer code
The following sections cover these pieces of information in detail. For an example of how to create an account, see
“Creating an account example payload” on page 151.

The account holder

The account holder is the primary contact associated with the account. This information is stored in PolicyCenter as an
AccountContact.

There are two ways you can specify the account holder in a POST /accounts payload:
• Using the initialAccountHolder attribute
• Using the accountHolder attribute to reference a contact created through request inclusion
The only difference between these two approaches is the way the information is specified. The first approach specifies
the initial account holder in the main attributes section, and the second specifies it using request inclusion.
Otherwise, the result of each approach is the same.
In either approach, you must specify the following information for the account holder:
• contactSubtype (typically Person or Company)
◦ For the Person subtype, you must also specify lastName and firstName
Creating accounts 147
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ For the Company subtype, you must also specify companyName

• primaryAddress, which must include:
◦ addressLine1
◦ city
◦ state
◦ postalCode

Using the initialAccountHolder attribute

The initialAccountHolder attribute lets you specify the account holder information in the attributes section of the
request payload. For example, the following snippet specifies the account holder using the initialAccountHolder
attribute:

{
"data": {
"attributes": {
"initialAccountHolder": {
"contactSubtype": "Person",
"firstName": "Bill",
"lastName": "Preston",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
...

Using the accountHolder attribute

The accountHolder attribute requires you to specify the AccountContact information in the included section of the
payload, as opposed to in the attributes section. You then reference the contact using a refid. For example, the
following snippet specifies the account holder using the accountHolder attribute:

{
"data": {
"attributes": {
"accountHolder": {
"refid": "BillPreston"
},
...
},
"included": {
"AccountContact": [
{
"attributes": {
"contactSubtype": "Person",
"firstName": "Bill",
"lastName": "Preston",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"method": "post",
"refid": "BillPreston",
"uri": "/account/v1/accounts/this/contacts"
}
]
}
}

The primary location

The primary location is the primary address associated with the account. This information is stored in PolicyCenter as
an AccountLocation.

148 Creating accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

There are two ways you can specify the account location in a POST /accounts payload:
• Using the initialPrimaryLocation attribute
• Using the primaryLocation attribute to reference a location created through request inclusion
The only difference between these two approaches is the way the information is specified. The first approach specifies
the primary location in the main attributes section, and the second specifies it using request inclusion. Otherwise,
the result of each approach is the same.
In either approach, by default, you must specify the following information for the primary location:
• addressLine1
• city
• state
• postalCode

Using the initialPrimaryLocation attribute

The initialprimaryLocation attribute lets you specify the primary location information in the attributes section
of the request payload. For example, the following snippet specifies the primary location using the
initialPrimaryLocation attribute:

{
"data": {
"attributes": {
"initialPrimaryLocation": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
...

Using the primaryLocation attribute

The primaryLocation attribute requires you to specify the AccountLocation information in the included section of
the payload, as opposed to in the attributes section. For example, the following snippet specifies the primary
location using the primaryLocation attribute:

{
"data": {
"attributes": {
"primaryLocation": {
"refid": "newlocation"
},
...
},
"included": {
"AccountLocation": [
{
"attributes": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"method": "post",
"refid": "newlocation",
"uri": "/account/v1/accounts/this/locations"
}
]
}
}

Non-specific locations
All locations, including an account's primary location, have a nonSpecific flag that indicates how complete the
location information is. This flag defaults to false.

Creating accounts 149

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• If the flag is set to false, the location is considered to be specific.

◦ A specific location is a location that includes a complete address. The definition of a complete address can vary
by locale. In North America, the minimum requirements for a complete address are a street address, city, state or
province, and postal code.
◦ This is the flag's default value. When the nonSpecific flag is not specified, the location is considered to be
specific and must consist of a complete address.
• If the flag is set to true, the location is considered to be non-specific.
◦ A non-specific location is a location that includes a state or province, as this is required to determine locale-
related constraints. But otherwise, it is not required to include any additional address information.
◦ For a location to be considered non-specific, the nonSpecific flag must be explicitly set to true.
For example, the following snippet specifies the primary location using the initialPrimaryLocation attribute and a
non-specific address:

{
"data": {
"attributes": {
"initialPrimaryLocation": {
"nonSpecific": true,
"state": {
"code": "CA"
}
...

The producer code

Every new account must be associated with exactly one producer code.

Retrieving producer codes

There are two endpoints you can use to retrieve producer codes - one in the Account API and one in the Admin API.
These endpoints are:
• GET /account/v1/producer-codes
• GET /admin/v1/producer-codes
The Admin API version returns all producer codes, regardless of their status. The Account API version returns only the
producer codes available to the caller. The Account API version omits producer codes that the caller cannot use (such
as producer codes that are inactive or that are not available to the specific caller).
When you execute either endpoint, the payload for each producer code looks similar to the following example.

{
"attributes": {
"branch": {
"branchCode": "301",
"displayName": "Minneapolis Branch UW",
"id": "pc:Sk46AxgTMK1O7s6659Ats"
},
"code": "301-008578",
"description": "ACV Property Insurance",
"displayName": "301-008578",
"id": "pc:16",
"organization": {
"displayName": "ACV Property Insurance",
"id": "pc:4",
"type": "Organization",
"uri": "/admin/v1/organizations/pc:4"
},
"producerStatus": {
"code": "Active",
"name": "Active"
}
}

For more information on working with producer codes through Cloud API, see “Producer codes” on page 465.

150 Creating accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Specifying producer codes

When creating an account, the request payload must include a producerCodes array with exactly one producer code.
For example:

{
"data": {
"attributes": {
"producerCodes": [
{
"id": "pc:16"
}
]
...

Creating an account example payload

The following payload creates a new account using the initialAccountHolder and initialPrimaryLocation
attributes.

POST /account/v1/accounts

{
"data": {
"attributes": {
"initialAccountHolder": {
"contactSubtype": "Person",
"firstName": "Bill",
"lastName": "Preston",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"initialPrimaryLocation": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"producerCodes": [
{
"id": "pc:16"
}
]
}
}
}

Name clearance and account status

Name clearance
Name clearance is a process executed during account creation that verifies the account does not already exist.

Name clearance in the base configuration

In the base configuration, when a new account is created through the user interface, PolicyCenter checks to see if the
account appears to be a duplicate of an existing account. If it does, PolicyCenter displays the names of potentially
matching accounts.
However, when using the POST /accounts endpoint, the account is always created, even if it appears to be a duplicate
of an existing account. The fact that there were potentially matching accounts is not included in the response payload.

Creating accounts 151

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Account status
On account creation, the account status is set to "Pending". This indicates that the account exists but that there are no
policies associated with it. Once the account has at least one policy, its status changes to "Active".

Child objects for an account

An account can have several types of child objects. They are summarized in the following table.

Object type More information

Additional account contacts “Account contacts” on page 157
Additional account locations “Account locations” on page 164
Activities “Activities” on page 421
Documents “Documents” on page 429
Notes “Notes” on page 437
Jobs “Account jobs and policies” on page 165
Policies “Account jobs and policies” on page 165

Creating accounts as an anonymous user

An anonymous user is a person who is not yet known to the insurer but who may establish a business relationship with
the insurer.
The base configuration supports an anonymous user flow. In this flow:
• Initially, the user is unauthenticated. The user creates a new account.
• When responding to the account creation, PolicyCenter sends back a self-signed JWT (JSON web token).
• The user is now an anonymous user. With the self-signed JWT, the user can create and quote submissions for the
account they created. They can also bind the policy.
Once an anonymous user binds a submission, they logically move from being an anonymous user to an external user.
For more information on the anonymous user auth flow, see the Cloud API Developer Guide.

152 Creating accounts

chapter 15

Managing accounts

This topic covers the different ways that a caller application can get information on existing accounts, and additional
actions they can take on accounts.
For information on creating accounts, see “Creating an account” on page 147.

Querying for accounts

Use the following endpoints to query for accounts:
• GET /account/v1/accounts
• GET /account/v1/accounts/{accountId}
For example, the following is a portion of the payload that is returned when retrieving account pc:477.

GET /account/v1/accounts/pc:477

{
"data": {
"attributes": {
"accountHolder": {
"displayName": "Agnes Allenson",
"id": "pc:SdImoclfPl10vrB0wMXoo"
},
"accountNumber": "8990509182",
"accountStatus": {
"code": "Pending",
"name": "Pending"
},
"id": "pc:477",
"numberOfContacts": "1",
"organizationType": {
"code": "individual",
"name": "Individual"
},
"primaryLocation": {
"displayName": "1: Location 0001",
"id": "pc:S_4dxAb4ZhvmMM-vrmoAU",
"type": "AccountLocation",
"uri": "/account/v1/accounts/pc:477/locations/pc:119"
},
"producerCodes": [
{
"displayName": "100-002541",
"id": "pc:6"
}
]
}
...

Managing accounts 153

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Searching for accounts

Sometimes, a caller application may need to access a specific account, but it does not know the account's ID or enough
information about the account to retrieve it using the GET /accounts endpoint directly. In these cases, the caller
application can use the following endpoint to search for the account.
• POST account/v1/search/accounts
The request object must include a body. The body must specify at least one of the following search parameters using
the following syntax:

{
"data": {
"attributes": {
"accountNumber": "stringValue",
"companyName": "stringValue",
"firstName": "stringValue",
"lastName": "stringValue",
"organization": {
"id": "stringValue"
},
"phoneNumber": "stringValue",
"producerCode": {
"id": "stringValue"
},
"taxId": "stringValue"
}
}
}

Note the following requirements and restrictions:

• The request object must include at least one of the required parameters.
◦ There are also optional search parameters that can be added. For a complete list, refer to the API definition of
the endpoint.
• When searching by companyName:
◦ The request object cannot include firstName or lastName.
◦ The search returns only accounts where the account holder is an exact match of the named company.
• When searching by first and last name:
◦ The request object must include both firstName and lastName.
◦ The request object must omit companyName.
◦ The search returns only accounts where the account holder is an exact match of the named person.
For example, the following payload will query for all accounts with account number C000143542:

{
"data": {
"attributes": {
"accountNumber": "C000143542"
}
}
}

The following payload will query for all accounts where the account holder has a first name of "Ray" and a last name
of "Newton":

{
"data": {
"attributes": {
"firstName": "Ray",
"lastName": "Newton"
}
}
}

154 Managing accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Searching by producer
Two search criteria pertain to producers: producerCode and organization.
If you know a producer's code, you can search for all accounts associated with that producer by including
producerCode as a search criteria. For example, the following searches for accounts associated with producer code pc:
16 (ACV Property Insurance).

{
"data": {
"attributes": {
"producerCode": {
"id": "pc:16"
}
}
}
}

In the base configuration, producers are stored in the Organization entity. If you know a producer's ID, you can
search for accounts associated with that producer by including the organization as search criteria. For example, the
following searches for accounts associated with the producer whose id is pc:4 (ACV Property Insurance).

{
"data": {
"attributes": {
"organization": {
"id": "pc:4"
}
}
}
}

Providing no search parameters

PolicyCenter will not execute an account search with no query parameters. If you attempt to execute an account search
without query parameters, either from the user interface or through Cloud API, PolicyCenter returns the following error
message:

Please enter enough search information: first name or last name, company name, account number,
phone number, producer information, or an official ID. If searching by last name with partial
match, either city and state, or ZIP are required. At least three letters are required for
names (five for companies) with partial match."

Note that this message is intended primarily for user interface account searches. This is why it makes reference to
partial matches and a minimum number of required letters.

Searching in Japanese
The search endpoint also supports certain Japanese locale-specific fields:
• companyNameKanji: Complete company name, in Japanese
• firstNameKanji: Complete first name, in Japanese. Can be used in combination with firstName or
lastNameKanji.
• lastNameKanji: Complete last name, in Japanese. Can be used in combination with lastName or firstNameKanji.
• particle: Particle used in account holder names (matching the particle property of an AccountContact
resource)
The following code block is a request body for a search based on first name and first name in Japanese:

{
"data": {
"attributes": {
"firstNameKanji": "太郎",
"firstName": "Taro"
}
}
}

Managing accounts 155

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Modifying accounts
PATCHing accounts
Use the following endpoint to PATCH values on an existing account:
• PATCH /account/v1/accounts/{accountId}
For example, the following call changes the preferred coverage and settlement currencies for account pc:477 to
Canadian dollars (cad).

PATCH /account/v1/accounts/pc:477

{
"data": {
"attributes": {
"preferredCoverageCurrency": {
"code": "cad"
},
"preferredSettlementCurrency": {
"code": "cad"
}
}
}
}

Merging accounts
Merging accounts is the action of collapsing two accounts into one. One account is designated as the source account.
The other is the target account. During the merge, information is moved from the source to the target, such as the
source account's policies, policy transactions, notes, activities, and other data. After the merge, the source account is
deleted and only the target account remains. For more information on merging accounts, see the Application Guide.
Use the following endpoint to merge accounts:
• POST /account/v1/accounts/{accountId}/merge
The POST is executed from the target account (the account that will be retained). The request requires a payload. This
is the syntax for the URL and the payload.

POST /account/v1/accounts/{targetAccountId}/merge

{
"data": {
"attributes": {
"account": {
"id": "<sourceAccountId>"
}
}
}
}

For example, the following call merges source account pc:1010 into target account pc:33.

POST /account/v1/accounts/pc:33/merge

{
"data": {
"attributes": {
"account": {
"id": "pc:1010"
}
}
}
}

Withdrawing accounts
Some accounts are created for prospects that do not elect to bind any policies and the insurer does not expect the
account to bind any policies in the future. In these cases, the insurer can withdraw the account.
To withdraw an account through Cloud API, use the following endpoint. The call does not require a request body:

156 Managing accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• POST /account/v1/accounts/{accountId}/withdraw
For example, the following call withdraws account pc:477.

POST /account/v1/accounts/pc:477/withdraw

<no request body>

Withdrawing an account changes the account status to "Withdrawn".

Note that you can only withdraw accounts whose status is "Pending". (In order to have this status, the account must
have no policies.)

Reopening accounts
To reopen a withdrawn account through Cloud API, use the following endpoint. The call does not require a request
body:
• POST /account/v1/accounts/{accountId}/reopen
For example, the following call withdraws account pc:477 (assuming the account has been withdrawn).

POST /account/v1/accounts/pc:477/reopen

<no request body>

Reopening an account changes the account status to "Pending".

Account contacts
In addition to the account holder, an account may have any number of additional contacts.

Querying for account contacts

Use the following endpoints to retrieve information about contacts for a specific account:
• GET /accounts/{accountId}/contacts
• GET /accounts/{accountId}/contacts/{contactId}

Masking the taxID field

The AccountContact resource has a taxID field which stores the tax ID of the contact. In the Cloud API base
configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the
response for a GET that retrieves a contact.

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

For some callers, such as internal or external users, the masking of tax ID may be appropriate as it protects personally
identifiable information. For other callers, such as services, this masking may cause a problem as the callers may
reference contacts internally using the tax ID.
There are two ways that the taxId field can be unmasked:
• You can configure the field so that it is always unmasked. For information on how to configure this, see the Cloud
API Developer Guide.
• You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission
will get responses with unmasked tax IDs. For information on how to configure this, see the section on API role
special permissions in the Cloud API Developer Guide.

Managing accounts 157

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Creating account contacts

Use the following endpoint to create an AccountContact for a given account:
• POST /accounts/{accountId}/contacts

Minimum creation criteria

You must specify the following information:
• contactSubtype (typically set to either Person or Company)
• firstName and lastName (for Person contacts)
• companyName (for Company contacts)
• primaryAddress, with at least:
◦ addressLine1
◦ city
◦ state
◦ postalCode
Note:

The preceding address information is not required if you’re creating a contact with a linked address. See
“Linking account contact addresses” on page 159 below for more information.
For example, the following request creates a new contact for account pc:202.
Command

POST /account/v1/accounts/pc:202/contacts

Request

{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
}
}
}

Modifying account contacts

Use the following endpoints to modify or delete an account contact:
• PATCH /account/v1/accounts/{accountId}/contacts/{contactId}
• DELETE /account/v1/accounts/{accountId}/contacts/{contactId}
For example, the following request assigns an email for account contact pc:444 on account pc:202.
Command

PATCH /account/v1/accounts/pc:202/contacts/pc:444

158 Managing accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Request

{
"data": {
"attributes": {
"emailAddress1": "[email protected]"
}
}
}

The following request deletes account contact pc:444 on account pc:202.

DELETE /account/v1/accounts/pc:202/contacts/pc:444

<no request body>

Linking account contact addresses

There might be times when you want a contact on an account to have the same address as another contact on that
account. Rather than reentering the same information for every contact at the same address, you can use linked contact
addresses. Linking addresses allows you to create or update a contact without reentering address information that exists
elsewhere on the account, and enables you to update an address on all contacts to which it applies with a single
command.
You add and update a linked address to a contact using these properties under the contact’s primaryAddress object:
• linkedAddress: An object containing the address information to link to.
◦ addressId: ID of the address to link to.
◦ contactId: ID of the primary named insured, account holder, or named insured associated with that address.
• linkedAddressUpdateMode: A value that determines how updates to the address are applied. Options are:
◦ update: When this value is specified, any updates to the address will be applied to all contacts to which the
address is linked.
◦ unlink: Updates the address only on the contact being updated. When an address is updated with this option
specified, that contact no longer has a linked address. This option removes the link, making this a stand-alone
address on the contact.
After an address has been linked, it includes the following property:
• isLinked: A Boolean value automatically set to true when an address is linked. When this value is true, updates to
the address must include the linkedAddressUpdateMode property.
The following example creates a new contact with a linked address. In this example, the contact is created with the
same address as the account holder. Here is the account holder information:

{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
...
"firstName": "Alicia",
"id": "pc:577",
"lastName": "Shirley",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "0399 Bridgepointe Parkway",
"addressLine2": "Floor 0399",
"addressLine3": "Developer Unit Habitation Cube #0399",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",

Managing accounts 159

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "0399 Bridgepointe Parkway, Floor 0399, Developer Unit Habitation Cube #0399, San Mateo,
CA 94404-0399",
"id": "pc:123",
"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
},

Create the contact using the account holder contact id (pc:577) and address id (pc:123) in the request.
Command

POST /account/v1/accounts/pc:202/contacts

Request

{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"linkedAddress": {
"addressId": "pc:123",
"contactId": "pc:577"
}
}
}
}
}

Response

{
"data": {
"attributes": {
...
"id": "pc:892",
"lastName": "Stewart",
"officialIds": {},
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "0399 Bridgepointe Parkway",
"addressLine2": "Floor 0399",
"addressLine3": "Developer Unit Habitation Cube #0399",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "0399 Bridgepointe Parkway, Floor 0399, Developer Unit Habitation Cube #0399, San Mateo,
CA 94404-0399",
"id": "pc:3333",
"isLinked": true,
"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
}
},

The response shows that the contact has been created with a primaryAddress that is identical to the linked address.
Notice the isLinked property is set to true. If you also retrieve the contact to which you linked and view the address
you linked to, you’ll see that the primaryAddress has an isLinked value of true for that contact also.
Command

GET /account/v1/accounts/pc:202/contacts/pc:577

160 Managing accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "0399 Bridgepointe Parkway",
"addressLine2": "Floor 0399",
"addressLine3": "Developer Unit Habitation Cube #0399",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "0399 Bridgepointe Parkway, Floor 0399, Developer Unit Habitation Cube #0399, San Mateo,
CA 94404-0399",
"id": "pc:123",
"isLinked": true,
"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
},

This next example updates the address for an existing contact that has a linked address. If a contact has a linked address
(isLinked is set to true), you must include a linkedAddressUpdateMode value to update the address.
Command

PATCH /account/v1/accounts/pc:202/contacts/pc:892

Request

{
"data": {
"attributes": {
"primaryAddress": {
"linkedAddressUpdateMode": "update",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressLine3": null
}
}
}
}

Response

{
"data": {
"attributes": {
...
"id": "pc:892",
"lastName": "Stewart",
"officialIds": {},
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "1234 Main St, Apt 2B, San Mateo, CA 94404-0399",
"id": "pc:5555",
"isLinked": true,

Managing accounts 161

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
}
},

Because we set the linkedAddressUpdateMode to update, the linked contact’s address has also been changed:

{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
...
"firstName": "Alicia",
"id": "pc:577",
"lastName": "Shirley",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressType": {
"code": "home",
"name": "Home"
},
"city": "San Mateo",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 399",
"displayName": "1234 Main St, Apt 2B, San Mateo, CA 94404-0399",
"id": "pc:123",
"isLinked": true,
"postalCode": "94404-0399",
"state": {
"code": "CA",
"name": "California"
}
},
...
},

Account contact roles

Each contact associated with an account can be assigned roles on the account and on the policies. Some of these roles
are dependent on the LOB, or are shared between the account and the policy. This topic describes how to manage
account-level contact roles.
Note:

The roles discussed in this topic are the roles users have on an account, such as Driver or NamedInsured. If
you’re looking for information on API roles related to authentication, see Cloud API Developer Guide.
The base configuration of PolicyCenter includes several roles that can be assigned to a contact at the account level. The
list of available roles is in the AccountContactRole typelist. The account contact endpoint provides properties that can
be set to add and remove these roles to and from the account contact.

Adding roles to an account contact

Setting a role property on an account contact to true gives that contact the corresponding role. For example, setting the
secondaryContact property to true will add the SecondaryContact role to the account contact. Setting it to false
will remove the role from the contact.
You can add roles to an account contact when you create the contact, and you can also update those roles later. The
following example creates an account contact on account pc:202 with the roles accountingContact and
secondaryContact.

162 Managing accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Command

POST /account/v1/accounts/pc:202/contacts

Request

{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"accountingContact": true,
"secondaryContact": true
}
}
}

Use the following command to update the roles on an existing account contact:
PATCH /account/v1/accounts/{accountID}/contacts/{contactID}
For example, the following request removes the SecondaryContact role from account contact pc:444 on account pc:
202 and adds the NamedInsured role
Command

PATCH /account/v1/accounts/pc:202/contacts/pc:444

Request

{
"data": {
"attributes": {
"namedInsured": true,
"secondaryContact": false
}
}
}

Any roles you set to true will be added to existing roles already assigned to the account contact. For example, if
contact pc:444 in the preceding example already had the role Driver, that contact would now have three roles
assigned: NamedInsured, AccountingContact, and Driver.
Note:

Attempting to remove a role (setting the value to false) will return an error if the role is in use at the policy
level for the contact.

Querying for contacts with a specified role

You can filter on accountContactRoles to retrieve all account contacts with a given role. This example retrieves all
contacts in account pc:202 that have the role AccountingContact:
Command

GET /account/v1/accounts/pc:202/contacts?fields=id,accountContactRoles&filter=accountContactRoles:in:AccountingContact

Response

{
"data": [
{
"attributes": {
"accountContactRoles": [

Managing accounts 163

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"code": "AccountingContact",
"name": "AccountingContact"
},
...
],
"id": "pc:444"
}
}
]
…
}

Account locations
In addition to the primary location, an account may have any number of additional locations.

Querying for account locations

Use the following endpoints to retrieve information about locations for a specific account:
• GET /account/v1/accounts/{accountId}/locations
• GET /account/v1/accounts/{accountId}/locations/{locationId}

Creating account locations

Use the following endpoint to create an AccountLocation for a given account:
• POST /accounts/{accountId}/locations

Minimum creation criteria

The required information for a location varies based on the locale. For example, for US locations, the minimum
amount of information you must specify is:
• addressLine1
• city
• state
• postalCode
For example, the following request creates a new location for account pc:202.

POST /account/v1/accounts/pc:202/locations

{
"data": {
"attributes": {
"addressLine1": "2870 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
}
}

For more information on locale-specific requirements, see the Cloud API Developer Guide

Modifying account locations

Use the following endpoint to modify an account location:
• PATCH /account/v1/accounts/{accountId}/locations/{locationId}

164 Managing accounts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following request assigns a location name for account location pc:717 on account pc:202.

PATCH /account/v1/accounts/pc:202/contacts/pc:717

{
"data": {
"attributes": {
"locationName": "Employee parking lot"
}
}
}

Use the following endpoint to delete an account location:

• DELETE /account/v1/accounts/{accountId}/locations/{locationId}
For example, the following request deletes account location pc:717 from account pc:202.

DELETE /account/v1/accounts/pc:202/contacts/pc:717

<no request body>

Account jobs and policies

Querying for job and policy information
To retrieve a list of jobs or policies for a given account, use the following endpoints:
• GET /account/v1/accounts/{accountId}/jobs
• GET /account/v1/accounts/{accountId}/policies
By default, only open jobs are returned. To see all jobs, add a filter query parameter such as this:

GET /accounts/{AccountId}/jobs?filter=*none

See “Endpoints with default filters” on page 56 for more information on default filters.
Note that there could also be authorization filters based on the account holder. See Cloud API Developer Guide for
more information.

Moving policies
In some situations, you may want to move a policy from a source account to a target account. For example, this could
be necessary if the policy was erroneously associated with the wrong account.
To move a policy to a given target account, use the following endpoint:
• POST /account/v1/accounts/{accountId}/move-policies
The POST is executed from the target account (the account that will own the policy moving forward). The request
object requires a request payload that specifies the IDs of the policies to move to the target account. These IDs are
specified in a policies array.
For example, the following call moves the policies with IDs pc:1021 and pc:1099 to account pc:477.

POST /account/v1/accounts/pc:477/move-policies

{
"data": {
"attributes": {
"policies": [
{
"id": "pc:1021"
},
{
"id": "pc:1099"
}
]
}
}
}

Managing accounts 165

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The "move policies" functionality has the following limitations:

• You cannot move an archived policy.
• You cannot move multiple policies at one time from different source accounts. Every group of moved policies must
be from the same source account going to the same target account.
• You cannot move a policy to an account that could not normally own that type of policy. (For example, you cannot
move a Personal Auto policy to an account that is a company.)
• All InsuranceSuite applications have a Messaging infrastructure used to send messages asynchronously to third-
party applications. You cannot move a policy if it has any pending messages associated with it.

166 Managing accounts

chapter 16

Managing bound policies

This topic covers the different actions that you can take on the bound policies owned by an account outside of any
policy transaction.

Querying for policies

Use the following endpoints to query for policies:
• GET /policy/v1/policies
• GET /policy/v1/policies/{policyId}
For example, the following is a portion of the payload that is returned when retrieving policy pc:909.

GET /policy/v1/policies/pc:909

{
"data": {
"attributes": {
"account": {
"displayName": "C000143542",
"id": "pc:Sl9Ku7grY4qRy28Y4GkRI",
},
"id": "pc:909",
"organization": {
"displayName": "Armstrong and Company",
"id": "pc:1",
},
"periodEnd": "2022-07-20T00:01:00.000Z",
"periodStart": "2022-01-20T00:01:00.000Z",
"policyNumber": "P000143542",
"primaryInsured": {
"displayName": "Ray Newton",
},
"primaryLocation": {
"displayName": "1: 1253 Paloma Ave, Arcadia, CA",
},
"producerCode": {
"displayName": "100-002541",
"id": "pc:6"
},
"product": {
"displayName": "Personal Auto",
"id": "PersonalAuto"
},
"termType": {
"code": "HalfYear",
"name": "6 months"
},
"totalCost": {
"amount": "764.00",
"currency": "usd"
}

Managing bound policies 167

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
...

Data in the Policy resource has multiple sources

Some resources manage data from multiple data model entities. The Policy resource is one of them. There are fields in
the Policy resource that map to the Policy entity, the PolicyPeriod entity, or the PolicyTerm entity.
Consequently, Cloud API does not have a separate set of endpoints for PolicyPeriod or PolicyTerm. The fields from
PolicyPeriod or PolicyTerm that are exposed in Cloud API are exposed solely through the /policy endpoints.

If you want to add extension fields to the PolicyCenter data model and expose those fields in Cloud API, Guidewire
recommends the following:
1. In the data model, add the fields to most appropriate entity (Policy, PolicyPeriod, or PolicyTerm).
2. In Cloud API, add the corresponding properties to the Policy schema and map the properties to the new fields in
whichever data model entity they have been declared.
For more information on how to extend schema, see the Cloud API Developer Guide.

Searching for policies

Sometimes, a caller application may need to access a specific policy, but it does not know the policy's ID or enough
information about the policy to retrieve it using the GET /policies endpoint directly. In these cases, the caller
application can use the following endpoint to search for the policy.
• POST policy/v1/search/policies
The request object must include a body. The body must specify at least one of the following search parameters using
the following syntax:

{
"data": {
"attributes": {
"companyName": "<stringValue>",
"firstName": "<stringValue>",
"lastName": "<stringValue>",
"officialId": "<stringValue>",
"phone": "<stringValue>",
"policyNumber": "<stringValue>",
"producerCode": {
"id": "<stringValue>"
}
}
}
}

Note the following requirements and restrictions:

• The request object must include at least one required parameter.
◦ There are also optional search parameters that can be added. For a complete list, refer to the API definition of
the endpoint.
• When searching by companyName:
◦ The request object cannot include firstName or lastName.
◦ The search returns only policies where the insured is an exact match of the named company.
• When searching by first and last name:
◦ The request object must include both firstName and lastName.
◦ The request object cannot include companyName.
◦ The search returns only policies where the insured is an exact match of the named person.
• When searching by official ID:

168 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ The search returns only policies where the insured's official ID (such as their Social Security Number of Federal
Employee ID) is an exact match of the provided official ID.
• When searching by phone:
◦ The search returns only policies where the insured's primary phone is an exact match of the provided phone
number.
For example, the following payload will search for all policies with policy number P000143542:

{
"data": {
"attributes": {
"policyNumber": "P000143542"
}
}
}

The following payload will search for all policies where the primary insured has a first name of "Ray" and a last name
of "Newton":

{
"data": {
"attributes": {
"firstName": "Ray",
"lastName": "Newton"
}
}
}

The following payload will search for all policies where the producer code is pc:16 (ACV Property Insurance).

{
"data": {
"attributes": {
"producerCode": {
"id": "pc:16"
}
}
}
}

In a development environment, a policy search may return a policy whose product is listed as "Manual", as in the
following example.

"product": {
"displayName": "Manual Products",
"id": "Manual"
}

This happens when the policy is using an Advanced Product Designer line of business that is still in visualized mode
and is not finalized or installed. For more information, see Integrating Products with PolicyCenter.

Providing no search parameters

PolicyCenter will not execute a policy search with no query parameters. If you attempt to execute a policy search
without query parameters, either from the user interface or through Cloud API, PolicyCenter returns the following error
message:

Please enter enough search information: first name or last name, company name, account number,
phone number, producer information, or an official ID. If searching by last name with partial
match, either city and state, or ZIP are required. At least three letters are required for names
(five for companies) with partial match."

Note that this message is intended for user interface policy searches, which is why it makes reference to partial matches
and a minimum number of required letters.

Policy search using free-text search

PolicyCenter supports two types of searches: database search and free-text search. Database search is enabled by
default. An insurer can configure PolicyCenter to use free-text search instead.

Managing bound policies 169

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The /policy/v1/search/policies endpoint executes whichever type of search is enabled, based on the value of the
FreeTextSearchEnabled application configuration parameter.

• If false, the policy search is done using a database search.

• If true, the policy search is done using a free-text search.
For more information on free-text search and how to configure the associated Solr extension, see the Configuration
Guide.

Moving policies between accounts

In some situations, you may want to move a policy from a source account to a target account. For example, this could
be necessary if the policy was erroneously associated with the wrong account.
To move a policy to a given target account, use the following endpoint:
• POST /account/v1/accounts/{accountId}/move-policies
The POST is executed from the target account (the account that will own the policy moving forward). The request
object requires a request payload that specifies the IDs of the policies to move to the target account. These IDs are
specified in a policies array.
For example, the following call moves the policies with IDs pc:1021 and pc:1099 to account pc:477.

POST /account/v1/accounts/pc:477/move-policies

{
"data": {
"attributes": {
"policies": [
{
"id": "pc:1021"
},
{
"id": "pc:1099"
}
]
}
}
}

The "move policies" functionality has the following limitations:

• You cannot move an archived policy.
• You cannot move multiple policies at one time from different source accounts. Every group of moved policies must
be from the same source account going to the same target account.
• You cannot move a policy to an account that could not normally own that type of policy. (For example, you cannot
move a Personal Auto policy to an account that is a company.)
• All InsuranceSuite applications have a Messaging infrastructure used to send messages asynchronously to third-
party applications. You cannot move a policy if it has any pending messages associated with it.

Policy producers
In PolicyCenter, the producer is stored as an instance of the Organization data model entity. A producer is associated
with a policy through a specific producer code.

The producer data model

Producer of record and producer of service
Most policies have only one producer associated with them, and that producer remains with the policy for the entire
term. However, there are times when the producer on a policy will change mid-term. For example, the insured may be
dissatisfied with the service provider by producer A and may request to have the policy serviced by producer B.

170 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

When a policy's producer changes, the two producers may agree that the original producer will retain commission for
the current policy term, even though the new producer will be providing service for the policy. When this occurs:
• The original producer is referred to as the producer of record.
• The new producer is referred to as the producer of service.
For more information on the business functionality of producers of record and producers of service, see the Application
Guide.

Producers in Cloud API resources

In Cloud API, both the Job and Policy resources have four fields that track information about the policy's producer.
• organization - The organization representing the producer of record
• organizationOfService - The organization representing the producer of service
• producerCode - The producer code that associates the policy with the producer of record
• producerCodeOfService - The producer code that associates the policy with the producer of service
The organization and producerCode fields reflect data as if they had been named organizationOfRecord and
producerCodeOfRecord.

When a policy's producer has not been changed mid-term:

• Both organization and organizationOfService reference the same organization (the producer).
• Both producerCode and producerCodeOfService reference the same producer code.
For example, the following is a snippet of the response to a GET of policy pc:115. For this policy, there has been no
mid-term change of producer.

GET /policies/v1/policies/pc:115

{
"data": {
"attributes": {
"organization": {
"displayName": "Armstrong and Company",
"id": "pc:1"
},
"organizationOfService": {
"displayName": "Armstrong and Company",
"id": "pc:1"
},
"producerCode": {
"displayName": "100-002541",
"id": "pc:6"
},
"producerCodeOfService": {
"displayName": "100-002541",
"id": "pc:6"
}
}
}
}

When a policy's producer has been changed mid-term:

• organization and organizationOfService reference different organizations.
◦ organization references the original producer (the producer of record).
◦ organizationOfService references the current producer (the producer of service).
• Both producerCode and producerCodeOfService reference different producer codes.
◦ producerCode references the original producer code (the producer code of record).
◦ producerCodeOfService references the current producer code (the producer code of service).

Managing bound policies 171

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following is a snippet of the response to a GET of policy pc:227. For this policy, there has been a
mid-term change of producer.

GET /policies/v1/policies/pc:227

{
"data": {
"attributes": {
"organization": {
"displayName": "Armstrong and Company",
"id": "pc:1"
},
"organizationOfService": {
"displayName": "ACV Property Insurance",
"id": "pc:4"
},
"producerCode": {
"displayName": "100-002541",
"id": "pc:6"
},
"producerCodeOfService": {
"displayName": "301-008578",
"id": "pc:16"
}
}
}
}

Producer information and the GET /policies endpoint

For the GET /policy/v1/policies endpoint, only two of the four producer fields are included in the summary view,
which defines the fields returned by default. If you need all four fields, use the fields query parameters. All four
fields are part of the detail view. Thus, the following query gets all policies and with all four producer fields in the
response:

GET /policy/v1/policies?fields=*detail

Changing a policy's producer

There are two ways you can change a policy's producer.

Changing both the producer of record and producer of service

In submissions, issuances, renewals, rewrites, and rewrite accounts, you can PATCH a policy's producer. In these
situations, the change results in only one producer associated with the policy. This producer is the producer of record
and the producer of service.
In the PATCH, specify the producerCodeOfService only. The producerCode is automatically updated to the same
value, and both the organizationOfService and organization fields are automatically updated to the organization
that owns the give producer code.
For example, the following request changes the producer (of record and of service) for submission job pc:123.

PATCH job/v1/jobs/pc:123

{
"data": {
"attributes": {
"producerCodeOfService": {
"id": "pc:16"
}
}
}
}

Changing the producer of service only

In policy change jobs, you can PATCH a policy's producer. In these situations, there will be two producers. The original
producer (prior to the PATCH) becomes the producer of record. The new producer (who is specified in the PATCH)
becomes the producer of service.

172 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

In the PATCH, specify the producerCodeOfService only. The organizationOfService is automatically updated to
the organization that owns the give producer code. The producerCode and organization fields are not modified.
These continue to reference the previous producer, who is now only the producer of record.
For example, the following request changes the producer of service for policy change job pc:789.

PATCH job/v1/jobs/pc:789

{
"data": {
"attributes": {
"producerCodeOfService": {
"id": "pc:16"
}
}
}
}

Policy jobs
Use the following endpoint to retrieve a list of jobs used to create or modify the policy:
• GET /policy/v1/policies/{policyId}/jobs

Policy contacts
Overview of policy contacts
In PolicyCenter, every job has an underlying policy. You can associate account contacts with this policy. For example,
when a submission is created for an account, the default behavior is to associate the account's "primary insured" contact
with the underlying policy as the "primary named insured". A contact associated with a policy is known as a policy
contact. Policy contacts exist on policies that are unbound (such as a submission's underlying policy) and on policies
that are bound.
In the PolicyCenter data model, there is no PolicyContact entity. Policy contacts are stored in the database using
multiple entities:
• The Contact entity
• The AccountContact entity
• One or more PolicyContactRole entities
In Cloud API, policy contacts are managed using a single resource named PolicyContact. This resource gathers the
information from multiple data model entities (Contact, AccountContact, and PolicyContactRole).
The following table summarizes the different base configuration /contact endpoints in each API and the resources
used by those endpoints.

API Example endpoints Root resource type

Account GET /account/v1/accounts/{accountId}/contacts AccountContact
POST /account/v1/accounts/{accountId}/contacts
GET /account/v1/accounts/{accountId}/contacts/{contactId}
PATCH /account/v1/accounts/{accountId}/contacts/{contactId}
DELETE /account/v1/accounts/{accountId}/contacts/{contactId}
Job GET /job/v1/accounts/{accountId}/contacts PolicyContact
POST /job/v1/accounts/{accountId}/contacts
GET /job/v1/accounts/{accountId}/contacts/{contactId}
PATCH /job/v1/accounts/{accountId}/contacts/{contactId}
DELETE /job/v1/accounts/{accountId}/contacts/{contactId}

Managing bound policies 173

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

API Example endpoints Root resource type

Policy GET /policy/v1/accounts/{accountId}/contacts PolicyContact
GET /policy/v1/accounts/{accountId}/contacts/{contactId}

Policy contacts on a policy

For every policy:
• There is always exactly one primary insured.
• There may be one or more additional named insureds.
• There may also be contacts with roles that are specific to the policy's lines of business, such as a policy contact on a
Personal Auto policy with the role of "driver".

Querying for all policy contacts

Use the following endpoints to retrieve information about all contacts for a specific policy:
• GET /policy/{policyId}/contacts
• GET /policy/{policyId}/contacts/{contactId}
These endpoints return all policy contacts, regardless of their specific role on the policy.

Querying for the primary insured

You can get a policy's named insured by retrieving the policy itself. The primaryInsured property identifies the
primary named insured.
For example, the following is a portion of the response when doing a GET for policy pc:3894:

GET /policy/v1/policies/pc:3894

...
"primaryInsured": {
"displayName": "Ray Newton",
"id": "test_pp:2",
"type": "PolicyContact",
...
},
...

Querying for the secondary named insured

You can get a policy's secondary insured by retrieving the policy itself. The secondaryNamedInsured property
identifies the secondary named insured.
For example, the following is a portion of the response when doing a GET for policy pc:3894:
Command

GET /policy/v1/policies/pc:3894

Response

...
"secondaryNamedInsured": {
"displayName": "Mary Newton",
"id": "test_pp:3",
"type": "PolicyContact",
...
},
...

Querying for additional named insured

Use the following endpoints to retrieve a policy's additional named insureds, if any:

174 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET policies/{policyId}/additional-named-insureds
• GET policies/{policyId}/additional-named-insureds/{additionalNamedInsuredId}
Technically speaking, each element returned by these endpoints is not a policy contact. Rather, it is information about
the association between a policy contact and the additional named insured role. It can optionally specify information
about this association.
For example, the following is a portion of the response when doing a GET for policy pc:3894:

GET /policy/v1/policies/pc:3894/additional-named-insureds

{
"attributes": {
"accountContact": {
"displayName": "Shirley Hemsworth",
"id": "pc:552",
"type": "AccountContact",
"uri": "/account/v1/accounts/pc:7071/contacts/pc:552"
},
"id": "353",
"relationship": "wife"
},

The response identifies that there is a contact with the "Additional Named Insured" role on the policy. The contact's id
is pc:552 (Shirley Hemsworth), and her relationship to the primary insured is "wife". The id of the role association
itself is 353.

Querying for contacts with a specified role

You can filter on policyContactRoles to retrieve all policy contacts with a given role. This example retrieves all
contacts on policy pc:202 that have the role PolicySecNamedInsured:
Command

GET /policy/v1/policies/pc:202/contacts?fields=id,policyContactRoles&filter=policyContactRoles:in:PolicySecNamedInsured

Response

{
"data": [
{
"attributes": {
"id": "pc:202",
"policyContactRoles": [
{
"code": "PolicySecNamedInsured",
"name": "PolicySecNamedInsured"
}
…
}

Masking the taxID field

The PolicyContact resource has a taxID field which stores the tax ID of the contact. In the Cloud API base
configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the
response for a GET that retrieves a contact.

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

For some callers, such as internal or external users, the masking of tax IDs 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:

Managing bound policies 175

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• You can configure the field so that it is always unmasked. For information on how to configure this, see the Cloud
API Developer Guide.
• You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission
will get responses with unmasked tax IDs. For information on how to configure this, see the section on API role
special permissions in the Cloud API Developer Guide.

Creating and modifying policy contacts

Policy contacts can be created or modified only from within the context of a policy transaction, such as a submission,
policy change, or renewal.
To add or modify a contact on an existing policy, you must execute a policy change and execute the work from there.
For more information, see “Policy changes” on page 221.

Policy locations
In addition to the primary location, a policy may have any number of additional locations.

Querying for the primary location

You can determine a policy's primary location by inspecting the policy itself. The primaryLocation property identifies
the primary location.
For example, the following is a portion of the response when doing a GET for policy pc:3894:

GET /policy/v1/policies/pc:3894

...
"primaryLocation": {
"displayName": "1: 1253 Paloma Ave, Arcadia, CA",
"id": "1",
"type": "PolicyLocation",
"uri": "/policy/v1/policies/pc:SNZEJIOVY-iX-69VD3056/locations/1"
},
...

Querying for policy locations

Use the following endpoints to retrieve information about all locations for a specific policy:
• GET /policy/v1/policies/{policyId}/locations
• GET /policy/v1/policies/{policyId}/locations/{locationId}

Creating and modifying policy locations

Policy locations can be created or modified only from within the context of a policy transaction, such as a submission,
policy change, or renewal. Locations on the job are converted into policy locations when the job is bound.
To add or modify a location on an existing policy, you must execute a policy change and execute the work from there.
For more information, see “Policy changes” on page 221.

Policy questions
During a submission, questions may have been posed to the insured. These questions could have been used to pre-
qualify the account, or to get additional information about a specific location. These questions and their answers are
available from the policy once the policy has been bound.
Questions can be optional, and it is possible for no answer to be provided to a question. From the policy, you can see
all the questions that were part of the submission, whether they were answered or not. You can also see any answers
that were provided.

176 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Querying for questions and their answers

Use the following endpoints to retrieve information about a set of questions and their answers, if any.

Endpoint Response
GET /policies/{policyId}/ The set of policy-level questions from the job (which are typically used for pre-qualification),
questions and their answers, if any
GET /policies/{policyId}/ The set of location-level questions for the specified location from the job (which are typically
locations/{locationId}/ used to gather additional information for rating), and their answers, if any
questions

Structure of a QuestionAnswer
A QuestionAnswer is a resource that stores a single question for a job or policy and its answer, if any.
The datatype of a question's answer depends on the nature of the question itself. For example, "Is the driver legally
blind?" has a Boolean answer, but "What was the date of the most recent safety course completed?" has a datetime
answer.
To accommodate this variation in the datatype of an answer, a QuestionAnswer has a questionType property. This
identifies the datatype of the answer. This property is set to one of the following: Boolean, Choice, Date, Integer,
String.

There are also a set of datatype-specific ...Value properties: booleanValue, choiceValue, dateValue,
integerValue, textValue. For a given QuestionAnswer, the answer is stored in the ...Value property that
corresponds to the questionType. The ...Value properties that are not relevant are set to null.
For example, if a QuestionAnswer's questionType is set to Boolean, then the answer is stored in the booleanValue
field. The choiceValue, dateValue, integerValue, and textValue properties are set to null.
If no answer was specified for a question, there is still a QuestionAnswer for the question, but all of its ...Value
properties are null.
There is also a displayValue property. This stores the question's answer, if any, converted to a string.

Structure of a /questions response

The response to a GET /questions request has a single answers attribute. This attribute contains a map of
QuestionAnswers. Each QuestionAnswer has the following syntax:

"<questionId>": {
"question": {
"displayName": "<displayText>"
"id": "<questionId>"
},
"questionType": {
"code": "<questionTypeCode>",
},
"displayValue": "<value>",
"booleanValue": <value>,
"choiceValue": {
"code": "<choiceValueCode>",
},
"dateValue": "<value>",
"integerValue": <value>,
"textValue": "<value>",
},

For any given question, some values are always set and some values are always null. If a property has a null value, it is
not included in the response. The following table defines how each value is set.

Property How the value is set

question Always included. It contains the id of the question and the displayName, which is the text shown on the user
interface to pose the question.
questionType Always included. It contains the questionTypeCode, which is one of the following: Boolean, Choice, Date,
Integer, String

Managing bound policies 177

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Property How the value is set

displayValue Set to the display value of the answer, if the question has an answer. Otherwise, set to null and omitted from the
response.
booleanValue Set to a Boolean value if the questionType is Boolean and the question has been answered. Otherwise, set to
null and omitted from the response.
choiceValue Set to a choiceValueCode if the questionType is Choice and the question has been answered. Otherwise,
set to null and omitted from the response. (The acceptable choiceValueCode values for a given question are
defined in the product definition and can vary from question to question.)
dateValue Set to a date value if the questionType is Date and the question has been answered. Otherwise, set to null
and omitted from the response.
integerValue Set to an integer value if the questionType is Integer and the question has been answered. Otherwise, set to
null and omitted from the response.
textValue Set to a string value if the questionType is String and the question has been answered. Otherwise, set to null
and omitted from the response.

Examples of answer responses

This is an example of a response to a GET /questions. The first question, MovingViolations2, is a Boolean
question. Its answer is true.

{
"data": {
"attributes": {
"answers": {
"MovingViolations2": {
"question": {
"displayName": "Any drivers with convictions for moving traffic violations within
the past 3 years? If 'Yes' please explain.",
"id": "MovingViolations2"
},
"questionType": {
"code": "Boolean"
},
"displayValue": "true",
"booleanValue": true
},
...

The second question, DriverNameConviction, is a string question. Its answer is "Driving without a license".

...
"DriverNameConviction": {
"question": {
"displayName": "Please provide the driver name and explain the conviction.",
"id": "DriverNameConviction"
},
"questionType": {
"code": "String"
},
"displayValue": "Driving without a license",
"textValue": "Driving without a license"
},
...

The third question, PACurrentlyInsured, is a choice question. Its answer is a question-specific code from the product
design (newdriver, which has a display value of "No - New driver").

...
"PACurrentlyInsured": {
"question": {
"displayName": "Is the applicant currently insured?",
"id": "PACurrentlyInsured"
},
"questionType": {
"code": "Choice"
},
"displayValue": "No - New Driver",
"choiceValue": {
"code": "newdriver",
"name": "No - New Driver"
}

178 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
...

The fourth question, CurrentSuspense, is a Boolean question. It has not been answered, so its displayValue and
booleanValue properties are null and therefore not included in the response.

...
"CurrentSuspense": {
"question": {
"displayName": "Is the applicant's license currently suspended, canceled, or revoked?",
"id": "CurrentSuspense"
},
"questionType": {
"code": "Boolean"
}
},
...

Prior policies
Every policy and job has a set of risk analysis information. The insurer can use this information to determine how to
process policy transactions. For example, this information could be used to determine whether or not to renew a policy.
One category of risk information is the prior policies. Prior policies is a list of policies that the insured has held before
the current policy. These could be policies with the insurer or with other insurers. For more information on the business
functionality of prior policies, see the Application Guide.
You can retrieve and manage prior policy information through Cloud API.

Prior policies in PolicyCenter

Prior policy information is stored in the PriorPolicy data model entity. Every entity has an array of PriorPolicies.
The fields in the PriorPolicy data model entity that are exposed in the user interface include the following:
• AnnualPremium
• Carrier
• EffectiveDate
• ExpirationDate
• NumLosses
• PolicyNumber
• TotalLosses (a monetary amount)
In the base configuration, prior policy information appears in the following places:
• Within the relevant Job wizards (such as submission and policy change), on the Risk Analysis step's Prior Policies
tab
• On the policy's Risk Analysis screen's Prior Policies tab
In the base configuration:
• You can view prior policy information in either location.
• You can edit prior policy information only in a Job wizard. (In other words, you cannot edit prior policy
information outside of the context of a job.)

Prior policies in Cloud API

Prior policy information is tracked in the PriorPolicy resource.
Through Cloud API:
• You can view prior policy information on a job or a policy.

Managing bound policies 179

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• For policies not yet bound, you can edit prior policy information on the submission job.
• For bound policies, you can edit prior policy information on the policy itself.

Querying for prior policy information

Use the following endpoints to query for prior policy information:
• Jobs
◦ GET /job/v1/jobs/{jobId}/prior-policies
◦ GET /job/v1/jobs/{jobId}/prior-policies/{priorPolicyId}
• Policies
◦ GET /policy/v1/policies/{policyId}/prior-policies
◦ GET /policy/v1/policies/{policyId}/prior-policies/{priorPolicyId}
For example, the following query retrieves the prior policy information for job pc:334.
GET /job/v1/jobs/pc:334/prior-policies

{
"count": 1,
"data": [
{
"attributes": {
"annualPremium": {
"amount": "5092.00",
"currency": "usd"
},
"carrier": "CommuteCoverage",
"effectiveDate": "2021-09-04",
"id": "pc:SlpveONavkeunmUPCU4nZ",
"numLosses": 1,
"policyNumber": "CO-43221-3",
"totalLosses": {
"amount": "5721.13",
"currency": "usd"
}
},
...

Creating prior policy information

Use the following endpoints to create prior policy information:
• POST /job/v1/jobs/{jobId}/prior-policies
• POST /policy/v1/policies/{policyId}/prior-policies

Minimum creation criteria

The only field required to create a PriorPolicy is effectiveDate.

POST example
The following payload creates a PriorPolicy for job pc:334. Note that it includes the required field (effectiveDate)
and additional optional fields.

POST /job/v1/jobs/pc:334/prior-policies

{
"data": {
"attributes": {
"carrier": "Interstate Insurance",
"effectiveDate": "2021-10-13",
"annualPremium": {
"amount": "617.00",
"currency": "usd"
},
"policyNumber": "BNL-123312-2"
}

180 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

Updating prior policy information

PATCHing prior policy information
Use the following endpoints to PATCH prior policy information:
• PATCH /job/v1/jobs/{jobId}/prior-policies/{priorPolicyId}
• PATCH /policy/v1/policies/{policyId}/prior-policies/{priorPolicyId}
For example, the following payload modifies prior policy pc:1119 for job pc:334.

PATCH /job/v1/jobs/pc:334/prior-policies/pc:1119

{
"data": {
"attributes": {
"numLosses": 0,
"totalLosses": {
"amount": "0.00",
"currency": "usd"
}
}
}
}

DELETEing prior policy information

Use the following endpoints to DELETE prior policy information:
• DELETE /job/v1/jobs/{jobId}/prior-policies/{priorPolicyId}
• DELETE /policy/v1/policies/{policyId}/prior-policies/{priorPolicyId}
For example, the following payload deletes prior policy pc:1119 from job pc:334.

DELETE /job/v1/jobs/pc:334/prior-policies/pc:1119

<no request payload>

Loss history
Every job and policy has a loss history, which is a list of any prior losses that have been incurred by the insured. This
information can be used to make business decisions such as whether to approve a submission or renewal. For more
information on the business functionality of loss history, see the Application Guide.
You can retrieve and manage loss history information through Cloud API.

Loss history in PolicyCenter

Every policy has a LossHistoryType field. This indicates the type of loss history information associated with the
policy. There are three possible types of loss history:
• Attached
• Manually entered
• No loss history
The default is "No loss history".

Managing bound policies 181

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Loss history: Attached

The LossHistoryType field can be set to Attached (code att). This indicates that information about prior losses is
defined in a set of attached documents. In addition to those documents, information about the loss history is
summarized in the following Policy fields:
• NumPriorLosses - The number of prior losses. (In the user interface, this is specified as the number of prior losses
in the past 5 years, but there is no enforcement of time span in the database.)
• PriorTotalIncurred - The total amount of the prior losses.
The documents that define the prior losses are associated with the policy in the same way as any other document. There
is no array specifically for loss history documents. However, all documents that pertain to loss history have a document
type of loss_history.

Loss history: Manually entered

The LossHistoryType field can be set to Manually entered (code man). This indicates that information about prior
losses is defined in a set of loss history entries whose contents are manually entered by an underwriter.
Information about the loss history is captured in the Policy entity's PriorLosses array. Each member is an instance of
the LossHistoryEntry entity, which has the following fields:
• AmountPaid
• AmountResv (the amount of any open reserve)
• Description
• LossStatus
• OccurenceDate
• TotalIncurred

Loss history: No Loss History

The LossHistoryType field defaults to No loss history (code nol). This indicates that there have been no prior losses.
You can also manually set the LossHistoryType field to No loss history.

Loss history in the user interface

In the base configuration, loss history information appears in the following places:
• Within the relevant Job wizards (such as submission and policy change), on the Risk Analysis step's Prior Losses tab
• On the policy's Risk Analysis screen's Prior Losses tab
In the base configuration:
• You can view loss history information in either location.
• You can edit loss history information only in a Job wizard. (In other words, you cannot edit loss history outside of
the context of a job.)

Loss history in Cloud API

Cloud API manages loss history using two resources.
The LossHistory resource is used for every type of loss history. It includes the following fields:
• lossHistoryType
◦ Set to a value from the LossHistoryType typelist (att, man, or nol)
• numPriorLosses
◦ The number of prior losses. This value is manually entered. It is not calculated dynamically.

182 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ Used only when lossHistoryType is set to att (attached)

• priorTotalIncurred
◦ The total amount incurred from prior losses. This value is manually entered. It is not calculated dynamically.
◦ Used only when lossHistoryType is set to att (attached)
The PriorLoss resource is used only for policies whose lossHistoryType is set to man (manually entered). Each
PriorLoss captures information about a single manually entered prior loss. It has the following fields:

• amountPaid (a MonetaryAmount)
• description
• lossStatus (a value from the LossEntryStatus typelist, such as Open or Closed)
• occurenceDate
• openReserve (a MonetaryAmount)
• totalIncurred (a MonetaryAmount)

Differences between the user interface and Cloud API

The user interface does not permit the creation or change of loss history information outside of the context of a job.
However, Cloud API has endpoints that can create and modify loss history information directly on policies, outside of
the context of a job.

Querying for loss history information

Retrieving loss history type
To determine a policy's loss history type, use the following endpoints:
• GET /job/v1/jobs/{job-id}/loss-history
• GET /policy/v1/policies/{policy-id}/loss-history
For example, the following request retrieves the loss history type for job pc:333.

GET job/v1/jobs/pc:333/loss-history?fields=lossHistoryType

{
"data": {
"attributes": {
"lossHistoryType": {
"code": "man",
"name": "Manually Entered"
}
},

Loss history: Attached

For policies with attached loss histories, use the following endpoints to get the number of losses and total incurred for
the specified job or policy:
• GET /job/v1/jobs/{job-id}/loss-history
• GET /policy/v1/policies/{policy-id}/loss-history
For example, the following request retrieves the loss history information for job pc:444.

GET job/v1/jobs/pc:444/loss-history

{
"data": {
"attributes": {
"lossHistoryType": {
"code": "att",
"name": "Attached"
},
"numPriorLosses": 2,

Managing bound policies 183

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"priorTotalIncurred": {
"amount": "300.00",
"currency": "usd"
}
},

There is no endpoint dedicated to retrieving the attached loss history documents. However, you can use the GET /
documents endpoint to retrieve only the documents associated with the policy whose type is loss history.

For example, the following request retrieves the loss history documents for job pc:444.

GET job/v1/jobs/pc:444/documents?filter=type:eq:loss_history

{
"count": 2,
"data": [
{
"attributes": {
"id": "pc:S8SvBsGKtMsbxOfdw35lB",
"name": "Loss Details - Accident on 2022/10/12",
"status": {
"code": "draft",
"name": "Draft"
},
"type": {
"code": "loss_history",
"name": "Loss history"
}
},
...
},
{
"attributes": {
"id": "pc:Stac2g5QJvz2K96tyBkFp",
"name": "Loss Details - Accident on 2020/07/08",
"status": {
"code": "final",
"name": "Final"
},
"type": {
"code": "loss_history",
"name": "Loss history"
}
},
...
}

Loss history: Manually entered

For policies with manually entered loss histories, use the following endpoints to get retrieve the loss history entry
information for the specified job or policy:
• GET /job/v1/jobs/{job-id}/loss-history/prior-losses
• GET /job/v1/jobs/{job-id}/loss-history/prior-losses/{priorLossId}
• GET /policy/v1/policies/{policy-id}/loss-history/prior-losses
• GET /policy/v1/policies/{policy-id}/loss-history/prior-losses/{priorLossId}
For example, the following request retrieves the prior losses for job pc:555.

GET job/v1/jobs/pc:555/loss-history/prior-losses

{
"count": 1,
"data": [
{
"attributes": {
"amountPaid": {
"amount": "2000.00",
"currency": "usd"
},
"description": "Accident (with $500 deductible)",
"id": "pc:Sgg81r2HeunCNnYYWSDvl",
"lossStatus": {
"code": "Closed",
"name": "Closed"
},
"occurrenceDate": "2022-08-08",
"openReserve": {
"amount": "0.00",

184 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"currency": "usd"
},
"totalIncurred": {
"amount": "2500.00",
"currency": "usd"
}
},
...

PATCHing policy-level loss history information

Use the following endpoints to PATCH loss history information on the Policy entity:
• PATCH /job/v1/jobs/{job-id}/loss-history
• PATCH /policy/v1/policies/{policy-id}/loss-history
For example, the following payload modifies the number of prior losses and total incurred for policy pc:444, whose
loss history is attached.
PATCH job/v1/jobs/pc:444/loss-history

{
"data": {
"attributes": {
"numPriorLosses": 3,
"priorTotalIncurred": {
"amount": "450.00",
"currency": "usd"
}
}
}
}

Working with loss history entries

When the LossHistoryType field is set to Manually entered (code man), information about prior losses is defined in a
set of loss history entries.
In Cloud API, loss history entries are managed using the PriorLoss resource. Each PriorLoss captures information
about a single manually entered prior loss. It has the following fields:
• amountPaid (a MonetaryAmount)
• description
• lossStatus (a value from the LossEntryStatus typelist, such as Open or Closed)
• occurenceDate
• openReserve (a MonetaryAmount)
• totalIncurred (a MonetaryAmount)

Creating loss history entries

For a policy whose LossHistoryType field is set to Manually entered (code man), you can use the following endpoints
to create a loss history entry:
• POST /job/v1/jobs/{jobId}/loss-history/prior-losses
• POST /policy/v1/policies/{policyId}/loss-history/prior-losses
When you create a loss history entry, there are no required fields. However, if you specify no fields, then the only field
populated with a default value is id. This may result in a business object with limited value.
For example, the following payload creates a loss history entry for job pc:1221:

POST /job/v1/jobs/pc:1221/loss-history/prior-losses

{
"data": {
"attributes": {

Managing bound policies 185

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"amountPaid": {
"amount": "2000.00",
"currency": "usd"
},
"description": "Accident (with $500 deductible)",
"lossStatus": {
"code": "Closed"
},
"occurrenceDate": "2022-08-01",
"openReserve": {
"amount": "0.00",
"currency": "usd"
},
"totalIncurred": {
"amount": "2500.00",
"currency": "usd"
}
}
}
}

PATCHING loss history entries

Use the following endpoints to PATCH a loss history entry:
• PATCH /job/v1/jobs/{jobId}/loss-history/prior-losses/{priorLossId}
• PATCH /policy/v1/policies/{policyId}/loss-history/prior-losses/{priorLossId}
For example, the following payload PATCHes the occurrence date for loss history entry pc:99099 for job pc:1221:

PATCH /job/v1/jobs/pc:1221/loss-history/prior-losses/pc:99099

{
"data": {
"attributes": {
"occurrenceDate": "2022-01-08"
}
}
}

DELETEing loss history entries

Use the following endpoints to DELETE a loss history entry:
• DELETE /job/v1/jobs/{jobId}/loss-history/prior-losses/{priorLossId}
• DELETE /policy/v1/policies/{policyId}/loss-history/prior-losses/{priorLossId}
For example, the following payload deletes loss history entry pc:99099 from job pc:1221:

DELETE /job/v1/jobs/pc:1221/loss-history/prior-losses/pc:99099

<no request body>

Pre-renewal directions
A pre-renewal direction is a special note attached to a policy that provides information on how to execute the policy's
next renewal job. There are three broad types of pre-renewal directions:
• Non-renew - The policy will not be renewed at the request of the insurer.
• Not taken - The policy will not be renewed at the request of the insured.
• Refer to an individual - The policy will be reviewed by the insurer to determine if it can be renewed.
The full set of possible values is defined in the PreRenewalDirection typelist.
When you create a pre-renewal direction note, you must specify:
• The direction
• The user that the renewal will be assigned to

186 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• A security level for the note

• Text for the note
The topic of the note is set to "Pre-renewal direction".
At any given time, a policy can have only one active pre-renewal direction. A new pre-renewal direction supersedes
any previous directions.
In Cloud API, pre-renewal directions can be managed from endpoints in the Policy API.

Retrieving pre-renewal directions

To determine a policy's current pre-renewal direction, execute a GET for the policy.
• The pre-renewal direction is stored in the preRenewalDirection field.
• The user assigned by the pre-renewal is stored in the preRenewalOwner field.
• If the GET includes the policy's notes, pre-renewal notes have a topic code of prerenewal.
The following request body is a snippet of the response for a GET of policy pc:44 with its associated notes. The snippet
includes the information related to pre-renewal directions.
GET /policy/v1/policies/pc:44?include=notes

{
"data": {
"attributes": {
"id": "pc:44",
"preRenewalDirection": "underwriter",
"preRenewalOwner": {
"assigneeId": "userId=pc:3630,groupId=pc:318",
"groupId": "pc:318",
"name": "Alice Applegate (Los Angeles Branch UW)",
"userId": "pc:3630"
}
},
"included": {
"Note": [
{
"attributes": {
"bodySummary": "Refer to underwriter to investigate excessive number of claims",
"confidential": true,
"securityType": {
"code": "internalonly",
"name": "Internal Only"
},
"topic": {
"code": "prerenewal",
"name": "Pre-renewal direction"
}
},
...

Setting pre-renewal directions

Use the following endpoint to set a policy's pre-renewal direction:
• POST /policy/v1/policies/{policyId}/set-prerenewal-direction

Minimum creation criteria

At a minimum, the request body must provide the following:
• body - The body of the pre-renewal note
• direction - The pre-renewal direction (A value from the PreRenewalDirection typelist)
• securityType - The security type of the note (A value from the NoteSecurityType typelist)
Additional fields may be required depending on the selected pre-renewal direction. The following table summarizes the
required fields.

Managing bound policies 187

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Pre-renewal direction direction value Additional required fields

Non-renew nonrenew nonRenewReason (A value from the NonRenewalCode typelist)
Not taken nottaken (none)
Refer to underwriter underwriter assignTo
Refer to underwriter assistant assistant assignTo
Refer to Customer Service Representative custrep assignTo
Non-renew and refer to underwriter nonrenewrefer assignTo,
nonRenewReason (A value from the NonRenewalCode typelist)

Non-renew example
For a non-renew direction, you must specify the non-renewal reason. This must be a typecode from the
NonRenewalCode typelist.

POST /policy/v1/policies/pc:44/set-prerenewal-direction

{
"data": {
"attributes": {
"body": "Excessive claims",
"direction": {
"code": "nonrenew"
},
"nonRenewReason": {
"code": "loss"
},
"securityType": {
"code": "internalonly"
}
}
}
}

Not taken example

For a non-renew direction, aside from body, direction, and securityType, no additional fields are required.

POST /policy/v1/policies/pc:44/set-prerenewal-direction

{
"data": {
"attributes": {
"body": "Insured is selling their car",
"direction": {
"code": "nottaken"
},
"securityType": {
"code": "internalonly"
}
}
}
}

Refer to review example

For a "refer to underwriter" direction, you must specify the underwriter and group to assign the renewal to in the
assignTo field.

POST /policy/v1/policies/pc:44/set-prerenewal-direction

{
"data": {
"attributes": {
"assignTo": {
"userId": "pc:3630",
"groupId": "pc:318"
},
"body": "Refer to underwriter to investigate excessive number of claims",",
"direction": {
"code": "underwriter"
},
"securityType": {

188 Managing bound policies

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "internalonly"
}
}
}
}

Clearing pre-renewal directions

You can clear a policy's pre-renewal direction. This removes any active pre-renewal direction without setting a new
one. The puts the policy in the same state it would be in if it had never had any pre-renewal direction.
Use the following endpoint to clear a policy's pre-renewal direction:
• POST /policy/v1/policies/{policyId}/clear-prerenewal-direction
The request does not require a body.

Additional actions for bound policies

Contingencies
In some situations, an insurer may need to identify that a policy has an issue to resolve, even though there are no active
jobs on the policy. For example, the rating for a personal auto policy may include a good driver discount that does not
take effect until a driving safety course has been completed. The course is not completed when the policy is bound.
Later, the course is completed and the discount must then be applied.
When situations like this occur, these outstanding issues can be managed through contingencies. A contingency is an
object that identifies an issue affecting a job or policy that must be resolved by a particular date. Depending on the
outcome, the insurer may opt to change or cancel the policy. Contingencies can have associated activities, documents,
and notes.
Cloud API provides a set of endpoints for managing contingencies. These endpoints exist in both the Job API and the
Policy API. For more information, see “Contingencies” on page 339.

Referral reasons
While a policy is in force, an insurer may become aware of information that has implications for the policy's renewal.
This information may require underwriter approval, but at the time the renewal has not yet been started. Because there
is no active job, the information cannot be captured as an underwriting issue.
To address these situations, PolicyCenter provides referral reasons. Like underwriting issues, a referral reason is an
object that tracks an issue that may require underwriter review. However, referral reasons are attached only to bound
policies. The next time a job is created for the policy, the referral reason may trigger the creation of an underwriting
issue.
Cloud API provides a set of endpoints for managing referral reasons. These endpoints exist in the Policy API. For more
information, see “Referral reasons” on page 415.

Managing bound policies 189

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

190 Managing bound policies

part 4

Business flows: Job types

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in PolicyCenter so that caller
applications can request data from or initiate action within PolicyCenter.
The following topics discuss how caller applications can manage specific types of jobs (also known as policy
transactions) within PolicyCenter. This includes:
• Submissions
• Renewals
• Audits
• Policy changes
• Cancellations
• Reinstatements
• Rewrites (including rewrite new account jobs)

Business flows: Job types 191

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

192 Business flows: Job types

chapter 17

Submissions

A submission is a policy transaction that creates a new policy. This topic covers how to create submissions through
Cloud API.
For details on the business functionality of submissions, see the Application Guide.

Overview of policy transaction management

Work with policy transactions typically involves endpoints from two different APIs:
• The Policy API, which has endpoints to:
◦ Initiate all types of policy transactions except for submissions
• The Job API, which has endpoints to:
◦ Initiate submissions
◦ Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
◦ Quote jobs
◦ Bind and issue jobs, or withdraw jobs
◦ Work with objects owned by jobs, such as activities and underwriting issues
Conceptually, a policy transaction is completed in four steps:
1. Initiate the policy transaction.
• This creates a new Job element whose status is "Draft".
2. Modify the job as needed.
• The status remains "Draft".
3. Quote the job.
a. The rating engine or rating service generates a quote for the job.
b. The status advances to "Quoted".
c. The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous
step. In other words, the status reverts to "Draft" and the job must be later requoted.
4. Complete the job.
a. This can be done by binding the job or by withdrawing or canceling the job.
b. The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.
Submissions 193
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Initiating a submission
Before you can create a new submission, the account that will own the submission must exist. For information on
creating accounts, see “Creating an account” on page 147.
Use the following endpoint to create a submission:
• POST /job/v1/submissions

Minimum creation criteria

At a minimum, the request payload must include the following information:
• The account
• The baseState
◦ This is the jurisdiction of the primary location of the account
◦ This must be set to a value from the Jurisdiction typelist
• The jobEffectiveDate
• The producerCode
• The product
◦ This specifies the type of policy the submission will create, such as a Personal Auto policy

Retrieving product ids

For submissions, the product attribute must be set to the ID of the product.
You can determine the ID through Advanced Product Designer. This value appears in the product's Identifier field.
You can also use the following endpoint from the Product Definition API to retrieve information about all available
products, including their product IDs.
• GET productdefinition/v1/products

Example of POSTing a submission

For example, the following request payload creates a new Personal Auto submission for account pc:401 with a base
state of California, a job effective date of August 1, 2022, and a producer code pc:16.

POST /job/v1/submissions

{
"data": {
"attributes": {
"account": {
"id": "pc:401"
},
"baseState": {
"code": "CA"
},
"jobEffectiveDate": "2022-08-01",
"producerCode": {
"id": "pc:16"
},
"product": {
"id": "PersonalAuto"
}
}
}
}

This new job instance has a job type of "Submission" and a status of "Draft". For the purposes of the following
examples, assume that the ID of this job is pc:4040.

194 Submissions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Modifying the submission

Modifying a submission job is the process of adding the content that is required to accurately reflect the desired policy.
For more information on how to modify a policy within the context of a job, see “Overview of modifying jobs” on
page 241.
Typically, multiple calls are needed to specify all of the required information. For submissions, you can combine
multiple calls into a single request using composite requests. For more information on composite requests, see
“Composite requests” on page 97.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see “Composite request submission example for Personal Auto” on page 200.

Risk analysis information

PolicyCenter gathers information that an underwriter can use to process a job, such as a submission. In the user
interface, this information is referred to as Risk Analysis information. This includes the following:
• Loss history - This is a list of prior losses that have been incurred by the insured. This information can be edited
during a submission or outside of the context of a job. For more information, see “Loss history” on page 181.
• Prior policies - This is a list of policies that the insured has had prior to this policy. They could be policies with the
insurer or with other insurers. This information can be edited during a submission or outside of the context of a job.
For more information, see “Prior policies” on page 179.

Quoting the submission

To quote a job (such as a submission), use the following endpoint:
• POST /job/v1/jobs/{jobId}/quote
The request object does not require a request body.
For example, the following request quotes job pc:4040:

POST /job/v1/jobs/pc:4040/quote

<no request body>

If the job lacks all the information required for rating, the call fails. For example, for the base configuration Personal
Auto product, a submission will fail if you specify a covered vehicle, but you do not specify a driver for the vehicle.
If the call succeeds, a quote is generated for the job. The status of the job is advanced to "Quoted".

Editing a quoted job

You can make further edits to the job. However, this cannot be done while the job's status is "Quoted". To make edits,
you must call the POST /job/v1/jobs/{jobId}/make-draft endpoint, which reverts the job's status to "Draft".
For example, the following request moves the quoted job pc:4040 back to a draft state:

POST /job/v1/jobs/pc:4040/make-draft

<no request body>

Additional quoting features

Cloud API has access to additional PolicyCenter quoting functionality. This includes:
• Retrieving payment information
• Generating multiple "side-by-side" quotes for a single job
• Overriding rating
For additional information, see “Quoting” on page 379.

Submissions 195
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Completing the submission

A submission can be completed in one of several ways.

Binding and issuing a submission at the same time

If the insurer and account holder agree upon the quote, the policy can be bound and issued.
• Binding refers to the act of both parties agreeing to the policy and making it a legally binding contract.
• Issuing refers to the act of printing and sending the documents that define the policy.
These actions are typically done at the same time, but they can be done separately.
Use the following endpoint to simultaneously bind and issue a policy:
• POST /job/v1/jobs/{jobId}/bind-and-issue
The request object does not require a request body.
For example, the following request binds and issues job pc:4040.

POST /job/v1/jobs/pc:4040/bind-and-issue

<no request body>

The submission's status is changed to "Bound".

Binding a submission without issuing

In some situations, an insurer and account holder may agree to bind a policy, even though all information about the
policy has not yet been collected. For example, a shipping business who is interested in a commercial auto policy may
need to provide the vehicle identification numbers for a fleet of several hundred trucks. This information is needed to
issue the policy, but it will take several weeks to provide it. The insurer agrees to bind the policy now, but to not issue
the policy until after the vehicle identification numbers have been received.
Use the following endpoint to bind a policy without issuing it:
• POST /job/v1/jobs/{jobId}/bind-only
The request object does not require a body.
For example, the following request binds job pc:4040 without issuing it.

POST /job/v1/jobs/pc:4040/bind-only

<no request body>

The submission's status is changed to "Bound".

Identifying a policy is bound but not issued

There is no flag on the Policy entity that directly identifies a policy is bound but not issued. You can identify a policy
is bound but not issued in the following ways:
• In the PolicyCenter user interface, the policy has an "Issuance Policy" menu item in the Actions menu.
• From Cloud API, any call that returns a policy as the root resource includes an issue link in the links section. This
includes GET, POST, and PATCH calls.

Issuing a previously bound policy

Issuance refers to the action of issuing a policy that was previously bound but unissued. From a technical standpoint,
issuance is a policy transaction.

196 Submissions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Issuance does not involve the original submission job. That job is considered to be concluded when the policy was
bound.
• Similar to policy change and renewal:
◦ Issuance jobs are created from the policy.
◦ Issuance jobs can modify the policy contents.
◦ Issuance jobs must be quoted and completed.
To issue a previously bound policy, you must:
1. Initiate the issuance job from the policy.
2. Modify the job as needed. This could involve specifying information that was not available when the policy was
bound.
3. Quote the issuance job.
4. Complete the issuance job.

Initiate the issuance job

Use the following endpoint to issue a previously bound but unissued policy. Note that this endpoint is in the Policy API
and is executed from the policy:
• POST /policy/v1/policies/{policyId}/issue
The request object requires an empty request body.
For example, the following creates an issuance job for policy pc:919.

POST /job/v1/jobs/pc:919/issue

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

This creates a new job instance whose job type is "Issuance" and whose status is "Draft". For the purposes of the
following examples, assume that the ID of this job is pc:8808.

Modify the issuance job as needed

To modify the job, use the Job API endpoints to specify information as if it were part of the original submission.

Quote the issuance job

To quote the issuance job, use the following endpoint:
• POST /job/v1/jobs/{jobId}/quote
The request object does not require a body.
For example, the following request quotes job pc:8808:

POST /job/v1/jobs/pc:8808/quote

<no request body>

If the quote at issuance is different than the quote when bound, this typically triggers an additional billing request to
either charge for or credit the difference.

Complete the issuance job

There is no /issue-only endpoint. To successfully complete an issuance job, you must use the /bind-and-issue
endpoint.

Submissions 197
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following request binds and issues issuance job pc:8808.

POST /job/v1/jobs/pc:8808/bind-and-issue

<no request body>

You can also withdraw the issuance job. For example, this might be appropriate if the issuance included significantly
erroneous information. To withdraw an issuance job, use the following endpoint:
• POST /job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:4040.

POST /job/v1/jobs/pc:8808/withdraw

<no request body>

Withdrawing and rejecting submissions

There are several ways a submission can end without becoming a policy:
• Withdraw - The submission is abandoned before a final decision is made. (For example, there could be a
significant error in the submission.)
• Decline - The submission is rejected by the insurer.
• Not Taken - The submission is rejected by the account holder.

Withdrawing a submission
Use the following endpoint to withdraw a submission:
• POST /job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:4040.

POST /job/v1/jobs/pc:4040/withdraw

<no request body>

The submission's status is changed to "Withdrawn".

Declining a submission
Use the following endpoint to decline a submission:
• POST /job/v1/jobs/{jobId}/decline
You must specify a rejectReason in the request body.
For example, the following request declines job pc:4040.

POST /job/v1/jobs/pc:4040/withdraw

{
"data": {
"attributes": {
"rejectReason": {
"code": "PaymentHistory"
}
}
}
}

The submission's status is changed to "Declined".

198 Submissions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Not taking a submission

Use the following endpoint to indicate a submission was not taken:
• POST /job/v1/jobs/{jobId}/not-take
You must specify a rejectReason in the request body.
For example, the following request indicates that job pc:4040 was not taken.

POST /job/v1/jobs/pc:4040/not-take

{
"data": {
"attributes": {
"rejectReason": {
"code": "nottaken"
}
}
}
}

The submission's status is changed to "Not taken".

Copying submissions
You can create a new submission by copying an existing submission. The submission can be unbound or bound. You
can also create a copy from a bound policy, in which case the submission used to create the policy is the one that is
copied.
To copy a submission, use one of the following endpoints:

Endpoint Source submission

POST /job/v1/jobs/{jobId}/copy-submission The specified submission
POST /policy/v1/policies/{jobId}/copy-submission The submission used to create the specified policy

The request does not require a body.

The copied submission is always in a draft state, regardless of the status of the source submission. Also, any pre-
qualification status or underwriter approvals do not get copied.
For example, the following creates a copy of submission job pc:4100.

POST /job/v1/jobs/pc:4100/copy-submission

<no request body>

Copying a multi-version submission

A job can have multiple versions. For more information on multi-version jobs, see “Multi-version quoting” on page
381.
If a job is multi-versioned, there is always only one selected version. By default, when you execute a copy-submission
on a multi-versioned job, the selected submission is used as the source submission. You can make a copy of a non-
selected version. To do this, you must include the jobVersion query parameter in the call, and you must specify the ID
of the desired version.
For example, suppose job pc:4100 has two versions. The IDs for the versions are pc:61 (the selected version) and pc:
62.
The following call creates a copy of version pc:61. This is because the call specifies no version, and pc:61 is the
selected version.

POST /job/v1/jobs/pc:4100/copy-submission

<no request body>

Submissions 199
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following call creates a copy of version pc:62.

POST /job/v1/jobs/pc:4100/copy-submission?jobVersion=pc:62

<no request body>

The jobVersion query parameter is available only on the Job API version of /copy-submission. It is not available on
the Policy API version of /copy-submission.

Additional features for submissions

PolicyCenter includes several features that can be used to manage multiple types of jobs, including submissions. The
following table summarizes these feature.

Feature Description More information

Contingencies An object that identifies an issue affecting a job or policy that must “Contingencies” on page 339
be resolved by a particular date.
Job locks A lock that indicates that there are associated underwriting issues “Job locks” on page 413
to review and that the job ought to remain unchanged while the
issues are resolved
Job search A search for all jobs that meet a given set of criteria “Job search” on page 351
Multi-version quoting The ability to create and compare multiple quotes for a single job “Multi-version quoting” on page
381
Out-of-sequence A conflict that occurs with two jobs for the same policy where job 2 “Out-of-sequence conflicts” on
conflicts has a transaction date later than job 1, but an effective date earlier page 353
than job 1.
Rating overrides The ability to override a specific Cost for a specific quote “Rating overrides” on page 383
Underwriting issues An object attached to a job or policy that tracks an issue that may “Underwriting issues” on page 407
require underwriter review

Composite request submission example for Personal Auto

The following is an example of a single composite request that creates an account and creates and quotes a Personal
Auto submission using the base configuration Personal Auto line of business.
Note: This example assumes you have generated the LOB-specific endpoints for the base configuration
Personal Auto line of business. It will not work in PolicyCenter if you have not yet generated LOB-specific
endpoints for the base configuration Personal Auto line of business. For more information on how to do this,
see the Cloud API Developer Guide.
The composite request does the following:
1. Creates a new account.
2. Create a Personal Auto submission for the account.
3. Answers the question "Is the applicant currently insured" with "No - New Driver" (newdriver).
4. Adds a line-level optional coverage (PALossOfUseCov).
5. Adds a vehicle.
6. Adds an optional coverage (PARentalCov) to the vehicle, and specifies the 20 dollars/day for 60 days (60/20)
coverage term.
7. Specifies contact information that is required for quoting (such as date of birth and number of accidents).
8. Specifies vehicle driver information (percent of time the contact driver the vehicle).
9. Sets the Anti-Lock Breaks Discount modifier to true.

200 Submissions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

10. Quotes the job.

{
"requests": [
{
"method": "post",
"uri": "/account/v1/accounts",
"body": {
"data": {
"attributes": {
"initialAccountHolder": {
"contactSubtype": "Person",
"firstName": "Tamsin",
"lastName": "Tester",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"initialPrimaryLocation": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"producerCodes": [
{
"id": "pc:16"
}
],
"organizationType": {
"code": "other"
}
}
}
},
"vars": [
{
"name": "accountId",
"path": "$.data.attributes.id"
},
{
"name": "driverId",
"path": "$.data.attributes.accountHolder.id"
}
]
},
{
"method": "post",
"uri": "/job/v1/submissions",
"body": {
"data": {
"attributes": {
"account": {
"id": "${accountId}"
},
"baseState": {
"code": "CA"
},
"jobEffectiveDate": "2022-08-01",
"producerCode": {
"id": "pc:16"
},
"product": {
"id": "PersonalAuto"
}
}
}
},
"vars": [
{
"name": "jobId",
"path": "$.data.attributes.id"
}
]
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/questions",
"body": {
"data": {
"attributes": {
"answers": {

Submissions 201
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"PACurrentlyInsured": {
"choiceValue": {
"code": "newdriver"
}
}
}
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/coverages",
"body": {
"data": {
"attributes": {
"pattern": {
"id": "PALossOfUseCov"
}
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles",
"body": {
"data": {
"attributes": {
"make": "Toyota",
"model": "Tercel",
"modelYear": 2010,
"costNew": {
"amount": "33000",
"currency": "usd"
},
"licenseState": {
"code": "CA"
},
"vin": "14HEW8RLGMDSP03AA"
}
}
},
"vars": [
{
"name": "vehicleId",
"path": "$.data.attributes.id"
}
]
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles/${vehicleId}/coverages",
"body": {
"data": {
"attributes": {
"pattern": {
"id": "PARentalCov"
},
"terms": {
"PARental": {
"choiceValue": {
"code": "60/20"
}
}
}
}
}
}
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/contacts/${driverId}",
"body": {
"data": {
"attributes": {
"dateOfBirth": "1980-10-10",
"licenseNumber": "CA7732839",
"licenseState": {
"code": "CA"
},
"numberOfAccidents": {
"code": "0"
},
"numberOfViolations": {
"code": "0"
},
"policyNumberOfAccidents": {
"code": "0"
},

202 Submissions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"policyNumberOfViolations": {
"code": "0"
}
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles/${vehicleId}/drivers",
"body": {
"data": {
"attributes": {
"percentageDriven": 100,
"policyDriver": {
"id": "${driverId}"
}
}
}
}
},
{
"method": "patch",
"uri": "/job/v1/jobs/${jobId}/lines/PersonalAutoLine/vehicles/${vehicleId}/modifiers/PAAntiLockBrakes",
"body": {
"data": {
"attributes": {
"booleanModifier": true
}
}
}
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/quote"
}
]
}

Submissions 203
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

204 Submissions
chapter 18

Renewals

A renewal is a policy transaction that creates a new term for an existing policy at the end of the latest term. This topic
covers how to manage renewals through Cloud API.
For details on the business functionality of renewals, see the Application Guide.

Overview of policy transaction management

Work with policy transactions typically involves endpoints from two different APIs:
• The Policy API, which has endpoints to:
◦ Initiate all types of policy transactions except for submissions
• The Job API, which has endpoints to:
◦ Initiate submissions
◦ Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
◦ Quote jobs
◦ Bind and issue jobs, or withdraw jobs
◦ Work with objects owned by jobs, such as activities and underwriting issues
Conceptually, a policy transaction is completed in four steps:
1. Initiate the policy transaction.
• This creates a new Job element whose status is "Draft".
2. Modify the job as needed.
• The status remains "Draft".
3. Quote the job.
a. The rating engine or rating service generates a quote for the job.
b. The status advances to "Quoted".
c. The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous
step. In other words, the status reverts to "Draft" and the job must be later requoted.
4. Complete the job.
a. This can be done by binding the job or by withdrawing or canceling the job.
Renewals 205
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

b. The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.

Initiating a renewal
Renewals are initiated from the policy itself. Use the following endpoint to create a renewal for a given policy:
• POST /policy/v1/policies/{policyId}/renew
The request requires an empty body (a body with no specified attributes).
For example, the following initiates a renewal for policy pc:44.

POST /policy/v1/policies/pc:44/renew

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

This call creates a new job instance whose job type is "Renewal".

Actions PolicyCenter takes when a renewal is initiated

PolicyCenter manages renewals using workflows. A renewal workflow is a set of events to execute to process a
renewal. PolicyCenter has multiple types of renewal workflows to manage the different stages a renewal could be in
and the different outcomes as defined by any pre-renewal direction.
For some policies (such as policies with no material changes, pre-renewal direction, or underwriting issues), no further
action is required. PolicyCenter automatically binds the policy at the appropriate time.
For other policies, additional actions may be required. For example, the renewal may require material changes. In this
case, the renewal must be converted to a draft state, the changes must be made, and the renewal must be requoted.
Also, the renewal may have underwriting issues that block its progress. For these policies, it may be necessary to
modify, quote, and/or complete the renewal through the user interface or through Cloud API.

Pre-renewal directions
A policy can have a pre-renewal direction. A pre-renewal direction is a special note attached to a policy that provides
information on how to execute the policy's renewal job when the renewal job is initiated automatically.
For more information on how to set and clear pre-renewal directions, see “Pre-renewal directions” on page 186.

Modifying the renewal

Some policies may require modification at renewal time, such as policies for which coverages need to be added or
removed.

Moving a quoted renewal to a draft state

Some renewals, such as renewals with no pre-renewal direction, are automatically quoted. Before the job can be
changed, the renewal's job must be set to "Draft". To do this, use the POST /job/v1/jobs/{jobId}/make-draft
endpoint, which reverts the job's status to "Draft".
For example, the following request moves the quoted job pc:4040 back to a draft state:

POST /job/v1/jobs/pc:4040/make-draft

<no request body>

206 Renewals
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Modifying the renewal

The specific information added, removed, or changed in a draft renewal varies based on the lines of business associated
with the job's product. This information is specified using LOB-specific endpoints. For an overview of these endpoints,
see “Overview of modifying jobs” on page 241.
The following is an example of adding a "limited liability for Mexico" line-level liability coverage to job pc:4040,
which was moved to a draft state in the previous example.

PATCH /job/v1/jobs/pc:4040/lines/PersonalAutoLine/coverages

{
"data": {
"attributes": {
"pattern": {
"id": "PALimitedMexicoCov"
}
}
}
}

Risk analysis information

PolicyCenter gathers information that an underwriter can use to process a job, such as a renewal. In the user interface,
this information is referred to as Risk Analysis information. This includes the following:
• Loss history - This is a list of prior losses that have been incurred by the insured. This information can be edited
during a submission or outside of the context of a job. For more information, see “Loss history” on page 181.
• Prior policies - This is a list of policies that the insured has had prior to this policy. They could be policies with the
insurer or with other insurers. This information can be edited during a submission or outside of the context of a job.
For more information, see “Prior policies” on page 179.

Changes to a policy after a renewal is created

It is possible to start a policy change on a policy that already has a pending renewal. When the policy change is bound,
there is no requirement for those changes to be copied to the renewal. However, you can opt to copy the changes to the
renewal, either from the user interface or from Cloud API. For more information on applying changes to a renewal, see
“Applying changes to a renewal” on page 228.

Quoting the renewal

To quote a job (such as a renewal), use the following endpoint:
• POST /job/v1/jobs/{jobId}/quote
The request object does not require a request body.
For example, the following request quotes job pc:4040:
POST /job/v1/jobs/pc:4040/quote

<no request body>

If the job lacks all the information required for rating, the call fails. For example, for the base configuration Personal
Auto product, a submission will fail if you specify a covered vehicle, but you do not specify a driver for the vehicle.
If the call succeeds, a quote is generated for the job. The status of the job is advanced to "Quoted".

Additional quoting capabilities

Cloud API has access to additional PolicyCenter quoting functionality. This includes:
• Retrieving payment information
• Generating multiple "side-by-side" quotes for a single job
• Overriding rating

Renewals 207
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For additional information, see “Quoting” on page 379.

Completing the renewal

The following table summarizes the different endpoints that can be used to complete a renewal.

Outcome Endpoint Action taken

Bind the renewal now /job/v1/jobs/{jobId}/ Issue the renewal immediately
bind-and-issue
Complete the job at a later date as /job/v1/jobs/{jobId}/ Change the policy period's status to renewing and start
a renewal pending-renew the PendingRenewalWF workflow
Complete the job at a later date as /job/v1/jobs/{jobId}/ Change the policy period's status to nonrenewing and
a non-renewal pending-non-renew start the PendingNonRenewalWF workflow
Complete the job at a later date as /job/v1/jobs/{jobId}/ Change the policy period's status to nottaking and start
a not taken pending-not-take the PendingNotTakenWF workflow
Withdraw the renewal /job/v1/jobs/{jobId}/ Withdraw the renewal
withdraw

Example of binding the renewal immediately

Use the following endpoint to bind a renewal immediately:
• POST /job/v1/jobs/{jobId}/bind-and-issue
The request object does not require a request body.
For example, the following request binds and issues job pc:333.

POST /job/v1/jobs/pc:333/bind-and-issue

<no request body>

The renewal's status is changed to "Bound".

Example of withdrawing a renewal

Use the following endpoint to withdraw the renewal:
• POST /job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:333.

POST /job/v1/jobs/pc:333/withdraw

<no request body>

The renewal's status is changed to "Withdrawn".

208 Renewals
chapter 19

Audits

PolicyCenter Cloud API includes endpoints that allow you to work with audits. Audits typically take place on policies
where the premium is based on estimated amounts that must later be replaced with actual amounts. An example of this
would be a Workers’ Comp policy where the premium can change based on the salaries of the covered workers.
PolicyCenter Cloud API supports two types of audits in the base configuration: final audit and premium report. Final
audit covers an entire policy term, while premium report covers specified time periods within a policy term.
Note:

Whether or not audits are available is dependent on LOB settings. In the base configuration, Workers’ Comp
and General Liability LOBs are set as auditable.
For complete details on audits, see Application Guide.

Audit policy definitions

Depending on your LOB configuration, audits might be scheduled automatically when you quote and bind your policy.
For example, you might create a Workers’ Comp policy that will have premium reports and a final audit scheduled for
the term of the policy. These audits are created based on an audit schedule pattern that defines audit properties such as
frequency of the premium reports (monthly, quarterly), and when audits begin and end. (See “Product definitions for
audit schedule patterns” on page 315 for information on retrieving audit schedule patterns.)

Audit policy vs audit job endpoints

Audits are accessible in Cloud API through the policy and job APIs. Audits are created with the policy API. Any
actions that take place on the audit between the time it’s created and the time a job is started are also done through the
policy API.
After an audit is started, there are a few actions that take place on the audit job, such as quoting and completing, and
therefore are done through the job API. However, most actions, including most updates to the audit, continue to be
done through the policy API. See the following sections for how and when to use the various endpoints in the policy
and job APIs:
• “Audit policy endpoints” on page 209
• “Audit job endpoints” on page 216

Audit policy endpoints

You can retrieve and update the details of audits, as well as create new audits, with the following endpoints:
Audits 209
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET /policy/v1/policies/{policyId}/audits
• GET /policy/v1/policies/{policyId}/audits/{auditId}
• POST /policy/v1/policies/{policyId}/audits
• PATCH /policy/v1/policies/{policyId}/audits/{auditId}
You can change the status of audit jobs with the following endpoints:
• POST /policy/v1/policies/{policyId}/audits/{auditId}/start
• POST /policy/v1/policies/{policyId}/audits/{auditId}/reverse
• POST /policy/v1/policies/{policyId}/audits/{auditId}/revise
• POST /policy/v1/policies/{policyId}/audits/{auditId}/waive

Retrieve audit details

Use the following endpoints to retrieve detailed information on audits for a policy:
• GET /policy/v1/policies/{policyId}/audits
• GET /policy/v1/policies/{policyId}/audits/{auditId}
This example retrieves information about all audits on policy pc:101:
Command

GET /policy/v1/policies/pc:101/audits

Response

"attributes": {
"actualAuditMethod": {
"code": "Voluntary",
"name": "Voluntary"
},
"auditMethod": {
"code": "Voluntary",
"name": "Voluntary"
},
"auditPeriodEndDate": "2021-11-01T07:01:00.000Z",
"auditPeriodStartDate": "2021-10-11T07:01:00.000Z",
"auditScheduleType": {
"code": "PremiumReport",
"name": "Premium Report"
},
"dueDate": "2021-11-16T08:01:00.000Z",
"id": "pc:101",
"initDate": "2021-10-27T07:01:00.000Z",
"job": {
"displayName": "0002370929",
"id": "pc:SiCsb2XDZXigd2aGUldeT",
"type": "Job",
"uri": "/job/v1/jobs/pc:901"
},
"status": "In Progress"
},
...

Create an audit
Use this endpoint to create a new audit on a policy:
• POST /policy/v1/policies/{policyId}/audits
The following fields are required in the request:

Name Type Description

auditMethod AuditMethod TypeKey How the audit is conducted. In the base configuration, this can be one of
the following:

210 Audits
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Name Type Description

• Estimate
• Phone
• Physical
• Voluntary

auditScheduleType AuditScheduleType The type of audit. In the base configuration this is either PremiumReport
TypeKey or FinalAudit. (For the General Liability LOB, only FinalAudit is
available in the base configuration.)
If an audit of type FinalAudit exists on a policy with a state of
scheduled, in progress, or complete, another audit of type FinalAudit
cannot be created for the same policy term.

dueDate datetime The date the audit is due.

This value can default to a specific amount of time beyond the policy end
date, based on your configuration. See Configuration for more
information.

initDate datetime The date the audit process starts.

auditPeriodEndDate datetime Required when auditScheduleType is PremiumReport.

Cannot overlap with dates of an existing premium report on the policy,
and must fall within the coverage dates of the policy period.
For auditScheduleType FinalAudit, this field is read only. The value
defaults to the policy period end or cancellation date.

auditPeriodStartDate datetime Required when auditScheduleType is PremiumReport. Cannot

overlap with dates of an existing premium report on the policy, and must
fall within the coverage dates of the policy period.
For auditScheduleType FinalAudit, this field is read only. The value
defaults to the policy period start date.

The following example creates a premium report audit on policy pc:101.

Command

POST /policy/v1/policies/pc:101/audits

Request

{
"data": {
"attributes": {
"auditMethod": {
"code": "Voluntary"
},
"auditScheduleType": {
"code": "PremiumReport"
},
"dueDate": "2025-03-14",
"initDate": "2024-12-21",
"auditPeriodEndDate": "2025-07-02",
"auditPeriodStartDate": "2025-06-03"
}
}
}

Update audit details

You can update the details of an audit with the following endpoint:

Audits 211
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• PATCH /policy/v1/policies/{policyId}/audits/{auditId}
The attributes that can be updated differ based on whether the audit job has started. The following table lists attributes
that can be updated only when the job is in a certain state. Attributes not listed can be updated before or after the audit
job has started.

Attribute Not updatable, must be set on creation Updatable only before start Updatable only after start
auditMethod X
actualAuditMethod X
auditScheduleType X
auditPeriodEndDate X (Premium report only)

auditPeriodStartDate X (Premium report only)

auditFee X (Final audit only)

receivedDate X
paymentReceived X (Premium report only)

instructions X (Final audit only)

This example changes the due date (which can be updated before or after audit start) for audit pc:800 on policy pc:101
to August 15, 2024:
Command

POST /policy/v1/policies/pc:101/audits/pc:800

Request

{
"data": {
"attributes": {
"dueDate": "2024-08-15"
}
}
}

Start an audit
Audits start automatically on their initDate through a batch process. However, you can start the audit job prior to that
date with the following POST command:
• POST /policy/v1/policies/{policyId}/audits/{auditId}/start
This example starts audit pc:800 on policy pc:101. This command does not take a request body.
Command

POST /policy/v1/policies/pc:101/audits/pc:800/start

Response

{
"data": {
"attributes": {
"actualAuditMethod": {
"code": "Estimated",
"name": "Estimated"
},
"auditMethod": {
"code": "Estimated",
"name": "Estimated"
},
"auditPeriodEndDate": "2025-07-02T07:00:00.000Z",
"auditPeriodStartDate": "2025-06-03T07:00:00.000Z",

212 Audits
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"auditScheduleType": {
"code": "PremiumReport",
"name": "Premium Report"
},
"dueDate": "2025-03-14T07:00:00.000Z",
"id": "pc:800",
"initDate": "2024-01-17T22:39:36.392Z",
"job": {
"displayName": "0000053333",
"id": "pc:750",
"type": "Job",
"uri": "/job/v1/jobs/pc:750"
},
"status": "In Progress",
"waived": false
},
}

Reverse an audit
It’s possible that an audit can be completed, but then need to be redone. For example, if another job that changes the
policy (such as a cancellation or policy change) completes after the audit job has completed, the audit might need to be
reversed so the changes can be accounted for. For final audits a reversal is done automatically when the policy change
or cancellation takes place.
You can also manually reverse an audit, under the following conditions:
• Audit must be a premium report. Because final audits happen automatically, only premium report audits can be
manually reversed.
• Final audit for the policy must not be complete. If a final audit for the policy is complete, premium report audits can
no longer be reversed.
See Application Guide for more information on reversing audits.
Use the following endpoint to reverse an audit.
• POST /policy/v1/policies/{policyId}/audits/{auditId}/reverse
This endpoint does not take a request body.
This example reverses audit pc:850 on policy pc:101.
Command

POST /policy/v1/policies/pc:101/audits/pc:850/reverse

Response

{
"data": {
"attributes": {
"actualAuditMethod": {
"code": "Voluntary",
"name": "Voluntary"
},
"auditMethod": {
"code": "Voluntary",
"name": "Voluntary"
},
"auditPeriodEndDate": "2024-09-01T07:01:00.000Z",
"auditPeriodStartDate": "2024-08-01T07:01:00.000Z",
"auditScheduleType": {
"code": "PremiumReport",
"name": "Premium Report"
},
"dueDate": "2024-09-16T07:01:00.000Z",
"id": "pc:850",
"initDate": "2024-01-23T23:56:41.475Z",
"job": {
"displayName": "0000703318",
"id": "pc:750",
"type": "Job",
"uri": "/job/v1/jobs/pc:750"
},
"receivedDate": "2024-01-23T08:00:00.000Z",
"reversalDate": "2024-01-24T08:00:00.000Z",
"status": "Reversed",
"totalCost": {

Audits 213
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"amount": "30950.00",
"currency": "usd"
},
"transactionAmount": {
"amount": "0.00",
"currency": "usd"
},
"waived": false
},

Revise an audit
If an audit needs to be updated after it’s been completed, you can revise the audit. Only final audits can be revised.
See Application Guide for more information on revising audits.
• POST /policy/v1/policies/{policyId}/audits/{auditId}/revise
The following command places audit pc:850 on policy pc:101 in a Revised state. The command does not take a request
body.
Command

POST /policy/v1/policies/pc:101/audits/pc:850/revise

Response

{
"data": {
"attributes": {
"actualAuditMethod": {
"code": "Physical",
"name": "Physical"
},
"auditMethod": {
"code": "Physical",
"name": "Physical"
},
"auditPeriodEndDate": "2024-10-11T07:01:00.000Z",
"auditPeriodStartDate": "2023-10-11T07:01:00.000Z",
"auditScheduleType": {
"code": "FinalAudit",
"name": "Final Audit"
},
"dueDate": "2024-01-19T08:01:00.000Z",
"id": "pc:850",
"initDate": "2024-01-22T21:16:07.683Z",
"job": {
"displayName": "0000333796",
"id": "pc:901",
"type": "Job",
"uri": "/job/v1/jobs/pc:901"
},
"receivedDate": "2024-01-19T08:00:00.000Z",
"revisingAudit": {
"displayName": "PolicyAudit pc:855",
"id": "pc:855",
"type": "PolicyAudit",
"uri": "/policy/v1/policies/pc:101/audits/pc:855"
},
"status": "Revised",
"totalCost": {
"amount": "33339.00",
"currency": "usd"
},
"transactionAmount": {
"amount": "7577.00",
"currency": "usd"
},
"waived": false
},

There are a few things to take note of in the response.

Status
No audit information, such as dates or audit method, has been revised on this audit. There is no request body, so
nowhere to revise the information. The reason for this behavior is that PolicyCenter maintains an audit history. Instead

214 Audits
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

of revising the audit (in this case pc:850), the audit has been given a status of Revised and a duplicate - or revising -
audit has been created.

"status": "Revised"

Revising audit
To avoid losing audit history, audit pc:850 is not actually revised. Instead, revising the audit creates and starts a new
audit job. Information for identifying the new audit is in the revisingAudit object, while information on the newly
started job is in the job object. In this example the new audit is pc:855, and the audit job for audit pc:855 is pc:901:

"revisingAudit": {
"displayName": "PolicyAudit pc:855",
"id": "pc:855",
"type": "PolicyAudit",
"uri": "/policy/v1/policies/pc:101/audits/pc:pc855"
},
…
"job": {
"displayName": "0000333796",
"id": "pc:901",
"type": "Job",
"uri": "/job/v1/jobs/pc:901"
},

If you run a GET command on the revisingAudit uri, you’ll see the information for the new audit. Because the job
started automatically, this new audit has a status of In Progress, as shown here:
Command

GET /policy/v1/policies/pc:101/audits/pc:855

Response

{
"data": {
"attributes": {
"actualAuditMethod": {
"code": "Physical",
"name": "Physical"
},
"auditMethod": {
"code": "Physical",
"name": "Physical"
},
"auditPeriodEndDate": "2024-10-11T07:01:00.000Z",
"auditPeriodStartDate": "2023-10-11T07:01:00.000Z",
"auditScheduleType": {
"code": "FinalAudit",
"name": "Final Audit"
},
"dueDate": "2024-01-22T21:23:32.232Z",
"id": "pc:855",
"initDate": "2024-01-22T21:23:32.232Z",
"job": {
"displayName": "0000444563",
"id": "pc:901",
"type": "Job",
"uri": "/job/v1/jobs/pc:901"
},
"receivedDate": "2024-01-19T08:00:00.000Z",
"revisionType": {
"code": "Revision",
"name": "Revision"
},
"status": "In Progress",
"waived": false
},

To change the information in the revising audit, use the PATCH command described above in “Update audit details” on
page 211.

Audits 215
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Waive an audit
You cannot delete a scheduled audit. Instead, if an audit has been scheduled but is no longer needed, you can waive the
audit. You cannot waive an audit that has started. (However, you can waive the audit job on an audit that has started.
See “Waive an audit job” on page 216 for more information.)
• POST /policy/v1/policies/{policyId}/audits/{auditId}/waive
This endpoint does not take a request body.
An audit that has been waived cannot be started or updated.

Audit job endpoints

As with other job types (such as submissions), you can quote and withdraw an audit job. (See “Quoting the
submission” on page 195 and “Withdrawing and rejecting submissions” on page 198 for information on quoting and
withdrawing.) In addition, you can complete and waive an audit job.

Waive an audit job

If an audit has started but is no longer needed, you can waive the audit by using the following endpoint:
• POST /jobs/{jobId}/waive
Note: If you want to waive a job that has not been started, use the waive endpoint on the policy. See “Waive an
audit” on page 216 for more information.
This endpoint does not take a request body.

Withdraw an audit job

Withdrawing an audit job is similar to waiving, but withdraw is done only on audits that have been revised. (See
“Revise an audit” on page 214 for more information.) If an audit has been revised and then later it’s determined the
revision is not necessary, the job can be withdrawn.
Use the following endpoint to withdraw an audit job:
• POST /jobs/{jobId}/withdraw
This endpoint does not take a request body.

Quote an audit job

To quote an audit job, use the following endpoint:
• POST /jobs/{jobId}/quote
Before you quote an audit job, there might be information you need to add to the job based on the validation
requirements implemented by the LOB. In the base configuration for Workers’ Comp and General Liability you must
include an audited amount. In Workers’ Comp you must also include a received date. If you run the quote endpoint
without updating the required validation information, you’ll receive errors similar to the following:

{
"status": 400,
"errorCode": "gw.api.rest.exceptions.BadInputException",
"userMessage": "Entity validation errors block 'quote' action",
"details": [
{
"message": "All audited amounts must be filled in to calculate premiums.",
"properties": {
"type": "WorkersCompLine",
"url": "/job/v1/jobs/pc:901/lines/WorkersCompLine",
"severity": "error"
}
},
{
"message": "Received date must be specified.",
"properties": {
"type": "WorkersCompLine",

216 Audits
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"url": "/job/v1/jobs/pc:901/lines/WorkersCompLine",
"severity": "error"
}
}
]
}

This example demonstrates updating the required validation information for Workers’ Comp in the base configuration.
It walks through finding the covered employees for audit job pc:901, updating the audited amount and received date,
and quoting the job.
Retrieve covered employees
The audited amount is the payroll amount reported by the customer. The employees covered by the audited amount
could be in multiple jurisdictions. To update this value through the API, you need to find the covered employee
associated with the audit job and update the fields that represent the various jurisdictions.
Command

GET /jobs/pc:901/lines/WorkersCompLine/covered-employees

Response

{
"count": 1,
"data": [
{
"attributes": {
"addedDate": "2024-02-01T08:01:00.000Z",
"id": "401",
"ifAnyExposure": false,
"location": {
"displayName": "1: 2306 Market St., San Francisco, CA",
"id": "401",
"type": "PolicyLocation",
"uri": "/job/v1/jobs/pc:901/locations/401"
},
"removedDate": "2025-02-01T08:01:00.000Z",
"specialCov": {
"code": "stat",
"name": "State Act"
},
"splits": {
"1": {
"basisAmount": 35,
"endDate": "2025-02-01T08:01:00.000Z",
"numEmployees": 50,
"startDate": "2024-02-01T08:01:00.000Z"
}
}
},

Notice the splits property. If there were multiple jurisdictions on this audit, there would be multiple objects under the
splits property. In this case there is only one, so this next step updates the audited amount for that split for covered
employee 401.
Update audited amount
Command

PATCH /jobs/pc:901/lines/WorkersCompLine/covered-employees/401

Request

{
"data": {
"attributes": {
"splits": {
"1": {
"auditedAmount": 4000
}
}
}
}
}

Audits 217
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

...
"id": "401",
...
"splits": {
"1": {
"auditedAmount": 40,
"basisAmount": 35,
"endDate": "2025-02-01T08:01:00.000Z",
"numEmployees": 50,
"startDate": "2024-02-01T08:01:00.000Z"
}
...

Update received date

Next, update the date that the payment was received. The received date is the date payment was received from the
customer. You set the received date on the audit policy. This update is done on the audit policy, not the job.
Command

PATCH /policies/pc:101/audits/pc:855

Request

{
"data": {
"attributes": {
"receivedDate": "2024-05-15"
}
}
}

Quote the job

Now it’s time to quote the audit job. After the job is quoted you can no longer update it. To update the job, you must
return it to draft state. (See “Quoting the submission” on page 195 for more information.) This endpoint does not take a
request body.
Command

POST /jobs/pc:901/quote

Response

{
"data": {
"attributes": {
...
"id": "pc:901",
...
"jobStatus": {
"code": "Quoted",
"name": "Quoted"
},
"jobType": {
"code": "Audit",
"name": "Audit"
},
...
},

As you can see in the response, the job has now been quoted.

Complete an audit job

Audit jobs are not bound or issued. Instead, when the audit is over, the job must be marked as complete. You can set an
audit job to complete with the following endpoint:
• POST /jobs/{jobId}/complete
This endpoint does not take a request body.

218 Audits
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Command

POST /jobs/pc:901/complete

Response

...
"id": "pc:901",
...
"jobStatus": {
"code": "AuditComplete",
"name": "Completed"
},
"jobType": {
"code": "Audit",
"name": "Audit"
},
...

Audits 219
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

220 Audits
chapter 20

Policy changes

A policy change is a policy transaction that makes material changes to the policy prior to its expiration date. This topic
covers how to manage policy changes through Cloud API.
For details on the business functionality of renewals, see the Application Guide.

Overview of policy transaction management

Work with policy transactions typically involves endpoints from two different APIs:
• The Policy API, which has endpoints to:
◦ Initiate all types of policy transactions except for submissions
• The Job API, which has endpoints to:
◦ Initiate submissions
◦ Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
◦ Quote jobs
◦ Bind and issue jobs, or withdraw jobs
◦ Work with objects owned by jobs, such as activities and underwriting issues
Conceptually, a policy transaction is completed in four steps:
1. Initiate the policy transaction.
• This creates a new Job element whose status is "Draft".
2. Modify the job as needed.
• The status remains "Draft".
3. Quote the job.
a. The rating engine or rating service generates a quote for the job.
b. The status advances to "Quoted".
c. The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous
step. In other words, the status reverts to "Draft" and the job must be later requoted.
4. Complete the job.
a. This can be done by binding the job or by withdrawing or canceling the job.
Policy changes 221
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

b. The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.

Initiating a policy change

Policy changes are initiated from the policy itself. Use the following endpoint to create a policy change for a given
policy:
• POST /policy/v1/policies/{policyId}/change
You must specify a jobEffectiveDate for the policy change.
For example, the following initiates a policy change for policy pc:44 with an effective date of June 6, 2023.

POST /policy/v1/policies/pc:44/change

{
"data": {
"attributes": {
"jobEffectiveDate": "2023-06-06"
}
}
}

This call creates a new job instance whose job type is "PolicyChange".

Modifying the policy change

The specific information added, removed, or changed in a draft policy change varies based on the lines of business
associated with the job's product. This information is specified using LOB-specific endpoints. For an overview of these
endpoints, see “Overview of modifying jobs” on page 241.
The following is an example of adding a "limited liability for Mexico" line-level liability coverage to job pc:4040.

PATCH /job/v1/jobs/pc:4040/lines/PersonalAutoLine/coverages

{
"data": {
"attributes": {
"pattern": {
"id": "PALimitedMexicoCov"
}
}
}
}

Quoting the policy change

To quote a job (such as a policy change), use the following endpoint:
• POST /job/v1/jobs/{jobId}/quote
The request object does not require a request body.
For example, the following request quotes job pc:4040:
POST /job/v1/jobs/pc:4040/quote

<no request body>

If the job lacks all the information required for rating, the call fails. For example, for the base configuration Personal
Auto product, a submission will fail if you specify a covered vehicle, but you do not specify a driver for the vehicle.
If the call succeeds, a quote is generated for the job. The status of the job is advanced to "Quoted".

Additional quoting capabilities

Cloud API has access to additional PolicyCenter quoting functionality. This includes:

222 Policy changes

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Retrieving payment information

• Generating multiple "side-by-side" quotes for a single job
• Overriding rating
For additional information, see “Quoting” on page 379.

Completing the policy change

The following table summarizes the different endpoints that can be used to complete a policy change.

Outcome Endpoint Action taken

Bind the policy change now /job/v1/jobs/{jobId}/bind-and-issue Issue the policy change immediately
Withdraw the policy change /job/v1/jobs/{jobId}/withdrawn Withdraw the policy change

Example of binding the policy change

Use the following endpoint to bind the policy change:
• POST /job/v1/jobs/{jobId}/bind-and-issue
The request object does not require a request body.
For example, the following request binds and issues job pc:333.

POST /job/v1/jobs/pc:333/bind-and-issue

<no request body>

The renewal's status is changed to "Bound".

Example of withdrawing a policy change

Use the following endpoint to withdraw the policy change:
• POST /job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:333.

POST /job/v1/jobs/pc:333/withdraw

<no request body>

The renewal's status is changed to "Withdrawn".

Issues specific to policy changes

Changing producers
In the context of a policy change, you can change a policy's producer of service without changing the producer of
record. For more information, see “Policy producers” on page 170.

Preemptions
A preemption is an event that occurs when two or more jobs are created from the same base policy period. The first job
to be bound preempts the second job. If you want to continue with the second job, it must be modified to handle the
changes made by the first job. Preemptions occurs most commonly with policy changes.
For example, suppose that there is a bound personal auto policy with a single car. A policy change is started to add a
motorcycle to the policy. Then, while the first job is still in progress, a second policy change is started that adds a van

Policy changes 223

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

to the policy. The motorcycle job has no knowledge of the van, and the van job has no knowledge of the motorcycle. If
the motorcycle job is bound first, it will preempt the van job. The policy now has both a car and a motorcycle on it.
The van job was only aware of the car. Before the van policy change can be completed, it must be modified to include
the motorcycle.
PolicyCenter provides support for working with preemptions. PolicyCenter identifies when a job has been preempted.
It provides a list of information on the preempting job that is not present in the preempted job. It also provides "handle
preemption" functionality that copies information from the preempting job over to the preempted job. For more
information, see the Application Guide.
Similarly, Cloud API provides support for preemptions. For a preempted job, you can view information about the
preempting job and execute "handle preemption" functionality. Similarly, when a policy change is bound and there is
an existing renewal for the policy, you can apply changes from the policy change to the renewal.

Identifying that a job has been preempted

When a job has been preempted, attempts to bind the job fail. PolicyCenter returns a BadInputException similar to the
following:

"userMessage": "Cannot take action 'bind-and-issue'. See the details element for further
information.",
"details": [
{
"message": "Branch 7888143943, 12/07/2021, 06/07/2022, 0006260834 has preemptions."
}
]

You can view information about the preempting job. If you want to bind the current job, you must handle the
preemptions.

Viewing preemption information

Use the following endpoint to view information about a job's preemptions:
• GET /job/v1/jobs/{jobId}/preemptions
The /preemptions endpoint returns two main types of information:
• An array of job diffs
• Information about the preempting job

The diffs array

The diffs array identifies all of the changes between the base job and the preempting job. These are the changes that
are not in the preempted job but would need to be for the preempted job to be bindable.
Each member of the array identifies one difference between the base job and the preempting job. This includes the
object (entity), the label of the diff field (field), the base job value (existingValue) and the preempting job value
(changedValue). The following code shows the syntax of each job diff array member.

{
"changedValue": <value>,
"entity": {
"displayName": <display name>,
"id": <id>
},
"existingValue": <value>,
"field": <value>
}

The difference can pertain to the value of a single field. For example, the following payload indicates that on a Medical
Payments coverage object, the choiceTerm1 field in the base job was 5000, but the preempting job changed it to
15000.

{
"changedValue": "15,000",
"entity": {

224 Policy changes

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"displayName": "Medical Payments",

"id": "85"
},
"existingValue": "5,000",
"field": "choiceTerm1"
}

The difference can also pertain to the addition or removal of an object. When this occurs, a "√" is used to indicate the
object is present, and a "" (an empty string) is used to indicate the object is absent. For example, the following payload
indicates that a 2000 Honda Civic was not present in the base job but was present in the preempting job. (In other
words, the preempting job added a Honda Civic.)

{
"changedValue": "√",
"entity": {
"displayName": "2000 Honda Civic in California",
"id": "32"
},
"existingValue": "",
"field": "2000 Honda Civic in California"
},

The preempting job

The payload also includes information about the preempting job, including:
• The job itself
• The job's effective date
• The job number
• The job type

Preemption payload example

For example, suppose that there is a personal auto policy with an Acura Integra. At roughly the same time, two policy
changes are started:
• First policy change:
◦ Job number: 0004375724
◦ Job id: pc:421
◦ Effective date: 11/05/2021
◦ Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
• Second policy change:
◦ Job number: 0004408964
◦ Job id: pc:505
◦ Effective date: 11/06/2021
◦ Material changes: Adds a Toyota Prius and associated coverages for driver Alicia Shirley
The first policy change is bound, causing that job to preempt the second job. As a result, the second job now has a
preemption.
The following shows a portion of the response payload for a GET /preemptions for job pc:505. Note that the array of
diffs in the payload contains the following information.
• The effective date for the preempting job
• The vehicle for the preempting job
• The vehicle's collision coverage for the preempting job
• The vehicle's comprehensive coverage for the preempting job
• The vehicle driver for the preempting job

Policy changes 225

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The payload also contains information about the preempting job.

GET /job/v1/jobs/pc:505/preemptions

{
"count": 1,
"data": [
{
"attributes": {
"diffs": [
{
"changedValue": "11/05/2021",
"entity": {
"displayName": "4509454228, 11/04/2021, 05/04/2022, 0004375724",
"id": "pc:421",
"type": "Job",
"uri": "/job/v1/jobs/pc:421"
},
"existingValue": "11/04/2021",
"field": "writtenDate"
},
{
"changedValue": "√",
"entity": {
"displayName": "2000 Honda Civic in California",
"id": "32"
},
"existingValue": "",
"field": "2000 Honda Civic in California"
},
{
"changedValue": "√",
"entity": {
"displayName": "Collision",
"id": "64"
},
"existingValue": "",
"field": "Collision"
},
{
"changedValue": "√",
"entity": {
"displayName": "Comprehensive",
"id": "63"
},
"existingValue": "",
"field": "Comprehensive"
},
{
"changedValue": "√",
"entity": {
"displayName": "Alicia Shirley",
"id": "15"
},
"existingValue": "",
"field": "Assigned Driver: Alicia Shirley"
}
],
"job": {
"displayName": "0004375724",
"id": "pc:421",
"type": "Job",
"uri": "/job/v1/jobs/pc:421"
},
"jobEffectiveDate": "2021-11-05T00:01:00.000Z",
"jobNumber": "0004375724",
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
},
...

Handling preemptions
Once a job has been preempted, it can no longer be bound in its current state. This is because the base policy period has
been modified by the preempting job, and the preempted job is now missing information present in the base policy
period.
PolicyCenter provides the ability to handle preemptions. This is an action you can take on a preempted job to copy
over the changes made by the preempting job. Handling a preemption brings a preempted job in line with the new
version of the base period. Once you have handled preemptions for a job, you can bind it.

226 Policy changes

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

To handle preemptions through Cloud API, use the following endpoint:

• POST /job/v1/jobs/{jobId}/handle-preemptions
You do not need to provide a request body.
Typically, handling a preemption modifies the contents of a job. Therefore, you need to quote the job prior to binding
it, even if you quoted the job prior to the preemption.

Example of handling preemptions

In the previous topic, there was an example of a personal auto policy with an Acura Integra. At roughly the same time,
two policy changes are started:
• First policy change:
◦ Job number: 0004375724
◦ Job id: pc:421
◦ Effective date: 11/05/2021
◦ Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
• Second policy change:
◦ Job number: 0004408964
◦ Job id: pc:505
◦ Effective date: 11/06/2021
◦ Material changes: Adds a Toyota Prius and associated coverages for driver Alicia Shirley
The first policy change is bound, causing that job to preempt the second job. As a result, the second job now has a
preemption.
Now, suppose you want to handle preemptions for the second job and then bind it. (For clarity sake, portions of the
response payload have been omitted in the following examples.)
First, you must handle preemptions.
POST /job/v1/jobs/pc:505/handle-preemptions

<no request body>

RESPONSE:
{
"data": {
"attributes": {
"job": {
"id": "pc:505",
"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
}
}
}
}

Next, you must quote the job.

POST /job/v1/jobs/pc:505/quote

<no request body>

RESPONSE:
{
"data": {
"attributes": {
"id": "pc:505",

Policy changes 227

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Quoted",
"name": "Quoted"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
},
"taxesAndSurcharges": {
"amount": "94.00",
"currency": "usd"
},
"totalCost": {
"amount": "1396.00",
"currency": "usd"
},
"totalPremium": {
"amount": "1302.00",
"currency": "usd"
}
}
}
}

Finally, you can bind and issue the job.

POST /job/v1/jobs/pc:505/bind-and-issue

<no request body>

RESPONSE:
{
"data": {
"attributes": {
"id": "pc:505",
"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Bound",
"name": "Bound"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
}
}
}

Applying changes to a renewal

It is possible for a policy change to preempt a future renewal whose state is either draft or bound. When the policy
change is bound, the user interface provides the option of applying the changes in the preempting job to the renewal.
This is similar to "handle preemption" functionality, but there are differences:
• The copying of information is initiated from the preempting job, not the preempted job.
• The copying of information is optional. If you choose to not copy the information, you can still bind the renewal.
To apply changes from a policy change to a renewal through Cloud API, use the following endpoint:
• POST /job/v1/jobs/{jobId}/apply-changes-to-renewal
You do not need to provide a request body.
Once the changes are applied to the renewal, you need to quote (or requote) the renewal before it can be bound.

Identifying when a renewal exists

When you execute a policy change from the PolicyCenter user interface, there is a button that identifies a renewal
exists. This button gives you the option to copy changes to the renewal.
When you execute a policy change from Cloud API, you can identify whether there is an existing renewal by checking
the links array of the response payload. If there is an apply-changes-to-renewal member, the job's policy has a
renewal and you may want to consider applying the policy changes to that renewal.

228 Policy changes

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following response payload snippet contains an apply-changes-to-renewal member, indicating the
changed policy has a renewal.
"links": {
..
"activity-patterns": {
"href": "/job/v1/jobs/pc:232/activity-patterns",
"methods": [
"get"
]
},
"apply-changes-to-renewal": {
"href": "/job/v1/jobs/pc:232/apply-changes-to-renewal",
"methods": [
"post"
]
},
"contacts": {
"href": "/job/v1/jobs/pc:232/contacts",
"methods": [
"get"
]
},
...

Policy changes 229

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

230 Policy changes

chapter 21

Cancellations and reinstatements

A cancellation is a policy transaction that terminates an existing policy prior to its expiration date. A reinstatement is a
policy transaction that reinstates a previously canceled policy. This topic covers how to manage cancellations and
reinstatements through Cloud API.
For details on the business functionality of cancellations and reinstatements, see the Application Guide.

Overview of policy transaction management

Work with policy transactions typically involves endpoints from two different APIs:
• The Policy API, which has endpoints to:
◦ Initiate all types of policy transactions except for submissions
• The Job API, which has endpoints to:
◦ Initiate submissions
◦ Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
◦ Quote jobs
◦ Bind and issue jobs, or withdraw jobs
◦ Work with objects owned by jobs, such as activities and underwriting issues
Conceptually, a policy transaction is completed in four steps:
1. Initiate the policy transaction.
• This creates a new Job element whose status is "Draft".
2. Modify the job as needed.
• The status remains "Draft".
3. Quote the job.
a. The rating engine or rating service generates a quote for the job.
b. The status advances to "Quoted".
c. The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous
step. In other words, the status reverts to "Draft" and the job must be later requoted.
4. Complete the job.

Cancellations and reinstatements 231

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

a. This can be done by binding the job or by withdrawing or canceling the job.
b. The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.

Cancellations
A cancellation is a policy transaction that terminates an existing policy prior to its expiration date. This topic covers
how to manage cancellations through Cloud API.
For details on the business functionality of cancellations, see the Application Guide.

Initiating a cancellation
Cancellations are initiated from the policy itself. Use the following endpoint to create a cancellation for a given policy:
• POST /policy/v1/policies/{policyId}/cancel
You must specify the following fields:
• cancellationReasonCode: A typecode from the ReasonCode typelist
• cancellationSource: A typecode from the CancellationSource typelist
• jobEffectiveDate: A date
For example, the following initiates a cancellation for policy pc:44.

POST /policy/v1/policies/pc:44/cancel

{
"data": {
"attributes": {
"cancellationReasonCode": {
"code": "cancel"
},
"cancellationSource": {
"code": "carrier"
},
"jobEffectiveDate": "2020-08-15"
}
}
}

This call creates a new job instance whose job type is "Cancellation". The job's state is Quoted.

Modifying and requoting the cancellation

Typically, a policy is not modified when it is canceled. The most common intent of a cancellation is to cancel the
policy in its current state.
However, it is technically possible to modify the contents of a policy within a cancellation prior to binding the
cancellation.
• Before the job can be changed, the renewal's job must be set to "Draft". To do this, use the POST /job/v1/jobs/
{jobId}/make-draft endpoint, which reverts the job's status to "Draft".
• Once the job has been changed, it must be requoted. To do this, use the POST /job/v1/jobs/{jobId}/quote
endpoint.

Completing the cancellation

The following table summarizes the different endpoints that can be used to complete a cancellation.

Outcome Endpoint
Cancel the policy now /job/v1/jobs/{jobId}/bind-and-issue
Schedule a cancellation for a future date /job/v1/jobs/{jobId}/pending-cancel

232 Cancellations and reinstatements

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Outcome Endpoint
Change the process date for a scheduled cancellation /job/v1/jobs/{jobId}/reschedule
Rescind a scheduled cancellation /job/v1/jobs/{jobId}/rescind
Withdraw the cancellation /job/v1/jobs/{jobId}/withdraw

Example of binding the cancellation immediately

Use the following endpoint to bind a cancellation immediately:
• POST /job/v1/jobs/{jobId}/bind-and-issue
The request object does not require a request body.
For example, the following request binds and issues job pc:333.

POST /job/v1/jobs/pc:333/bind-and-issue

<no request body>

The cancellation's status is changed to "Bound".

Example of withdrawing a cancellation

Use the following endpoint to withdraw the cancellation:
• POST /job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:333.

POST /job/v1/jobs/pc:333/withdraw

<no request body>

The cancellation's status is changed to "Withdrawn".

Reinstatements
A reinstatement is a policy transaction that reinstates a previously canceled policy. This topic covers how to manage
cancellations through Cloud API.
For details on the business functionality reinstatements, see the Application Guide.

Initiating a reinstatement
Reinstatements are initiated from the policy itself. Reinstatements can be initiated only from canceled policies.
Use the following endpoint to create a reinstatement for a given canceled policy:
• POST /policy/v1/policies/{policyId}/reinstate
You must specify the following fields:
• reinstateCode: A typecode from the ReinstateCode typelist
For example, the following initiates a reinstatement for policy pc:44.

POST /policy/v1/policies/pc:44/reinstate

{
"data": {
"attributes": {
"reinstateCode": {
"code": "payment"
}

Cancellations and reinstatements 233

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}
}

This call creates a new job instance whose job type is "Reinstatement". The job's state is Draft. The reinstatement's
jobEffectiveDate is automatically set to the job effective date of the corresponding cancellation.

Modifying and quoting the reinstatement

Typically, a policy is not modified when it is reinstated. The most common intent of a reinstatement is to reinstate the
policy in the state it was in when it was canceled.
However, it is necessary to quote the reinstatement. This is because additional charges may have been added as a result
of the reinstatement, such as a reinstatement fee. To quote the reinstatement, use the POST /job/v1/jobs/{jobId}/
quote endpoint. The request object does not require a request body.

For example, the following request quotes job pc:4040:

POST /job/v1/jobs/pc:4040/quote

<no request body>

Completing the reinstatement

The following table summarizes the different endpoints that can be used to complete a reinstatement.

Outcome Endpoint
Reinstate the policy /job/v1/jobs/{jobId}/bind-and-issue
Withdraw the reinstatement /job/v1/jobs/{jobId}/withdraw

Example of binding the reinstatement

Use the following endpoint to bind a reinstatement:
• POST /job/v1/jobs/{jobId}/bind-and-issue
The request object does not require a request body.
For example, the following request binds and issues job pc:333.

POST /job/v1/jobs/pc:333/bind-and-issue

<no request body>

The reinstatement's status is changed to "Bound".

Example of withdrawing the reinstatement

Use the following endpoint to withdraw the reinstatement:
• POST /job/v1/jobs/{jobId}/withdraw
The request object does not require a body.
For example, the following request withdraws job pc:333.

POST /job/v1/jobs/pc:333/withdraw

<no request body>

The reinstatement's status is changed to "Withdrawn".

234 Cancellations and reinstatements

chapter 22

Rewrite and Rewrite New Account

A rewrite is a policy transaction that creates a new policy from an existing policy. Typically, a rewrite is done when
some significant error occurred during the initial submission of policy. The original policy does not reflect the original
intent of policy, and a new set of policy documents showing correct information is required.
A rewrite new account is a policy transaction that takes data from an existing policy and creates a new policy with a
new policy number in new account. Rewriting a policy to another account means moving the policy going forward to
another account, but the policy history including earlier policy terms stay with its current account.
This topic covers how to manage rewrites through Cloud API. For details on the business functionality of rewrites, see
the Application Guide.
There are three types of policy transaction rewrites:
• Full term rewrite: Overwrites the entire term of an existing policy
• New term rewrite: Creates a new term for the policy
• Mid-term rewrite: Rewrites the remainder of an existing policy term
The full term and new term policy rewrites are called flat rewrites.
With the system APIs, a policy rewrite transaction is preceded by a cancellation policy transaction. When canceling a
policy in preparation for a rewrite, the value provided for the cancellationReasonCode property must be either
flatrewrite or midtermrewrite, as described above. When rewriting the policy, the value provided for the
rewriteType property must be either rewriteFullTerm, rewriteNewTerm, or rewriteRemainderOfTerm, as
described above.

Rewrite period cancellationReasonCode property value rewriteType property value

Full term flatrewrite rewriteFullTerm
New term flatrewrite rewriteNewTerm
Mid-term midtermrewrite rewriteRemainderOfTerm

Overview of policy transaction management

Work with policy transactions typically involves endpoints from two different APIs:
• The Policy API, which has endpoints to:
◦ Initiate all types of policy transactions except for submissions

Rewrite and Rewrite New Account 235

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• The Job API, which has endpoints to:

◦ Initiate submissions
◦ Modify the contents of a policy (such as its coverables, coverages, and policy contacts)
◦ Quote jobs
◦ Bind and issue jobs, or withdraw jobs
◦ Work with objects owned by jobs, such as activities and underwriting issues
Conceptually, a policy transaction is completed in four steps:
1. Initiate the policy transaction.
• This creates a new Job element whose status is "Draft".
2. Modify the job as needed.
• The status remains "Draft".
3. Quote the job.
a. The rating engine or rating service generates a quote for the job.
b. The status advances to "Quoted".
c. The job can be modified at this point. But if it is modified, the policy transaction falls back to the previous
step. In other words, the status reverts to "Draft" and the job must be later requoted.
4. Complete the job.
a. This can be done by binding the job or by withdrawing or canceling the job.
b. The status advances to "Bound", "Declined", or "Withdrawn", depending on the outcome and job type.

Rewrite transaction
The rewrite policy transaction can be executed on a canceled policy.
1. Initiate the rewrite policy transaction.
• Submit a POST request to the /policy/v1/policies/{policyId}/rewrite endpoint
• The request payload must contain a value for the rewriteType property. Acceptable values are
rewriteFullTerm, rewriteNewTerm, and rewriteRemainderOfTerm.
{
"data": {
"attributes": {
"rewriteType": {
"code": "RewriteFullTerm"
}
}
}
}

• The response payload contains the associated job, which is in Draft state. Use the job ID in subsequent calls.
2. Revise the job as needed, to reflect changes to the policy. (For more information on how to modify a policy
within the context of a job, see “Overview of modifying jobs” on page 241.)
3. Generate a quote.
Submit a business action POST to the /job/v1/jobs/{jobId}/quote endpoint.
4. Complete the policy transaction.
Submit a business action POST to the /job/v1/jobs/{jobId}/bind-and-issue endpoint.

236 Rewrite and Rewrite New Account

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Rewrite new account transaction

1. Initiate the rewrite new account policy transaction.
Submit a POST request to the /policy/v1/policies/{policyId}/rewrite-account endpoint. The request
payload must contain a valid account ID value for the account.id property.

{
"data": {
"attributes": {
"account": {
"id": "pc:102"
}
}
}
}

The response payload contains the associated job, which is in Draft state. Use the job ID in subsequent calls.
2. Revise the job as needed, to reflect changes to the policy.
3. Generate a quote.
Submit a business action POST to the /job/v1/jobs/{jobId}/quote endpoint.
4. Complete the policy transaction.
Submit a business action POST to the /job/v1/jobs/{jobId}/bind-and-issue endpoint.

Rewrite and Rewrite New Account 237

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

238 Rewrite and Rewrite New Account

part 5

Business flows: Job policies

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in PolicyCenter so that caller
applications can request data from or initiate action within PolicyCenter.
The following topics discuss how caller applications can modify the contents of a policy within the context of a job.
This includes working with:
• Lines of business
• Coverables and coverages
• Modifiers
• Questions
• Exposures, exclusions, and conditions
• Synchronization and deferred validation
• Policy contacts
• Policy locations
• Job role assignment
• Product definition metadata
• Job PATCHes

Business flows: Job policies 239

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

240 Business flows: Job policies

chapter 23

Overview of modifying jobs

A policy can be created or modified only through the context of a policy transaction. The different types of policy
transactions include the following:
• Submission (to create a new policy)
• Renewal (to create a new term for an existing policy)
• Policy change
• Cancellation
• Reinstatement
• Rewrite
In PolicyCenter, policy transactions are managed by instances of the Job data model entity. Similarly, in Cloud API,
policy transactions are managed by instances of the Job resource. Every job has an associated policy. The majority of
the work related to modifying a job lies in specifying the contents of the policy for the job.

Contents of a policy
The contents of a policy can be divided into two categories.
• LOB-specific
◦ The structure of these contents vary based on the associated lines of business.
◦ Developers work with these contents using LOB-specific endpoints, which must be generated by the developer.
• LOB-generic
◦ The structure of these contents remains the same, regardless of the associated lines of business.
◦ Developers work with these contents using LOB-generic endpoints, which are already present in the base
configuration.
The following table summarizes the contents of a policy and the sections of the documentation that discuss how to add
this type of contents to a job.

Content Type Definition Example from Personal LOB relationship More information
Auto
Line A set of information that Personal Auto Line LOB-specific “Lines” on page 245
is used to define a type
of product offered by an
insurer

Overview of modifying jobs 241

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Content Type Definition Example from Personal LOB relationship More information
Auto
Coverable A thing that is covered by Vehicle LOB-specific “Coverables and
the policy coverages” on page
249
Coverage For each coverable, a Collision coverage (for a LOB-specific “Coverables and
specific type of covered specific vehicle) coverages” on page
loss 249
Coverage term A value that further A deductible for a given LOB-specific “Coverables and
defines or limits the collision coverage coverages” on page
extent of a coverage 249
Modifier Information relevant to An "Anti-Lock Breaks" LOB-specific “Modifiers” on page
rating that is not modifier that provides a 265
necessarily tied to a discount for collision
specific coverable or coverage if the vehicle
coverage has anti-lock breaks
Question Information that can be The question "Has any LOB-specific “Questions” on page
used to pre-qualify an policy or coverage been 273
account or gather declined, canceled, or
additional information non-renewed during the
relevant to rating prior 3 years?" Saying
yes could disqualify the
account.
Exposure A thing that is not a Driver. This provides LOB-specific “Exposures,
coverable but gathers information about a exclusions, and
additional information to vehicle's drivers that can conditions” on page
help rate or process a affect pricing (such as 279
policy the driver's age), but
coverages are not
attached directly to any
driver.
Exclusion A limit to coverages that A "Custom Equipment" LOB-specific “Exposures,
defines circumstances exclusion, which exclusions, and
where the coverage does excludes coverage for conditions” on page
not apply damage done to 279
"aftermarket equipment
and modifications"
Condition A contractual obligation A condition stating that LOB-specific “Exposures,
of the insurance policy cancellation for non- exclusions, and
that are neither payment requires a 30- conditions” on page
coverages nor exclusions day notice (and not just a 279
10-day notice as
mandated in the
jurisdiction)
Policy contact An account contact The policy's primary LOB-generic “Policy contacts” on
associated with a policy insured person page 291
Policy location An account location The location where a LOB-generic “Policy locations” on
associated with a policy vehicle is garaged page 307

242 Overview of modifying jobs

chapter 24

Lines of business

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
This topic discusses how to work with lines.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Overview of lines of business

Lines of business
A line of business (LOB) is a set of information that is used to define a type of product offered by an insurer. For
example, "Personal Auto Line" is a line of business used to define the "Personal Auto" product. The primary type of
information in a line of business includes the following:

Type Definition Example from Personal Auto

Coverable A thing that is covered by the policy Vehicle

Lines of business 243

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Type Definition Example from Personal Auto

Coverage For each coverable, a specific type of covered loss Collision coverage (for a specific vehicle)
Coverage term A value that further defines or limits the extent of a A deductible for a given collision coverage
coverage
Modifier Information relevant to rating that is not necessarily An "Anti-Lock Breaks" modifier that provides a discount for
tied to a specific coverable or coverage collision coverage if the vehicle has anti-lock breaks
Question Information that can be used to pre-qualify an The question "Has any policy or coverage been declined,
account or gather additional information relevant to canceled, or non-renewed during the prior 3 years?" Saying
rating yes could disqualify the account.
Exposure A thing that is not a coverable but gathers additional Driver. This provides information about a vehicle's drivers
information to help rate or process a policy that can affect pricing (such as the driver's age), but
coverages are not attached directly to any driver.
Exclusion A limit to coverages that defines circumstances A "Custom Equipment" exclusion, which excludes coverage
where the coverage does not apply for damage done to "aftermarket equipment and
modifications"
Condition A contractual obligation of the insurance policy that A condition stating that cancellation for non-payment
are neither coverages nor exclusions requires a 30-day notice (and not just a 10-day notice as
mandated in the jurisdiction)

LOB-specific endpoints
Every line of business has its own set of information, such as its own coverables, its own coverages, and so on. When
you want to interact with this LOB-specific information, you must use endpoints specific to that LOB.
For example, the Personal Auto line of business for a given insurer might have the following endpoints:
• POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles
• POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages
• POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/drivers
• GET /jobs/{jobId}/lines/PersonalAutoLine/modifiers
The LOB-specific endpoints are discussed in later topics in this section.
LOB-specific endpoints are not present in the base configuration of Cloud API for PolicyCenter. These endpoints must
be generated by the insurer for each product. They reflect the structure of that product as defined by the insurer. The
examples in this topic all come from LOB-specific endpoints generated for the base configuration version of Personal
Auto.
• For general information on how to generate LOB-specific endpoints for any product, see the Cloud API Developer
Guide.
• For information on how to generate the endpoints for the base configuration Personal Auto product, see the Cloud
API Developer Guide.

LOB-generic endpoints
Most of the endpoints that advance a job's state are not specific to any LOB. This includes endpoints such as:
• POST /job/v1/jobs/{jobId}/quote
• POST /job/v1/jobs/{jobId}/bind-and-issue
These endpoints are discussed in the topics on each job type, such as the “Submissions” on page 193 topic.
There are also endpoints that work with objects available to all jobs, regardless of its LOB. This includes endpoints for
working with objects such as:
• Contacts
• Locations

244 Lines of business

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The LOB-generic endpoints are discussed in later topics in this section.

Lines
A line is a set of LOB-specific resources owned by a job or policy.
For most types of resources, every resource has a unique ID. However, the value of a line instance's ID is set to the
LOB's identifier as specified in the product definition. For example, suppose there is a personal auto line whose
identifier is set to "PersonalAutoLine". This means that, for every personal auto job and policy, the ID of the line
resource is "PersonalAutoLine".
A line resource can have the following direct descendent children:
• Line-level coverages
• Coverables
• Other line-specific objects, such as exposures and exclusions (For example, a person auto line could include driver
exposures)

LOB-endpoint pattern for lines

For each LOB, there are endpoints to get, modify, and delete a line resource. They follow these patterns:
• GET /jobs/{jobId}/lines/{lineId}
• PATCH /jobs/{jobId}/lines/{lineId}
• DELETE /jobs/{jobId}/lines/{lineId}
For example, for a personal auto line, the endpoints might be:
• GET /jobs/{jobId}/lines/PersonalAutoLine
• PATCH /jobs/{jobId}/lines/PersonalAutoLine
• DELETE /jobs/{jobId}/lines/PersonalAutoLine
For information on how to generate LOB-specific endpoints, see the Cloud API Developer Guide. The examples in this
section of the documentation use endpoints from the base configuration Personal Auto product. For information on
how to generate these endpoints, see the Cloud API Developer Guide.

Creating and modifying lines

Lines are created automatically when the job is created.
• If the product is a single-line product, that line is created by default. There are no POST or DELETE endpoints for
the line.
• If the product is a multi-line product, all lines are created by default. There are POST and DELETE endpoints so
you can modify which lines are attached to the policy as needed.
The line resource specifies its pattern and pattern code. Beyond this, the amount of information on the line resource
itself varies from line to line. Some lines may store only a small amount of information on the line resource itself.
Others may have a more robust amount of information.
For example, the following response comes from a GET for a line resource for the base configuration Personal Auto
LOB. All fields are included.

"attributes": {
"coverableJurisdiction": {
"code": "CA",
"name": "California"
},
"numAddInsured": 0,
"pattern": {
"displayName": "Personal Auto Line",
"id": "PersonalAutoLine"
},

Lines of business 245

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"patternCode": "PersonalAutoLine"
},

Additional LOB-specific endpoints

LOB-specific endpoints in the Policy API
When you generate LOB-specific endpoints, endpoints are added to both the Job API and the Policy API.
• The Job API endpoints give you the ability to retrieve, create, modify, and delete LOB-specific resources.
• The Policy API endpoints give you only the ability to retrieve LOB-specific resources.
As a general rule, for every LOB-specific GET in the Job API, there is a corresponding GET in the Policy API. The
Policy API GETs can only be used for existing policies. They cannot retrieve job-specific information.
For example, the Personal Auto product discussed in the previous examples would have the following GETs in the
Policy API:
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/coverages
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/coverages/{coverageId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/modifiers
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/modifiers/{modifierId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/policy-driver-mvrs
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/policy-driver-mvrs/
{policyDriverMVRId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/questions
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages/
{coverageId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/drivers
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/drivers/
{driverId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/modifiers
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/modifiers/
{modifierId}
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/vhcle-addl-
interests
• GET /policy/v1/policies/{policyId}/lines/PersonalAutoLine/vehicles/{vehicleId}/vhcle-addl-
interests/{vhcleAddlInterestId}

Contrasting job, policy, product, and line of business

A policy transaction is an operation that creates, modifies, or ends a policy. There are several specific types of policy
transactions, including submission, renewal, policy change, cancellation, and reinstatement.
A job is a PolicyCenter operation that executes a policy transaction. Within the context of PolicyCenter, the terms job
and policy transaction are virtually synonymous, though "job" is used more often in the technical layer and "policy
transaction" in the user interface.

246 Lines of business

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Every job and every policy is associated with a specific type of product. A product is a type of policy offered by an
insurer. For example, an insurer may have a "Personal Auto" product that is used to create personal auto policies.
A line of business (LOB) is a set of information that is used to define a type of product offered by an insurer. For
example, "Personal Auto Line" is a line of business used to define the "Personal Auto" product.
Most products have a single line of business. For example, an insurer could offer a Commercial Property product that
consists of a single line of business - the "Commercial Property Line". For these types of products, the product and the
underlying LOB are often discussed interchangeably.
However, some products have multiple lines of business. For example, an insurer could offer a Commercial Package
product that consists of two lines of business, the "Commercial Property Line" and the "General Liability Line". Note
that these types of products are referred to as both multi-line products and package products.
Note that a given LOB could be:
• Used by only one product (which could be a single line or multi-line product)
• Used by multiple products (each of which could be a single line or multi-line product)

Lines of business 247

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

248 Lines of business

chapter 25

Coverables and coverages

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
This topic discusses how to work with coverables, coverages, and coverage terms.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Overview of coverables
A coverable is something on a policy to which coverages are attached, such as a vehicle or a building.

LOB-endpoint pattern for line coverables

In every line of business, the line itself is a coverable. Liability coverages that cover the policy holder are typically
attached to the line.
For each LOB, there are endpoints to get, modify, and delete a line resource. They follow these patterns:
• GET /jobs/{jobId}/lines/{lineId}
Coverables and coverages 249
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• PATCH /jobs/{jobId}/lines/{lineId}
• DELETE /jobs/{jobId}/lines/{lineId}
For example, for a personal auto line, the endpoints might be:
• GET /jobs/{jobId}/lines/PersonalAutoLine
• PATCH /jobs/{jobId}/lines/PersonalAutoLine
• DELETE /jobs/{jobId}/lines/PersonalAutoLine
For information on how to generate LOB-specific endpoints, see the Cloud API Developer Guide. The examples in this
section of the documentation use endpoints from the base configuration Personal Auto product. For information on
how to generate these endpoints, see the Cloud API Developer Guide.

LOB-endpoint pattern for non-line coverables

For every non-line coverable, there are endpoints to get a collection of coverables, and to create, get, modify, and
delete a coverable element. These endpoints follow these patterns:
• GET /jobs/{jobId}/lines/{lineId}/{coverablesName}
• POST /jobs/{jobId}/lines/{lineId}/{coverablesName}
• GET /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}
• PATCH /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}
• DELETE /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}
For example, personal auto lines typically have one type of coverable - vehicles. For a personal auto line, the endpoints
might be:
• GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles
• POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles
• GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}
• PATCH /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}
• DELETE /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}
For information on how to generate LOB-specific endpoints, see the Cloud API Developer Guide. The examples in this
section of the documentation use endpoints from the base configuration Personal Auto product. For information on
how to generate these endpoints, see the Cloud API Developer Guide.

Hierarchical coverables
Some lines of business may define a hierarchy of parent and child coverables. For example, a Commercial Property
line may have building coverables, and within each building there could be equipment coverables. For this LOB, there
would be hierarchical endpoints for each coverable, such as the following POST endpoints:
• POST /jobs/{jobId}/lines/CommercialPropertyLine/locations/{locationId}/buildings
• POST /jobs/{jobId}/lines/CommercialPropertyLine/locations/{locationId}/buildings/
{buildingId}/equipment

Adding coverables
Coverables are added using the appropriate LOB-specific endpoints. The information that can and must be included in
the request will vary based on the coverable. Keep in mind that some values may not be required to create the
coverable but may be required later to quote or bind the job.

250 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For the base configuration Personal Auto product, there are no required fields for creating a vehicle. However, the
following fields are required to quote the policy: costNew, licenseState, make, model, modelYear, vin. The
following request payload is an example of creating a vehicle with fields that will pass validation for quoting.

POST /job/v1/jobs/pc:4040/lines/PersonalAutoLine/vehicles

{
"data": {
"attributes": {
"costNew": {
"amount": "33000",
"currency": "usd"
},
"licenseState": {
"code": "CA"
},
"make": "Toyota",
"model": "Tercel",
"modelYear": 2010,
"vin": "459DEF32PO98Q1121"
}
}
}

Data created in addition to the coverable

When you create a coverable, either through PolicyCenter directly or through Cloud API, PolicyCenter automatically
creates all coverages and child objects (such as exposures or exclusions) that meet the following criteria:
• They are available when the call is made.
• They have an existence type of "Required" or "Suggested".
For example, in the base configuration Personal Auto product, the PACollisionCov coverage is required on a vehicle.
Thus, whenever you create a vehicle, PolicyCenter automatically adds a PACollisionCov coverage to it (provided it is
available)..
Caller applications with sufficient authorization can disable this automatic creation of coverages and child objects. For
more information, see “Synchronization and deferred validation” on page 283.

Overview of coverages
A coverage is a specific type of loss covered on the policy. From a policy structure standpoint, there are two types of
coverages: line-level coverages and coverable-level coverages.

LOB-endpoint pattern for line-level coverages

A line-level coverage is a coverage attached to the line resource. Line-level coverages are often liability coverages that
protect the policy holder (and any other named insureds). For example, for the personal auto line, "Liability - Bodily
Injury and Property Damage" is a line-level coverage. Line-level coverages are attached to the line resource to indicate
that apply to everyone covered by the policy.
For every line, there are endpoints to get a collection of line-level coverages, and to create, get, modify, and delete a
line-level coverage element. These endpoints follow these patterns:
• GET /jobs/{jobId}/lines/{lineId}/coverages
• POST /jobs/{jobId}/lines/{lineId}/coverages
• GET /jobs/{jobId}/lines/{lineId}/coverages/{coverageId}
• PATCH /jobs/{jobId}/lines/{lineId}/coverages/{coverageId}
• DELETE /jobs/{jobId}/lines/{lineId}/coverages/{coverageId}
For example, for a personal auto line, the endpoints might be:
• GET /jobs/{jobId}/lines/PersonalAutoLine/coverages
• POST /jobs/{jobId}/lines/PersonalAutoLine/coverages

Coverables and coverages 251

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET /jobs/{jobId}/lines/PersonalAutoLine/coverages/{coverageId}
• PATCH /jobs/{jobId}/lines/PersonalAutoLine/coverages/{coverageId}
• DELETE /jobs/{jobId}/lines/PersonalAutoLine/coverages/{coverageId}

LOB-endpoint pattern for coverable-level coverages

A coverable-level coverage is a coverage that attached to a specific coverable. Coverable-level coverages are often
property coverages that protect loss or damage of the associated coverable. For example, for the personal auto line,
"Collision" is a coverable-level coverage that is attached to a specific vehicle.
For every coverable in a line, there are endpoints to get a collection of coverages, and to create, get, modify, and delete
a line-level coverage element. These endpoints follow these patterns:
• GET /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}/coverages
• POST /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}/coverages
• GET /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}/coverages/{coverageId}
• PATCH /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}/coverages/{coverageId}
• DELETE /jobs/{jobId}/lines/{lineId}/{coverablesName}/{coverableNameId}/coverages/
{coverageId}

For example, for a personal auto line, the endpoints might be:
• GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages
• POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages
• GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages/{coverageId}
• PATCH /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages/{coverageId}
• DELETE /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/coverages/{coverageId}

Coverages for hierarchical coverables

If a line has a hierarchy of coverables, then there is also a hierarchy of coverage endpoints. For example, suppose there
is a Commercial Property line with building coverables and equipment coverables. Equipment is always associated
with a given building. In this case, the endpoints for adding coverages for buildings and equipment would look like
this:
• POST /jobs/{jobId}/lines/CommercialPropertyLine/locations/{locationId}/buildings/
{buildingId}/coverages
• POST /jobs/{jobId}/lines/CommercialPropertyLine/locations/{locationId}/buildings/
{buildingId}/equipment/{equipmentId}/coverages

Adding coverages
Automatically added coverages
For installed products, when a line or coverable is created, the PolicyCenter default behavior is to create all associated
coverages that meet the following criteria:
• They are available when the call is made.
• They have an existence type of "Required" or "Suggested".
For example, in the base configuration Personal Auto product, the PACollisionCov coverage is required on a vehicle.
Thus, whenever you create a vehicle, PolicyCenter automatically adds a PACollisionCov coverage to it (provided it is
available).
(For visualized products, no coverages are added automatically.)

252 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Caller applications with sufficient authorization can disable this automatic creation of coverages and child objects. For
more information, see “Synchronization and deferred validation” on page 283.

Manually adding line-level coverages

To add line-level coverages manually, use the appropriate LOB-specific endpoints. To create a coverage, you must
know the coverage's ID. You can use the following endpoint from the Product Definition API to retrieve information
about all available line-level coverages for a given line, including their IDs:
• GET productdefinition/v1/lines/{lineId}/coverages
You can then use the POST /jobs/{jobId}/lines/{lineId}/coverages endpoint to create line-level coverages for
the submission. The coverage ID is specified in the pattern attribute.
The following is an example of creating a Personal Auto Liability coverage (whose pattern ID is PALiabilityCov) for
submission job pc:4040.

POST /job/v1/jobs/pc:4040/lines/PersonalAutoLine/coverages

{
"data": {
"attributes": {
"pattern": {
"id": "PALiabilityCov"
}
}
}
}

Manually adding coverable-level coverages

To add coverable-level coverages manually, use the appropriate LOB-specific endpoints. To create a coverage, you
must know the coverage's ID. You can use the following endpoint from the Product Definition API to retrieve
information about all available coverable-level coverages for a given line, including their IDs:
• GET productdefinition/v1/lines/{lineId}/coverables/{coverableID}/coverages
You can then use the POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/ coverages
endpoint to create coverable-level coverages for the submission. The coverage ID is specified in the pattern attribute.
The following is an example of creating a Collision coverage (whose pattern ID is PACollisionCov) for the Toyota
Tercel (103) on submission job pc:4040.

POST /job/v1/jobs/pc:4040/lines/PersonalAutoLine/vehicles/103/coverages

{
"data": {
"attributes": {
"pattern": {
"id": "PACollisionCov"
}
}
}
}

Data created in addition to the coverage

When you create a coverage, either through PolicyCenter directly or through Cloud API, PolicyCenter automatically
creates all coverage terms that meet the following criteria:
• They are available when the call is made.
• They are required.
For example, in the base configuration Personal Auto product, the PACollisionCov coverage has a required
PACOLDeductible coverage term (collision deductible). Thus, whenever you create a PACollisionCov coverage,
PolicyCenter automatically adds a PACOLDeductible coverage term to it (provided it is available).
Caller applications with sufficient authorization can disable this automatic creation of coverages and child objects. For
more information, see “Synchronization and deferred validation” on page 283.

Coverables and coverages 253

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Coverage terms
A coverage term is a value associated with a coverage that further defines the extent of the coverage. They are also
commonly referred to as "covterms". The most common examples of coverage terms are deductibles and limits, such
as:
• A $1000 deductible on collision coverage, which stipulates that if a vehicle is damaged by collision, the insured
must pay the first $1000 of repair.
• A $100,000 third-party injury liability limit, which stipulates that if the insured is responsible for injuries to a third
party, the coverage pays only up to $100,000.
A coverage can have zero, one, or many coverage terms. Each coverage term can be optional or required. Each
coverage term can have a default value.

Coverage term syntax

Coverage terms are not managed in their own resource. Rather, they are specified in as part of the associated Coverage
resource in its terms map. The partial syntax is shown below.

{
"data": {
"attributes": {
"id": "<coverageId>",
"terms": {
"<covTermId>": {
"covTermType": "<value>",
"displayValue": "<value>",
"decimalValue": "<value>",
"booleanValue": <value>,
"choiceValue": {
"code": "<valueFromPreductDefinition>"
},
"dateValue": "<value>",
"directValue": "<value>",
"stringValue": "<value>",
"typekeyValue": {
"code": "<valueFromTypelist>"
},
}
}
},

Coverage term ids

Every coverage term as an id value. These values are defined in the product definition. For example, a Personal Auto
rental coverage term could have an id of PARental.

Coverage term types

Every coverage term has a covTermType, which identifies the datatype of the coverage term value and how the value is
used.
The value of the coverage term is specified using a corresponding ...Value property. The following table identifies
the difference values for covTermType and the corresponding ...Value property used to store its value.

covTermType Property that stores the coverage term value

decimal bigDecimalValue
boolean booleanValue
choice choiceValue (used for coverage terms whose value is selected from a set of values defined in the product
definition)
date dateTimeValue
direct directValue
string stringValue

254 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

covTermType Property that stores the coverage term value

typekey typekeyValue (used for coverage terms whose value is selected from a set of values defined in a typelist)

Note that even though the covTerm schema has multiple ...Value fields, for a given covTerm only one of them will
have a value. The other ...Value fields will be null.

Coverage term example

For example, suppose there is a PARentalCov coverage with a PARental coverage term. Its value is a choice defined in
the product definition, and it is currently set to 25 dollars per day for 30 days (30/25). The JSON for the coverage
would be as follows:

{
"data": {
"attributes": {
"id": "PARentalCov",
"terms": {
"PARental": {
"covTermType": "choice",
"displayValue": "30 days x 25/day",
"choiceValue": {
"code": "30/25"
}
}
}
},
...

When creating a coverage:

• You do not need to specify optional coverage terms.
◦ If you do not specify the coverage term, it is not added to the coverage.
• You do not need to specify values for required coverage terms with defaults.
◦ If you do not specify the coverage term, it is added with the default value.
• You must specify values for required coverage terms that do not have default values.
The following is an example of creating a rental coverage (whose pattern ID is PARentalCov) for the Toyota Tercel
(103) on submission job pc:4040. The coverage has a coverage term (PARental), whose value is set to 20 dollars per
day for 60 days (60/20).

POST /job/v1/jobs/pc:4040/lines/PersonalAutoLine/vehicles/103/coverages

{
"data": {
"attributes": {
"pattern": {
"id": "PARentalCov"
},
"terms": {
"PARental": {
"choiceValue": {
"code": "60/20"
}
}
}
}
}
}

Scheduled items
Sometimes, an account holder wants a policy to cover a specific item that has unusual value. There is a generic
coverage on the policy that could apply to the item. But because of the item's unusual value, it ought to be covered by
its own coverage. The insurer may require additional information, such as the item's value and how this value was
determined. The item's coverage may also require a deductible or limit that is outside the range of what is allowed by
the more generic coverage. These types of "unusual value" items appear on the policy in a list that is called a schedule.
Thus, the items themselves are called scheduled items.

Coverables and coverages 255

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, suppose that a homeowners line of business has a Personal Property coverage. This coverage covers
personal property in the home and has a limit of up to $10,000. It is intended for generic and easily replaceable items,
such as clothing, furniture, or appliances. Ray Newton has a homeowners policy with Personal Property coverage. But
he recently acquired a painting of a Dutch sailboat whose appraised value is $40,000. He wants this item covered by
the policy for its appraised value. Therefore, the painting is added to the policy as a scheduled item. Information about
the painting, its value, its appraisal method, and the limit of its coverage are included in the policy.
From a data perspective, a scheduled item is a child object of a coverage. But it is unlike other coverage children in that
it contains information normally associated with coverables (such as item type or item description) as well as
information normally associated with coverage terms (such as an item-specific deductible or limit).
The nature of scheduled items varies across LOBs. Similar scheduled items from different LOBs may have
significantly different definitions in their products. Some LOBs may not have any scheduled items. And in some cases,
an LOB from one source (such as an SBT-based LOB) may have them when that same LOB from a different source
(such as an APD-native version of that LOB) may not.

Scheduled item endpoints

Cloud API generates separate endpoints for each type of scheduled item. Typically, each of these endpoints is the child
of a /coverages endpoint. The endpoint paths for scheduled items have paths similar to the following patterns:
• Collection endpoints: .../<coverables>/{<coverable>Id}/coverages/{coverageId}/scheduled-items
• Element endpoints: .../<coverables>/{<coverable>Id}/coverages/{coverageId}/scheduled-items/
{scheduledItemId}

For example, suppose you have a homeowners product with dwelling coverables that can have coverages attached to
them. Some coverages can have scheduled items. The LOB endpoints for this product would include the following:
• GET /jobs/{jobId}/lines/HOPLine/coverage-parts/{coveragePartId}/dwellings/{dwellingId}/
coverages/{coverageId}/scheduled-items
• POST /jobs/{jobId}/lines/HOPLine/coverage-parts/{coveragePartId}/dwellings/{dwellingId}/
coverages/{coverageId}/scheduled-items
• GET /jobs/{jobId}/lines/HOPLine/coverage-parts/{coveragePartId}/dwellings/{dwellingId}/
coverages/{coverageId}/scheduled-items/{scheduledItemId}
• PATCH /jobs/{jobId}/lines/HOPLine/coverage-parts/{coveragePartId}/dwellings/{dwellingId}/
coverages/{coverageId}/scheduled-items/{scheduledItemId}
• DELETE /jobs/{jobId}/lines/HOPLine/coverage-parts/{coveragePartId}/dwellings/{dwellingId}/
coverages/{coverageId}/scheduled-items/{scheduledItemId}

Resources for scheduled items

Different types of scheduled items require different properties
Every type of scheduled item is defined using a different set of properties.
For example, scheduled items for a homeowners HOPScheduledPersonalProperty coverage could require these
properties:
• Description (a string value)
• Property type (a value from a set of choices defined in the product definition)
• Date of appraisal (a dateOnly value)
• Appraised value (a decimal value)
But, scheduled items for an Inland Marine IMScheduledEquipment coverage could require these properties:
• Description (a string value)

256 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Equipment type (a typecode value)

• Purchase date (a dateOnly value)
• Replacement price (a decimal value)
• Covered by warranty (a Boolean value)
Normally, when different types of objects have different properties, Cloud API manages each object type with a
different type of resource. However, it would be inefficient for Cloud API to generate a separate type of resource for
every type of scheduled item across every LOB managed by the insurer.
To simplify endpoint architecture, Cloud API uses a single ScheduledItem resource for all types of scheduled items.

Structure of the ScheduledItem resource

The ScheduledItem resource has the following top-level attributes:

{
"data": {
"attributes": {
"id": ...,
"properties": ...
}
}
}

The properties field is a map. Every member of the map is a scheduled item property whose name is a
ScheduledItemPropertyPattern (such as "Description"). The property is set to a JSON object that specifies the
property's value, such as "Painting: Dutch sailboat".
The ScheduledItemPropertyPattern must be a ScheduledItemPropertyPattern from the product definition for this
type of scheduled item. For example, suppose you have a scheduled item for the homeowners
HOPScheduledPersonalProperty coverage from the previous example. The following table identifies the
ScheduledItemPropertyPattern (and its data type) for each piece of information to specify about the scheduled item.

Information to specify ScheduledItemPropertyPattern Associated data type

Description Description string
Property type HOPScheduledPersonalProperty ItemType choice (from a set of choices in the product
definition)
Date of appraisal DateOfAppraisal date only
Appraised value HOPScheduledPersonalProperty decimal
ItemAppraisedValue

Each property would start like this:

{
"data": {
"attributes": {
"properties": {
"Description":
...,
"HOPScheduledPersonalPropertyItemType":
...,
"DateOfAppraisal":
...,
"HOPScheduledPersonalPropertyItemAppraisedValue":
...
}
}
}
}

Each ScheduledItemPropertyPattern must be set to a JSON object that specifies the pattern's value, such as "Painting:
Dutch sailboat". The JSON object must contain one of the following "<X>value" fields:
• booleanValue
• choiceValue (for choice values defined in the product definition)

Coverables and coverages 257

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• dateOnlyValue
• dateTimeValue
• decimalValue
• integerValue
• locationValue (for values set to a Location)
• partyValue (for values set to an involved party, such as the insured)
• stringValue
• typekeyValue (for typecode values)
For each property, the "<X>value" field must correspond to the data type for the ScheduledItemPropertyPattern . For
example, if the ScheduledItemPropertyPattern specifies a string value (such as for Description), then the JSON object
must include the stringValue field. If the ScheduledItemPropertyPattern specifies a date value (such as for
DateOfAppraisal), then the JSON object must include the dateOnlyValue field.

Suppose you have a scheduled item from the previous JSON payload with the following values:
• Description: Painting: Dutch sailboat
• Property type: Fine art
• Date of appraisal: February 2, 2020
• Appraised value: $40,000
The payload for the properties map would look like this:
{
"data": {
"attributes": {
"properties": {
"Description": {
"stringValue": "Painting: Dutch sailboat"
},
"HOPScheduledPersonalPropertyItemType": {
"choiceValue": {
"code": "fine_arts"
}
},
"DateOfAppraisal": {
"dateOnlyValue": "2020-02-02"
},
"HOPScheduledPersonalPropertyItemAppraisedValue": {
"decimalValue": "40000"
}
}
}
}

For most of the "<X>value" fields, the value itself is specified in the JSON payload as a string. There are a few
exceptions:
• choiceValue and typekeyValue values are specified as JSON objects with a child code field
locationValue and partyValue values are specified as JSON objects with a child id value

Scheduled items in response payloads

In response payloads, properties in the properties map have two additional read-only fields:
• displayValue lists a user-friendly version of the property's value.
• valueType identifies the data type of the ScheduledItemPropertyPattern. The value of valueType is determined by
which field was used to specify the value. (If the value was specified using the stringValue field, then valuetype
is set to "string".)
For example, in a response payload, the first two elements from the previous example would appear as follows:

{
"data": {

258 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"attributes": {
"properties": {
"Description": {
"displayValue": "Painting: Dutch sailboat",
"stringValue": "Painting: Dutch sailboat",
"valueType": "string"
},
"HOPScheduledPersonalPropertyItemType": {
"choiceValue": {
"code": "fine_arts"
},
"displayValue": "Fine arts",
"valueType": "choice"
},
...

Querying for scheduled items

The exact structure of each GET /scheduled-items endpoint varies based on the LOB.
For example, the following request retrieves the HOPScheduledPersonalProperty scheduled items for policy c:505.
There is one result: a painting of a Dutch sailboat valued at $40,000.
Command

GET /job/v1/jobs/pc:505/lines/HOPLine/coverages/HOPScheduledPersonalProperty/scheduled-items

Response body

{
"count": 1,
"data": [
{
"attributes": {
"id": "101",
"properties": {
"Appraiser": {
"displayValue": "Cranleigh's Fine Arts",
"stringValue": "Cranleigh's Fine Arts",
"valueType": "string"
},
"DateOfAppraisal": {
"dateOnlyValue": "2020-02-02",
"displayValue": "Feb 2, 2020",
"valueType": "date"
},
"Description": {
"displayValue": "Painting: Dutch sailboat",
"stringValue": "Painting: Dutch sailboat",
"valueType": "string"
},
"HOPScheduledPersonalPropertyItemAppraisedValue": {
"decimalValue": "40000.0000",
"displayValue": "$40,000.00",
"valueType": "decimal"
},
"HOPScheduledPersonalPropertyItemLimit": {
"decimalValue": "40000.0000",
"displayValue": "$40,000.00",
"valueType": "decimal"
},
"HOPScheduledPersonalPropertyItemType": {
"choiceValue": {
"code": "fine_arts",
"name": "Fine Arts"
},
"displayValue": "Fine Arts",
"valueType": "choice"
},
"HOPScheduledPersonalPropertyItemValuation": {
"choiceValue": {
"code": "ACV",
"name": "Actual cash value"
},
"displayValue": "Actual cash value",
"valueType": "choice"
},
"SerialNo": {
"displayValue": "1",
"stringValue": "1",
"valueType": "string"
}
}

Coverables and coverages 259

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
...

Creating scheduled items

Identifying a scheduled item's definition
To create a scheduled item, you must know the product definition for the scheduled item. This includes the names of
the ScheduledItemPropertyPattern values, their data types, and valid choice values, when relevant.
This information is available from the Product Definition API. To retrieve it, execute a GET /
productdefinition/v1/lines/{lineId}/coverages request. This request returns information about all of the line-
level coverages. It also contains information about coverages with scheduled items.
For example, suppose you are working with the homeowners line in the previous example. The code for this line is
HOPLine. The following request retrieves information about the line-level coverages.

GET /productdefinition/v1/lines/HOPLine/coverages

If a coverage includes scheduled items, it has a scheduledItemProperties array. For example, the following is a
snippet of the product definition for the Scheduled Personal Property coverage.

{
"attributes": {
"clauseType": "coverage",
"description": "Scheduled Personal Property",
"id": "HOPScheduledPersonalProperty",
"name": "Scheduled Personal Property",
"scheduledItemProperties": [
<ScheduledItemPropertyPatterns are defined here>
]

This array contains every defined ScheduledItemPropertyPattern for the coverage. In most cases, the most relevant
fields are the id, name, and valueType.

Non-choice property pattern examples

For example, these are the non-choice ScheduledItemPropertyPattern values for Scheduled Personal Property.
(Fields other than id, name, and valueType have been omitted.)

{
"attributes": {
"clauseType": "coverage",
"description": "Scheduled Personal Property",
"id": "HOPScheduledPersonalProperty",
"name": "Scheduled Personal Property",
"scheduledItemProperties": [
{
"id": "Description",
"name": "Description",
"valueType": "shorttext"
},
{
"id": "SerialNo",
"name": "Serial No",
"valueType": "shorttext"
},
{
"id": "Appraiser",
"name": "Appraiser",
"valueType": "shorttext"
},
{
"id": "AppraisalInfo",
"name": "Appraisal Information",
"valueType": "shorttext"
},
{
"id": "DateOfAppraisal",
"name": "Date Of Appraisal",
"valueType": "dateonly"
},
{
"id": "HOPScheduledPersonalPropertyItemLimit",
"name": "Limit",

260 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"valueType": "Decimal"
},
{
"id": "HOPScheduledPersonalPropertyItemAppraisedValue",
"name": "Appraised Value",
"valueType": "Decimal"
},
...
]

Choice property pattern examples

If a ScheduledItemPropertyPattern value has a valueType of choice, it has an additional choices array. Properties
are listed in alphabetical order, so the choice array appears before the description, id, and valueType fields. Be
aware that when GETting or POSTing a scheduled item, the valueType is listed as choice. But in the product
definition, the valueType is listed as Option.
For example, these are the choice ScheduledItemPropertyPattern values for Scheduled Personal Property. (Fields
other than id, name, and valueType have been omitted.)
{
"attributes": {
"clauseType": "coverage",
"description": "Scheduled Personal Property",
"id": "HOPScheduledPersonalProperty",
"name": "Scheduled Personal Property",
"scheduledItemProperties": [
{
"choices": [
{
"code": "cameras",
"description": "Cameras"
},
{
"code": "fine_arts",
"description": "Fine Arts"
},
{
"code": "jewelry",
"description": "Jewelry"
},
...
],
"id": "HOPScheduledPersonalPropertyItemType",
"name": "Type",
"valueType": "Option"
},
{
"choices": [
{
"code": "HOPScheduledPersonalPropertyItemDeductible0",
"description": "$0"
},
{
"code": "HOPScheduledPersonalPropertyItemDeductible1000",
"description": "$1,000"
},
{
"code": "HOPScheduledPersonalPropertyItemDeductible5000",
"description": "$5,000"
},
...
],
"id": "HOPScheduledPersonalPropertyItemDeductible",
"name": "Deductible",
"valueType": "Option"
},
{
"choices": [
{
"code": "ReplCost",
"description": "Replacement cost"
},
{
"code": "ACV",
"description": "Actual cash value"
}
],
"id": "HOPScheduledPersonalPropertyItemValuation",
"name": "Valuation Method"
"valueType": "Option"
},
...
]

Coverables and coverages 261

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Creating a scheduled item

When POSTing a scheduled item, each field in the properties map must be set to the id of one of the
ScheduledItemPropertyPattern values. It must then be followed by one of the <X>value fields (such as
stringValue or choiceValue) based on the property's valueType.

There is no single set of property values that are required for all scheduled items. Both the required and possible values
vary based on the structure of the line of business. In some cases, a scheduled item may have no required values.
As an example, suppose PolicyCenter requires the following values for a HOPScheduledPersonalProperty scheduled
item from the previous example: Description, HOPScheduledPersonalPropertyItemType. The following request
would create a minimal scheduled item of a 10-carat diamond appraised at $5000 for policy pc:505.
Command

POST /job/v1/jobs/pc:505/lines/HOPLine/coverages/HOPScheduledPersonalProperty/scheduled-items

Request body

{
"data": {
"attributes": {
"properties": {
"Description": {
"stringValue": "10-carat diamond",
},
"HOPScheduledPersonalPropertyItemType": {
"choiceValue": {
"code": "jewelry"
}
},
"HOPScheduledPersonalPropertyItemAppraisedValue": {
"decimalValue": "5000"
}
}
}
}
}

Coverage validation
Default validation for coverages
In most cases, PolicyCenter restricts the following behaviors:
• Coverages
◦ Cannot create an unavailable coverage
◦ Cannot delete a required coverage
• Coverage terms
◦ Cannot set the value for an unavailable coverage term
◦ Cannot set the value for a read-only coverage term
◦ Cannot set the value for a hidden coverage term
◦ Cannot set the value to an unavailable option or package
◦ Cannot set the value to an unavailable typekey
◦ Cannot set the value outside of the min/max range
Some of these behaviors may be the result of the submission becoming out of sync. In these cases, you can rectify the
situation by calling the appropriate /sync-coverages endpoint. For more information, see “Synchronization and
deferred validation” on page 283.

262 Coverables and coverages

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Deferring validation
For Cloud API, the default validation behavior is referred to as immediate validation. In this approach, validation is
provided with each call. A validation error in one call can prevent later calls from executing. This approach is
appropriate for caller application the build submissions interactively, such as those backing a user interface.
There is a second behavior called deferred validation. In this approach, validation takes place only once the caller
application has put the submission into what it believes to be a consistent state. This is an option for non-interactive
caller applications with sufficient authorization. This approach can simplify submission processing by preventing
validation checks when the submission is known to potentially be in an inconsistent state. This approach can also
reduce the need to determine if coverages need to be synchronized.
For more information on deferred validation, see “Synchronization and deferred validation” on page 283.

Coverables and coverages 263

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

264 Coverables and coverages

chapter 26

Modifiers

A modifier, also referred to as a rate modifier, is a value used by the rating engine to adjust the policy premium (or
some portion of it). There are multiple types of modifiers, many of which are specific to a jurisdiction. Modifiers can
be at the product level or the product line level. Modifiers added to a product affect ratings for all lines in that product.
Modifiers added to a product line affect only that line.
Guidewire provides endpoints for accessing modifiers at different levels.
• “Modifier product definitions”: Retrieve the modifiers defined for the installed products and product lines.
• “Line-level modifiers”: For a specific job, retrieve and set values on modifiers attached to the line, such as a
MultiPolicyDiscount modifier on a PersonalAutoLine.
• “Object-level modifiers”: For a specific job, retrieve and set values on modifiers attached to an object on a line,
such as a vehicle AntiLockBrakes discount on a PersonalAutoLine.
See "Quoting and rating overview" in the Application Guide for more information on rating.

Product and product line modifiers

Modifiers can exist at the product and product line level, and can also apply to line coverables. They are created as part
of product installation and configuration, so there are no endpoints to create or update product-level or line-level
modifiers.
Note that product-level modifiers are not copied over when the product is attached to a multi-line product.
For more information, see “Modifiers” on page 265.

Product modifier endpoints

Use the following endpoints to retrieve product and product line modifiers:
• GET /productdefinition/v1/products/{productId}/modifiers
• GET /productdefinition/v1/lines/{lineId}/modifiers
• GET /productdefinition/v1/lines/{lineId}/coverables/{coverableId}/modifiers
Note:

Not all the modifier functionality available through these endpoints is currently supported in Advanced Product
Designer (APD). For example, APD does not support creation of modifiers under coverables, or split modifiers.
However, products built through other means might have these modifiers, and they can be retrieved with these
endpoints. For more information see APD Rate modifiers.
Modifiers 265
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Responses
Endpoint responses include a variety of information about the modifiers, including the modifier type:

"modifierDataType": {
"code": "boolean",
"name": "boolean"
},

Modifiers can be of type Boolean, date, rate, or typekey. If the modifier is a typekey, the response will also include the
name of the typelist:

"modifierDataType": {
"code": "typekey",
"name": "typekey"
},
…
"typeList": "ProfessionalDiscount"

For modifiers of type rate, rate factors are included in the response:

"modifierDataType": {
"code": "rate",
"name": "#notnull"
},
…
"rateFactors": [
{
"defaultMaximum": "0.05",
"defaultMinimum": "-0.05",
"id": "z0hi6ldfeujdpddo0f1hjou9r49",
"name": "#notnull",
"priority": 1,
"rateFactorType": {
"code": "Building",
"name": "#notnull"
}
},

The type is used to specify a value when the modifier is added to a job. See “Line-level and object-level modifiers” on
page 268 for more information.
If a modifier is a scheduled modifier, a value of true will be returned in the scheduledRate property:

"scheduleRate": true

See Rate modifiers for more information on scheduled and unscheduled rate modifiers.

Examples
This first example retrieves modifiers that apply to all lines for the CommercialPackage product.
Command

GET /productdefinition/v1/products/CommercialPackage/modifiers

Response

{
"data": [
{
"attributes": {
"defaultMaximum": "0.25",
"defaultMinimum": "-0.25",
"description": "#notnull",
"descriptionKey": "Product_CommercialPackage.Modifier_CPPIRPM.Description",
"displayJustification": true,
"displayRange": true,
"displayValueFinal": true,
"id": "CPPIRPM",
"modifierDataType": {
"code": "rate",
"name": "#notnull"
},
"name": "#notnull",
"nameKey": "Product_CommercialPackage.Modifier_CPPIRPM.Name",

266 Modifiers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"priority": -1,
"rateFactors": [
{
"defaultMaximum": "0.05",
"defaultMinimum": "-0.05",
"id": "z0hi6ldfeujdpddo0f1hjou9r49",
"name": "#notnull",
"priority": 1,
"rateFactorType": {
"code": "Building",
"name": "#notnull"
}
},
{
"defaultMaximum": "0.03",
"defaultMinimum": "-0.03",
"id": "zo8h89djdetef2d1nfvvjst1r3a",
"name": "#notnull",
"priority": 2,
"rateFactorType": {
"code": "Employees",
"name": "#notnull"
}
},
{
"defaultMaximum": "0.07",
"defaultMinimum": "-0.07",
"id": "zsrha43mufo20ahpqut8gs8mk4a",
"name": "#notnull",
"priority": 3,
"rateFactorType": {
"code": "Location",
"name": "#notnull"
}
},
{
"defaultMaximum": "0.08",
"defaultMinimum": "-0.08",
"id": "zuch6p28k1rjbf4n29m29fqbg69",
"name": "#notnull",
"priority": 4,
"rateFactorType": {
"code": "Management",
"name": "#notnull"
}
},
{
"defaultMaximum": "0.05",
"defaultMinimum": "-0.05",
"id": "zo0i2mgj33jnberjeomo2fcdd3a",
"name": "#notnull",
"priority": 5,
"rateFactorType": {
"code": "Premises",
"name": "#notnull"
}
},
{
"defaultMaximum": "0.02",
"defaultMinimum": "-0.02",
"id": "z91j6pugcp57188kedd1ko0e7d8",
"name": "#notnull",
"priority": 6,
"rateFactorType": {
"code": "Protection",
"name": "#notnull"
}
}
],
"scheduleRate": true
}
},
…

To retrieve the modifiers that apply to the HOPLine (which is a line under the HOPHomeowners product in the base
configuration), use the following command:
Command

GET /productdefinition/v1/lines/HOPLine/modifiers

Response

{
"data": [

Modifiers 267
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"attributes": {
"description": "",
"descriptionKey": "PolicyLine_HOPLine.Modifier_HOPMultiPolicy.Description",
"id": "HOPMultiPolicy",
"modifierDataType": {
"code": "boolean",
"name": "boolean"
},
"name": "Multi Policy",
"nameKey": "PolicyLine_HOPLine.Modifier_HOPMultiPolicy.Name",
"priority": 100,
"referenceDateByType": {
"code": "PolicyTerm",
"name": "Policy Term"
}
}
},
…
],

You can also retrieve the modifiers for the coverables on a line. The following example retrieves the modifiers for the
HOPDwelling coverable on the HOPLine LOB.
Command

GET /productdefinition/v1/lines/HOPLine/coverables/HOPDwelling/modifiers

Response

{
"data": [
{
"attributes": {
"description": "",
"descriptionKey": "PolicyLine_HOPLine.Modifier_HOPMannedSecurity.Description",
"id": "HOPMannedSecurity",
"modifierDataType": {
"code": "boolean",
"name": "boolean"
},
"name": "Manned Security",
"nameKey": "PolicyLine_HOPLine.Modifier_HOPMannedSecurity.Name",
"priority": 200,
"referenceDateByType": {
"code": "PolicyTerm",
"name": "Policy Term"
}
}
},
…

Line-level and object-level modifiers

When a job is created, specific modifier values are attached either to the line itself (such as a MultiPolicyDiscount
modifier) or to an object on that line (such as a vehicle with an AntiLockBreaks discount).

Modifier endpoints
Every line has endpoints to get a collection of modifiers, and to get or modify a modifier element. These endpoints
follow these patterns:
• Line-level modifiers
◦ GET /jobs/{jobId}/lines/{lineId}/modifiers
◦ GET /jobs/{jobId}/lines/{lineId}/modifiers/{modifierId}
◦ PATCH /jobs/{jobId}/lines/{lineId}/modifiers/{modifierId}
• Object-level modifiers
◦ GET /jobs/{jobId}/lines/{lineId}/{objectName}/{objectNameId}/modifiers
◦ GET /jobs/{jobId}/lines/{lineId}/{objectName}/{objectNameId}/modifiers/{modifierId}

268 Modifiers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ PATCH /jobs/{jobId}/lines/{lineId}/{objectName}/{objectNameId}/modifiers/{modifierId}
For example, personal auto lines can have line-level modifiers and modifiers attached to vehicles. For a personal auto
line, the endpoints to work with modifiers might be:
• Line-level modifiers
◦ GET /jobs/{jobId}/lines/PersonalAutoLine/modifiers
◦ GET /jobs/{jobId}/lines/PersonalAutoLine/modifiers/{modifierId}
◦ PATCH /jobs/{jobId}/lines/PersonalAutoLine/modifiers/{modifierId}
• Object-level modifiers
◦ GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/modifiers
◦ GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/modifiers/{modifierId}
◦ PATCH /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/modifiers/{modifierId}

Creating modifiers
When a line or modifiable object is created, a set of modifier objects is automatically created. Thus, there are no
POST /modifiers or DELETE /modifiers endpoints.
You cannot specify defaults in the product definition. Modifiers might have built-in default values, depending on the
type:
• For Boolean modifiers, PolicyCenter defaults them value to false.
• For schedule rate modifiers, PolicyCenter defaults the rateOverride to $0.
• For all other modifiers, there are no default values.
Modifier values are always expressed as one of the following datatypes: Boolean, date, rate (decimal), or typekey.

Retrieving modifiers and their values

Use the following endpoints to retrieve modifiers and their values.

Type of modifiers Endpoint

Line-level modifiers GET /jobs/{jobId}/lines/{lineId}/modifiers
GET /jobs/{jobId}/lines/{lineId}/modifiers/{modifierId}
Object-level modifiers GET /jobs/{jobId}/lines/{lineId}/{objectName}/{objectNameId}/modifiers
GET /jobs/{jobId}/lines/{lineId}/{objectName}/{objectNameId}/modifiers/
{modifierId}

The following is the syntax for the fundamental attributes of a modifier:

"attributes": {
"id": "PAMultiPolicyDiscount",
"modifierType": {
"code": "<modifierTypeCode>"
},
"booleanModifier": <value>,
"dateModifier": "<value">,
"rateModifier": "<value>",
"typekeyModifier": {
"code": "<value>"
}
},

For any given modifier, the id and modifierType are always included in the response. If the modifier has been set to a
value, then the corresponding *Modifier property is also included. If the modifier is a typekey modifier, the typelist
that defines its values is specified in the product definition. If the modifier has not been set, the response has no
*Modifier property.

Modifiers 269
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Note that even though the Modifier schema has multiple *Modifier fields, for a given modifier only one of them will
have a value. The other *Modifier fields will be null.
For example, the following are modifiers for a Personal Auto vehicle. Note the following:
• The first modifier is a Boolean modifier and has been set to false.
• The second modifier is a typekey modifier and has been set to alarmonly. (Based on the product definition, this
modifier uses the AntiTheftType typelist.)
• The third modifier is also a typekey modifier, but its value has not been set.

{
"attributes": {
"id": "PAAntiLockBrakes",
"modifierType": {
"code": "boolean"
}
"booleanModifier": false,
}
},
{
"attributes": {
"id": "PAAntiTheft",
"modifierType": {
"code": "typekey"
},
"typekeyModifier": {
"code": "alarmonly"
}
}
},
{
"attributes": {
"id": "PAPassiveRestraint",
"modifierType": {
"code": "typekey",
"name": "typekey"
}
}
}
...

Specifying modifier values

To specify a value for a modifier, use the following endpoints.

Type of modifiers Endpoint

Line-level modifiers PATCH /jobs/{jobId}/lines/{lineId}/modifiers/{modifierId}
Object-level modifiers PATCH /jobs/{jobId}/lines/{lineId}/{objectName}/{objectNameId}/modifiers/
{modifierId}

For example, the following call sets the value of the PAPassiveRestraint modifier on vehicle 505 to "Driver Side Only"
(code driver from the PassiveRestraintType typelist).
Command

PATCH /job/v1/jobs/pc:1111/lines/PersonalAutoLine/vehicles/505/modifiers/PAPassiveRestraint

Response

{
"data": {
"attributes": {
"typekeyModifier": {
"code": "driver"
}
}
}
}

270 Modifiers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Modifier validation
Default validation for modifiers
In most cases, PolicyCenter does not allow the following behaviors:
• Setting the values for an unavailable modifier.
• Setting the value for the rateModifier field outside of the min/max range.
• Setting the value for rate factors on the modifier outside of the min/max range.
Some of these behaviors may occur as the result of a submission becoming out of sync. In these cases, you can rectify
the situation by calling the appropriate /sync-modifiers endpoint. For more information, see “Synchronization and
deferred validation” on page 283.

Deferring validation
For Cloud API, the default validation behavior is referred to as immediate validation. In this approach, validation is
provided with each call. A validation error in one call can prevent later calls from executing. This approach is
appropriate for caller applications that build submissions interactively, such as those backing a user interface.
There is a second behavior called deferred validation. In this approach, validation takes place only after the caller
application has put the submission into what it believes to be a consistent state. This is an option for non-interactive
caller applications with sufficient authorization. This approach can simplify submission processing by preventing
validation checks when the submission is known to potentially be in an inconsistent state. This approach can also
reduce the need to determine whether modifiers need to be synchronized.
For more information on deferred validation, see “Synchronization and deferred validation” on page 283.

Modifiers 271
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

272 Modifiers
chapter 27

Questions

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
This topic discusses how to work with questions.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Overview of questions
From an LOB perspective, a question is a prompt for information that can be used to pre-qualify an account holder or
obtain additional information for rating a policy.
Questions are grouped together into question sets. There are three elements of a product that a question set can be
associated with:
• The policy period
• The line
• A policy location
Questions 273
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

When a policy period, line, or policy location is created, a set of QuestionAnswers are created for any associated
questions as defined in the product definition. Each QuestionAnswer stores a question and its answer, if an answer has
been provided.

LOB-endpoint pattern for questions

For every question set, there is a set of two endpoints:
• GET .../questions
◦ Retrieves all possible questions and their answers
• PATCH .../questions
◦ PATCHes the answers to one or more questions
There can be multiple pairs of question endpoints, depending on how many question sets a product has and where those
questions sets are attached to the product.
Policy period question set endpoints exist at the job level. From a technical perspective, these are not LOB-specific
endpoints. There is a single pair of endpoints for all products:
• GET /job/v1/jobs/{jobId}/questions
• PATCH /job/v1/jobs/{jobId}/questions
Line question set endpoints exist at the line level. These are LOB-specific endpoints. There is one pair of endpoints
for each line question set in each product. For example:
• GET /job/v1/jobs/{jobId}/lines/{lineId}/questions
• PATCH /job/v1/jobs/{jobId}/lines/{lineId}/questions
Location question set endpoints exist at the location level. From a technical perspective, these are not LOB-specific
endpoints. There is a single pair of endpoints for all products:
• GET /job/v1/jobs/{jobId}/locations/{locationId}/questions
• PATCH /job/v1/jobs/{jobId}/locations/{locationId}/questions

Answering questions
Use the following endpoints to retrieve all questions and their answers for a policy period, line, or policy location.

Type of questions Endpoint

Policy period questions GET /job/v1/jobs/{jobId}/questions
Line questions GET /jobs/{jobId}/lines/{lineId}/questions
Location questions GET /jobs/{jobId}/locations/{locationId}/questions

Structure of a QuestionAnswer
A QuestionAnswer is a resource that stores a single question for a job or policy and its answer, if any.
The datatype of a question's answer depends on the nature of the question itself. For example, "Is the driver legally
blind?" has a Boolean answer, but "What was the date of the most recent safety course completed?" has a datetime
answer.
To accommodate the varying datatype of an answer, a QuestionAnswer has a questionType property. This identifies
the datatype of the answer. It is set to one of the following: Boolean, Choice, Date, Integer, String.
There are also a set of datatype-specific ...Value properties: booleanValue, choiceValue, dateValue,
integerValue, textValue. For a given QuestionAnswer, the answer is stored in the ...Value property that
corresponds to the questionType. The ...Value properties that are not relevant are set to null.

274 Questions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Some questions do not require an answer. If a question has no answer, there is still a QuestionAnswer for it, but all of
its ...Value properties are null.
There is also a displayValue property. This stores the question's answer, if any, converted to a string.

Structure of a /questions response

The response to a GET /questions has a single answers attribute. This attribute contains a map of QuestionAnswers.
Each QuestionAnswer has the following syntax:

"<questionId>": {
"question": {
"displayName": "<displayText>"
"id": "<questionId>"
},
"questionType": {
"code": "<questionTypeCode>",
},
"displayValue": "<value>",
"booleanValue": <value>,
"choiceValue": {
"code": "<choiceValueCode",
},
"dateValue": "<value>",
"integerValue": <value>,
"textValue": "<value>",
},

For any given question, some values are always set and some values are always null. If a property has a null value, it is
not included in the response. The following table defines how each value is set.

Property How the value is set

question Always included. It contains the id of the question and the displayName, which is the text shown on the user
interface to pose the question.
questionType Always included. It contains the questionTypeCode, which is one of the following: Boolean, Choice, Date,
Integer, String
displayValue Set to the display value of the answer, if the question has an answer. Otherwise, set to null.
booleanValue Set to a Boolean value if the questionType is Boolean and the question has been answered. Otherwise, set to
null.
choiceValue Set to a choiceValueCode if the questionType is Choice and the question has been answered. Otherwise,
set to null. (The acceptable choiceValueCode values for a given question are defined in the product definition
and can vary from question to question.)
dateValue Set to a date value if the questionType is Date and the question has been answered. Otherwise, set to null.
integerValue Set to an integer value if the questionType is Integer and the question has been answered. Otherwise, set to
null.
textValue Set to a string value if the questionType is String and the question has been answered. Otherwise, set to
null.

Note that for any given question that has an answer, there are four values that are included:
• question (the question id)
• questionType (the datatype of the answer)
• displayValue (the answer, rendered as a string)
• The ...Value field corresponding to the questionType (the answer, rendered as its native datatype)
Even though the QuestionAnswer schema has multiple ...Value fields, for a given QuestionAnswer that has an
answer, only one of them has a value. The other ...Value fields are null. (If the question has no answer, all of
the ...Value fields are null.)

Examples of answer responses

This is an example of a response to a GET /questions.

Questions 275
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The first question, MovingViolations2, is a Boolean question. Its answer is true.

{
"data": {
"attributes": {
"answers": {
"MovingViolations2": {
"question": {
"displayName": "Any drivers with convictions for moving traffic violations within
the past 3 years? If 'Yes' please explain.",
"id": "MovingViolations2"
},
"questionType": {
"code": "Boolean"
},
"displayValue": "true",
"booleanValue": true
},
...

The second question, DriverNameConviction, is a string question. Its answer is "Driving without a license".

...
"DriverNameConviction": {
"question": {
"displayName": "Please provide the driver name and explain the conviction.",
"id": "DriverNameConviction"
},
"questionType": {
"code": "String"
},
"displayValue": "Driving without a license",
"textValue": "Driving without a license"
},
...

The third question, PACurrentlyInsured, is a choice question. Its answer is a question-specific code from the product
design (newdriver, which has a display value of "No - New driver").

...
"PACurrentlyInsured": {
"question": {
"displayName": "Is the applicant currently insured?",
"id": "PACurrentlyInsured"
},
"questionType": {
"code": "Choice"
},
"displayValue": "No - New Driver",

"choiceValue": {
"code": "newdriver",
"name": "No - New Driver"
}
},
...

The fourth question, CurrentSuspense, is a Boolean question. It has not been answered, so its displayValue and
booleanValue properties are null and therefore not included in the response.

...
"CurrentSuspense": {
"question": {
"displayName": "Is the applicant's license currently suspended, canceled, or revoked?",
"id": "CurrentSuspense"
},
"questionType": {
"code": "Boolean"
}
},
...

Specifying answers
To specify a question answer, use the following endpoints.

276 Questions
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Type of questions Endpoint

Policy period questions PATCH /job/v1/jobs/{jobId}/questions

Line questions PATCH /jobs/{jobId}/lines/{lineId}/questions

Location questions PATCH /jobs/{jobId}/locations/{locationId}/questions

You can specify one or more answers. Each answer must have the following syntax:

"<questionId>": {
"booleanValue": <value>,
"choiceValue": {
"code": "<choiceValueCode",
},
"dateValue": "<value>",
"integerValue": <value>,
"textValue": "<value>",
},

You must provide the ...Value property whose type matches the question type, and no other ...Value property. For
example, to answer a Boolean question, you must specify booleanValue and only booleanValue.
The following is an example of providing two answers to the job in the previous example.

PATCH /job/v1/jobs/pc:1111/questions

{
"data": {
"attributes": {
"answers": {
"CurrentSuspense": {
"booleanValue": true
},
"PACurrentlyInsured": {
"choiceValue": {
"code": "notknown"
}
}
}
}
}
}

Note that the answers property is a map and not an array.

• The members of the answers property are not enclosed in square braces ([ ]).
• Each member of the map is identified by its question ID.
• Unlike arrays, PATCHes to maps are not destructive. The only members that are modified are the members
specified in the PATCH. Members that are not specified in the PATCH are neither removed nor changed.

Question validation
Default validation for questions
In most cases, PolicyCenter restricts the following behavior:
• Cannot set the value for an unavailable Question
This behavior may be the result of the submission becoming out of sync. In these cases, you can rectify the situation by
calling the appropriate /sync-questions endpoint. For more information, see “Synchronization and deferred
validation” on page 283.

Deferring validation
For Cloud API, the default validation behavior is referred to as immediate validation. In this approach, validation is
provided with each call. A validation error in one call can prevent later calls from executing. This approach is
appropriate for caller application the build submissions interactively, such as those backing a user interface.

Questions 277
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

There is a second behavior called deferred validation. In this approach, validation takes place only once the caller
application has put the submission into what it believes to be a consistent state. This is an option for non-interactive
caller applications with sufficient authorization. This approach can simplify submission processing by preventing
validation checks when the submission is known to potentially be in an inconsistent state. This approach can also
reduce the need to determine if questions need to be synchronized.
For more information on deferred validation, see “Synchronization and deferred validation” on page 283.

278 Questions
chapter 28

Exposures, exclusions, and conditions

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
• Users assigned to the job
This topic discusses how to work with exposures, exclusions, and conditions.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Overview of exposures, exclusions, and conditions

Exposures, exclusions, and conditions provide additional information about the policy.
• An exposure defines additional information to help rate or process a coverage
• An exclusion is a limit to a coverage that defines circumstances where the coverage does not apply
• A condition is a contractual obligation of the insurance policy that is neither a coverage nor an exclusion.

Exposures, exclusions, and conditions 279

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Unlike coverables, coverages, modifiers, and questions, there is no data structure or behavior common to all exposures
or to all exclusions or to all conditions. Each type of object has different implications for the legal extent of the policy
or how it is rated. But from a technical perspective, they behave in a similar way.

LOB-endpoint pattern for exposures

For every exposure, there are endpoints to get a collection of exposures, and to create, get, modify, and delete an
exposure element. These endpoints follow these patterns:
• GET /jobs/{jobId}/lines/{lineId}/{exposureName}
• POST /jobs/{jobId}/lines/{lineId}/{exposureName}
• GET /jobs/{jobId}/lines/{lineId}/{exposureName}/{exposureId}
• PATCH /jobs/{jobId}/lines/{lineId}/{exposureName}/{exposureId}
• DELETE /jobs/{jobId}/lines/{lineId}/{exposureName}/{exposureId}
For example, in personal auto lines, information about vehicle drivers can change how the coverages are rated or
processed. Thus, a vehicle has one or more driver exposures. For a personal auto line, the endpoints to work with
drivers might be:
• GET /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/drivers
• POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles/{vehicleId}/drivers
• GET /jobs/{jobId}/lines/{lineId}/{vehicles}/{vehicleId}/drivers/{driverId}
• PATCH /jobs/{jobId}/lines/{lineId}/{vehicles}/{vehicleId}/drivers/{driverId}
• DELETE /jobs/{jobId}/lines/{lineId}/{vehicles}/{vehicleId}/drivers/{driverId}

LOB-endpoint pattern for exclusions and conditions

Unlike exposures, exclusions and conditions do not have their own endpoints. They are included in the /coverages
endpoint for the related coverage. For information on coverage endpoint patterns, see “Overview of coverages” on
page 251.
For example, a commercial liability line could have the following:
• A line-level "Underground Resources and Equipment" exclusion
• A line-level "Use of Explosives Limitation" condition
For a commercial liability line, the endpoints to work with this exclusion and condition would be the same as the
endpoint to work with the line-level coverages:
• GET /jobs/{jobId}/lines/CommercialLiabilityLine/coverages
• POST /jobs/{jobId}/lines/CommercialLiabilityLine/coverages
• GET /jobs/{jobId}/lines/CommercialLiabilityLine/coverages/{coverageId}
• PATCH /jobs/{jobId}/lines/CommercialLiabilityLine/coverages/{coverageId}
• DELETE /jobs/{jobId}/lines/CommercialLiabilityLine/coverages/{coverageId}

Adding exposures, exclusions, and conditions

Adding exposures
To add exposures, use the appropriate LOB-specific endpoint. For example, the Personal Auto line of business has a
driver exposure. The endpoint for creating drivers is POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles/
{vehicleId}/drivers.

280 Exposures, exclusions, and conditions

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following request payload is an example of creating a driver for the vehicle in the previous example. The driver is
Bill Preston (pc:78) who drives the previously created Toyota Tercel (103) 100% of the time.

POST /job/v1/jobs/pc:4040/lines/PersonalAutoLine/vehicles/103/drivers

{
"data": {
"attributes": {
"percentageDriven": 100,
"policyDriver": {
"id": "pc:78"
}
}
}
}

Adding exclusions and conditions

To add exclusions or conditions, use the appropriate LOB-specific /coverages endpoint.
For example, a Commercial Liability line of business could have a GLUndergroundResources exclusion and a
GLUseOfExplosives condition. The following request payload is an example of adding these to the policy.

POST /job/v1/jobs/pc:6788/lines/CommercialLiabilityLine/coverages/GLUndergroundResources

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

POST /job/v1/jobs/pc:6788/lines/CommercialLiabilityLine/coverages/GLUseOfExplosives

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

Exposures, exclusions, and conditions 281

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

282 Exposures, exclusions, and conditions

chapter 29

Synchronization and deferred

validation

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
This topic discusses the need to synchronize policy data, how you can defer validation, and how you can disable the
creation of default values.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Out-of-sync policy data

Availability and requiredness logic
In PolicyCenter, a policy is represented as a hierarchy of objects. The hierarchy includes coverables, coverages,
questions, modifiers, exposures, exclusions, and conditions. Typically, these objects do not exist independently from
Synchronization and deferred validation 283
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

one another. Rather, the product definition defines logic that identifies how the state of one object can determine
whether another object must or must not exist.
This type of logic typically falls into two categories: availability logic and requiredness logic.
Availability logic identifies when a given object is available or unavailable, depending on the state of another object.
For example, a Personal Auto product for the US could have logic that states a "PIP - Oregon" coverage is available for
a vehicle only if the vehicle is garaged in Oregon. Thus:
• The coverage is available if the vehicle is in Oregon.
• The coverage is not available if the vehicle is not in Oregon.
Requiredness logic identifies when a given object is required, depending on the state of another object. For example, a
Personal Auto product could have logic that states if the value of a vehicle is over $50,000, then a "no drivers under the
age of 25" exclusion is required. Thus:
• The exclusion is required if the vehicle's value is over $50,000.
• The exclusion is not required if the vehicle's value is $50,000 or less.

Out-of-sync policies
When you create a policy through Cloud API, there is no requirement as to the order in which objects are created or
modified. As a result, the structure of a policy may become out-of-sync. An out-of-sync policy is a policy which has
objects or logic that are inconsistent with each other.
There are two primary ways in which a policy can become out-of-sync: inconsistency with availability logic, and
inconsistency with requiredness logic.

Inconsistency with availability logic

Availability calculations are cached. This means that the set of available fields, coverages, coverage terms, and so on
reflect what was available when the object was created or when the data was last synced. If you change an object
without synchronizing the data, the availability calculations could identify that something is available when it should
not be, or that something is not available when it should be. This can prevent you from adding allowed objects to the
policy. It can also fail to prevent you from adding prohibited objects to the policy.
For example, suppose there is a Personal Auto product for the US with logic that states:
• "PIP - Oregon" coverage is available for a vehicle only if the vehicle is garaged in Oregon.
• "PIP - Washington" coverage is available for a vehicle only if the vehicle is garaged in Washington.
You create a vehicle in Oregon. The availability calculations for the vehicle are cached, indicating that you can add
"PIP - Oregon" coverage. Later, you change the vehicle's location to Washington. At this point, "PIP - Oregon"
coverage should not be allowed, and "PIP - Washington" coverage should be allowed. But because the availability
calculation was cached when the vehicle was created, "PIP - Washington" coverage is not allowed, and "PIP - Oregon"
coverage is.

Inconsistency with requiredness logic

When one object is created, other objects may be required and may be created automatically. However, if the state of
the first object is changed, the related objects are not updated automatically.
For example, suppose that a Personal Auto product has logic that states if the value of a vehicle is over $50,000, then a
"no drivers under the age of 25" exclusion is required. You create a vehicle whose value is under $50,000. The
exclusion is not required and not created automatically. Later, you change the value of the vehicle to more than
$50,000. At this point, the exclusion is required, but it is not created automatically.
This type of out-of-sync data may not prevent you from building the policy. But when you attempt to quote the policy,
quoting validation fails because required objects are missing.

284 Synchronization and deferred validation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Resolving out-of-sync data

When a policy's data becomes out-of-sync, you can fix the situation by synchronizing the data. The Job API includes a
set of /sync endpoints that synchronize job data. For more information, see “The /sync endpoints” on page 285.
You can also use a set of query parameters to defer validation. This gives you the ability to suppress validation checks
while the policy is known to be in an inconsistent state. For more information, see “Deferring validation” on page 287.

The /sync endpoints

Every line of business has a set of /sync... endpoints that can address issues with out-of-sync data. The following
sections cover each set of endpoints and what how they synchronize data.

The /sync-coverages endpoints

An LOB can have the following /sync-coverages endpoints:
• POST /jobs/{jobId}/lines/{lineId}/sync-coverages
• POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-coverages
Note that coverages can be nested. For a given line of business, there could be a POST that starts with POST /jobs/
{jobId}/lines/{lineId}/{coverableName}/{coverableId}, which is then followed by one of more instances of /
{coverableName}/{coverableId} before terminating with /sync-coverages.

Generating the endpoints

During code generation, APD adds these endpoints to every coverable, including the line itself (if it is a coverable).

Endpoint behavior
When you execute a POST /sync-coverages, Cloud API:
• Adds missing available-and-required coverages, conditions, and exclusions
• Removes unavailable coverages, conditions, and exclusions
• Adds missing covterms to coverages, conditions, and exclusions
• Removes unavailable covterms from coverages, conditions, and exclusions
• Resets the value if a covterm has an unavailable option, unavailable package, or unavailable or retired typekey as its
current value. (The value is set to the default, or null if there is no default.)

The /sync-fields endpoints

An LOB can have the following /sync-fields endpoints:
• POST /jobs/{jobId}/lines/{lineId}/sync-fields
• POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-fields
• POST /jobs/{jobId}/lines/{lineId}/.../{exposureName}/{exposureId}/sync-fields

Generating the endpoints

During code generation, APD adds these endpoints to every coverable (including the line itself) and every exposure
that meet the following conditions:
• The coverable or exposure already exists in the data model and the corresponding data model entity implements the
SyncableAdapter interface, or
• The coverable or exposure does not already exist in the data model. (This occurs when you are generating entities
and endpoints at the same time for a new APD line).

Synchronization and deferred validation 285

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

If the data model entity for the coverable of exposure does not implement the SyncableAdapter interface, the /sync-
fields endpoints are not generated. This can occur in the following circumstances:

• In some releases prior to the current release, Cloud API did not add the SyncableAdapter interface to new
coverables and exposures. Thus, the code generation for those releases did not create /sync-fields endpoints.
(Regenerating the LOB-specific endpoints on the current release will most likely generate the /sync-fields
endpoints.)
• Lines of business that are not native to APD (such as base configuration LOBs or SBT lines) typically have
coverables and exposures that do not implement the SyncableAdapter interface. Therefore, LOB-specific
endpoints for these LOBs do not have /sync-fields endpoints.

Endpoint behavior
When you execute a POST /sync-fields, Cloud API:
• "Adds" missing available fields
• "Removes" unavailable fields
• Nulls out the value of any fields that have unavailable typekeys as their value

The /sync-modifiers endpoints

An LOB can have the following /sync-modifiers endpoints:
• POST /jobs/{jobId}/lines/{lineId}/sync-modifiers
• POST /jobs/{jobId}/lines/{lineId}/{coverableName}/{coverableId}/sync-modifiers
• POST /jobs/{jobId}/lines/{lineId}/.../{exposureName}/{exposureId}/sync-modifiers

Generating the endpoints

During code generation, APD adds these endpoints to every coverable that meets one of the following conditions:
• The coverable is already declared in the data model and the data model entity implements the Modifiable
interface, or
• The coverable is part of a product that was originally designed outside of APD (such as a base configuration
product or a product from a Standards-Based Template).
These endpoints are added for installed products only. They are not present for visualized products.

Endpoint behavior
When you execute a POST /sync-modifiers, Cloud API:
• Adds missing available modifiers
• Removes unavailable modifiers
• Updates the state on modifiers to make sure it matches the state of the parent entity
• Adds missing available rate factors to modifiers
• Removes unavailable rate factors from modifiers

The /sync-questions endpoints

An LOB can have the following /sync-questions endpoints:
• POST /jobs/{jobId}/sync-questions
• POST /jobs/{jobId}/lines/{lineId}/sync-questions
• POST /jobs/{jobId}/locations/{locationId}/sync-questions
There can also be /sync-questions endpoints for any coverable or exposure that has been made an AnswerContainer.

286 Synchronization and deferred validation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Generating the endpoints

In the base configuration, these endpoints already exist for the job itself and for policy locations.
During code generation, APD adds endpoints to:
• Every location-based coverable
◦ This type of endpoint is essentially proxy for calling /sync-questions on the linked policy location.
• Every policy line, because the base configuration PolicyLine entity implements the AnswerContainer interface
• Any other coverables or exposures that are already declared in the data model and the data model entity implements
the AnswerContainer interface
These endpoints are added for installed products only. They are not present for visualized products.

Endpoint behavior
When you execute a POST /sync-questions, Cloud API:
• Adds answer entities to hold the answer for any missing available questions
• Removes answers for any unavailable questions

When to call a /sync endpoint

The need to sync coverables, coverages, modifiers, or questions depends on the structure of the LOB and the order in
which a given caller application makes changes. Therefore, it is up to the caller application to determine when a /sync
endpoint must be called. Note the following:
• From a data integrity standpoint, there is no harm in calling a /sync endpoint, even when all information is already
in sync.
• From a performance standpoint, calling a /sync endpoint does require system resources. A caller application's
performance could be compromised unnecessarily if it makes repeated calls to /sync endpoints when the coverage
data is already in sync.
As an alternative to synchronizing job data, you can also defer validation. For more information, see “Deferring
validation” on page 287.

Deferring validation
During submission processing, PolicyCenter executes validation to ensure a submission meets all requirements. For
example, suppose an insurer has a rule stating that all Personal Auto vehicles must have collision coverage. As the
submission is being created, PolicyCenter identifies any vehicles without collision coverage and prevents further
processing until the coverage is added.
For Cloud API, this default validation behavior is referred to as immediate validation. In this approach, validation is
provided with each call. A validation error in one call can prevent later calls from executing. This approach is
appropriate for caller applications that build submissions interactively, such as those backing a user interface.
There is a second behavior called deferred validation. In this approach, validation takes place only after the caller
application has put the submission into what it believes to be a consistent state. This is an option for non-interactive
caller applications with sufficient authorization. This approach can simplify submission processing by preventing
validation checks when the submission is known to be in an inconsistent state.

The deferValidation query parameter

Deferred validation is implemented by use of the deferValidation query parameter. This is a Boolean query
parameter that defaults to false. It is available on the following sets of endpoints:
• Coverable endpoints (such as POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles)

Synchronization and deferred validation 287

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Coverage endpoints (such as POST /jobs/{jobId}/lines/{lineId}/coverages)

• Question endpoints (such as POST /job/v1/jobs/{jobId}/questions)
• Graph submission endpoint (POST /graph/v1/submissions)
When the query parameter is set to true, the following behaviors are implemented:
• POST/PATCH of a coverable
◦ Disable availability and editability checking for risk model fields. If a risk model field is unavailable, its
availability bit will be set and it will be updated anyway.
◦ Disable availability checking for typekeys
◦ Disable min/max checking for risk model fields
• POST/PATCH of a coverage
◦ Disable availability checking of the coverage (or condition or exclusion) itself
◦ Disable availability and editability checking of coverage terms. If a coverage term is unavailable, it will be
created and set anyway during the update.
◦ Disable availability checking on coverage term options and packages
◦ Disable availability checking on coverage term typekeys
◦ Disable min/max checking on direct and datetime covterms
• DELETE of a coverage
◦ Allow deletion even if the coverage is marked as required
• PATCH of question answers
◦ Force creation of the associated AnswerDelegate entity if it has not already been created, which means it was
unavailable the last time questions were synced
• POST of graph submissions
◦ All the POST behaviors listed above
For example, suppose Personal Auto submission pc:6066 has vehicle 103, which is located in Oklahoma. The caller
application plans to do the following:
1. PATCH the vehicle so that it is located in Texas
2. POST a "PIP - Texas" coverage to the vehicle
The POST will fail. This is because, when the vehicle was created, the availability logic was cached. This logic
identifies that the vehicle is in Oklahoma.
There are two solutions to the problem. You could execute a POST /vehicles/{vehicleId}/sync-coverages before
POSTing the coverage. Alternately, you could use the deferValidation query parameter when POSTing the coverage
For example:

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles/103/coverages?deferValidation=true

You cannot defer validation when quoting a job. Validation is always executed when the job is quoted.

Authorization to defer validation

The deferValidation query parameter is not available to all callers by default. In order to use the query parameter,
the caller must be associated with a role whose role.yaml file has the deferProductModelValidation special
permission.
For more information on authorization and special permissions, see the Cloud API Developer Guide.

288 Synchronization and deferred validation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Limitations to deferred validation

The deferValidation query parameter can reduce the number of times you need to call the /sync endpoints. For
example, the query parameter lets you set values that are unavailable given the current state of the job, but that will be
available by the time the job data is complete. (Without the query parameter, you would need to call the appropriate /
sync endpoint before adding the unavailable values.)

However, the query parameter may not entirely eliminate the need to call the /sync endpoints. For example, suppose
you are modifying a job using deferred validation. Initially, there is a coverage that is unavailable. Later, the state of the
job data causes the coverage to become available, and the coverage is required when it is available. Because validation
has been deferred, there is no indication that a required coverage is missing until you attempt to quote the job. Once the
quote fails validation, you will still need to call the appropriate /sync endpoint.

Default value creation

In some cases when you create certain resources, children of those resources are also created by default. This isn’t
always a desirable behavior. When creating a new submission, there are query parameters that prevent the automatic
creation of certain resources on the job.

The createDefaultCoverages query parameter

By default, when you create a coverable, PolicyCenter automatically creates all coverages (and conditions and
exclusions) that meet the following criteria:
• They are available when the call is made
• They have an existence type of "Required" or "Suggested"
Sometimes, a job may not want these default coverages. But it can be cumbersome for a caller to determine what
coverages were added automatically and then remove the undesired ones. In these situations, it may be easier to have a
coverable with no default coverages.
You can create a coverable without default coverages using the createDefaultCoverages query parameter. This is a
Boolean query parameter whose default is true. It is available on the following sets of endpoints:
• Line endpoints
◦ For example, POST /jobs/{jobId}/lines
◦ Note that POST /lines endpoints are present only for multi-line products
• Non-line coverable endpoints
◦ For example, POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles
• The POST /job/v1/submissions endpoint
◦ This suppresses the creation of coverages, conditions, and exclusions on the default policy lines.
◦ This also suppresses the creation of coverages, conditions, and exclusions on any coverable that is created
automatically, such as a Commercial Property's default primary location coverable.
• The POST /graphs/v1/submissions endpoint
• ◦ All the preceding behaviors on the Job API endpoints are performed on the Graph API endpoint.
When the query parameter is set to false, the following behaviors are implemented:
• POST of a coverable
◦ Disable creation of default coverages, exclusions, and conditions
For example, suppose you have Personal Auto submission pc:6066. A vehicle is POSTed to the submission. The
following call will create the vehicle with all default coverages.

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles

Synchronization and deferred validation 289

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

In contrast, the following call will also create the vehicle, but with no default coverages.

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles?createDefaultCoverages=false

This query parameter does not have special permissions. Any caller that can access coverable endpoints can also use
this query parameter.

The createCoveredLocationForPrimaryLocation query parameter

By default, when a submission is initially created many property LOBs will automatically create a line-specific
covered location for the primary location on a policy. However, this behavior can be undesirable in the context of a
Composite API or graph POST submissions request. Because the ID of an automatically-created covered location can't
be known ahead of time, there's no way to update that location in the same request. For example, there is no way to
automatically create the location and then attach buildings or coverages to it within the composite request or the Graph
API /submissions request.
Set the createCoveredLocationForPrimaryLocation query parameter to false to disable the creation of a default
covered location. This allows the caller to explicitly create the covered location as a separate request so that its ID can
be known (in a composite request) or so that it can have children specified (in a graph POST request).
This query parameter is true by default. It’s available on the following endpoints:
• POST /job/v1/submissions
• POST /graph/v1/submissions

290 Synchronization and deferred validation

chapter 30

Policy contacts

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
This topic discusses how to work with policy contacts.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Overview of policy contacts

In PolicyCenter, every job has an underlying policy. You can associate account contacts with this policy. For example,
when a submission is created for an account, the default behavior is to associate the account's "primary insured" contact
with the underlying policy as the "primary named insured". A contact associated with a policy is known as a policy
contact. Policy contacts exist on policies that are unbound (such as a submission's underlying policy) and on policies
that are bound.
In the PolicyCenter data model, there is no PolicyContact entity. Policy contacts are stored in the database using
multiple entities:

Policy contacts 291

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• The Contact entity

• The AccountContact entity
• One or more PolicyContactRole entities
In Cloud API, policy contacts are managed using a resource named PolicyContact. This resource gathers the
information from multiple data model entities (Contact, AccountContact, and PolicyContactRole).
The following table summarizes the different base configuration /contact endpoints in each API and the resources
used by those endpoints.

API Example endpoints Root resource type

Account GET /account/v1/accounts/{accountId}/contacts AccountContact
POST /account/v1/accounts/{accountId}/contacts
GET /account/v1/accounts/{accountId}/contacts/{contactId}
PATCH /account/v1/accounts/{accountId}/contacts/{contactId}
DELETE /account/v1/accounts/{accountId}/contacts/{contactId}
Job GET /job/v1/jobs/{jobId}/contacts PolicyContact
POST /job/v1/jobs/{jobId}/contacts
GET /job/v1/jobs/{jobId}/contacts/{contactId}
PATCH /job/v1/jobs/{jobId}/contacts/{contactId}
DELETE /job/v1/jobs/{jobId}/contacts/{contactId}
Policy GET /policy/v1/policies/{policyId}/contacts PolicyContact
GET /policy/v1/policies/{policyId}/contacts/{contactId}

Policy contact roles

Some policy contact roles are LOB-agnostic. You can use these roles for contacts on any policy, regardless of the
underlying LOB. In Cloud API, you can specify the following LOB-agnostic roles for a policy contact.

Role's display name Underlying policy role entity

Primary named insured PolicyPriNamedInsured
Additional named insured PolicyAddlNamedInsured
(used for any contact associated with a policy, but not displayed in the user interface) APDPolicyInvolvedParty

Some policy contact roles are LOB-specific. For example, in the base configuration Personal Auto product, adding a
contact to a job's underlying policy using the POST /vehicle-drivers endpoint adds the "driver" role to the contact.
The behavior of LOB-specific roles is dependent on how the product is modeled.
The remainder of this topic discusses how to manage policy contacts and the LOB-agnostic policy contact roles.

Working with all policy contacts on a job

This topic describes the different ways you can work with policy contacts.

Querying for all policy contacts on a job

Use the following endpoints to retrieve information about all contacts for a specific job, regardless of their roles:
• GET /job/v1/jobs/{jobId}/contacts
• GET /job/v1/jobs/{jobId}/contacts/{contactId}

292 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Masking the taxID field

The PolicyContact resource has a taxID field which stores the tax ID of the contact. In the Cloud API base
configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the
response for a GET that retrieves a contact.

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

For some callers, such as internal or external users, the masking of tax ID is appropriate as it protects personally
identifiable information. For other callers, such as services, this masking may cause a problem as the callers may
reference contacts internally using the tax ID.
There are two ways that the taxId field can be unmasked:
• You can configure the field so that it is always unmasked. For information on how to configure this, see the Cloud
API Developer Guide.
• You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission
will get responses with unmasked tax IDs. For information on how to configure this, see the section on API role
special permissions in the Cloud API Developer Guide.

Adding a policy contact

There are two ways in which you can add a contact to a policy:
• Create a new policy contact on the job
• Add an existing account contact to the job

Creating a new policy contact

You can create a new policy contact directly on the job. This will add the contact to both the policy and the account.
Note: The policy must be in Draft status before you can update it with a new policy contact. To move a policy
to Draft status, run the following endpoint:
POST /job/v1/jobs/{jobId}/make-draft
Required fields for creating a policy contact are the same as those for creating an account contact:
• contactSubtype (typically set to either Person or Company)
• firstName and lastName (for Person contacts)
• companyName (for Company contacts)
• primaryAddress, with at least:
◦ addressLine1
◦ city
◦ state
◦ postalCode
Note:

The preceding address information is required only if you’re not creating a contact with a linked address. See
“Linking policy contact addresses” on page 295 below for more information.
Use the following endpoint to add a new policy contact:

Policy contacts 293

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• POST /job/v1/jobs/{jobId}/contacts
For example:
Command

POST /job/v1/jobs/pc:101/contacts

Request Body

{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
}
}
}

Adding an account contact to a job

You can also add an existing account contact to a job.
To associate an existing account contact with a job's policy, use the following endpoint:
• POST /job/v1/jobs/{jobId}/contacts
The request must include an accountContact property that specifies the ID of the existing account contact. For
example, the following request adds the existing account contact pc:97 to job pc:5000.
Command

POST /job/v1/jobs/pc:5000/contacts

Request Body

{
"data": {
"attributes": {
"accountContact": {
"id": "pc:97"
}
}
}
}

Modifying contact policy roles

When you create or add a policy contact, the contact is added to the underlying policy with the
APDPolicyInvoledParty role. This is a generic role that simply identifies the contact as having an association with the
policy.
Once the policy contact has been added, you can modify this role.
• To make the contact the primary named insured on the policy, see “Primary and secondary named insured contacts”
on page 299.
• To make the contact an additional named insured on the policy, see “Adding additional named insureds” on page
301.

Updating and deleting policy contacts

You can update and delete policy contacts with the following endpoints:

294 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• PATCH /job/v1/jobs/{jobId}/contacts
• DELETE /job/v1/jobs/{jobId}/contacts

Updating a policy contact

Use the following endpoint to PATCH a policy contact:
• PATCH /job/v1/jobs/{jobId}/contacts
For example, the following PATCHes contact pc:44 on job pc:1001.
Command

PATCH /job/v1/jobs/pc:1001/contacts/pc:44

Request Body

{
"data": {
"attributes": {
"emailAddress1": "[email protected]"
}
}
}

Note that much of the information about an account contact and a policy contact are stored in the same data model
entity - the Contact entity. Therefore, when you PATCH a policy contact, changes to values stored in the Contact
entity will also be reflected in the account contact.

Deleting a policy contact

When you "delete" a policy contact, the contact is not removed from PolicyCenter. Rather, the contact is removed only
from the policy. The associated account contact remains on the account.
Use the following endpoint to DELETE the association between a policy contact and the policy:
• DELETE /job/v1/jobs/{jobId}/contacts
For example, the following removed contact pc:44 from job pc:1001. (pc:44 will remain on the account.)

DELETE /job/v1/jobs/pc:1001/contacts/pc:44

<no request body>

Linking policy contact addresses

There might be times when you want a contact on a policy to have the same address as another contact on the same
account. Rather than reentering the same information for every contact at the same address, you can use linked contact
addresses. Linking addresses allows you to create or update a contact without reentering address information that exists
elsewhere on the account, and enables you to update an address on all contacts to which it applies with a single
command.
You add and update a linked address to a contact using these properties under the contact’s primaryAddress object:
• linkedAddress: An object containing the address information to link to.
◦ addressId: ID of the address to link to.
◦ contactId: ID of the primary named insured, account holder, or named insured associated with that address.
• linkedAddressUpdateMode: A value that determines how updates to the address are applied. Options are:
◦ update: When this value is specified, any updates to the address will be applied to all contacts to which the
address is linked.

Policy contacts 295

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ unlink: Updates the address only on the contact being updated. When an address is updated with this option
specified, that contact no longer has a linked address. This option removes the link, making this a stand-alone
address on the contact.
After an address has been linked, it includes the following property:
• isLinked: A Boolean value automatically set to true when an address is linked. When this value is true, updates to
the address must include the linkedAddressUpdateMode property.
The following example creates a new contact with a linked address. In this example, the contact is created with the
same address as the account holder. Here is the account holder information:

{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "NamedInsured",
"name": "NamedInsured"
}
],
...
"firstName": "Mike",
"id": "pc:577",
"lastName": "Sherman",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "2304 Market St.",
"addressLine2": "Floor 0000",
"addressLine3": "Developer Unit Habitation Cube #0000",
"addressType": {
"code": "business",
"name": "Business"
},
"city": "San Francisco",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 0",
"displayName": "2304 Market St., Floor 0000, Developer Unit Habitation Cube #0000, San Francisco, CA
94114",
"id": "pc:123",
"postalCode": "94114",
"state": {
"code": "CA",
"name": "California"
}
},
...
}

Create the contact using the account holder contact id (pc:577) and address id (pc:123) in the request.
Command

POST /job/v1/jobs/pc:202/contacts

Request

{
"data": {
"attributes": {
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"linkedAddress": {
"addressId": "pc:123",
"contactId": "pc:577"
}
}
}
}
}

Response

{
"data": {

296 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"attributes": {
...
"firstName": "Samantha",
"id": "pc:892",
"lastName": "Stewart",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "2304 Market St.",
"addressLine2": "Floor 0000",
"addressLine3": "Developer Unit Habitation Cube #0000",
"addressType": {
"code": "business",
"name": "Business"
},
"city": "San Francisco",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 0",
"displayName": "2304 Market St., Floor 0000, Developer Unit Habitation Cube #0000, San Francisco, CA
94114",
"id": "pc:125",
"isLinked": true,
"postalCode": "94114",
"state": {
"code": "CA",
"name": "California"
}
}
},
...
}

The response shows that the contact has been created with a primaryAddress that is identical to the linked address.
Notice the isLinked property is set to true. If you also retrieve the contact to which you linked and view the address
you linked to, you’ll see that the primaryAddress has an isLinked value of true for that contact also.
Command

GET /account/v1/accounts/pc:202/contacts/pc:577

Response

{
"data": {
"attributes": {
...
"firstName": "Mike",
"id": "pc:577",
"lastName": "Sherman",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "2304 Market St.",
"addressLine2": "Floor 0000",
"addressLine3": "Developer Unit Habitation Cube #0000",
"addressType": {
"code": "business",
"name": "Business"
},
"city": "San Francisco",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 0",
"displayName": "2304 Market St., Floor 0000, Developer Unit Habitation Cube #0000, San Francisco, CA
94114",
"id": "pc:123",
"isLinked": true,
"postalCode": "94114",
"state": {
"code": "CA",
"name": "California"
}
},
...
}

This next example updates the address for an existing contact that has a linked address. If a contact has a linked address
(isLinked is set to true), you must include a linkedAddressUpdateMode value to update the address.

Policy contacts 297

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Command

PATCH /job/v1/jobs/pc:202/contacts/pc:892

Request

{
"data": {
"attributes": {
"primaryAddress": {
"linkedAddressUpdateMode": "update",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressLine3": null
}
}
}
}

Response

{
"data": {
"attributes": {
...
"firstName": "Samantha",
"id": "pc:892",
"lastName": "Stewart",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressType": {
"code": "business",
"name": "Business"
},
"city": "San Francisco",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 0",
"displayName": "1234 Main St, Apt 2B, San Francisco, CA 94114",
"id": "pc:125",
"isLinked": true,
"postalCode": "94114",
"state": {
"code": "CA",
"name": "California"
}
}
},
...
}

Because we set the linkedAddressUpdateMode to update, the linked contact’s address has also been changed:

{
"data": {
"attributes": {
"firstName": "Mike",
"id": "pc:577",
"lastName": "Sherman",
...
"primaryAddress": {
"CEDEX": "11",
"addressLine1": "1234 Main St",
"addressLine2": "Apt 2B",
"addressType": {
"code": "business",
"name": "Business"
},
"city": "San Francisco",
"country": "US",
"county": "San Mateo",
"description": "Created by the Address Builder with code 0",
"displayName": "1234 Main St, Apt 2B, San Francisco, CA 94114",
"id": "pc:123",
"isLinked": true,
"postalCode": "94114",
"state": {
"code": "CA",
"name": "California"
}

298 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
...
}

Primary and secondary named insured contacts

A primary named insured contact is an account contact associated with the policy using the PolicyPriNamedInsured
role. A policy can have only one primary named insured, but can also have a secondary named insured with the role
PolicySecNamedInsured.

The default primary named insured

When you create a policy, the submission job must specify an account. By default, the account contact with the
"primary insured" role on the account is associated with the policy as the "primary named insured" on the policy.

Changing who is the primary named insured

If a policy has multiple account contacts, you can change which one is the primary named insured. To do this, use the
POST /jobs/{jobId}/change-primary-named-insured endpoint. The POST requires a body with a
primaryNamedInsured property whose ID is set to the ID of the appropriate account contact.

For example, the following changes the primary named insured from Ray Newton to Helena Newton (test_pp:3):

PATCH /job/v1/jobs/pc:4477/change-primary-named-insured

{
"data": {
"attributes": {
"primaryNamedInsured": {
"id": "test_pp:3"
}
}
}
}

Adding a secondary named insured

To add a secondary named insured, update the job.
Command
PATCH /job/v1/jobs/pc:4477

Request body

{
"data": {
"attributes": {
"secondaryNamedInsured": {
"id": "test_pp:4"
}
}
}
}

Optionally, you can include the relationship between the secondary primary named insured and the primary named
insured.

{
"data": {
"attributes": {
"secondaryNamedInsured": {
"id": "test_pp:4".
"relationship": "spouse"
}
}
}
}

Policy contacts 299

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Additional named insured contacts

Within the context of a policy, an additional named insured is a contact associated with the policy using the
PolicyAddlNamedInsured role. A policy can have any number of additional named insureds.

The AdditionalNamedInsured resource

The additional named insured role is managed using a distinct resource type: AdditionalNamedInsured. This resource
does not represent a policy contact. Rather, it represents that an existing policy contact has the
PolicyAddlNamedInsured role. Like all other resources, the AdditionalNamedInsured resource has an id field. But
this id is the id of the relationship, not of the contact itself.
For example, suppose a policy has two contacts: Ray Newton (id test_pp:1) and Helena Newton (id test_pp:3). Ray
Newton is not an additional named insured. Helena is an additional named insured, and the id of the relationship is
test_pp:707. For the policy:

• Ray Newton, has the following resources:

◦ A PolicyContact with id test_pp:1.
• Helena Newton, has the following resources:
◦ A PolicyContact with id test_pp:3.
◦ An AdditionalNamedInsured with id test_pp:707.
The AdditionalNamedInsured resource includes a relationship property. This is an optional string used to identify
the additional named insured's relationship to the primary insured, such as "spouse" or "roommate".

The AdditionalNamedInsured endpoints

The additional named insured role is managed using a set of /additional-named-insured endpoints. Note the
following behaviors of the various GET endpoints:
• If a contact does not have the additional named insured role:
◦ The contact itself is returned by GET /contacts.
◦ No relationship is returned by GET /additional-named-insureds.
• If a contact does have the additional named insured role:
◦ The contact itself is returned by GET /contacts.
◦ The relationship is returned by GET /additional-named-insureds.

Querying for additional named insureds

Use the following endpoints to retrieve information about additional named insureds for a specific job:
• GET /job/v1/jobs/{jobId}/additional-named-insureds
• GET /job/v1/jobs/{jobId}/additional-named-insureds/{additionalNamedInsuredIdId}
These endpoints return only the policy contacts that have the additional named insured role on the job's underlying
policy.
For example, the following is a portion of the response when querying for additional named insureds on job pc:4477.

GET /job/v1/jobs/pc:4477/additional-named-insured

{
"count": 1,
"data": [
{
"attributes": {
"accountContact": {
"displayName": "Helena Newton",
"id": "test_pp:3"
},

300 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"id": "test_pp:707",
"relationship": "wife"
}
}
]
...

Adding additional named insureds

You can only add existing account contacts to a job as an additional named insured. To do so, use the following
endpoint:
• POST /job/v1/jobs/{jobId}/additional-named-insured
The request must include an accountContact property that specifies the ID of an existing account contact. It can also
include an optional relationship property.
For example, the following request adds the existing account contact pc:4533 to job pc:4477. The additional named
insured is designated as the "sister" of the primary insured.

POST /job/v1/jobs/pc:4477/additional-named-insured

{
"data": {
"attributes": {
"accountContact": {
"id": "pc:4533"
},
"relationship": "sister"
}
}
}

Updating additional named insureds

Use the following endpoint to PATCH an additional named insured:
• PATCH /job/v1/jobs/{jobId}/additional-named-insured/{additionalNamedInsuredId}
The only field you can patch is relationship.
For example, the following request modifies the relationship of the additional named insured 309 on job pc:4477.

PATCH /job/v1/jobs/pc:4477/additional-named-insured/309

{
"data": {
"attributes": {
"relationship": "roommate"
}
}
}

Use the following endpoint to DELETE an additional named insured:

• DELETE /job/v1/jobs/{jobId}/additional-named-insured/{additionalNamedInsuredId}
No request body is required.
This endpoint removes the Additional Named Insured role from the contact, but it does not delete the contact from the
policy.
For example, the following request deletes additional named insured 309 on the underlying policy for job pc:4477.

DELETE /job/v1/jobs/pc:4477/additional-named-insured/309

<no request body>

An additional named insured on a job or policy cannot be deleted while it is in use by a policy location. See “Location
named insureds” on page 304 for more information.

Policy contacts 301

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

LOB-specific additional insured contacts

All policies have a primary named insured. A policy can also have any number of additional named insureds. In
addition, a policy can have additional insureds that are LOB-specific. Endpoints for LOB-specific additional insureds
are available only if you have at least one additional insured defined for the LOB.
To manage these LOB-specific additional insureds, use the following endpoints:
• GET /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds
• POST /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds
• GET /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds/{additionalInsuredId}
• PATCH /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds/{additionalInsuredId}
• DELETE /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds/{additionalInsuredId}
• GET /policy/v1/policies/{policyId}/lines/{lineId}/additional-insureds
• GET /policy/v1/policies/{policyId}/lines/{lineId}/additional-insureds/{additionalInsuredId}

Querying for additional insureds on the policy

Use the following endpoints to query for additional insureds on a policy line:
• GET /policy/v1/policies/{policyId}/lines/{lineId}/additional-insureds
• GET /policy/v1/policies/{policyId}/lines/{lineId}/additional-insureds/{additionalInsuredId}
You cannot add, update, or delete additional insureds through the policy, you can only query. Additional insureds can
be added, modified, and removed only in the context of a job. The following sections describe how to manage
additional insureds through the associated job.

Querying for LOB additional insureds

Use the following endpoints to retrieve information about additional insureds for a specific job:
• GET /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds
• GET /job/v1/jobs/{jobId}/lines/{lineId}/additional-insureds/{additionalInsuredId}
These endpoints return policy contacts that have an additional insured role on the job's underlying policy for the
specified line.
For example, the following is a portion of the response when querying for additional insureds on the BusinessAutoLine
line for job pc:4477.
Command

GET /job/v1/jobs/pc:4477/lines/BusinessAutoLine/additional-insureds

Response

{
"data": [
{
"attributes": {
"additionalInsuredType": {
"code": "LESSOR",
"name": "Lessor"
},
"contact": {
"displayName": "EverReady Rentals",
"id": "pc:1234",
"type": "PolicyContact",
…
},
"id": "1"
}
},
…

302 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Adding LOB additional insureds

To add an existing account contact to a job as an additional insured, use the following endpoint:
• POST /job/v1/jobs/{jobId}/lines/{lineId}/additional-insured
Note:

Before modifying the job, it must be in a Draft state. If the job has been quoted, you can revert its state to Draft
by running the following command:
POST /job/v1/jobs/{jobId}/make-draft
The request must include the following properties:
• additionalInsuredType: A typecode specifying the relationship of the contact.
• contact: The ID of an existing contact on the policy.
• additionalInformation: A string with additional information. This property is required only for insured types
that have been configured to accept additional information. If the insured type has not been configured for
additional information, this property is unavailable. See the note at the end of this section for more information.
For example, the following request adds the existing account contact pc:4533 as an additional insured of type Lessor to
job pc:4477 on the BusinessAutoLine line.
Command

POST /job/v1/jobs/pc:4477/lines/BusinessAutoLine/additional-insureds

Request

{
"data": {
"attributes": {
"additionalInsuredType": {
"code": "LESSOR"
},
"contact": {
"id": "pc:4533"
}
}
}
}

Note:

The additionalInformation property is never optional, it’s either required or it’s not available. Each
additional insured type is defined in the AddtionalInsuredType.XX.ttx typelist configuration file (with XX
being the code for the LOB, such as BA for the BusinessAutoLine). If additional information is required, there
will be a matching entry in the AdditionalInformationType.XX.ttx file.

Modifying LOB additional insureds

Use the following endpoint to modify an additional insured:
• PATCH /job/v1/jobs/{jobId}/lines/{lineId}/additional-insured/{additionalInsuredId}
For example, the following request changes the insured type of the contact with the additional insured relationship 309
on job pc:4477 on the BusinessAutoLine line.
Command

PATCH /job/v1/jobs/pc:4477/lines/BusinessAutoLine/additional-insured/309

Request

{
"data": {
"attributes": {
"additionalInsuredType": {

Policy contacts 303

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "VENDOR"
}
}
}
}

Use the following endpoint to DELETE an additional insured:

DELETE /job/v1/jobs/{jobId}/lines/{lineId}/additional-insured/{additionalInsuredId}

No request body is required.

This endpoint removes the additional insured role from the contact, but it does not delete the contact from the policy.

Location named insureds

A location named insured is an additional named insured contact on a job or policy that is associated with a policy
location. Support for location named insureds is dependent on the LOB configuration. The LOB might be configured
for any of the following:
• Location named insureds are not allowed.
• One additional named insured contact can be associated with each policy location.
• Multiple additional named insured contacts can be associated with each policy location.
Use the endpoints discussed here to work with location named insureds on LOBs where they are supported.

Creating an association
To create an association between a contact and a policy location, use the following command:
• POST /job/v1/jobs/{jobId}/locations/{locationId}/named-insureds
The following restrictions apply to creating an association between a contact and a policy location:
• The contact and the location must already exist on the job or policy to associate them. You cannot use these
endpoints to create either a contact or a policy location. (See “Policy contacts” on page 291 and “Creating policy
locations” on page 308 for creating policy contacts and locations.)
• The contact cannot be the primary or secondary named insured on the policy.
• You cannot create an association on a bound or quoted policy job. The job must be in draft status.
If the contact does not have the role of additional named insured on the policy, associating it with the policy location
will give it that role.
The following example associates contact pc:200 with location 101 on job pc:50:
Command

POST /job/v1/jobs/pc:50/locations/101/named-insureds

Request

{
"data": {
"attributes": {
"contact": {
"id": "pc:200"
}
}
}
}

Retrieving location named insureds

Use the following commands to retrieve location named insureds:

304 Policy contacts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET /job/v1/jobs/{jobId}/locations/{locationId}/named-insureds
• GET /job/v1/jobs/{jobId}/locations/{locationId}/named-insureds/{locationNamedInsuredId}
• GET /policy/v1/policies/{policyId}/locations/{locationId}/named-insureds
• GET /policy/v1/policies/{policyId}/locations/{locationId}/named-insureds/
{locationNamedInsuredId}

The following example retrieves all location named insureds for location 101 on job pc:50.
Command

GET /job/v1/jobs/pc:50/locations/101/named-insureds

Response

{
"data": [
{
"attributes": {
"contact": {
"displayName": "Mike Sherman",
"id": "pc:201",
"type": "PolicyContact",
"uri": "/job/v1/jobs/pc:50/contacts/pc:200"
},
"id": "1"
},

This example retrieves the location named insureds from policy pc:123 for location 101.
Command

GET /policy/v1/policies/pc:123/locations/101/named-insureds

Response

{
"data": [
{
"attributes": {
"contact": {
"displayName": "Mike Sherman",
"id": "pc:200",
"type": "PolicyContact",
"uri": "/policy/v1/policies/pc:123/contacts/pc:200"
},
"id": "1"
},

Updating location named insureds

You cannot change anything about the association between a policy location and a contact, they’re either associated or
they’re not. But you can delete the association.
• DELETE /job/v1/jobs/{jobId}/locations/{locationId}/named-insureds/{locationNamedInsuredId}
The Delete command deletes the association between the contact and the policy location. It does not delete the contact
or the policy location themselves.
If the contact was given the role of additional named insured on the policy when it was associated with the policy
location, deleting the association does not remove that role. The contact will continue to be on the policy as an
additional named insured.

Policy contacts 305

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

306 Policy contacts

chapter 31

Policy locations

The contents of a policy can be divided into two categories.

Some content is LOB-specific. The exact structure of these contents vary based on the associated lines of business. This
includes:
• Lines
• Coverables
• Coverages and coverage terms
• Modifiers
• Questions
• Exposures
• Exclusions
• Conditions
Some content is LOB-generic. The structure of these contents remains the same, regardless of the associated lines of
business. This includes:
• Policy contacts
• Policy locations
This topic discusses how to work with policy locations.
To view an example of a composite request that creates an account, creates a submission, modifies each type of policy
content, and then quotes the submission, see the Cloud API Developer Guide.

Overview of policy locations

PolicyCenter uses two data model entities for storing location information: AccountLocation and PolicyLocation.
Policy locations can be added, modified, or removed only in the context of a job. When you add a location to a policy,
it is stored as a PolicyLocation and associated with an AccountLocation. While the job is open, changes to a
PolicyLocation are mirrored in its associated AccountLocation, and changes to an AccountLocation are mirrored
in its associated PolicyLocation. When the job is bound, each PolicyLocation is associated with the resulting policy
and can no longer be changed. (Changes to the AccountLocation do not impact the PolicyLocation.)

Policy locations 307

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Querying for a policy's locations

Use the following endpoints to retrieve information about the policy locations for a specific job:
• GET /job/v1/jobs/{jobId}/locations
• GET /job/v1/jobs/{jobId}/locations/{locationId}
Note that account locations and policy locations are distinct resources. Therefore, the ID of a job's PolicyLocation is
different than the ID of the corresponding AccountLocation.

Creating policy locations

Use the following endpoints to create policy locations for a specific job:
• POST /job/v1/jobs/{jobId}/locations
There are two ways to create a PolicyLocation:
• Associate an existing AccountLocation with the policy
• Specify a new PolicyLocation, which also creates a new AccountLocation and associates the two
Note: The creation functionality for policy contacts is different than it is for policy locations. A contact must
exist on the account before it can be added to a policy. But a location that does not already exist on the account
can be added to a policy. In this case, the location is added to the account and the policy simultaneously.
To create a policy location by associating an existing AccountLocation with the job, the POST references the id of an
existing AccountLocation. For example, the following creates a PolicyLocation for job pc:25 that is linked to the
existing AccountLocation pc:881.

POST /job/v1/jobs/pc:25/locations

{
"data": {
"attributes": {
"accountLocation": {
"id": "pc:881"
}
}
}
}

To create a policy location by specifying a new PolicyLocation, the POST specifies information about the new
location. The required information for a location varies based on the locale. For example, for US locations, the
minimum amount of information you must specify is:
• addressLine1
• city
• state
• postalCode
Whenever you specify a new location, PolicyCenter:
• Creates a new AccountLocation
• Creates a PolicyLocation that is linked to the new account location
For example, the following specifies a new policy location for job pc:25.

POST /job/v1/jobs/pc:25/locations

{
"data": {
"attributes": {
"addressLine1": "1414 Ming Ave",
"city": "Bakersfield",
"state": {

308 Policy locations

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "CA"
},
"postalCode": "90604"
}
}
}

PATCHing policy locations

Use the following endpoints to PATCH a specific PolicyLocation for a specific job:
• PATCH /job/v1/jobs/{jobId}/locations/{locationId}
When you PATCH a job's PolicyLocation, the associated AccountLocation is also updated.
For example, the following specifies an addressLine2 for policy location 201 on job pc:25.

PATCH /job/v1/jobs/pc:25/locations/201

{
"data": {
"attributes": {
"addressLine2": "Suite 505"
}
}
}

DELETEing policy locations

Use the following endpoint to DELETE a specific policy location from a specific job:
• DELETE /job/v1/jobs/{jobId}/locations/{locationId}
The request does not require a body.
When you DELETE a policy location, the associated account location remains.
For example, the following deletes policy location 201 from job pc:25.

DELETE /job/v1/jobs/pc:25/locations/201

<no request body>

Note that you cannot delete a location that is designated as the primary location. If you want to delete a primary
location, you must first PATCH the policy and designate some other location as the primary location.

Policy locations 309

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

310 Policy locations

chapter 32

Job user role assignment

This topic discusses how to assign users to jobs with specific roles on that job, such as "Underwriter".

Overview of job user role assignment

In the context of a job, a role (such as Underwriter) can be assigned to a user and group (such as Alice Applegate from
the Los Angeles Branch UW group). The roles that can be assigned are defined in the UserRoles typelist.
Some job role assignment occurs automatically. For example, the Creator role is assigned automatically to the user who
creates a job. Job roles can also be assigned manually.
A single user can have multiple roles on a job. However, a single job role cannot be held by more than one user.
In Cloud API, job roles are managed through a roles array. Every member of the array has the following structure:

"roles": [
{
"group": "<groupId>",
"role": {
"code": "<UserRolesCode>",
"name": "<UserRolesName>"
},
"user": "<userId>"
},

For example, the following roles array identifies Alice Applegate (pc:8) from the Los Angeles Branch UW group (pc:
55) as the Creator and Underwriter for the job.

"roles": [
{
"group": "pc:55",
"role": {
"code": "Creator",
"name": "Creator"
},
"user": "pc:8"
},
{
"group": "pc:55",
"role": {
"code": "Underwriter",
"name": "Underwriter"
},
"user": "pc:8"
}
]

Job user role assignment 311

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Retrieving job user roles

Use the following endpoint to retrieve a list of job role assignments for a job:
• GET /job/v1/jobs/{jobId}/user-roles

Assigning job user roles

Use the following endpoint to assign a job role to a user on a given job:
• POST /job/v1/jobs/{jobId}/user-roles/assign
The request body must specify the user, group, and role using the syntax below.

{
"data": {
"attributes": {
"group": "<groupId>",
"role": {
"code": "<UserRolesCode>"
},
"user": "<userId>"
}
}
}

Each call consist of one role being assigned to a group and user. If that role was already assigned to another user, it is
reassigned to the specified user. Beyond that, other assignments on the job are not affected.
For example, the following assigns the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:
1117) on job pc:9.

POST /job/v1/jobs/pc:9/user-roles/assign

{
"data": {
"attributes": {
"group": "pc:1117",
"role": {
"code": "Auditor"
},
"user": "pc:220"
}
}
}

PATCHing job user roles

Use the following endpoint to PATCH the role assignment for a job:
• PATCH /job/v1/jobs/{jobId}/user-roles
You can use the PATCH endpoint to add or remove multiple role assignments in one call.
PATCHes in Cloud API are destructive, not additive. When you PATCH the roles array, the new content replaces the
previous content entirely.
If you want to only add user role assignments to a job, the PATCH must contain all current members of the roles array
as well as the new one.
• To add multiple role assignments or reassignments, add multiple new entries to the roles array.
• To remove role assignments, omit those entries from the roles array.
• If there are assignments you do not want to change, you must also include those assignments in the roles array.
For example, suppose job pc:9 has already assigned the roles of Creator and Underwriter to Alice Applegate (pc:8)
from the Los Angeles Branch UW group (pc:55) and the role of Customer Rep to Chris Clark (pc:303) from the Los
Angeles Branch UW group (pc:55). The following PATCH does the following:

312 Job user role assignment

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Adds the role of Auditor to Betty Baker (pc:220) from Eastern Region Underwriting (pc:1117).
• Unassigns the role of Customer Rep. (This is done by omitting it from the roles array.)
• Makes no changes to the Creator or Underwriter roles. (They are included in the roles array with their original
data.)

PATCH /job/v1/jobs/pc:9/user-roles

{
"data": {
"attributes": {
"group": "pc:1117",
"role": {
"code": "Auditor"
},
"user": "pc:220"
},
{
"group": "pc:55",
"role": {
"code": "Creator"
},
"user": "pc:8"
},
{
"group": "pc:55",
"role": {
"code": "Underwriter"
},
"user": "pc:8"
}
}
}

Job user role assignment 313

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

314 Job user role assignment

chapter 33

Working with product definitions

The Product Definition API supports a set of endpoints for querying audit schedule patterns, lines, products, and
reference code data. The endpoints return JSON representations of the product data models for the specified type.
• “Product definitions for audit schedule patterns” on page 315
• “Product definitions for lines” on page 317
• “Product definitions for products” on page 317
• “Product definitions for reference code data” on page 318

Product definitions for audit schedule patterns

The audit schedule patterns endpoints provide read-only access to metadata about the different types of audit schedules.
Note: For information on policy audits, see “Audits” on page 209.

The following endpoints are available:

• GET /productdefinition/v1/audit-schedule-patterns
• GET /productdefinition/v1/audit-schedule-patterns/{auditSchedulePatternId}
The fields returned in the response can vary based on the type of audit (such as Final Audit and Premium Report). For
example, a Premium Report audit can have a frequency defined because those audits can occur based on a regular
schedule, whereas a Final Audit happens only once per policy period and therefore doesn’t use a frequency attribute.
Here is an example showing possible responses of both a Final Audit and a Premium Report.
Command

GET /productdefinition/v1/audit-schedule-patterns

Response

{
"data": [
{
"attributes": {
"auditMethod": {
"code": "Phone",
"name": "Phone"
},
"description": "",
"descriptionKey": "AuditSchedule_CancellationPhone.Description",
"dueBusinessDayAdjustment": {

Working with product definitions 315

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "NextBusinessDay",
"name": "Next Business Day"
},
"dueDelayAmount": 15,
"dueDelayDirection": {
"code": "After",
"name": "after"
},
"dueDelayUnit": {
"code": "CalendarDays",
"name": "Calendar Days"
},
"id": "CancellationPhone",
"initBusinessDayAdjustment": {
"code": "NextBusinessDay",
"name": "Next Business Day"
},
"initDelayAmount": 0,
"initDelayDirection": {
"code": "Before",
"name": "before"
},
"initDelayUnit": {
"code": "CalendarDays",
"name": "Calendar Days"
},
"isSeries": false,
"name": "Cancellation Audit by Phone",
"nameKey": "AuditSchedule_CancellationPhone.Name",
"type": {
"code": "FinalAudit",
"name": "Final Audit"
}
},
…
{
"attributes": {
"auditMethod": {
"code": "Voluntary",
"name": "Voluntary"
},
"calendarMonthRoundDate": 15,
"description": "",
"descriptionKey": "AuditSchedule_ReportCalendarMonthExclLast.Description",
"dueBusinessDayAdjustment": {
"code": "NextBusinessDay",
"name": "Next Business Day"
},
"dueDelayAmount": 15,
"dueDelayDirection": {
"code": "After",
"name": "after"
},
"dueDelayUnit": {
"code": "CalendarDays",
"name": "Calendar Days"
},
"excludeLastAuditPeriod": true,
"frequency": {
"code": "Monthly",
"name": "Monthly"
},
"id": "ReportCalendarMonthExclLast",
"initBusinessDayAdjustment": {
"code": "NextBusinessDay",
"name": "Next Business Day"
},
"initDelayAmount": 5,
"initDelayDirection": {
"code": "Before",
"name": "before"
},
"initDelayUnit": {
"code": "CalendarDays",
"name": "Calendar Days"
},
"intervalComputationType": {
"code": "CalendarMonth",
"name": "Calendar Month"
},
"isSeries": true,
"minimumAuditPeriodLength": 15,
"name": "Monthly Reports by calendar month, exclude last month",
"nameKey": "AuditSchedule_ReportCalendarMonthExclLast.Name",
"paymentPlanCode": "ReportingPlanId",
"reportingDefaultDepositPct": "10",
"type": {
"code": "PremiumReport",
"name": "Premium Report"

316 Working with product definitions

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
},

Product definitions for lines

The product definition line endpoints provide read-only access to product data models.
The /productdefinition/v1/lines/* endpoints can be used to query lines and their associated coverables,
coverages, exposures, modifiers, and questions. Use the following endpoints to retrieve the data models for each line
type:
• GET /productdefinition/v1/lines
• GET /productdefinition/v1/lines/{lineId}
• GET /productdefinition/v1/lines/{lineId}/coverables
• GET /productdefinition/v1/lines/{lineId}/coverables/{coverableId}
• GET /productdefinition/v1/lines/{lineId}/coverables/{coverableId}/coverages
• GET /productdefinition/v1/lines/{lineId}/coverables/{coverableId}/modifiers
• GET /productdefinition/v1/lines/{lineId}/coverages
• GET /productdefinition/v1/lines/{lineId}/exposures
• GET /productdefinition/v1/lines/{lineId}/exposures/{exposureId}
• GET /productdefinition/v1/lines/{lineId}/modifiers
• GET /productdefinition/v1/lines/{lineId}/questions
Note: These is also one POST command available for a product definition line endpoint:

• POST /productdefinition/v1/lines/{lineId}/activate-edition
See Cloud API Developer Guide for more information on this endpoint.

Product definitions for products

The product endpoints provide read-only access to product data models.

Products endpoints
The /productdefinition/v1/products/* endpoints can be used to query products and their associated lines, questions,
modifiers, and editions. Use the following endpoints to retrieve the data models for each product type:
• GET /productdefinition/v1/products
• GET /productdefinition/v1/products/{productId}
• GET /productdefinition/v1/products/{productId}/editions
• GET /productdefinition/v1/products/{productId}/modifiers
• GET /productdefinition/v1/products/{productId}/lines
• GET /productdefinition/v1/products/{productId}/questions

Product editions
You can retrieve summary information for all editions of a product by using the following endpoint:
• GET /productdefinition/v1/products/{productId}/editions
For example, to retrieve the edition codes for the PersonalAuto product, use the following command:

Working with product definitions 317

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Command

GET /productdefinition/v1/products/PersonalAuto/editions

Response

{
"data": [
{
"attributes": {
"code": "BaseEdition",
"description": "Base Product",
"id": "BaseEdition",
"name": "Base Product"
}
}

The editions can have three sources:

• Editions for a visualized product
• Editions from the InstalledEditions table for an installed product not synced to cloud
• Editions from the APD Cloud service for an installed product synced to cloud
This endpoint is intended to work across all three sources. However, there might be some inconsistencies due to
differences in how the products are implemented. For example:
• Locally-installed editions have a notion of "status" (pre-loaded, activated, or withdrawn) that doesn't apply to the
other cases.
• Locally-installed editions have no notion of a name, description, effective or expiration dates, or applicable
segments and jurisdictions.
• Locally-installed and visualized editions are attached to the line rather than the product, while cloud-synced
editions are attached to the product. This endpoint attempts to abstract over that difference by aggregating all line-
level editions and treating them as a product-level edition, and only writing out concrete properties if they're the
same for all editions.
The main use for this endpoint is to retrieve codes for use with the /common/v1/entity-schemas endpoint. Use the
code attribute from the /productdefinition/v1/products/{productId}/editions response with the editionCode
query parameter for the entity-schemas endpoint. See “Business entity schema query parameters” on page 500 for
more information.

Product definitions for reference code data

The /productdefinition/v1/reference-data/* endpoints can be used to query collections of reference code data,
such as cost codes or class codes.
The following types of reference code data are supported:

Endpoint Description Resource Guidewire entity

/productdefinition/v1/reference-data/bop- BOP class codes BOPClassCode BOPClassCode
class-codes
/productdefinition/v1/reference-data/cost- Cost codes CostCode CostCode
codes
/productdefinition/v1/reference-data/ Industry codes IndustryCode IndustryCode
industry-codes
/productdefinition/v1/reference-data/risk- Risk classes RiskClass RiskClass
classes
/productdefinition/v1/reference-data/tax- Tax locations TaxLocation TaxLocation
locations

318 Working with product definitions

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Endpoint Description Resource Guidewire entity

/productdefinition/v1/reference-data/uw- Underwriting issue codes UWIssueType UWIssueType
issue-types
/productdefinition/v1/reference-data/wc- Workers' Comp class codes WCClassCode WCClassCode
class-codes
/productdefinition/v1/reference-data/wc- Workers' Comp federal WCFedLiabClassCode WCFedLiabClassCode
fed-liab-class-codes liability class codes

Working with product definitions 319

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

320 Working with product definitions

chapter 34

PATCHing jobs

This topic discusses changes you can make to a job directly on the Job resource.

Read-only fields
Once a job has been created, some fields are read-only and cannot be changed. This includes the following fields:
• account
• createdDate
• id
• jobNumber
• jobStatus
• jobType
• organization and organizationOfService
• periodStart and periodEnd
• producerCode
• quoteType
Note that organization, producerCode, and organizationOfService can be modified indirectly by changing the
job's producerCodeofService. For more information, see “Policy producers” on page 170.

Fields you can modify using PATCH /{jobId}

Some of the fields on a Job resource can be modified using the PATCH /job/v1/jobs/{jobId} endpoint. This most
commonly PATCHed fields include the following:
• baseState
◦ A value from the State typelist
• preferredCoverageCurrency
◦ A value from the Currency typelist
◦ This can be modified only if PolicyCenter is in multicurrency mode
• primaryLocation
PATCHing jobs 321
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ This can be changed to the ID of another location on the job

• termType
◦ A value from the TermType typelist
• uwCompany
◦ The ID of an underwriting company
For example, the following PATCH changes job pc:4477 so that the job's base state is Washington, the term type is
annual, and the underwriting company is Acme Low Hazard Insurance (uwc:1):

PATCH /job/v1/jobs/pc:4477

{
"data": {
"attributes": {
"baseState": {
"code": "WA"
},
"termType": {
"code": "Annual"
},
"uwCompany": {
"id": "uwc:1"
}
}
}
}

Fields you can modify using specific endpoints

The following fields can be changed using specific endpoints:
• effectiveDate
• primaryInsured
• selectedVersion
To change the effective date, use the POST /jobs/{jobId}/change-effective-date endpoint. The POST requires a
body with a jobEffectiveDate property.
For example, the following changes the effective date of job pc:4477 to January 1, 2024:

PATCH /job/v1/jobs/pc:4477/change-effective-date

{
"data": {
"attributes": {
"jobEffectiveDate": "2024-01-01"
}
}
}

To change the primary insured, use the POST /jobs/{jobId}/change-primary-named-insured endpoint. The
POST requires a body with a primaryNamedInsured property whose ID is set to the ID of another contact on the
account.
For example, the following changes the primary named insured from Ray Newton to Helena Newton (test_pp:3):

PATCH /job/v1/jobs/pc:4477/change-primary-named-insured

{
"data": {
"attributes": {
"primaryNamedInsured": {
"id": "test_pp:3"
}
}
}
}

322 PATCHing jobs

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Versions are used for quoting multi-version policies. For information on how to change the selected version of a job,
see “Multi-version quoting” on page 381.

PATCHing jobs 323

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

324 PATCHing jobs

part 6

Business flows: Job support

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in PolicyCenter so that caller
applications can request data from or initiate action within PolicyCenter.
The following topics discuss how caller applications can use PolicyCenter functionality that supports multiple types of
jobs. This includes:
• “Affinity groups”
• “Archiving”
• “Contingencies”
• “Form patterns”
• “Job searches”
• “Out-of-sequence conflicts”
• “Policy compare”
• “Policy holds”
• “Quoting” (including multi-version quoting and cost overrides)
• “Reinsurance risks”
• “Streamlined account and submission creation”
• “Underwriting issues”

Business flows: Job support 325

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

326 Business flows: Job support

chapter 35

Affinity groups

The following topic covers how affinity groups can be managed through Cloud API.

Overview of affinity groups

In some situations, an insurer wants to process some aspect of underwriting in the same way for a specific set of
policies. For examples, a specific set of policies might need access to a specific offering or may need to have rating
calculated in a specific way. To identify these sets of policies, PolicyCenter uses affinity groups.
An affinity group is a named group that a policy can be added to during the processing of an associated job, such as a
submission or a policy change. An affinity group can be associated with any of the following attributes:
• A producer and one or more producer codes
• A set of one or more jurisdictions
• A set of one or more products
If the affinity group specifies at least one producer code, then in order to be added to the group, the policy must be
associated with one of the producer codes. The same logic is true for jurisdictions and products.
In the PolicyCenter base configuration, affinity groups are created from the Administration tab. Once they have been
created, they can be associated with policies on the Policy Info step of the various job wizards, such as the Submission
Wizard. However, in the base configuration, there is no special behavior given to a policy associated with an affinity
group. This special behavior must be defined by the insurer through configuration.
For more information on the business functionality of affinity groups, refer to the Application Guide.

Affinity group types

Every affinity group has a type, which is set to either Open or Closed.
• An open affinity group cannot have a producer or any producer codes.
• A closed affinity group must have a producer.
In the PolicyCenter user interface, closed affinity groups must also have at least one producer code. In Cloud API,
there are separate endpoints for creating an affinity group and assigning its producer codes. Therefore, you can create
an affinity group through Cloud API with no producer code.

Affinity groups 327

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Working with affinity groups

Querying for affinity groups
To query for information about affinity groups, use the following endpoints:
• GET /admin/v1/affinity-groups
• GET /admin/v1/affinity-groups/{affinityGroupId}
For example, the following query retrieves information about affinity group pc:707:

GET /admin/v1/affinity-groups/pc:707

{
"data": {
"attributes": {
"affinityGroupType": {
"code": "Open",
"name": "Open"
},
"id": "pc:707",
"jurisdictions": [
{
"code": "CA",
"name": "California"
}
],
"name": "West Coast WC Affinity Group",
"primaryContactFirstName": "Rochelle",
"primaryContactLastName": "Nwodim",
"primaryContactPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
}
},
"products": [
"WorkersComp"
],
"startDate": "2020-09-09T00:00:00.000Z"
},
....

Creating affinity groups

To create an affinity group, use the following endpoint:
• POST /admin/v1/affinity-groups
The only required attributes are:
• affinityGroupType - Set to a value from the AffinityGroupType typelist (either Open or Closed)
• name - Set to the group name
For example, the following request creates a minimal affinity group:

POST /admin/v1/affinity-groups

{
"data": {
"attributes": {
"affinityGroupType": {
"code": "Open"
},
"name": "Cloud API Affinity Group 1"
}
}
}

The following request creates a more robust affinity group:

POST /admin/v1/affinity-groups

{
"data": {
"attributes": {

328 Affinity groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"affinityGroupType": {
"code": "Closed"
},
"jurisdictions": [
{
"code": "NY"
}
],
"name": "Cloud API Affinity Group 2",
"organization": {
"id": "pc:5"
},
"primaryContactFirstName": "Elizabeth",
"primaryContactLastName": "Madison",
"products": [
"WorkersComp"
],
"startDate": "2022-10-18T00:00:00.000Z"
}
}
}

Modifying affinity groups

To PATCH an affinity group, use the following endpoint:
• PATCH /admin/v1/affinity-groups/{affinityGroupId}
For example, the following request PATCHes affinity group pc:707 by adding a description.

PATCH /admin/v1/affinity-groups/pc:707

{
"data": {
"attributes": {
"description": "Affinity group for WC policies in the Western region"
}
}
}

There is no endpoint in Cloud API to delete an affinity group.

Working with affinity group producer codes

A closed affinity group is typically associated with one or more producer codes. There is a separate set of endpoint for
working with an affinity group's producer codes.

Querying for an affinity group's producer codes

To query for an affinity group's producer codes, use the following endpoint:
• GET /admin/v1/affinity-groups/{affinityGroupId}/producer-codes
For example, the following request queries for the producer codes for affinity group pc:909. Note that it has two
producer codes: 100-002541 (pc:7) and 501-002542 (pc:7).

GET /admin/v1/affinity-groups/pc:909

{
"count": 2,
"data": [
{
"attributes": {
"id": "pc:6",
"producerCode": {
"displayName": "100-002541",
"id": "pc:6"
}
},
...
},
{
"attributes": {
"id": "pc:7",
"producerCode": {
"displayName": "501-002542",
"id": "pc:7"
}

Affinity groups 329

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
...
}
}
],
...
}

Identifying producer code REST IDs

To associate a producer code with an affinity group, you must know the producer code's REST ID. There are two
endpoints you can use to retrieve producer codes and their IDs - one in the Account API and one in the Admin API.
These endpoints are:
• GET /account/v1/producer-codes
• GET /admin/v1/producer-codes
The Admin API version returns all producer codes, regardless of their status. The Account API version returns only the
producer codes available to the caller. The Account API version omits producer codes that the caller cannot use (such
as producer codes that are inactive or that are not available to the specific caller).

Associating a producer code with an affinity group

To associate a producer code with an affinity group, use the following endpoint:
• POST /admin/v1/affinity-groups/{affinityGroupId}/producer-codes
This endpoint does not create a new producer code. Rather, it creates an association between the affinity group and an
existing producer code.
For example, the following request associates producer code 501-002543 (pc:8) with affinity group pc:909.

POST /admin/v1/affinity-groups/pc:909/producer-codes

{
"data": {
"attributes": {
"producerCode": {
"id": "pc:8"
}
}
}
}

A closed affinity group can have multiple producer codes. However, each POST can associate only one producer code
with the affinity group.

Removing a producer code from an affinity group

To remove a producer code from an affinity group, use the following endpoint:
• DELETE /admin/v1/affinity-groups/{affinityGroupId}/producer-codes/{producerCode}
This endpoint does not delete the producer code. Rather, it deletes the association between the affinity group and the
producer code.
For example, the following request removes producer code 501-002543 (pc:8) from affinity group pc:909.

DELETE /admin/v1/affinity-groups/pc:909/producer-codes/pc:8

<no request body>

330 Affinity groups

chapter 36

Comparing jobs

PolicyCenter supports the ability to compare different jobs for the same policy so that you can see how each job is
modifying the base policy.
• You can compare an unbound job to the policy it is based on.
• You can compare jobs for the same policy.
You can also compare jobs through Cloud API.

Comparing a job to its base policy

Comparing a job to its base policy in PolicyCenter
PolicyCenter supports the ability to compare an unbound job to the policy it is based on. In the base configuration, this
information is shown in the user interface on the Policy Review step of the relevant job wizards. It appears on the
Differences tab on a subtab whose label is "Comparing Existing Policy and <current job>".

The organization of LOB-specific information shown on this tab is determined by an LOB-specific "DiffTree" XML
file. For example, the organization of information for Personal Auto policies is defined in the PADiffTree.XML file. For
more information on DiffTree XML files and how to configure them, see the Configuration Guide.

Comparing a job to its base policy in Cloud API

To compare a job to its base policy in Cloud API, use the following endpoint:
• POST /job/v1/jobs/{jobId}/review-diffs
The request does not require a body.
The /review-diffs endpoint returns a JobReviewDiffs resource, which details the differences between the job and
its base policy.

Structure of the JobReviewDiffs resource

The JobReviewDiffs resource has the following structure:
• basedOnJob
◦ Information about the bound policy
• diffTree
Comparing jobs 331
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ Hierarchical information about the differences between the bound policy and the current job
Within the diffTree section, some of the information may be LOB-agnostic. For example, there could be diffTree
sections for "Policy Info" (changes at the policy level) or "Line Coverages". Other information may be LOB-specific.
This information is defined by the DiffTree XML file for the line of business. For example, for a Personal Auto policy,
there could be a diffTree section for "Vehicles".
Every node in the diffTree has a changeType field, which can have one of four values:
• Add - The node defines an entity not present on the policy that is being added by the job.
• Remove - The node defines an entity present on the policy that is being removed by the job.
• Change - The node defines a field whose value is being changed by the job.
• Window - The node defines an entity whose effective window is being changed.
In the base configuration, changes of type Add, Remove, and Change can be made through the user interface and can be
done for any type of job. Changes of type Window cannot be made through the user interface (though they can be made
through Gosu), and can only be done for certain types of jobs, such as General Liability and Worker's Compensation.

Example of a /review-diffs response

For example, suppose there is a PersonalAuto policy whose id is pc:818 and whose effective date is 05/23/2022. There
is also an unbound policy change whose effective date is 05/25/2022. The job is making the following changes:
• A 2003 Acura RSX vehicle is being added
• A 2005 Buick LaCrosse vehicle is being removed
• Line Coverage "Underinsured Motorist - Property Damage" is being added
• Line Coverage "Mexico Coverage - Limited" is being removed

Overall structure of the response

At a high level, the structure of the response is as follows:

"attributes": {
"basedOnJob": {
...
},
"diffTree": {
"children": [
{
"children": [
...
],
"label": "Policy Info"
},
{
"children": [
...
],
"label": "Vehicles"
},
{
"children": [
...
],
"label": "Line Coverages"
},
],
"label": "Difference Tree Root"
}
}

The first part of the response provides information about the original job that the current job is based on.
The second part of the response is the diffTree.

332 Comparing jobs

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The basedOnJob section

For this example, the basedOnJob information would look like this:

"basedOnJob": {
"displayName": "47586734721",
"id": "pc:818",
"type": "Job",
"uri": "/job/v1/jobs/pc:818"
},

The diffTree Policy Info section

For this example, the first children node details changes at the policy level.

"children": [
{
"changeType": "Change",
"entity": {
"displayName": "P000143542, 04/23/2022, 10/23/2022, 0003800396",
"id": "pc:S7YjIyCbFh-UcbMSCMlrZ",
"type": "Job",
"uri": "/job/v1/jobs/pc:S7YjIyCbFh-UcbMSCMlrZ"
},
"field": "writtenDate",
"label": "Written Date",
"value1": "05/23/2022",
"value2": "05/25/2022"
}
],
"label": "Policy Info"

In this example, value1 identifies the effective date of the underlying policy (05/23/2022) and value2 identifies the
effective date of the policy change (05/25/2022).

The Vehicles section

For this example, there is a Vehicles node. For each vehicle, there is information about the vehicle itself and any of its
child objects, such as coverages, modifiers, and drivers.
For the vehicle being added (the 2003 Acura RSX), the changeType fields are set to Add.

{
"children": [
{
"changeType": "Add",
"children": [
{
"children": [
{
"changeType": "Add",
"entity": {
"displayName": "Collision",
"id": "38"
},
"label": "Collision"
},
...
],
"label": "Coverages"
},
{
"children": [
{
"changeType": "Add",
"entity": {
"displayName": "Anti Theft Discount (California)",
"id": "57"
},
"label": "Anti Theft Discount (California)"
},
...
],
"label": "Modifiers"
},
{
"changeType": "Add",
"entity": {
"displayName": "Ray Newton",
"id": "11"
},

Comparing jobs 333

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"label": "Assigned Driver: Ray Newton"

}
],
"entity": {
"displayName": "2003 Acura RSX in California",
"id": "19"
},
"label": "2003 Acura RSX in California"
},
...

The Vehicles section continues with the vehicle being removed (the 2005 Buick LaCrosse). The changeType fields
are set to Remove.

{
"changeType": "Remove",
"children": [
{
"children": [
{
"changeType": "Remove",
"entity": {
"displayName": "Collision",
"id": "4"
},
"label": "Collision"
},
...
],
"label": "Coverages"
},
{
"children": [
{
"changeType": "Remove",
"entity": {
"displayName": "Anti Theft Discount (California)",
"id": "6"
},
"label": "Anti Theft Discount (California)"
},
...
],
"label": "Modifiers"
},
{
"changeType": "Remove",
"entity": {
"displayName": "Ray Newton",
"id": "2"
},
"label": "Assigned Driver: Ray Newton"
}
],
"entity": {
"displayName": "2005 Buick LaCrosse in California",
"id": "2"
},
"label": "2005 Buick LaCrosse in California"
}
],
"label": "Vehicles"
},

The Line Coverages section

The Line Coverages section identifies line-level coverages being added or removed. In this example:
• "Underinsured Motorist - Property Damage" is being added
• "Mexico Coverage - Limited" is being removed

{
"children": [
{
"children": [
{
"changeType": "Remove",
"entity": {
"displayName": "Mexico Coverage - Limited",
"id": "5"
},
"label": "Mexico Coverage - Limited Coverage"
}
],

334 Comparing jobs

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"label": "Mexico Coverage - Limited"

},
{
"children": [
{
"changeType": "Add",
"entity": {
"displayName": "Underinsured Motorist - Property Damage",
"id": "53"
},
"label": "Underinsured Motorist - Property Damage Coverage"
}
],
"label": "Underinsured Motorist - Property Damage"
}
],
"label": "Line Coverages"
}

Comparing two jobs on the same policy

Comparing two jobs on the same policy in PolicyCenter
PolicyCenter supports the ability to compare two jobs on the same policy. In the base configuration, this information
can be viewed in the user interface from the policy's Policy Transactions screen by selecting the two jobs and clicking
the Compare button. The information appears on a screen whose label is Differences Between Pending Policy
Transactions.
As is the case when comparing a job to its base policy, the organization of LOB-specific information shown on this
screen is defined in an LOB-specific "DiffTree" XML file. For example, the organization of information for Personal
Auto policies is defined in PADiffTree.XML. For more information on DiffTree XML files and how to configure them,
see the Configuration Guide.

Comparing two jobs on the same policy from Cloud API

To compare two jobs on the same policy from Cloud API, use the following endpoint:
• POST /policy/v1/policies/{policyId}/compare-jobs
The request body must identify the ids of the jobs to compare. The syntax for the request body is:

{
"data": {
"attributes": {
"job1": {
"id": "<id-of-first-job>"
},
"job2": {
"id": "<id-of-second-job>"
}
}
}
}

The /compare-jobs endpoint returns a CompareJobAttributes resource. For this endpoint, the resource details the
differences that job2 introduces assuming that job1 has been bound.

Structure of the CompareJobAttributes resource

The CompareJobAttributes resource has the following structure:
• diffTree
◦ Information about the differences between the selected jobs
The diffTree node in the CompareJobAttributes resource has the same structure as the diffTree node in the
JobReviewDiffs resource for the /review-diffs endpoint.

• The diffTree section may have information that is LOB-agnostic (such as "Policy Info" or "Line Coverages")
and/or information that is LOB-specific (such as "Vehicles").

Comparing jobs 335

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Every node in the diffTree has a changeType field, which can have one of four values:
◦ Add - The node defines an entity not present in the policy or the first job that is being added by the second job.
◦ Remove - The node defines an entity present in the policy or the first job that is being removed by the second
job.
◦ Change - The node defines a field whose value is either in the policy or is being set by the first job and is then
being changed by the second job.
◦ Window - The node defines an entity whose effective window is being changed.
• In the base configuration, changes of type Add, Remove, and Change can be made through the user interface and can
be done for any type of job. Changes of type Window cannot be made through the user interface (though they can be
made through Cloud API), and can only be done for certain types of jobs, such as General Liability and Worker's
Compensation.

Example of a /compare-jobs response

Suppose you have a personal auto policy with an id of pc:202. It has two vehicles: a Mazda RX-8 and a Buick
LaCrosse. Then, you start two policy changes without binding either.
• The first policy change (pc:addSienna) adds a new vehicle (a Toyota Sienna).
• The second policy change (pc:removeLaCrosse) removes the second existing vehicle (the Buick LaCrosse).
All vehicles are driven by the insured, Ray Newton.
You then make a request to the /compare-jobs endpoint as follows.

POST /policy/v1/policies/pc:202/compare-jobs

{
"data": {
"attributes": {
"job1": {
"id": "pc:addSienna"
},
"job2": {
"id": "pc:removeLaCrosse"
}
}
}
}

The output defines all changes present either in the policy or the first job that are not present in the second job. This
means:
• The Mazda Rx-8 and its driver are not referenced. (Neither job affects this vehicle.)
• The Buick LaCrosse and its driver will be marked as removed. (The second job is removing this vehicle.)
• The Toyota Sienna and its driver will also be marked as removed. (This is added by the first job, but not referenced
in the second job. Therefore, from the second job's perspective, this vehicle is not on the policy.)
The following is a snippet of the response:

{
"data": {
"attributes": {
"diffTree": {
"children": [
{
"children": [
{
"changeType": "Remove",
"children": [
{
"changeType": "Remove",
"entity": {
"displayName": "Ray Newton",
"id": "14"
},
"label": "Assigned Driver: Ray Newton"
}
],

336 Comparing jobs

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"entity": {
"displayName": "2002 Toyota Sienna in California",
"id": "22"
},
"label": "2002 Toyota Sienna in California"
},
{
"changeType": "Remove",
"children": [
{
"changeType": "Remove",
"entity": {
"displayName": "Ray Newton",
"id": "2"
},
"label": "Assigned Driver: Ray Newton"
}
],
"entity": {
"displayName": "2005 Buick LaCrosse in California",
"id": "2"
},
"label": "2005 Buick LaCrosse in California"
}
],
"label": "Vehicles"
}
],
"label": "Difference Tree Root"
},
"job1": {
"job": {
"displayName": "0003903670",
"id": "pc:addSienna"
},
"jobEffectiveDate": "2022-07-21T00:01:00.000Z",
"jobNumber": "0003903670",
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
},
"job2": {
"job": {
"displayName": "0004002589",
"id": "pc:removeLaCrosse"
},
"jobEffectiveDate": "2022-07-21T00:01:00.000Z",
"jobNumber": "0004002589",
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
}
}
}
}

Reversing the order of the job IDs

Reversing the order in which the jobs are listed "reverses" the output. Objects that were reflected as added will now be
reflected as removed. Objects that were removed will now be added.
For example, suppose you make the following request to the /compare-jobs endpoint. This is the same as the previous
request, except the ids have been swapped.

POST /policy/v1/policies/pc:202/compare-jobs

{
"data": {
"attributes": {
"job1": {
"id": "pc:removeLaCrosse"
},
"job2": {
"id": "pc:addSienna"
}
}

Comparing jobs 337

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

The output still defines all changes present either in the policy or the first job that are not present in the second job.
With the jobs listed in this order:
• The Mazda Rx-8 and its driver are not referenced. (Neither job affects this vehicle.)
• The Buick LaCrosse and its driver will be marked as added. (The second job (pc:addSienna) is adding this vehicle.)
• The Toyota Sienna and its driver will also be marked as added. (This is removed by the first job
(pc:removeLaCrosse), but is not referenced in the second job. Therefore, from the second job's perspective, this
vehicle is still on the policy.)
The following is a snippet of the response:

{
"data": {
"attributes": {
"diffTree": {
"children": [
{
"children": [
{
"changeType": "Add",
"children": [
{
"changeType": "Add",
"entity": {
"displayName": "Ray Newton"
},
"label": "Assigned Driver: Ray Newton"
}
],
"entity": {
"displayName": "2002 Toyota Sienna in California",
"id": "22"
},
"label": "2002 Toyota Sienna in California"
},
{
"changeType": "Add",
"children": [
{
"changeType": "Add",
"entity": {
"displayName": "Ray Newton"
},
"label": "Assigned Driver: Ray Newton"
}
],
"entity": {
"displayName": "2005 Buick LaCrosse in California",
"id": "2"
},
"label": "2005 Buick LaCrosse in California"
}
],
"label": "Vehicles"
}
],
"label": "Difference Tree Root"
},
"job1": {
"job": {
"displayName": "0004002589",
"id": "pc:removeLaCrosse"
}
...
},
"job2": {
"job": {
"displayName": "0003903670",
"id": "pc:addSienna"
}
...
}
}
}
}

338 Comparing jobs

chapter 37

Contingencies

In some situations, an insurer may need to identify that a job that is in progress has an issue to resolve, but it might be
appropriate to resolve the issue after the job is bound. Similarly, an insurer may need to identify that a policy has an
issue to resolve, even though there are no active jobs on the policy. For example, the rating for a personal auto
submission may include a good driver discount that requires a report on the driver's driving history. The insurer could
choose to bind the policy before the driving history has been received.
When situations like this occur, these outstanding issues can be managed through contingencies. A contingency is an
object that identifies an issue affecting a job or policy that must be resolved by a particular date. Depending on the
outcome, the insurer may opt to change or cancel the policy. Contingencies can have associated activities, documents,
and notes.
For more information on the business functionality of contingencies, refer to the Application Guide.
Cloud API provides a set of endpoints for managing contingencies. These endpoints exist in both the Job API and the
Policy API.

Querying for contingencies

Querying for contingencies
Use the following endpoints to retrieve information about existing contingencies.

Endpoint Description
GET /jobs/{jobId}/contingencies Retrieve all contingencies for the given job
GET /jobs/{jobId}/contingencies/{contingencyId} Retrieve the given job contingency
GET /policies/{policyId}/contingencies Retrieve all contingencies for the given policy
GET /policies/{policyId}/contingencies/{contingencyId} Retrieve the given policy contingency

There is a single schema for contingencies. It is used by both contingencies associated with jobs and contingencies
associated with policies.
For example, the following is the attributes portion of the payload for contingency pc:70 associated with policy pc:62:

GET /policy/v1/policies/pc:62/contingencies/pc:70

{
...
"attributes": {
"action": {
"code": "ChangeRetroactively",

Contingencies 339
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"name": "Change policy retroactively"

},
"actionStartDate": "2021-11-04T00:00:00.000Z",
"actionStarted": false,
"createDate": "2021-11-04T23:26:33.069Z",
"createUser": {
"displayName": "Alice Applegate",
"id": "pc:S8PjyiRN14A1u20zgJ76k",
"type": "User",
"uri": "/admin/v1/users/pc:S8PjyiRN14A1u20zgJ76k"
},
"description": "Driving record required for
good driver discount",
"dueDate": "2021-11-11T00:00:00.000Z",
"id": "pc:111",
"status": {
"code": "Pending",
"name": "Pending"
},
"title": "Driving record required"
},
...

Querying for related information

Use the following endpoints to retrieve information about activities, documents, and notes related to existing
contingencies.
Contingencies associated with jobs

Endpoint Description
GET /jobs/{jobId}/contingencies/{contingencyId} Retrieve the given activity associated with the given contingency
/activities on the given job
GET /jobs/{jobId}/contingencies/{contingencyId} Retrieve the given document associated with the given
/documents contingency on the given job
GET /jobs/{jobId}/contingencies/{contingencyId} Retrieve the given note associated with the given contingency on
/notes the given job

Contingencies associated with policies

Endpoint Description
GET /policies/{policyId}/contingencies/ Retrieve the given activity associated with the given contingency
{contingencyId}/activities on the given policy
GET /policies/{policyId}/contingencies/ Retrieve the given document associated with the given
{contingencyId}/documents contingency on the given policy
GET /policies/{policyId}/contingencies/ Retrieve the given note associated with the given contingency on
{contingencyId}/notes the given policy

For more information on working with activities, documents, or notes, see the following:
• “Activities” on page 421
• “Documents” on page 429
• “Notes” on page 437

Creating contingencies
Use the following endpoints to create a contingency associated with either a job or a policy:
• POST /jobs/{jobId}/contingencies
• POST /policies/{policyId}/contingencies

Minimum creation criteria

At a minimum, a contingency must specify:

340 Contingencies
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• A title
• A description
• A dueDate
• An action, which must be set to a typecode from the ContingencyAction typelist
For example, the following request creates a new contingency for policy pc:62 with the given title and description. The
due date is November 11, 2021. If the contingency is not resolved by then, PolicyCenter will take the action of
retroactively changing the policy (to remove the good driver discount).

POST /policy/v1/policies/pc:62/contingencies

{
"data": {
"attributes": {
"action": {
"code": "ChangeRetroactively"
},
"description": "Driving record required for good driver discount",
"dueDate": "2021-11-11T00:00:00.000Z",
"title": "Driving record required"
}
}
}

Creating related objects

Use the following endpoint to create activities, documents, and notes for a contingency.
Contingencies associated with jobs

Endpoint Description
POST ​/jobs​/{jobId}​/contingencies​/{contingencyId}​/activities Create an activity associated with the given contingency on the
given job
POST /jobs/{jobId}/contingencies/{contingencyId} Create a document associated with the given contingency on
/documents the given job
POST /jobs/{jobId}/contingencies/{contingencyId} Create a note associated with the given contingency on the
/notes given job

Contingencies associated with policies

Endpoint Description
POST /policies/{policyId}/contingencies/ Create an activity associated with the given contingency on the
{contingencyId}/activities given policy
POST /policies/{policyId}/contingencies/ Create a document associated with the given contingency on the
{contingencyId}/documents given policy
POST /policies/{policyId}/contingencies/ Create a note associated with the given contingency on the given
{contingencyId}/notes policy

When an activity is created directly for an account, job, or policy, you must specify an activity pattern. However, when
an activity is created for a contingency, you must omit the activity pattern. All activities created through contingencies
use the "New Contingency" activity pattern (uw_review_contingency). If the request payload contains an activity
pattern, the request fails.
For more information on working with activities, documents, or notes, see the following:
• “Activities” on page 421
• “Documents” on page 429
• “Notes” on page 437

Contingencies 341
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Closing contingencies
Initially, the status of each contingency is set to "Pending". While the status is pending, the contingency is considered
to be open.
A contingency can be closed either by resolving it or by waiving it. You can both resolve and waive contingencies
through Cloud API. Except for the endpoint paths and the final status of the contingency, the behaviors of the two
operations are the same.

Resolving contingencies
To resolve a contingency, use one of the following endpoints as appropriate:
• POST /jobs/{jobId}/contingencies/{contingencyId}/resolve
• POST /policies/{policyId}/contingencies/{contingencyId}/resolve
The /resolve endpoints do not require a request body.
When you resolve a contingency:
• status is set to "Resolved".
• closedDate is set to the current time.
• closedUser is set to the API call's session user.
For more information on how the session user is determined, see the Cloud API Developer Guide.

Waiving contingencies
To waive a contingency, use one of the following endpoints as appropriate:
• POST /jobs/{jobId}/contingencies/{contingencyId}/waive
• POST /policies/{policyId}/contingencies/{contingencyId}/waive
The /waive endpoints do not require a request body.
When you waive a contingency:
• status is set to "Waived".
• closedDate is set to the current time.
• closedUser is set to the API call's session user.
For more information on how the session user is determined, see the Cloud API Developer Guide.

342 Contingencies
chapter 38

Form patterns

For the insured, the physical representation of an insurance policy is a collection of policy forms. Policy forms define
aspects of the policy such as coverages, exposures, exclusions, and government regulations. The forms themselves are
not stored in PolicyCenter; they’re stored in an external documentation management system and are typically accessed
through integration with an external forms printing service. PolicyCenter stores form patterns, a set of information used
to identify each form.
For detailed information on forms, see the Application Guide.
For more information on external forms printing service integration, see Plugins, Prebuilt Integrations, and SOAP
APIs.

Form patterns information

Cloud API uses the /admin/v1/form-patterns endpoint to work with all aspects of a form pattern. With this endpoint
and its child endpoints you can retrieve and update form pattern basic information, products, transaction types,
jurisdiction availability and replacements, and policy change behavior.

Retrieving form patterns

Use the following endpoints to retrieve form patterns:
• GET /admin/v1/form-patterns
• GET /admin/v1/form-patterns/{policyFormPatternId}
Note:

The information retrieved by these endpoints includes everything located on all tabs of the Form Pattern
screen in the user interface except jurisdiction availability. See ““Form patterns lookups”” below for
information on retrieving jurisdiction availability. See Application Guide for user interface information.
The following retrieves all available form patterns:
Command

GET /admin/v1/form-patterns

Response

{
"data": [

Form patterns 343

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"attributes": {
"code": "DecSheet",
"customFormInference": true,
"edition": "0100",
"endorsementNumbered": false,
"formNumber": "PA 00DS",
"id": "pc:101",
"inferenceTime": {
"code": "bind",
"name": "Bind Time"
},
"jobTypes": [
{
"code": "PolicyChange",
"name": "Policy Change"
},
{
"code": "Renewal",
"name": "Renewal"
},
{
"code": "Rewrite",
"name": "Rewrite"
},
{
"code": "Submission",
"name": "Submission"
}
],
"name": "Dec Sheet",
"policyLine": {
"displayName": "Personal Auto Line",
"id": "PersonalAutoLine"
},
"priority": 0,
"products": [
{
"displayName": "Personal Auto",
"id": "PersonalAuto"
}
],
"reissueOnChange": true,
"removalEndorsement": false
},
…
},
{
"attributes": {
"code": "FormCPP01",
"edition": "00 00",
"endorsementNumbered": true,
"formNumber": "CPP 01",
"genericFormInference": {
"code": "GenericAlwaysAddedForm",
"displayName": "No additional criteria"
},
"id": "pc:102",
"inferenceTime": {
"code": "quote",
"name": "Quote Time"
},
"jobTypes": [
{
"code": "PolicyChange",
"name": "Policy Change"
},
{
"code": "Renewal",
"name": "Renewal"
},
{
"code": "Rewrite",
"name": "Rewrite"
},
{
"code": "Submission",
"name": "Submission"
}
],
"name": "Commercial Package Policy Definition",
"priority": 1,
"products": [],
"reissueOnChange": false,
"removalEndorsement": false
},
…

344 Form patterns

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Creating form patterns

You can create a new form pattern with the following endpoint:
• POST /admin/v1/form-patterns
The following properties are required in the request:

Parameter Type Description

code string The form pattern code. This value must be globally unique. PolicyCenter
uses this value to link the form to a form pattern. This value cannot
contain spaces.

edition string The form edition. PolicyCenter uses this value, in conjunction with the
formNumber field, to indicate that two or more patterns are different
editions of the same form. Similar to formNumber, this is an arbitrary
string, but typically it is the edition used by the issuance system.
Note: If you add a new edition, you must also update the availability
dates of the old and new patterns. Merely setting the edition is not
sufficient.

endorsementNumbered Boolean True if this form must have an endorsement number assigned to it at
inference time.
The endorsement number indicates the order in which the form is added
to the policy. The insurer decides whether the form requires an
endorsement number.
Some insurers require an endorsement number for forms added after
issuing the policy. For example, a form added in a policy change could
require an endorsement number.

formNumber string The form number. This is an arbitrary string, but it typically is the form
number used by the issuance system. This field is the form label that
shows in the PolicyCenter user interface.

genericFormInference string The string must be the name of a class that implements the gw.forms.
GenericFormInference interface. Depending on the value, other
fields could be required. See “Form inference” on page 347 below for
more details.
Note: This property is not required if you’re using a custom inference
class. See “Form inference” on page 347 below for details.

inferenceTime FormInferenceTime Forms cannot be assigned directly to policies. They are applied
Typekey automatically at a specified stage of the policy creation process, such as
when the policy is quoted or bound. This field specifies the stage at
which the form is applied to the policy.

jobTypes Typekey from the An array of job types that use this form pattern.
FormPatternJobs
typefilter on the Jobs
typelist

name string A human-readable description of the form pattern.

products array of Product code ids The products to which this form pattern applies.

The following example creates a new form pattern for the PersonalAuto product that gets applied to a policy when a
submission or policy change is quoted:

Form patterns 345

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Command

POST /admin/v1/form-patterns

Request

{
"data": {
"attributes": {
"code": "Code001",
"edition": "0001",
"endorsementNumbered": true,
"formNumber": "Test001",
"genericFormInference": {
"code": "GenericRemovalAndReplacementEndorsementForm"
},
"inferenceTime": {
"code": "quote"
},
"jobTypes": [
{
"code": "PolicyChange"
},
{
"code": "Submission"
}
],
"name": "Test Form 001",
"products": [
{
"id": "PersonalAuto"
}
]
}
}
}

Updating form patterns

You can use the following endpoints to update and delete form patterns:
• PATCH /admin/v1/form-patterns/{policyFormPatternId}
• DELETE /admin/v1/form-patterns/{policyFormPatternId}
The following example changes the job type to Renewal on form pattern pc:910:
Command

PATCH /admin/v1/form-patterns/pc:910

Request

{
"data": {
"attributes": {
"jobTypes": [
{
"code": "Renewal"
}
]
}
}
}

Note that in this example the Renewal job type is not added to existing job types for this form; all existing job types on
form pattern pc:910 are replaced with the value specified in the PATCH request. This is due to the fact that PATCH on
an array in Cloud API is destructive, not additive. When you PATCH an array, the new content replaces the previous
content. If you want to add to an array, the PATCH request must contain all current members of the array as well as the
member being added.
To delete the form pattern in the preceding example, use the following command:

DELETE /admin/v1/form-patterns/pc:910

346 Form patterns

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Note: DELETE works only in development mode. The command will throw an exception if you try to delete a
form pattern when the server is in production mode.
Form inference
When you create a new form pattern, you can use custom form inference or generic form inference. This section
describes using generic form inference. To use custom form inference, see "Adding a custom inference class for form
patterns" in the Application Guide and "Configuring custom form inference" in the Application Guide for more
information.
If you use generic form inference, you must include a value for the genericFormInference property. The code is a
string that contains the name of a class that implements the gw.forms.GenericFormInference interface.
Depending on the value of the genericFormInference property, there could be properties required for form pattern
creation in addition to those specified in the table above. The following table lists the additional required properties for
each base configuration generic form inference condition.

genericFormInference value Additional required properties

GenericAdditionalInsuredForm policyLine

GenericAdditionalInterestForm policyLine

GenericAlwaysAddedEveryJobForm none

GenericAlwaysAddedForm none

GenericClauseNonExistenceForm clause
policyLine

GenericClauseSelectionForm clause
policyLine

GenericCovTermSelectionForm clause
policyLine
selectedCovTerm

GenericCoverableTypeKeyForm coverableType
coverableTypeKey
coverableTypeKeyExistsOnAll
coverableTypeList
policyLine

GenericRemovalAndReplacementEndorsementForm none

GenericRemovalEndorsementForm none

You might have a form that requires inference logic beyond what you can specify with the base configuration classes.
In this case, you can either configure a new generic forms inference class or specify a custom form inference class. The
custom form inference class overrides the base configuration settings.

Form patterns lookups

PolicyCenter automatically generates the list of forms for a policy by using forms inference logic and configuration
settings. For example, if a user submits a new auto policy, the forms to print when issuing the policy can be inferred by
the coverages, vehicles, and other fields. Included in this logic is a lookup of the jurisdiction and availability.

Form patterns 347

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Forms can be designated as being explicitly available or unavailable in certain jurisdictions. With Cloud API, you can
retrieve, add, and update jurisdiction availability information through the form patterns lookups endpoints.
Note: The information accessed by these endpoints corresponds to the information in the Availability table
under the Jurisdictions tab in the user interface.

Retrieving jurisdiction availability

The list of jurisdiction availability for each form pattern is accessed through the form pattern lookups endpoints:
• GET /admin/v1/form-patterns/{policyFormPatternId}/lookups
• GET /admin/v1/form-patterns/{policyFormPatternId}/lookups/{lookupId}
Here is an example of retrieving the jurisdiction availability for form pattern pc:102:
Command

GET /admin/v1/form-patterns/pc:102/lookups

Response

{
"data": [
{
"attributes": {
"availability": {
"code": "Unavailable",
"name": "Unavailable"
},
"id": "pc:909",
"jurisdiction": {
"code": "OK",
"name": "Oklahoma"
},
"startEffectiveDate": "1989-12-01T08:00:00.000Z"
},
…
},
{
"attributes": {
"availability": {
"code": "Available",
"name": "Available"
},
"id": "pc:910",
"jurisdiction": {
"code": "MT",
"name": "Montana"
},
"startEffectiveDate": "1989-12-01T08:00:00.000Z"
},
…
}

Adding jurisdiction availability

You can add jurisdiction availability information to a form pattern with the following endpoint:
• POST /admin/v1/policy-form-patterns/{policyFormPatternId}/lookups
The following example makes form pc:910 unavailable in the Florida jurisdiction as of July 26, 2024:
Command

POST /admin/v1/form-patterns/pc:910/lookups

Request

{
"data": {
"attributes": {
"availability": {
"code": "Unavailable"
},
"startEffectiveDate": "20240726",
"jurisdiction": {

348 Form patterns

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "FL"
}
}
}
}

Updating jurisdiction availability

You can update and delete a form pattern jurisdiction availability with the following endpoints:
• PATCH /admin/v1/form-patterns/{policyFormPatternId}/lookups/{lookupId}
• DELETE /admin/v1/form-patterns/{policyFormPatternId}/lookups/{lookupId}
The following example changes the availability of the jurisdiction with ID pc:90001 on form pattern pc:910 to
Available:

Command

PATCH /admin/v1/form-patterns/pc:910/lookups/pc:90001

Request

{
"data": {
"attributes": {
"availability": {
"code": "Available"
}
}
}
}

The following command deletes jurisdiction availability pc:90001 from form pattern pc:910:

DELETE /admin/v1/form-patterns/pc:910/lookups/pc:90001

Form patterns with lookups

You can use request inclusion to create a form pattern with lookups. Here is an example:
Command

POST /admin/v1/form-patterns

Request

{
"data": {
"attributes": {
"code": "Code002",
"edition": "0001",
"endorsementNumbered": true,
"formNumber": "Test002",
"genericFormInference": {
"code": "GenericAlwaysAddedForm"
},
"inferenceTime": {
"code": "quote"
},
"jobTypes": [
{
"code": "PolicyChange"
},
{
"code": "Submission"
}
],
"name": "Test Form 002",
"products": [
{
"id": "PersonalAuto"
}
]

Form patterns 349

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
},
"included": {
"FormPatternLookup": [
{
"attributes": {
"availability": {
"code": "Available"
},
"endEffectiveDate": "2024-01-01",
"jurisdiction": {
"code": "CA"
},
"startEffectiveDate": "2022-01-01"
},
"method": "post",
"uri": "/admin/v1/form-patterns/this/lookups"
}
]
}
}

Policy and job forms

You can retrieve a list of all the forms associated with a particular job or policy. Because forms are inferred, you can’t
directly add a form to a job or a policy, nor can you update it or delete it from the policy.
Use the following endpoints to retrieve a list of forms for a job or a policy:
• GET /job/v1/jobs/{jobId}/forms
• GET /policy/v1/policies/{policyId}/forms
These endpoints do not return an actual representation of the forms. Instead they return identifying information that
indicates the physical forms that the issuance system creates.
Note: When you retrieve a list of forms on a policy, the list can change between quoting and binding. The list
may be different because the information to accurately infer some forms is available only at binding or
issuance.

350 Form patterns

chapter 39

Job search

Use the following endpoint to search for jobs:

• /job/v1/search/jobs
To execute a search, a caller can submit a POST request to a search endpoint. The request payload must contain at least
one of the following properties:
• companyName: Complete company name of the insured
• firstName and lastName: Complete first and last name of the insured
• jobNumber: The job number
• officialId: Official identification code
• phone: A phone number
• policyNumber: The policy number
• producerCode.id: A valid producer code
When searching for jobs, the caller must also include the jobType.code property, which denotes the type of job (such
as submission or renewal).
The response payload of a search request can be further filtered by adding any of the following properties to the
request:
• city: A city location associated with a job
• jurisdiction.code: A jurisdiction code
• postalCode: A postal code associated with a job
• product.id: A product ID for the LOB
• state.code: A state associated with a job
• street: A street address associated with a job

Job search 351

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

352 Job search

chapter 40

Out-of-sequence conflicts

Out-of-sequence policy transactions are policy transactions with an effective date that is before the effective date of a
previous policy transaction on the same policy. Insurers sometimes call these situations out-of-sequence endorsements.
PolicyCenter uses the term out-of-sequence.
An out-of-sequence conflict occurs when a policy change has a transaction date later than another policy transaction,
but an effective date earlier than that other policy transaction.
The Job API provides endpoints that can be used to identify and resolve out-of-sequence conflicts on policy
transactions.

Identifying out-of-sequence conflicts

Policy changes are applied to jobs that are in Draft state, which is when a potential out-of-sequence conflict could be
introduced.
While the job is in Draft state, no out-of-sequence warnings are raised, even when a conflicting change is added. When
a caller attempts to quote a job that contains one or more out-of-sequence conflicts, a 400 response will be returned
with a message informing the caller of the presence of conflicts.
To identify out-of-sequence conflicts on a job, a caller can submit a GET request to the /job/v1/jobs/{jobId}/oos-
conflicts endpoint. If are no conflicts, then the request will return an empty response.

For a job that has out-of-sequence conflicts, the response body will contain a conflicts property, which is an array
holding one or more conflict objects.
The following example shows an out-of-sequence conflict for date of birth values set for Bill Preston:

{
"data": {
"attributes": {
"conflicts": [
{
"conflictValues": [
{
"displayValue": "01/01/1975",
"effectiveDate": "2019-03-01T00:01:00.000Z"
},
{
"displayValue": "01/01/1977",
"effectiveDate": "2019-04-01T00:01:00.000Z"
}
],
"entity": {
"displayName": "Bill Preston",
"id": "pc:703",
"type": "PolicyContact",
"uri": "/job/v1/jobs/pc:204/contacts/pc:703"

Out-of-sequence conflicts 353

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
"field": "dateOfBirthInternal",
"id": "b0aca4bc",
"originalValue": "01/01/1970",
"yourValue": "01/01/1980"
}
]
},
. . .
}
}

The response body contains the following fields:

• conflictValues: An array of objects for each conflict, containing two or more objects
• displayValue: A value that is in conflict
• effectiveDate: The effective date of the associated value
• entity: The target Guidewire entity
• field: The field that has the conflict
• id: The unique identifier for the conflict
• originalValue: The original field value prior to the conflict
• yourValue: The latest field value applied by the caller that gave rise to the conflict

Resolving out-of-sequence conflicts

To resolve out-of-sequence conflicts on a job, a caller must submit a POST request to the /job/v1/jobs/{jobId}/
oos-conflicts/resolve endpoint. The request body must contain an overrides field, which is an array of override
selections for resolving the conflicts. All conflicts must be resolved in the POST.
To retain the original field values for each conflict, thus discarding all subsequent changes, a caller can submit a
request body that contains an empty array for the overrides field:

{
"data": {
"attributes": {
"overrides": [ ]
}
}
}

If the caller wishes to keep one or more changes to any conflicted fields, then the request body must explicitly declare
value selections for all fields that are in conflict. In this case, the
overrides

array must contain an object for each conflict, each having the following properties:
• id: The conflict ID, as a string
• resolution: A string value of either acceptYours or discardYours
As previously mentioned, each conflict object contains an originalValue and yourValue field. When resolving
conflicts, a caller must choose which of those values to retain. To keep the original value, the caller would apply the
discardYours value to the resolution property. Otherwise, the caller would apply the acceptYours value to the
property.
In the following example request body, the conflicting birthdates for Bill Preston are resolved by choosing the value
indicated by the yourValue field in the initial conflict object:

{
"data": {
"attributes": {
"overrides": [
"id": "b0aca4bc",
"resolution": "acceptYours"
]

354 Out-of-sequence conflicts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}
}

Example: Identifying and resolving out-of-sequence conflicts

It is possible to create multiple out-of-sequence conflicts on a job. This example shows how to resolve three conflicts
on the same job.
Consider the following sequence:
1. In the initial job, an account was created for Bill Preston, his date of birth was set to January 1, 1970, and his
address was set to null. Additionally, the number of employees at his company was set at 0.
2. In the first change to the job, Bill's date of birth was revised to January 1, 1975, and he was given an address, the
first line of which is 24 Appletree Rd.
3. In the second change, Bill's date of birth was revised to January 1, 1977, and the number of employees at his
company was raised to 2.
4. In the third change, Bill's date of birth was revised yet again, to January 1, 1980, and the first line of his address
was changed to 88 Maple Lane. Also, the number of employees at his company was changed to null.
The above information, in table form:

Sequence Date of birth Address Employee count

1 1970-01-01 null 0
2 1975-01-01 24 Appletree Rd.
3 1977-01-01 2
4 1980-01-01 88 Maple Lane null

After these changes have been submitted, a call to /job/v1/jobs/{jobId}/oss-conflicts returns the following
response:

{
"data": {
"attributes": {
"conflicts": [
{
"conflictValues": [
{
"displayValue": "01/01/1975",
"effectiveDate": "2019-03-01T00:01:00.000Z"
},
{
"displayValue": "01/01/1977",
"effectiveDate": "2019-04-01T00:01:00.000Z"
}
],
"entity": {
"displayName": "Bill Preston",
"id": "pc:703",
"type": "PolicyContact",
"uri": "/job/v1/jobs/pc:204/contacts/pc:703"
},
"field": "dateOfBirthInternal",
"id": "b0aca4b",
"originalValue": "01/01/1970",
"yourValue": "01/01/1980"
},
{
"conflictValues": [
{
"displayValue": "Address Line 1; Future Change",
"effectiveDate": "2019-03-01T00:01:00.000Z"
},
{
"displayValue": "Address Line 1; Future Change",
"effectiveDate": "2019-04-01T00:01:00.000Z"
}
],
"entity": {
"displayName": "1: Address Line 1; OOS Change, CA",
"id": "201",

Out-of-sequence conflicts 355

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"type": "PolicyLocation",
"uri": "/job/v1/jobs/pc:204/locations/201"
},
"field": "addressLine1Internal",
"id": "df78662",
"originalValue": "",
"yourValue": "Address Line 1; OOS Change"
},
{
"conflictValues": [
{
"displayValue": "2",
"effectiveDate": "2019-04-01T00:01:00.000Z"
}
],
"entity": {
"displayName": "1: Address Line 1; OOS Change, CA",
"id": "201",
"type": "PolicyLocation",
"uri": "/job/v1/jobs/pc:204/locations/201"
},
"field": "employeeCountInternal",
"id": "47761d4",
"originalValue": "0",
"yourValue": ""
}
]
},
. . .
}

The same response can be constrained using field selection, by appending ?

fields=conflicts.id,conflicts.field,conflicts.originalValue,conflicts.yourValue to the request URL:

{
"data": {
"attributes": {
"conflicts": [
{
"field": "dateOfBirthInternal",
"id": "b0aca4b",
"originalValue": "01/01/1970",
"yourValue": "01/01/1980"
},
{
"field": "addressLine1Internal",
"id": "df78662",
"originalValue": "",
"yourValue": "88 Maple Lane"
},
{
"field": "employeeCountInternal",
"id": "47761d4",
"originalValue": "0",
"yourValue": ""
}
]
}
}
}

Note that in the response object the JSON null type is represented by an empty string.
To resolve these conflicts, choices must be made between the original values and the most recent values, and this
information must be passed in the request body to POST /job/v1/jobs/{jobId}/oss-conflicts/resolve:

{
"data": {
"attributes": {
"overrides": [
{
"id": "b0aca4b",
"resolution": "acceptYours"
},
{
"id": "df78662",
"resolution": "acceptYours"
},
{
"id": "47761d4",
"resolution": "discardYours"
}

]
}

356 Out-of-sequence conflicts

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

Following this post, Bill's birthdate will be January 1, 1980, his address will be 88 Maple Lane, and the number of
employees at his company will be set to "0".

Out-of-sequence conflicts 357

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

358 Out-of-sequence conflicts

chapter 41

Policy archiving

The topics in this section describe how to use Cloud API to work with archived policies in PolicyCenter. To get a full
understanding of how archiving works in PolicyCenter, review the Data Archiving documentation.
The following are the Cloud API endpoints (all of which are located in the policy API) specific to archiving:
• GET /bulk-policy-archive-retrievals
• POST /bulk-policy-archive-retrievals
• GET /bulk-policy-archive-retrievals/{bulkPolicyArchiveRetrievalRecordId}
• DELETE /bulk-policy-archive-retrievals/{bulkPolicyArchiveRetrievalRecordId}
• POST /policies/{policyId}/retrieve-from-archive
• POST /policies/{policyId}/set-do-not-archive
In addition, you can filter on policies to find archiving information.
The following sections describe how to use Cloud API for policy archiving actions.
• “Determine whether archiving is enabled” on page 359
• “List archived policies” on page 360
• “Set policies to Do Not Archive” on page 361
• “Retrieve an archived policy” on page 362
• “Bulk policy archive retrieval” on page 362

Determine whether archiving is enabled

Before you can use any of the archiving endpoints, you must have archiving enabled in PolicyCenter. See Data
Archiving for more information.
If you attempt to access one of the archiving endpoints on a policy when archiving has not been enabled you receive
the following error:

{
"status": 400,
"errorCode": "gw.api.modules.rest.framework.v1.exceptions.OperationNotCurrentlyAllowedException",
"userMessage": "The operation is not currently allowed for this resource",
"details": [
{
"message": "Cannot perform this action because Archiving is not enabled"

Policy archiving 359

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
]
}

If you attempt to access the bulk-policy-archive-retrievals endpoint when archiving is disabled you receive a
“404 no resource found” error.

List archived policies

You can retrieve a list of archived policies by filtering on the policies themselves or by filtering for archived policies
within jobs.

List all archived policies

You can retrieve a list of all policies that have been archived by filtering on the archived property. The following
example returns the id, policyNumber, and archived properties of all policies where archived is true.
Command

GET /policy/v1/policies?fields=id,policyNumber,archived&filter=archived:eq:true

Response

{
"data": [
{
"attributes": {
"archived": true,
"id": "pc:10",
"policyNumber": "1012345678"
}
},
{
"attributes": {
"archived": true,
"id": "pc:12",
"policyNumber": "2712345678"
}
}
…
}
}

Policies that are not archived could have an archived value of false or the value could be null. Therefore, to find all
jobs with policies that are not archived, filter for policies where archived is not true (rather than filtering for false):

GET /policy/v1/policies?fields=id,policyNumber,archived&filter=archived:ne:true

Note:

It’s possible that a policy could be returned that doesn’t seem to match the filter criteria. For example, you
could filter for policies where archived is set to true and see a policy in the return data that does not have that
property set to true. This can happen when an older term on the policy is archived, but the most recent term is
not. The query will return the policy because at least one of the terms on the policy is archived, but it will not
show the archived property as true because by default it’s showing data for only the most recent term. See
“Retrieve an archived policy” later in this topic for information on using the asOfDate parameter to track
policies by policy term.

List archived policies by job

You can retrieve a list of jobs associated with archived policies by filtering on the archived property. The following
example returns the id, policyNumber, and archived properties of all jobs where archived is true.
Command

GET /job/v1/jobs?fields=id,policyNumber,archived&filter=archived:eq:true

360 Policy archiving

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

{
"data": [
{
"attributes": {
"archived": true,
"id": "pc:101",
"policyNumber": "1012345678"
}
},
{
"attributes": {
"archived": true,
"id": "pc:105",
"policyNumber": "2712345678"
}
},
{
"attributes": {
"archived": true,
"id": "pc:320",
"policyNumber": "2712345678"
}
},
...
}
}

Policies that are not archived could have an archived value of false or the property could be null. Therefore, to find all
jobs with policies that are not archived, filter for policies where archived is not true (rather than filtering for false):

GET /job/v1/jobs?fields=id,policyNumber&filter=archived:ne:true

Set policies to Do Not Archive

When archiving is enabled, policies that meet the archiving criteria will be automatically archived. See Data Archiving
for information on how policies are determined to be archivable.
If you have a policy that you don’t want archived, set that policy’s Do Not Archive flag to true. In Cloud API, you can
set this flag to true (do not archive) or false (archive when appropriate) by using this command:
POST /policies/{policyId}/set-do-not-archive
In the request body, pass in the doNotArchive property with the desired value. Here’s an example that prevents
archiving of the policy by setting the doNotArchive property to true:
Command

POST /policies/pc:310/set-do-not-archive

Request

{
"data": {
"attributes": {
"doNotArchive": true
}
}
}

Optionally, you can include a comment in the request body:

{
"data": {
"attributes": {
"doNotArchive": true,
"comment": "This policy should not be archived"
}
}
}

Policy archiving 361

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

To allow a policy that has been set to Do Not Archive to be archived, call set-do-not-archive with doNotArchive
set to false in the request body.
If you set this property to true on a policy that has already been archived, that policy will not automatically be
retrieved, it will remain archived until you retrieve it.

Retrieve an archived policy

Retrieving a policy from the archive will restore it to the database and it will no longer be archived.
Note:
See Data Archiving for information on retrieving archived policies from previous versions of PolicyCenter.
Use the following command to retrieve a single archived policy:
POST /policies/{policyId}/retrieve-from-archive
For example, to retrieve archived policy pc:320, us the following:
Command

POST /policies/pc:320/retrieve-from-archive

A request body is not required, but optionally you can include a reason for the retrieval.
Request

{
"data": {
"attributes": {
"reason": "This policy needs to be unarchived"
}
}
}

There is no response body on a successful retrieval. However, the response header provides information about the
policy that can be useful when tracking the policy term that was retrieved. Look for the “Location” URL in the
response header, which includes the asOfDate:
Location: /policy/v1/policies/pc:320?asOfDate=2023-05-08T07:01:00.000Z
Running a GET on this URL will ensure you retrieve information for this policy term in the case where a policy
changes after this date.
Note:

PolicyCenter does not retrieve the policy immediately. Policies are retrieved when the Restore Policy Term
work queue runs. Typically, this process runs at scheduled times throughout the day. Users with certain
administrative privileges can run the RestorePolicyTerm process manually from the user interface in the Server
Tools Work Queue Info screen.

Bulk policy archive retrieval

You can perform archiving actions on policies in bulk, retrieving multiple policies at once and maintaining a record of
those retrievals.
Note:

See Data Archiving for information on retrieving archived policies from previous versions of PolicyCenter.

Bulk retrieve archived policies

You can retrieve multiple policies from archive at once. To do this, call the following endpoint, passing it an array of
policy numbers you want to retrieve.

362 Policy archiving

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

POST /policy/v1/bulk-policy-archive-retrievals
For example:
Command

POST /policy/v1/bulk-policy-archive-retrievals

Request

{
"data": {
"attributes": {
"policyNumbers": ["7890123456","P012345678"],
"policyTermRetrievalFilter": "AllTerms",
"title": "Bulk Retrieval 1"
}
}
}

The following fields are required in the request body:

• policyNumbers: An array of policy numbers to retrieve.
• title: Any string that helps you identify the bulk retrieval. The title does not have to be unique, but it can be
helpful to give some context as to the purpose or contents of the retrieval.
• policyTermRetrievalFilter: In the base configuration, allowed values are AllTerms,
TermsInLastNumOfYears, TermsWithinPeriod. If you set this value to TermsInLastNumOfYears, you must also
provide a value for yearsOfTermsRetrieved. If you set this value to TermsWithinPeriod, you must also provide
values for toDateTermsRetrieved and fromDateTermsRetrieved.
If any of the policies cannot be retrieved the entire process fails and none of the policies in the bulk process are
retrieved.
Note:

PolicyCenter does not retrieve the policies immediately. Policies are retrieved when the Restore Policy Term
work queue runs. Typically, this process runs at scheduled times throughout the day. Users with certain
administrative privileges can run the RestorePolicyTerm process manually from the UI in the Server Tools
Work Queue Info screen.
Bulk archive retrieval status
You can use Cloud API endpoints to determine the status of a bulk retrieval.
To retrieve a list of all bulk retrieval records, use the following command:
Command

GET /policy/v1/bulk-policy-archive-retrievals

Response

{
"data": [
{
"attributes": {
"createdDate": "2023-06-12T21:53:25.621Z",
"id": "pc:789",
"title": "Bulk Retrieval 1"
},
…
}
}

Append fields=*all to see the status of all policies within each retrieval batch:
Command

GET /policy/v1/bulk-policy-archive-retrievals?fields=*all

Policy archiving 363

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

{
"data": [
{
"attributes": {
"createdDate": "2023-06-12T21:53:25.621Z",
"id": "pc:789",
"policyTermRetrievalStatuses": [
{
"policyNumber": "P012345678",
"status": "Archived",
"uri": "/policy/v1/policies/pc:110?asOfDate=2023-05-08T07:01:00.000Z"
},
{
"policyNumber": "7890123456",
"status": "Retrieved",
"uri": "/policy/v1/policies/pc:122?asOfDate=2021-03-09T08:01:00.000Z"
}
],
"policyTermsInArchive": 1,
"policyTermsRetrieved": 1,
"policyTermsRetrieving": 0,
"title": "Bulk Retrieval 1"
},
…

You can check on the status of an individual bulk retrieval by including the id of the retrieval. For example:
Command

GET /policy/v1/bulk-policy-archive-retrievals/pc:789

Response

{
"data": {
"attributes": {
"createdDate": "2023-06-12T21:53:25.621Z",
"id": "pc:789",
"policyTermsInArchive": 0,
"policyTermsRetrieved": 2,
"policyTermsRetrieving": 0,
"title": "Bulk Retrieval 1"
},
…
}

The response includes the following fields:

• policyTermsInArchive: The number of policy terms in the bulk retrieval that have not yet been retrieved.
• policyTermsRetrieved: The number of policy terms in the bulk retrieval that have been retrieved.
• policyTermsRetrieving: The number of policy terms in the bulk retrieval that are being processed for retrieval.

Bulk archive record deletion

After a bulk policy archive retrieval has completed and you no longer need a record of that retrieval, you can delete the
record.
DELETE /policy/v1/bulk-policy-archive-retrievals/{retrieval-id}
This command does not delete any of the policies associated with the retrieval, it deletes only the record of the bulk
retrieval.

364 Policy archiving

chapter 42

Policy holds

The purpose of a policy hold is to allow insurers to temporarily prevent certain transactions from taking place on
policies within one or more geographic regions. There are two types of policy holds: underwriting and regulatory.
Underwriting holds are put in place to account for natural disasters. For example, insurers may not want to allow users
to create or update policies in a region that is predicted to be hit by a hurricane in the near future.
Regulatory holds are put in place when regulations, such as rate or coverage changes, are in process. Insurers might not
want to begin creating or updating a policy only to have to update it again when the change becomes official or is
entered into the system.

Working with policy holds

Use the following endpoints to work with the basic details for policy holds:
• GET /admin/v1/policy-holds
• GET /admin/v1/policy-holds/{policyHoldId}
• POST /admin/v1/policy-holds
• PATCH /admin/v1/policy-holds/{policyHoldId}
• DELETE /admin/v1/policy-holds/{policyHoldId]

Querying for policy holds

To retrieve a list of all policy holds, use the following endpoint:
GET /admin/v1/policy-holds
For example:

GET /admin/v1/policy-holds

{
"data": [
{
"attributes": {
"description": "UW Hold 5",
"displayName": "UW Hold 5",
"holdType": {
"code": "UWHold",
"name": "Underwriting Hold"
},

Policy holds 365

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"id": "pc:105",
"policyHoldCode": "uw-hold-5",
"startDate": "2023-03-30",
"uwIssueLongDescription": "UW policy hold 5",
"uwIssueType": {
"code": "UWPolicyHold",
"displayName": "UW Policy Hold"
}
},
...
},
{
"attributes": {
"description": "UW Hold 4",
"displayName": "UW Hold 4",
"endDate": "2023-09-10",
"holdType": {
"code": "UWHold",
"name": "Underwriting Hold"
},
"id": "pc:104",
"policyHoldCode": "uw-hold-4",
"startDate": "2023-03-30",
"uwIssueLongDescription": "UW policy hold 4",
"uwIssueType": {
"code": "UWPolicyHold",
"displayName": "UW Policy Hold"
}
},
...

To retrieve a single policy hold, include the policy hold ID with the endpoint.
GET /admin/v1/policy-holds/{policyHoldId}
For example, the following query returns information about the policy hold with the id pc:104:

GET /admin/v1/policy-holds/pc:104

{
"count": 1,
"data": [
{
"attributes": {
"description": "UW Hold 4",
"displayName": "UW Hold 4",
"endDate": "2023-09-10",
"holdType": {
"code": "UWHold",
"name": "Underwriting Hold"
},
"id": "pc:104",
"policyHoldCode": "uw-hold-4",
"startDate": "2023-03-30",
"uwIssueLongDescription": "UW policy hold 4",
"uwIssueType": {
"code": "UWPolicyHold",
"displayName": "UW Policy Hold"
}
},
...

Creating policy holds

To create a new policy hold, use the following method:
POST /admin/v1/policy-holds
Provide the following fields in the request:

Property Description Required?

description A description of the policy hold. Yes
holdType The type of hold. Values are from the UWIssueCheckingSet typelist with the Yes
PolicyHoldsTypeFilter applied. By default, available values are:
• UWHold
• RegulatoryHold

366 Policy holds

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Property Description Required?

policyHoldCode A unique code for this policy hold. Yes
This value cannot contain spaces.
startDate The start date of the policy hold. Must be in the format YYYY-MM-DD. Yes
uwIssueLongDescription A description of the underwriting issue. Yes
endDate The end date of the policy hold. Must be in the format YYYY-MM-DD. No
uwIssueType • The underwriting issue type. With the base configuration, the following are Yes
required:
• If holdType is UWHold, this value must be UWPolicyHold
• If holdType is RegulatoryHold, this value must be RegulatoryPolicyHold

The following examples show how to create new underwriting and regulatory policy holds.

Creating an underwriting policy hold

Command

POST /admin/v1/policy-holds

Request body

{
"data": {
"attributes": {
"description": "UW Hold 1",
"holdType": {
"code": "UWHold"
},
"policyHoldCode": "uw-hold-1",
"startDate": "2023-03-30",
"uwIssueLongDescription": "Underwriting policy hold 1",
"uwIssueType": {
"code": "UWPolicyHold"
}
}
}
}

Creating a regulatory policy hold

Creating a regulatory policy hold is similar to creating an underwriting hold. Note the values in the holdType and
uwIssueType fields.

Request body

{
"data": {
"attributes": {
"description": "Reg Hold 1",
"holdType": {
"code": "RegulatoryHold"
},
"policyHoldCode": "reg-hold-1",
"startDate": "2023-03-30",
"uwIssueLongDescription": "Regulatory policy hold 1",
"uwIssueType": {
"code": "RegulatoryPolicyHold"
}
}
}
}

Modifying policy holds

Use the following endpoint to modify a policy hold:
PATCH /admin/v1/policy-holds/{policyHoldId}

Policy holds 367

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following fields can be updated with the PATCH endpoint:

• description
• startDate
• endDate
• uwIssueLongDescription
Command

PATCH /admin/v1/policy-holds/pc:101

Request body

{
"data": {
"attributes": {
"endDate": "2023-05-30"
}
}
}

Deleting policy holds

You can delete a policy hold with the DELETE endpoint.
DELETE /admin/v1/policy-holds/{policyHoldId}
For example:

DELETE /admin/v1/policy-holds/pc:101

Policy hold components

Policy holds include additional components that further define the hold.
• Policy hold rules: Defines the types of policies to which the hold applies.

IMPORTANT: If you create a policy hold without creating any rules, the policy hold will not take effect even
if you’ve reached the start date.

See “Adding policy hold rules” on page 370 for more information.
Note: If you create a policy hold without creating any rules for that hold, in addition to the policy hold not
taking effect, the details of that policy hold will not be updateable in the user interface until policy hold
rules are added, either through the UI or the Cloud API.
• Policy hold geographic zones: Defines the geographic regions to which the hold applies. If you create a policy hold
without defining at least one geographic zone, the policy hold will apply to all geographic zones.
See “Policy hold geographic zones” on page 373 for more information.

Policy hold rules

Policy hold rules identify the types of policies that are being placed on hold. Policy hold rules specify the Line of
Business (policyLineType), the Policy Transaction Type (jobType), the Transaction Date Type (jobDateType), and
Coverage (coveragePattern).
The following endpoints are available for policy hold rules:
• GET /admin/v1/policy-holds/{policyHoldId}/rules

368 Policy holds

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET /admin/v1/policy-holds/{policyHoldId}/rules/{policyHoldRuleId}
• POST /admin/v1/policy-holds/{policyHoldId}/rules
• PATCH /admin/v1/policy-holds/{policyHoldId}/rules/{policyHoldRuleId}
• DELETE /admin/v1/policy-holds/{policyHoldId}/rules/{policyHoldRuleId}

Querying for policy hold rules

To retrieve all the rules for a policy hold, use the following endpoint:
GET /admin/v1/policy-holds/{policyHoldId}/rules
For example:

GET /admin/v1/policy-holds/pc:101/rules

{
"count": 2,
"data": [
{
"attributes": {
"id": "pc:10001",
"jobDateType": {
"code": "Effective",
"name": "Effective Date"
},
"jobType": {
"code": "Renewal",
"name": "Renewal"
},
"policyLineType": {
"code": "PersonalAutoLine",
"name": "Personal Auto"
}
},
...

},
{
"attributes": {
"coveragePattern": {
"displayName": "Underinsured Motorist - Bodily Injury",
"id": "PAUIMBICov"
},
"id": "pc:10002",
"jobDateType": {
"code": "Effective",
"name": "Effective Date"
},
"jobType": {
"code": "Issuance",
"name": "Issuance"
},
"policyLineType": {
"code": "PersonalAutoLine",
"name": "Personal Auto"
}
},
...
}

To retrieve a single policy hold rule, include the policy hold rule ID.
GET /admin/v1/policy-holds/{policyHoldId}/rules/{policyHoldRuleId}
For example:

GET /admin/v1/policy-holds/pc:101/rules/pc:10002

{
"count": 1,
"data": [
{
"attributes": {
"coveragePattern": {
"displayName": "Underinsured Motorist - Bodily Injury",
"id": "PAUIMBICov"
},
"id": "pc:10002",
"jobDateType": {

Policy holds 369

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "Effective",
"name": "Effective Date"
},
"jobType": {
"code": "Issuance",
"name": "Issuance"
},
"policyLineType": {
"code": "PersonalAutoLine",
"name": "Personal Auto"
}
},
...
}

Adding policy hold rules

You can add a new policy hold rule with the following endpoint:
POST /admin/v1/policy-holds/{policyHoldId}/rules
The following fields are available when creating a policy hold rule:

Field Description Required?

jobDateType A typekey containing the transaction date type. You can retrieve the available values with the Yes
following command:

GET /common/v1/typelists/JobDateType

The following fields are available in the base configuration:

• For a Reference policy hold, this value must be Reference
• For an Underwriting policy hold, this value must be either Effective or Written

jobType A typekey containing the policy transaction type. Yes

Possible values in the base configuration:
• Audit
• Cancellation
• Issuance
• PolicyChange
• Reinstatement
• Renewal
• Rewrite
• RewriteNewAccount
• Sumbission

policyLineType A typekey containing the line of business. Use the following command to retrieve the available Yes
values:

GET /common/v1/typelists/PolicyLine?fields=typeKeys

Possible values in the base configuration:

• APDManualPolicyLine
• PersonalAutoLine
• PolicyLine

coveragePattern The type of coverage the rule applies to. See “Adding policy hold rule coverages” on page No
371 for more information.

The following is an example of creating a new policy hold rule.

370 Policy holds

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Command

POST /admin/v1/policy-holds/pc:101/rules

Request body

{
"data": {
"attributes": {
"jobDateType": {
"code": "Reference"
},
"jobType": {
"code": "Rewrite"
},
"policyLineType": {
"code": "PersonalAutoLine"
}
}
}
}

Adding policy hold rule coverages

In addition to the attributes included in the preceding example, you can add a type of coverage to a rule. To add a
coverage, you need to include the coverage ID when you create or modify the rule. Retrieving the coverage ID requires
you to make a series of queries to typelists.
For example, if your policyLineType is PersonalAutoLine, you can retrieve available coverages by running the
following:

GET productdefinition/v1/lines/PersonalAutoLine/coverages?fields=id,name,clauseType

{
"data": [
{
"attributes": {
"clauseType": "exclusion",
"id": "PAExcludeFedEmployeeUse",
"name": "Exclude Federal Employee Use"
}
},
{
"attributes": {
"clauseType": "coverage",
"id": "PALiabilityCov",
"name": "Liability - Bodily Injury and Property Damage"
}
},
{
"attributes": {
"clauseType": "coverage",
"id": "PAMedPayCov",
"name": "Medical Payments"
}
},
...

The coverages you can use in your rule have a clauseType of coverage.
You can then retrieve all coverables for that line type, and then retrieve the coverages for each coverable.
Retrieve the coverables for PersonalAutoLine:

GET productdefinition/v1/lines/PersonalAutoLine/coverables?fields=id

{
"data": [
{
"attributes": {
"id": "PersonalVehicle"
}
}
...

Policy holds 371

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Retrieve the coverages for the PersonalVehicle coverable:

GET productdefinition/v1/lines/PersonalAutoLine/coverables/PersonalVehicle/coverages?fields=id,name,clauseType

{
"count": 7,
"data": [
{
"attributes": {
"clauseType": "coverage",
"id": "PAComprehensiveCov",
"name": "Comprehensive"
}
},
{
"attributes": {
"clauseType": "coverage",
"id": "PACollisionCov",
"name": "Collision"
}
},
...

After finding the coverage you want to add to your policy rule, you can include the coverage ID when you add or
update your rule. In this example, collision coverage is included with the rule.
Command

POST /admin/v1/policy-holds/pc:101/rules

Request body with coveragePattern

{
"data": {
"attributes": {
"jobDateType": {
"code": "Effective"
},
"jobType": {
"code": "Issuance"
},
"policyLineType": {
"code": "PersonalAutoLine"
},
"coveragePattern": {
"code": "PACollisionCov"
}
}
}
}

Modifying policy hold rules

Use the following endpoint to modify policy hold rules:
PATCH /admin/v1/policy-holds/{policyHoldId}/rules/{policyHoldRuleId}
All fields in the preceding table available for adding policy hold rules are also available for updating.
Command

PATCH /admin/v1/policy-holds/pc:101/rules/pc:10001

Request body

{
"data": {
"attributes": {
"jobType": {
"code": "Renewal"
}
}
}
}

372 Policy holds

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Deleting policy hold rules

Use the DELETE endpoint to delete a rule from a policy hold.
DELETE /admin/v1/policy-holds/{policyHoldId}/rules/{policyHoldRuleId}
For example:

DELETE /admin/v1/policy-holds/pc:101/rules/pc:10001

Policy hold geographic zones

Policy hold geographic zones allow you to limit the policy hold to one or more geographic regions (referred to as Hold
Regions in the user interface). If you don’t define at least one geographic zone, the hold will apply to all policies that
match the specified rules.
The following endpoints are available for policy hold geographic zones:
• GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones
• GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}
• POST /admin/v1/policy-holds/{policyHoldId}/geographic-zones
• DELETE /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}

Querying for policy hold geographic zones

To retrieve all geographic zones associated with a policy hold, use the GET endpoint.
GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones
For example:

GET /admin/v1/policy-holds/pc:101/geographic-zones

{
"count": 2,
"data": [
{
"attributes": {
"code": "OR:Wasco",
"country": {
"code": "US",
"name": "United States"
},
"id": "pc:12001",
"zoneType": {
"code": "county",
"name": "County"
}
},
...
},
{
"attributes": {
"code": "CA",
"country": {
"code": "US",
"name": "United States"
},
"id": "pc:12002",
"zoneType": {
"code": "state",
"name": "State"
}
},
...

To retrieve only a single geographic zone, include the zone ID with the GET endpoint.
GET /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}

Policy holds 373

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example:

GET /admin/v1/policy-holds/pc:101/geographic-zones/pc:12001

{
"count": 1,
"data": [
{
"attributes": {
"code": "OR:Wasco",
"country": {
"code": "US",
"name": "United States"
},
"id": "pc:12001",
"zoneType": {
"code": "county",
"name": "County"
}
},
...
}

Retrieving geographic zone IDs

Before you can add a geographic zone to a policy hold, you need to find the ID for the zone you want to add. You can
retrieve geographic zones using the following endpoint:
/admin/v1/geographic-zones

It's best practice to always include filters in your command when searching for a geographic zone due to the large
number of zones available. For example, if you want to retrieve the ID for the U.S. state of California, use the
following command:

GET /admin/v1/geographic-zones?filter=country:eq:US&filter=zoneType:eq:state&filter=code:eq:CA

{
"count": 1,
"data": [
{
"attributes": {
"code": "CA",
"country": {
"code": "US",
"name": "United States"
},
"displayName": "CA",
"id": "US:SbytI2CuZcXKoqyOiaSxI",
"name": "CA",
"zoneType": {
"code": "state",
"name": "State"
}
},
...
}

Adding policy hold geographic zones

To add a geographic zone to a policy hold, use the following command:
POST /admin/v1/policy-holds/{policyHoldId}/geographic-zones
The only field you can populate when adding a geographic zone to a policy hold is the id. Here’s an example:
Command

POST /admin/v1/policy-holds/pc:101/geographic-zones

Request body

{
"data": {
"attributes": {
"geographicZone": {
"id": "US:S3_ouEweXXJCd6rFBcPnk"
}
}

374 Policy holds

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

Modifying policy hold geographic zones

You cannot modify a geographic zone on a policy hold. To modify the list of geographic zones applied to your policy
hold, you need to delete existing zones and add new ones.

Deleting policy hold geographic zones

To remove a geographic zone from a policy hold, use the following command:
DELETE /admin/v1/policy-holds/{policyHoldId}/geographic-zones/{policyHoldZoneId}
For example:

DELETE /admin/v1/policy-holds/pc:101/geographic-zones/pc:12001

Example: Policy hold setup

This example walks through the steps for creating a new policy hold and associating rules and geographic zones to that
hold.
The policy hold created in this example places holds on Personal Auto submissions with Liability - Bodily Injury and
Property Damage coverage whose effective dates are on or after April 10, 2023.
For specific details on endpoints and fields, see the following:
• “Working with policy holds” on page 365
• “Policy hold rules” on page 368
• “Policy hold geographic zones” on page 373

Create policy hold details

The first step in this example is to create a policy hold with the following details:
• Hold Type: UnderwritingHold
• Code: uw-hold-1
• Description: UW hold 1
• Hold Start Date: April 10, 2023
• UW Issue Type: UW Policy Hold
• Long Description: Underwriting policy hold 1
These details from the user interface equate to the following policy-holds Cloud API attributes and values, which
we’ll include in the request body:
• holdType: UWHold
• policyHoldCode: uw-hold-1
• description: UW hold 1
• startDate: 2023-04-10
• uwIssueType: UWPolicyHold
• uwIssueLongDescription: Underwriting policy hold 1
Command

POST /admin/v1/policy-holds

Policy holds 375

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Request body

{
"data": {
"attributes": {
"description": "UW hold 1",
"holdType": {
"code": "UWHold"
},
"policyHoldCode": "uw-hold-1",
"startDate": "2023-04-10",
"uwIssueLongDescription": "Underwriting policy hold 1",
"uwIssueType": {
"code": "UWPolicyHold"
}
}
}
}

Request response

{
"data": {
"attributes": {
...
"description": "UW hold 1",
"displayName": "UW hold 1",
"holdType": {
"code": "UWHold",
"name": "Underwriting Hold"
},
"id": "pc:101",
"policyHoldCode": "uw-hold-1",
"startDate": "2023-04-10",
...
"uwIssueLongDescription": "Underwriting policy hold 1",
"uwIssueType": {
"code": "UWPolicyHold",
"displayName": "UW Policy Hold"
}
},
...
}

Make note of the id returned in the response, in this case pc:101. You’ll need this value to add rules and geographic
zones in the next two sections.

Add rules to the policy hold

Now that we’ve created our policy hold, we need to add at least one rule.

IMPORTANT: If you don’t add at least one rule to the policy hold, the hold will not take effect even if you’ve
reached the start date.

In this example, we’re going to add the following rule to our policy hold:
• Line of Business: Personal Auto
• Policy Transaction Type: Submission
• Transaction Date Type: Effective Date
In the Cloud API, the attributes for these values are the following:
• policyLineType: PersonalAutoLine
• jobType: Submission
• jobDateType: Effective
In our endpoint we’ll use the policy hold ID we captured from the response in the previous step.
Command

POST /admin/v1/policy-holds/pc:101/rules

376 Policy holds

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Request body

{
"data": {
"attributes": {
"jobDateType": {
"code": "Effective"
},
"jobType": {
"code": "Submission"
},
"policyLineType": {
"code": "PersonalAutoLine"
}
}
}
}

Add a policy hold rule coverage

When you add a rule, you can also include a type of coverage by supplying a coverage ID. The types of coverage
available will depend on the line of business (policyLineType) you’ve specified. See “Policy hold rules” on page 368
for information on retrieving coverage IDs to apply to policy hold rules.
The following updates the rule created in the preceding step to add collision coverage.
Command

PATCH /admin/v1/policy-holds/pc:101/rules/pc:10001

Request body with coveragePattern

{
"data": {
"attributes": {
"coveragePattern": {
"code": "PACollisionCov"
}
}
}
}

Add geographic zones to the policy hold

After adding one or more rules to your policy hold, you’ll most likely want to add a geographic zone.

IMPORTANT: If you don’t add a geographic zone, the hold will be applied to all policies that match the
associated policy hold rules, regardless of the geographic region the policy is in.

To add a zone, you first need to retrieve the zone ID.

Retrieve the geographic zone ID

Due to the large number of geographic zones available, simply querying for all of them to find the one you want isn’t
ideal. Instead, you should use filters to narrow down your search to find a zone you’re looking for.
In this example, we want our policy hold to cover all policies in the state of California. So we’ve added the following
filters to our endpoint:
• Country is the U.S.: country:eq:US
• Our geographic zone is at the state level: zoneType:eq:state
• The state is California: code:eq:CA

GET /admin/v1/geographic-zones?filter=country:eq:US&filter=zoneType:eq:state&filter=code:eq:CA

{
"count": 1,
"data": [

Policy holds 377

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"attributes": {
"code": "CA",
"country": {
"code": "US",
"name": "United States"
},
"displayName": "CA",
"id": "US:SbytI2CuZcXKoqyOiaSxI",
"name": "CA",
"zoneType": {
"code": "state",
"name": "State"
}
},
...
}

We can now see that the id for the geographic zone covering the state of California is US:SbytI2CuZcXKoqyOiaSxI.
Save this value, we’ll use it in the next section.

Add the geographic zone

To add a geographic zone to the policy hold, you’ll need the IDs for the policy hold and the geographic zone. From the
previous steps in this example, those values are:
• Policy hold ID: pc:101
• Geographic zone ID: US:SbytI2CuZcXKoqyOiaSxI
The geographic zone ID goes in the request body to specify which zone we’re applying to the policy hold:
Request body

{
"data": {
"attributes": {
"geographicZone": {
"id": " US:SbytI2CuZcXKoqyOiaSxI"
}
}
}
}

This policy hold ID goes in the endpoint command to specify the policy hold to which this zone is being added.
Command

POST /admin/v1/policy-holds/pc:101/geographic-zones

You’ve now created a policy hold that will become active as soon as the start date is reached.
For more information on policy holds, see “Policy holds” on page 365.

378 Policy holds

chapter 43

Quoting

Cloud API for PolicyCenter supports several PolicyCenter features that provide greater control over the quoting
process. This includes the following:
• Multi-version quoting (where multiple quotes are generated simultaneously for the same job)
• Rating overrides (where the amount for a given Cost is manually overridden)

Costs and transactions

When a policy is quoted, the associated expenses are broken down into costs and transactions. The costs include the
details on the various costs associated with quoting the policy premiums. The transactions are details of changes to the
costs. For complete details on costs and transactions, see Application Guide
You can use Cloud API to retrieve collections of costs and transactions. You cannot use these endpoints to modify costs
or transactions, only to retrieve them.

Retrieving costs
Use the following endpoints to retrieve costs associated with a job or a policy:
• GET /job/v1/jobs/{jobId}/costs
• GET /policy/v1/policies/{policyId}/costs
For example:
Command

GET /policy/v1/policies/pc:101/costs

Response

{
"data": [
{
"attributes": {
"amount": {
"amount": "84066.00",
"currency": "usd"
},
"chargePattern": {
"code": "Premium",
"name": "Premium"
},
"coverable": {
"displayName": "California",

Quoting 379
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"id": "1"
},
"effectiveDate": "2023-11-16T08:01:00.000Z",
"expirationDate": "2024-11-16T08:01:00.000Z",
"id": "2",
"policyLine": {
"displayName": "Workers' Comp Line",
"id": "WorkersCompLine",
"uri": "/policy/v1/policies/pc:101/lines/WorkersCompLine"
},
"rateAmountType": {
"code": "StdPremium",
"name": "Standard premium"
},
"termAmount": {
"amount": "84066.00",
"currency": "usd"
}
},

Retrieving transactions
Use the following endpoint to retrieve a list of transactions on a job:
• GET /job/v1/jobs/{jobId}/transactions
For example:
Command

GET /job/v1/jobs/pc:500/transactions

Response

{
"data": [
{
"attributes": {
"amount": {
"amount": "84066.00",
"currency": "usd"
},
"amountBilling": {
"amount": "84066.00",
"currency": "usd"
},
"charged": false,
"cost": {
"displayName": "Emp liab increased limits",
"id": "pc:890"
},
"displayName": "Emp liab increased limits",
"effectiveDate": "2023-11-16",
"expirationDate": "2024-11-16",
"id": "107",
"postedDate": "2023-11-28T19:19:00.976Z",
"toBeAccrued": false,
"written": true,
"writtenDate": "2023-11-28"
},
…
},
{
"attributes": {
"amount": {
"amount": "-24361.00",
"currency": "usd"
},
"amountBilling": {
"amount": "-24361.00",
"currency": "usd"
},
"charged": false,
"cost": {
"displayName": "Emp liab increased limits",
"id": "pc:978"
},
"displayName": "Emp liab increased limits",
"effectiveDate": "2023-11-16",
"expirationDate": "2024-11-16",
"id": "106",
"postedDate": "2023-11-28T19:19:00.976Z",
"toBeAccrued": false,
"written": true,
"writtenDate": "2023-11-28"

380 Quoting
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
…
},

Multi-version quoting
Multi-version quoting is a PolicyCenter feature that is available on submission, policy change, renewal, and rewrite
policy transactions. Within a single policy transaction, multiple quotes can be generated and compared. The Job API
supports this functionality. For details on multi-version quoting and other policy transactions in PolicyCenter, see the
Application Guide.
Multi-version quoting is supported through the following Job API endpoints:
• /job/v1/jobs/{jobId}/versions
• /job/v1/jobs/{jobId}/versions/{versionId}
• /job/v1/jobs/{jobId}/change-version
• /job/v1/jobs/{selectedJobId}?jobVersion={unselectedJobId}

Multi-version quoting and side-by-side quoting

Side-by-side quoting is a feature of the PolicyCenter user interface in which multiple quotes for the same submission
are shown next to each other at the same time. You can use the multi-version quoting endpoints to generate a similar
user interface presentation in a third-party application. The caller application needs to make multiple calls to retrieve
the quote of each version. This information can then be presented at the same time in whatever manner suits the caller
application.

Job version properties

By default, a job has one version from the moment it is created, and that version is in selected state. To access the job
versions, callers can submit a GET request to the /job/v1/jobs/{jobId}/versions collection.
The following code block shows the response payload of a GET request to the /versions collection of a newly created
job, which contains one version:

{
"count": 1,
"data": [
{
"attributes": {
"id": "pc:401",
"name": "Version #1",
"number": 1,
"selected": true,
"status": {
"code": "Draft",
"name": "Draft"
}
},
. . .
}
],
. . .
}

The attributes field contains the following properties:

• id : The ID value of the version. The first version of a job will have the same ID value as the job itself.
• name : A human-readable string that can be used to identify the job version.
• number : The 1-based index number of the version in the versions collection. The property is syntactic sugar,
providing a handle that applications can use when iterating over a versions array.
• selected : A Boolean value indicating the selected state of the version.
• status : A typekey value indicating the job status. Jobs are in Draft status from time of creation, or in Quoted
status once a quote has been generated.

Quoting 381
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Other than name, these properties are read-only values.

Creating a new job version

A caller can create a new version of a job by submitting a POST request to the /job/v1/jobs/{jobId}/versions
endpoint. At minimum, the request payload must contain data and attributes properties, and the latter can be empty:

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

Optionally, the caller can provide a name for the version:

{
"data": {
"attributes": {
"name": "My new version"
}
}
}

On creation, the new job version is in Draft status, it is not selected, and the version number is incremented by one. The
ID value is specific to the version.

{
"data": {
"attributes": {
"id": "pc:402",
"name": "My new version",
"number": 2,
"selected": false,
"status": {
"code": "Draft",
"name": "Draft"
}
},
. . .
}
}

Selecting a job version

By default, the initial job and first version are the same, having the same ID value, and this version is selected.
Subsequent versions are deselected by default.
A caller can select a job version by submitting a POST request to the /job/v1/jobs/{jobId}/change-version
endpoint. The request payload must specify the version to be selected:

{
"data": {
"attributes": {
"selectedVersion": {
"id": "pc:402"
}
}
}
}

In the payload above, the selectedVersion.id value is set to the ID value of the job version that was created in the
previous section. This job version will now be selected, and the all other job versions will be in a deselected state.

Working with job versions

A job version that is selected and in Draft status can be modified or quoted through the /job/v1/jobs/
{selectedJobId} endpoints.

Alternatively, a caller can modify or quote an deselected job version that is in Draft status by applying the jobVersion
query parameter to the request. These calls have the following patterns:

382 Quoting
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• /job/v1/jobs/{selectedJobId}?jobVersion={unselectedJobId}
• /job/v1/jobs/{selectedJobId}/{businessAction}?jobVersion={unselectedJobId}
Typically, each version is modified until considered done and then quoted. The quoted versions can then be offered for
side-by-side comparison. To further modify a quoted version, a caller can apply the /make-draft business action to
that version, make the modification, and then re-quote.

Rating overrides
When you quote a job, PolicyCenter rates the job to determine the cost of each coverage. This information is stored in
a series of Cost objects. The Cost objects are then used to calculate the quote.
PolicyCenter also provides the ability to manually override the rating for one or more specific Costs. When you
override rating, you can change exactly one of the following Cost values:
• Base rate
• Adjusted rate
• Amount
• Term amount
You cannot override costs on a job until the job has been quoted. Overriding a cost does not change the status of the
job. It remains with its status of "Quoted". Also, some cost types may be designated as not allowing overrides. For
example, tax costs may not allow overrides as they must always reflect a fixed percent of some other cost.
In the base application, the only lines of business that support rating overrides are: Worker’s Compensation, Inland
Marine, and Commercial Property. However, any line of product could be configured to support rating overrides.
For more information on the business functionality of rating overrides, see the Application Guide.

Rating overrides in Cloud API

To create a rating override, you must first determine the IDs of the relevant Cost objects. You can then override the rate
or amount of each Cost as appropriate.
For example, suppose there is a quoted submission for a Commercial Property policy. The submission's ID is pc:S99.
The policy includes a building with Business Personal Property Coverage. There are two costs for this coverage:
• Business Personal Property Coverage Basic Group I
◦ Base rate: 0.1500
◦ Adjusted rate: 0.1148
◦ Term amount: 11.00
◦ Amount: 11.00
• Business Personal Property Coverage Basic Group II
◦ Base rate: 0.1500
◦ Adjusted rate: 0.0822
◦ Term amount: 8.00
◦ Amount: 8.00
You want to modify these costs in the following way:
• Business Personal Property Coverage Basic Group I
◦ Override base rate value: 0.2000
▪ Business Personal Property Coverage Basic Group II

Quoting 383
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ Override term amount value: 10.00

Retrieving Cost IDs
To retrieve the costs for a quoted job, use the following endpoint:
• GET job/v1/jobs/{jobId}/costs
The following is an example of a request for the costs for the submission discussed in the previous example, and a
portion of the response. From this output, you can see that the IDs of the two costs are 49 and 50.

GET job/v1/jobs/pc:S99/costs

{
"count": 5,
"data": [
{
"attributes": {
"adjustedRate": "0.1148",
"amount": {
"amount": "11.00",
"currency": "usd"
},
"baseRate": "0.1500",
"coverable": {
"displayName": "1: Building # 1",
"id": "14"
},
"coverage": {
"displayName": "Business Personal Property Coverage",
"id": "CPBPPCov"
},
"id": "49",
"termAmount": {
"amount": "11.00",
"currency": "usd"
}
}
},
{
"attributes": {
"adjustedRate": "0.0822",
"amount": {
"amount": "8.00",
"currency": "usd"
},
"baseRate": "0.1500",
"coverable": {
"displayName": "1: Building # 1",
"id": "14"
},
"coverage": {
"displayName": "Business Personal Property Coverage",
"id": "CPBPPCov"
},
"id": "50",
"termAmount": {
"amount": "8.00",
"currency": "usd"
}
}
},
...

Creating rating overrides

To create a rating override, use the following endpoint:
• POST job/v1/jobs/{jobId}/override-rating
The body of the request must contain an overrides array. Each member of the array must specify the costId of the
associated Cost and exactly one of the following override properties:
• overrideAdjustedRate
• overrideAmountBilling
• overrideBaseRate
• overrideTermAmountBilling
A given Cost can only have one override at a time.

384 Quoting
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

(The OverrideCostsAttributes schema also includes two deprecated fields: overrideAmount and
overrideTermAmount. These fields have been included for backwards compatibility. However, Guidewire recommends
using overrideAmountBilling and overrideTermAmountBilling, respectively, as the latter fields use the policy's
settlement currency.)
You can optionally provide an overrideReason, which must be defined as a string.
The response to the /override-rating call contains the Costs for the entire job.

Rating overrides example

The following is an example of a POST that creates the two rating overrides discussed in the previous example.

POST job/v1/jobs/pc:S99/override-rating

{
"data": {
"attributes": {
"overrides": [
{
"costId": "49",
"overrideBaseRate": ".2",
"overrideReason": "Greater risk level at this location"
},
{
"costId": "50",
"overrideTermAmountBilling": "10",
"overrideReason": "Greater risk level at this location"
}
]
}
}
}

Amount overrides compared to rate overrides

For a given Cost, you can override either the amount (using either the overrideAmountBilling or
overrideTermAmountBilling fields) or the rate (using either the overrideBaseRate or overrideAdjustedRate
fields).
The approach to use is determined by how rating is calculated for the given line of business. Some lines of business,
such as the base configuration Worker's Compensation line, use amount overrides. Other lines of business, such as the
base configuration Commercial Property line, use term overrides.

Quoting 385
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

386 Quoting
chapter 44

Reinsurance risks

Reinsurance is insurance for insurance companies. A direct policy insurer will bundle risk coverages in a way that
allows them to share those risks with other insurers. Those shared risks can be described as reinsurance risks, or
reinsurables. For a complete description and details of reinsurance, see the Application Guide .
The following endpoints retrieve the reinsurance risks that are associated with a job or policy:
• GET /job/v1/jobs/{jobId}/reinsurables
• GET /job/v1/jobs/{jobId}/reinsurables/{reinsurableId}
• GET /policy/v1/policies/{policyId}/reinsurables
• GET /policy/v1/policies/{policyId}/reinsurables/{reinsurabldId}
Reinsurables details
Applicable reinsurance risks are automatically attached to the job (and by extension the policy) when the job is quoted.
Therefore, there are no endpoints that create or update reinsurables on policies and jobs; it’s an automatic process.
Because reinsurables are assigned when a job is quoted, if a job is in Draft mode the reinsurables endpoints will return
an empty data set for that job.
The base configuration comes with two types of reinsurables, policyRisk and locationRisk. (A policy risk reinsurable is
any risk associated with the policy other than location. A location risk reinsurable is associated with a specific location,
such as the home in a homeowners policy.)
Keep in mind that the reinsurables returned in the responses to these endpoints are reinsurance risks that are capable of
being reinsured; they haven’t necessarily been reinsured. To determine whether a particular reinsurable has been
reinsured, check the riskNumber property in the response:

"riskNumber": "100"

If the riskNumber contains a value (as it does here), the reinsurable is reinsured. If the riskNumber is null, the
reinsurable is capable of being reinsured, but has not yet been reinsured.
Examples
The following examples demonstrate how to retrieve reinsurables for a policy and a job, respectively. Both the policy
and job have a Workers’ Comp coverage reinsurable.
Command

GET /policy/v1/policies/pc:100/reinsurables

Reinsurance risks 387

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

{
"data": [
{
"attributes": {
"displayName": "Policy-level",
"id": "101",
"reinsuranceCurrency": {
"code": "usd",
"name": "USD"
},
"riCoverageGroupType": {
"code": "WorkersComp",
"name": "Workers Comp"
},
"riskNumber": "100"
},

Command

GET /job/v1/jobs/pc:500/reinsurables

Response

{
"data": [
{
"attributes": {
"displayName": "Policy-level",
"id": "101",
"reinsuranceCurrency": {
"code": "usd",
"name": "USD"
},
"riCoverageGroupType": {
"code": "WorkersComp",
"name": "Workers Comp"
},
"riskNumber": "100"
},

This example retrieves reinsurables for policy pc:101, which has an Auto Liability coverage reinsurable with a Total
Insured Value of $600,000 USD:
Command

GET /policy/v1/policies/pc:101/reinsurables

Response

{
"data": [
{
"attributes": {
"displayName": "Policy-level",
"id": "2",
"reinsuranceCurrency": {
"code": "usd",
"name": "USD"
},
"riCoverageGroupType": {
"code": "AutoLiability",
"name": "Auto Liability"
},
"riskNumber": "1",
"totalInsuredValue": {
"amount": "600000.00",
"currency": "usd"
}
},

388 Reinsurance risks

chapter 45

Streamlined account and submission

creation

Accounts and submissions are hierarchical entities with multiple levels of information. For example, you create an
account, then add contacts to the account, then add additional locations, and so on. Request inclusion and composite
requests give you the ability to combine those calls into a single request, but you still have to build the object one call
at a time. Furthermore, you never get a single response that contains the entire hierarchy; each piece of the hierarchy is
returned from a separate call.
For some caller applications, such as those involved in High Volume Quoting (see Configuration Guide), it’s more
convenient to build an entire account or submission in a single call, and then process the single set of results returned
from those calls. The endpoints in the Graph API give you the ability to do this.
In this section:
• “Understanding the Graph API” on page 389
• “Example: Creating a policy using the graph endpoints” on page 393

Understanding the Graph API

The Graph API has endpoints that let you POST the entire hierarchy of an account or submission in a single request,
and then return the hierarchy in a single response.

The Graph API

The Graph API includes the following endpoints:
• POST /graph/v1/accounts
• POST /graph/v1/submissions
The POST /graph/v1/accounts endpoint lets you create an account by specifying the entire hierarchy for the account
in a single request. This endpoint uses the same schemas as those used by the /account/v1/accounts endpoint and its
related endpoints. So, any field available to those schemas is available to the POST /graph/v1/accounts endpoint.
The POST /graph/v1/submissions endpoint lets you create a complete job submission. You specify the entire
hierarchy for the submission in a single request. This endpoint uses the same schemas as those used by the Job API
Streamlined account and submission creation 389
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

endpoints, including any LOB-specific endpoints. So, any field available to those schemas is available to the POST /
graph/v1/submissions endpoint.

The responses from these endpoints include the entire hierarchy of the account and submission resources. This
complete response provides a consistent and ordered set of information so caller applications know what to expect. It
also allows caller applications to more easily pass data back to PolicyCenter if necessary without having to first
determine the ordering.
These endpoints are similar to the POST /account/v1/accounts and POST /job/v1/submissions endpoints, but
there are some key differences, discussed in the next section.
For more on the /account/v1/accounts endpoint see “Creating an account” on page 147
For more on the /job/v1/submissions endpoint see “Submissions” on page 193

Graph vs Account and Job APIs

The Graph API endpoints are built from the same code as the Account and Job API endpoints. This means that the
Graph API endpoints return the same information and the same properties as the Account and Job API endpoints,
including any custom extensions that have been added. But there are several differences.

Streamlined process
The Account and Job APIs have separate endpoints to access the child elements of account and job. The Graph API
endpoints do not have separate endpoints for child elements because they're not needed. All account and job
information, including all child resources, are included within the requests and responses for the Graph API endpoints.
For example, a request to POST /graph/v1/accounts can contain all account information, including child information
such as contacts and locations.
Note:

Keep in mind that while POST /graph/v1/submissions creates an entire job and submission, it does not quote
or bind the submission.

No pagination
When you run an Account or Job API endpoint, pagination is in place that by default restricts the number of elements
returned at once. With the Graph API endpoints, all the account and submission information is included in the POST
command response. The Graph API overrides any specified pagination values and returns all elements of each
collection.
See “The pagination query parameters” on page 58 for more information on pagination.

POST only
The purpose of the Graph API endpoints is to produce an entire account and submission that can be passed along for
processing by the caller application. So unlike the Account and Job API endpoints, the Graph API /accounts and /
submissions endpoints provide only POST commands. Updates cannot be made that will produce a modified version
of the entire account or submission graph response. However, you can use the the Account and Job API endpoints to
modify the data that was created with the Graph API endpoints.

Using Graph API endpoints in a composite request

The Composite API (“Composite requests” on page 97) provides an endpoint that allows you to string together a series
of API requests, passing variables - such as an account ID - returned from one sub-request to another. The sub-requests
run in the order specified in the composite request, each sub-request completing before the next begins.
You can use Graph API requests within a Composite API request to create a complete submission. For example, you
can call POST /graph/v1/accounts, then POST /graph/v1/submissions as part of a single composite request. If you
also want to quote the submission, you can include a call to POST /jobs/v1/{jobId}/quote, passing in the jobId

390 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

returned from the call to the graph /submissions endpoint. See “Example: Creating a policy using the graph
endpoints” on page 393 for an example.
Note:

You can produce the same results by using composite requests with the Account and Job APIs to manually
build out the entire string of commands required to create a submission. However, you typically need to do this
only if you require an especially fine-tuned order of operations.

Order of operations
If you use the Account and Job API endpoints to create a submission, you need to carefully keep track of the order in
which to make the requests, being sure to pass the appropriate IDs from one request to another. One of the biggest
advantages to using the Graph API is that the endpoints know how to carry out operations in an order that makes sense.
By default, the Graph API will process the list of children for a given resource based on the alphabetical ordering of the
properties defined in the graph schema. For example, if a policy line has children named coverages and locations in
the graph schema, the coverages children will be processed first.
In some cases, you may want to change this order, generally to ensure that resources are created before other resources
attempt to reference them. For example, the base configuration overrides the ordering so that contacts and locations
are both processed before any other entities on the Job schema, so that PolicyContacts and PolicyLocations are created
before any LOB resources that may need to refer to them are processed.
You might have a case, such as a custom extension with top-level children that are referenced elsewhere in the graph,
where you need to control the processing order. You can do this by adding the graphUpdateOrder extension to the
appropriate property in the graph schema file. For example:

...
"x-gw-extensions": {
"graphUpdateOrder": 1
}
...

See Cloud API Developer Guide for information on the graph schema file.

Adding Ref IDs

As mentioned earlier, the Graph API POST operations create complete accounts and submissions by carrying out the
creation of resources and their children in a logical order. In some cases, you might want to reference one of those
resources for use in creating another. Graph API uses the refid property to accomplish this.
Note:

In Cloud API, refid is typically used for request inclusion (Cloud API Business Flows and Configuration
Guide). When used for request inclusion, separate data and inclusion sections are required. For use in Graph
API, the refid is used inline with the element’s other properties.
For example, you might create a contact that you want to designate as the account holder. You can include a refid on
the contact. Then add that same refid to the accountHolder. Graph API will first create the contact, then, using the
refid, will add that contact as the account holder when it creates the account. Here’s an example:

{
"data": {
"attributes": {
...
"accountHolder": {
"refid": "newperson"
},
"contacts": [
{
"refid": "newperson",
"contactSubtype": "Person",
"firstName": "August",
"lastName": "Joseph",

Streamlined account and submission creation 391

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
}
],
...

In the response, the accountHolder is the contact that was created with that refid:

"accountHolder": {
"displayName": "August Joseph",
"id": "pc:120"
},
...
"contacts": [
{
...
"displayName": "August Joseph",
"id": "pc:120",
...
],

See Cloud API Business Flows and Configuration Guide for more information on request inclusions.

Additonal Graph API functionality

The Graph API endpoints share certain functionality with other API endpoints in PolicyCenter to take note of.

Sort order
Most of the resources in the graph for accounts and submissions are returned as collections. As with other API
endpoints, the response from each Graph API endpoint returns data in the default sort order for each resource. This
means that, for example, the /accounts endpoint might return a list of contacts in the response in a different order than
they were listed in the request.

Response output
If you call GET /job/v1/jobs, the response by default will include a summary list of each job that is returned.
However, if you call GET /job/v1/jobs/{jobID} to retrieve a single job, the response will by default include more
details about the specified job than the collection-level command response. The response for all POST operations in the
Graph API will by default return the detailed list for all collection items.

Request query parameters

The Graph API endpoints accept the following query parameters.
POST /graph/v1/accounts query parameters

Parameter Description More information

fields As with other endpoints, you can override the default set of See “The fields query parameter” on page 51 for
returned values by using the fields query parameter. more information.

POST /graph/v1/submissions query parameters

Parameter Description More information

createCoveredLocationForPrimaryLocation This parameter enables or disables the See “Default value creation”
creation of the default covered location on page 289 for more on creating
for primary location. Default is true default coverages.
(enabled).

392 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Parameter Description More information

createDefaultCoverages This parameter enables or disables the See “Default value creation”
creation of default coverages. Defaults is on page 289 for more on creating
true (enabled) default coverages.

deferValidation In some cases you might want to defer See “Deferring validation” on
validations, such as availability checks. To page 287 for more on deferring
defer validations on a submission, set this validation.
parameter to true. Default is false.

fields As with other endpoints, you can override See “The fields query
the default set of returned values by using parameter” on page 51 for
the fields query parameter. more information.

Authorization
As with other Cloud API endpoints, in order to call endpoints in the Graph API the caller must have permission to
those endpoints in their role.yaml file and the appropriate access.yaml file.That includes endpoint-level permission (via
role.yaml files), resource-level permissions (via the access.yaml files), and field-level permissions (via the role.yaml
files).
In addition to the standard endpoint permissions, Graph API permissions also depend on the endpoint-level, resource-
level, and field-level permissions for the corresponding endpoints within the Account and Job APIs. These permissions
are applied to the creation during the POST, and are also used to filter what is returned on the response. Here are some
examples.
Creation Authorization
Every graph schema property maps to an Account or Job API endpoint. For example, contacts on the Account maps
to /account/v1/accounts/{accountId}/contacts. Adding an element to the contacts array in the request requires
exactly the same permissions as a POST to that Account API endpoint would require: if the POST to the Account API
would fail, the POST to the Graph API will fail the same way. This applies to field-level edits as well: if you can't edit
a field in the Account API, you can't include that field in a Graph API request.
Response
Response rules are similar to the creation rules. If you can't view the response from the /account/v1/accounts/
{accountId}/contacts endpoint in the Account API, the contacts property won't appear on the /graph/v1/
accounts response. Similarly, if you can't view a particular set of contact fields in the Account API, those fields won't
appear in the Graph API response either. The Graph API is designed to give callers the same permissions as to the
Account and Job APIs.

Example account and submission creation

See “Example: Creating a policy using the graph endpoints” on page 393 for complete examples of using the Graph
API endpoints.

Example: Creating a policy using the graph endpoints

As described in “Streamlined account and submission creation” on page 389, you can create an entire submission by
using two endpoints from the Graph API:
• POST /graph/v1/accounts
• POST /graph/v1/submissions
These endpoints can be run independently or included in a composite request to create an end-to-end submission. The
response is an output graph that can be read by calling applications that need to process an entire submission at once.

Streamlined account and submission creation 393

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Overview
The examples presented here demonstrate the process of creating a complete account and submission using the Graph
API.
• The first example creates an account. The account includes an initial account holder, primary location, and an
additional locaction.
• The next example creates a submission. The submission includes several pieces of information that would require
calls to multiple child endpoints if you were to use the Job API to complete a similar task. This example shows how
to create the entire submission in one step.
• The final example creates a composite request that strings together the commands from the preceding examples to
create an account and a submission, and quote the submission. It then shows binding and issuing the submission.

Create an account for the submission

Every submission must be associated with an account. All the account information for a submission can be gathered in
one step with the following command:

POST /graph/v1/accounts

The required request fields are the same for posting a Graph API account as for posting to an Account API account
(see “Creating an account” on page 147).
In addition to the required and other top-level account fields, you can include fields that are considered children of the
account, such as contacts and locations. The following request creates an account and includes an additional location.
Request

{
"data": {
"attributes": {
"producerCodes": [{
"id": "pc:6"
}],
"initialAccountHolder": {
"contactSubtype": "Person",
"firstName": "August",
"lastName": "Joseph",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"initialPrimaryLocation": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"locations": [{
"active": true,
"addressLine1": "1234 Main St.",
"city": "San Diego",
"country": "US",
"postalCode": "91911",
"state": {
"code": "CA"
}
}]
}
}
}

Response

{
"data": {
"attributes": {
"accountHolder": {

394 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"displayName": "August Joseph",

"id": "pc:120"
},
"accountNumber": "12345678",
"accountStatus": {
"code": "Pending",
"name": "Pending"
},
"contacts": [{
"accountContactRoles": [{
"code": "AccountHolder",
"name": "AccountHolder"
}],
...
"locations": [{
"active": true,
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"country": "US",
"displayName": "1: 2850 S. Delaware St., San Mateo, CA",
"id": "pc:SpsZPtDDb4H8uswOqP_fh",
"locationNum": 1,
"nonSpecific": false,
"postalCode": "94403",
"state": {
"code": "CA",
"name": "California"
}
},
{
"active": true,
"addressLine1": "1234 Main St.",
"city": "San Diego",
"country": "US",
"displayName": "2: 1234 Main St., San Diego, CA",
"id": "pc:SjqOMu8aIXl4bbeUHfwzt",
"locationNum": 2,
"nonSpecific": false,
"postalCode": "91911",
"state": {
"code": "CA",
"name": "California"
}
}
],
...
"primaryLocation": {
"displayName": "1: 2850 S. Delaware St., San Mateo, CA",
"id": "pc:2345",
...
}
}
}

Create the job graph for a submission

All the job information for a submission can be gathered in one step with the following command:

POST /graph/v1/submissions

The request for this POST command can contain all information included in the job hierarchy, such as answers,
locations, and all the submission details.
The following request performs these actions:
1. Creates a submission from an existing account (id: pc:120).
2. Answers the question “Is the applicant currently insured” with “No - New Driver” (newdriver).
3. Creates a new contact. Assigns a refid to the contact.
4. Includes a new PersonalAutoLine with the following (only one LOB can be specified, multiple lines in a request
are not supported):
a. Answers two questions (q1 and q3) on the line
b. Adds liability coverage
c. Adds a vehicle
d. Adds a driver to the vehicle. Driver is the contact with the refid defined earlier.

Streamlined account and submission creation 395

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Note:

The POST /graph/v1/submissions endpoint does not quote the submission. To quote the submission you need
to call POST /job/v1/jobs/quote.
Request

{
"data": {
"attributes": {
"account": {
"id": "pc:120"
},
"baseState": {
"code": "CA"
},
"jobEffectiveDate": "2023-09-01",
"producerCode": {
"id": "pc:6"
},
"product": {
"id": "PersonalAuto"
},
"answers": {
"PACurrentlyInsured": {
"choiceValue": {
"code": "newdriver"
}
}
},
"contacts": [{
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"refid": "testUser"
}],
"lines": {
"PersonalAutoLine": {
"answers": {
"q1": {
"booleanValue": false
},
"q3": {
"choiceValue": {
"code": "no"
}
}
},
"coverages": {
"PALiabilityCov": {
"terms": {
"PALiability": {
"choiceValue": {
"code": "100/200/50"
}
}
}
}
},
"numAddInsured": 1,
"vehicles": [{
"annualMileage": 10000,
"bodyType": {
"code": "convertible"
},
"color": "Yellow",
"commutingMiles": 50,
"costNew": {
"amount": "25000.00",
"currency": "usd"
},
"coverages": {
"PACollisionCov": {
"terms": {
"PACollDeductible": {
"choiceValue": {
"code": "1000"
}
}

396 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
},
"PARentalCov": {
"pattern": {
"id": "PARentalCov"
},
"terms": {
"PARental": {
"choiceValue": {
"code": "30/15"
}
}
}
}
},
"drivers": [{
"percentageDriven": 100,
"policyDriver": {
"refid": "testUser"
}
}],
"make": "NewMake",
"model": "NewModel",
"modelYear": 2015,
"modifiers": {
"PAAntiLockBrakes": {
"booleanModifier": true,
"eligible": false,
"valueFinal": false
}
},
"vin": "1234567890"
}]
}
}
}
}
}

Response

{
"data": {
"attributes": {
"account": {
"displayName": "12345678",
"id": "pc:120",
"type": "Account",
"uri": "..."
},
"answers": {
...
"PACurrentlyInsured": {
"choiceValue": {
"code": "newdriver",
"name": "No - New Driver"
},
"displayValue": "No - New Driver",
"question": {
"displayName": "Is the applicant currently insured?",
"id": "PACurrentlyInsured"
},
"questionType": {
"code": "Choice",
"name": "Choice"
}
},
...
},
"contacts": [{
"accountContact": {
"displayName": "August Joseph",
"id": "pc:110",
"type": "AccountContact",
"uri": "..."
},
...
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "Submission",
"name": "Submission"
},
"lines": {
"PersonalAutoLine": {
"answers": {

Streamlined account and submission creation 397

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"q1": {
"booleanValue": false,
"displayValue": "false",
"question": {
"displayName": "Have you been convicted for a moving traffic violation within the past 3 years?",
"id": "q1"
},
"questionType": {
"code": "Boolean",
"name": "Boolean"
}
},
"q2": {
"question": {
"displayName": "Has any policy or coverage been declined, canceled, or non-renewed during the prior 3
years?",
"id": "q2"
},
"questionType": {
"code": "Boolean",
"name": "Boolean"
}
},
"q3": {
"choiceValue": {
"code": "no",
"name": "No - previous policy did not renew"
},
"displayValue": "No - previous policy did not renew",
"question": {
"displayName": "Has your license ever been canceled, suspended or revoked?",
"id": "q3"
},
"questionType": {
"code": "Choice",
"name": "Choice"
}
},
...
"coverages": {
"PALiabilityCov": {
"clauseType": "coverage",
"id": "PALiabilityCov",
"pattern": {
"displayName": "Liability - Bodily Injury and Property Damage",
"id": "PALiabilityCov"
},
"selected": true,
"terms": {
"PALiability": {
"choiceValue": {
"code": "100/200/50",
"name": "100/200/50"
},
"covTermType": "choice",
"displayValue": "100/200/50",
"pattern": {
"displayName": "Auto Liability Package",
"id": "PALiability"
}
}
}
},
"PALimitedMexicoCov": {
"clauseType": "coverage",
"id": "PALimitedMexicoCov",
"pattern": {
"displayName": "Mexico Coverage - Limited",
"id": "PALimitedMexicoCov"
},
"selected": true,
"terms": {}
},
"PAMedPayCov": {
"clauseType": "coverage",
"id": "PAMedPayCov",
"pattern": {
"displayName": "Medical Payments",
"id": "PAMedPayCov"
},
"selected": true,
"terms": {
"PAMedLimit": {
"choiceValue": {
"code": "5000",
"name": "5,000"
},
"covTermType": "choice",
"displayValue": "5,000",
"pattern": {

398 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"displayName": "Medical Limit",

"id": "PAMedLimit"
}
}
}
},
"PAUMBICov": {
"clauseType": "coverage",
"id": "PAUMBICov",
"pattern": {
"displayName": "Uninsured Motorist - Bodily Injury",
"id": "PAUMBICov"
},
"selected": true,
"terms": {
"PAUMBI": {
"choiceValue": {
"code": "25/50",
"name": "25/50"
},
"covTermType": "choice",
"displayValue": "25/50",
"pattern": {
"displayName": "Uninsured Motorist - BI Limits",
"id": "PAUMBI"
}
}
}
},
"PAUMPDCov": {
"clauseType": "coverage",
"id": "PAUMPDCov",
"pattern": {
"displayName": "Uninsured Motorist - Property Damage",
"id": "PAUMPDCov"
},
"selected": true,
"terms": {
"PAUMPDLimit": {
"choiceValue": {
"code": "3500",
"name": "3,500"
},
"covTermType": "choice",
"displayValue": "3,500",
"pattern": {
"displayName": "Uninsured Motorist - Property Damage Limit",
"id": "PAUMPDLimit"
}
}
}
}
},
...
"patternCode": "PersonalAutoLine",
"vehicles": [{
"annualMileage": 10000,
"bodyType": {
"code": "convertible",
"name": "Convertible"
},
"color": "Yellow",
"commutingMiles": 50,
"costNew": {
"amount": "25000.00",
"currency": "usd"
},
"coverableJurisdiction": {
"code": "CA",
"name": "California"
},
"coverages": {
"PACollisionCov": {
"clauseType": "coverage",
"id": "PACollisionCov",
"pattern": {
"displayName": "Collision",
"id": "PACollisionCov"
},
"selected": true,
"terms": {
"PACollDeductible": {
"choiceValue": {
"code": "1000",
"name": "1,000"
},
"covTermType": "choice",
"displayValue": "1,000",
"pattern": {
"displayName": "Collision Deductible",

Streamlined account and submission creation 399

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"id": "PACollDeductible"
}
}
}
},
"PAComprehensiveCov": {
"clauseType": "coverage",
"id": "PAComprehensiveCov",
"pattern": {
"displayName": "Comprehensive",
"id": "PAComprehensiveCov"
},
"selected": true,
"terms": {
"PACompDeductible": {
"choiceValue": {
"code": "500",
"name": "500"
},
"covTermType": "choice",
"displayValue": "500",
"pattern": {
"displayName": "Comprehensive Deductible",
"id": "PACompDeductible"
}
}
}
},
"PARentalCov": {
"clauseType": "coverage",
"id": "PARentalCov",
"pattern": {
"displayName": "Rental Reimbursement",
"id": "PARentalCov"
},
"selected": true,
"terms": {
"PARental": {
"choiceValue": {
"code": "30/15",
"name": "30 days x 15/day"
},
"covTermType": "choice",
"displayValue": "30 days x 15/day",
"pattern": {
"displayName": "Rental Package",
"id": "PARental"
}
}
}
}
},
"drivers": [{
"id": "301",
"percentageDriven": 100,
"policyDriver": {
"displayName": "Samantha Stewart",
"id": "pc:145",
"type": "PolicyContact",
"uri": "..."
}
}],
"garageLocation": {
"displayName": "1: 2850 S. Delaware St., San Mateo, CA",
"id": "501",
"type": "PolicyLocation",
"uri": "..."
},
"id": "301",
"leaseOrRent": false,
"make": "NewMake",
"model": "NewModel",
"modelYear": 2015,
...
"locations": [{
"accountLocation": {
"displayName": "1: 2850 S. Delaware St., San Mateo, CA",
"id": "pc:Sro4vpAp3iD5oMrD7SqwF",
"type": "AccountLocation",
"uri": "..."
},
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"country": "US",
"displayName": "1: 2850 S. Delaware St., San Mateo, CA",
"id": "501",
"locationNum": 1,
"postalCode": "94403",
"primary": true,
"state": {

400 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "CA",
"name": "California"
},
"territoryCodes": {
"PersonalAutoLine": {
"code": "31"
}
}
}],
...
"producerCode": {
"displayName": "100-000001",
"id": "pc:6"
},
"producerCodeOfService": {
"displayName": "100-000001",
"id": "pc:6"
},
"product": {
"displayName": "Personal Auto",
"id": "PersonalAuto"
},
"quoteType": {
"code": "Full",
"name": "Full Application"
},
"termType": {
"code": "HalfYear",
"name": "6 months"
},
...
}
}
}
}

Create a submission composite request

You can use a composite request to create a single request that will gather all account and submission information. The
following example runs the POST commands on accounts and submissions to generate the account and submission
graphs.
Command

POST /composite/v1/composite

This example combines the examples in the preceding sections into one composite request. It also performs the
additional step of quoting the submission, then binds and issues the submission.
The composite request performs the following steps:
1. Calls POST /graph/v1/accounts to create an account
2. Saves the account ID from the account that was created to be passed into the body of the next sub-request.
3. Calls POST /graph/v1/submissions to create a submission
4. Saves the job ID from the submission to be passed into the body of the next sub-request
5. Calls POST /job/v1/jobs/{jobId}/quote to quote the job
When the composite request completes, you can then call POST /job/v1/jobs/{jobId}/bind-and-issue to bind and
issue the job.
Request

{
"requests": [{
"method": "post",
"uri": "/graph/v1/accounts",
"body": {
"data": {
"attributes": {
"producerCodes": [{
"id": "pc:6"
}],
"initialAccountHolder": {
"contactSubtype": "Person",
"firstName": "August",
"lastName": "Joseph",

Streamlined account and submission creation 401

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
}
},
"initialPrimaryLocation": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"locations": [{
"active": true,
"addressLine1": "1234 Main St.",
"city": "San Diego",
"country": "US",
"postalCode": "91911",
"state": {
"code": "CA"
}
}]
}
}
},
"vars": [{
"name": "accountId",
"path": "$.data.attributes.id"
}]
},
{
"method": "post",
"uri": "/graph/v1/submissions",
"body": {
"data": {
"attributes": {
"account": {
"id": "${accountId}"
},
"baseState": {
"code": "CA"
},
"jobEffectiveDate": "2023-09-01",
"producerCode": {
"id": "pc:6"
},
"product": {
"id": "PersonalAuto"
},
"answers": {
"PACurrentlyInsured": {
"choiceValue": {
"code": "newdriver"
}
}
},
"contacts": [{
"contactSubtype": "Person",
"firstName": "Samantha",
"lastName": "Stewart",
"primaryAddress": {
"addressLine1": "2850 S. Delaware St.",
"city": "San Mateo",
"postalCode": "94403",
"state": {
"code": "CA"
}
},
"refid": "testUser"
}],
"lines": {
"PersonalAutoLine": {
"answers": {
"q1": {
"booleanValue": false
},
"q3": {
"choiceValue": {
"code": "no"
}
}
},
"coverages": {
"PALiabilityCov": {
"terms": {

402 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"PALiability": {
"choiceValue": {
"code": "100/200/50"
}
}
}
}
},
"numAddInsured": 1,
"vehicles": [{
"annualMileage": 10000,
"bodyType": {
"code": "convertible"
},
"color": "Yellow",
"commutingMiles": 50,
"costNew": {
"amount": "25000.00",
"currency": "usd"
},
"coverages": {
"PACollisionCov": {
"terms": {
"PACollDeductible": {
"choiceValue": {
"code": "1000"
}
}
}
},
"PARentalCov": {
"pattern": {
"id": "PARentalCov"
},
"terms": {
"PARental": {
"choiceValue": {
"code": "30/15"
}
}
}
}
},
"drivers": [{
"percentageDriven": 100,
"policyDriver": {
"refid": "testUser"
}
}],
"make": "NewMake",
"model": "NewModel",
"modelYear": 2015,
"modifiers": {
"PAAntiLockBrakes": {
"booleanModifier": true,
"eligible": false,
"valueFinal": false
}
},
"vin": "1234567890"
}]
}
}
}
}
},
"vars": [{
"name": "jobId",
"path": "$.data.attributes.id"
}]
},
{
"method": "post",
"uri": "/job/v1/jobs/${jobId}/quote"
}
]
}

The response from the composite request contains sub-responses with the results of each of the calls within the request.

IMPORTANT: The response shown here is only a very small sample of the graph that will actually be returned.
Shown here is just enough to demonstrate that responses have been returned from the three separate POST
commands, and that the submisson has successfully moved through creation of an account and a submission to
a quoted state.

Streamlined account and submission creation 403

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

{
"responses": [{
"body": {
"data": {
"attributes": {
"accountHolder": {
"displayName": "August Joseph",
"id": "pc:120"
},
"accountNumber": "12345678",
"accountStatus": {
"code": "Pending",
"name": "Pending"
},
...
"status": 201
},
{
"body": {
"data": {
"attributes": {
"account": {
"displayName": "12345678",
"id": "pc:130",
"type": "Account",
"uri": "..."
},
...
"id": "pc:150",
"jobEffectiveDate": "2023-09-01T07:01:00.000Z",
"jobNumber": "0000123456",
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "Submission",
"name": "Submission"
},
"lines": {
"PersonalAutoLine": {
"answers": {
"q1": {
"booleanValue": false,
"displayValue": "false",
...
"status": 201
},
{
"body": {
"data": {
"attributes": {
"account": {
"displayName": "12345678",
"id": "pc:120",
"type": "Account",
"uri": "..."
},
"id": "pc:150",
"jobEffectiveDate": "2023-09-01T07:01:00.000Z",
"jobNumber": "0000123456",
"jobStatus": {
"code": "Quoted",
"name": "Quoted"
},
"jobType": {
"code": "Submission",
"name": "Submission"
},
...
"status": 200
}
]
}

At this point you can perform the additional step of binding and issuing the submission:
Command

POST /job/v1/jobs/pc:150/bind-and-issue

404 Streamlined account and submission creation

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response

{
"data": {
"attributes": {
"account": {
"displayName": "12345678",
"id": "pc:120",
...
"id": "pc:150",
"jobEffectiveDate": "2023-09-01T07:01:00.000Z",
"jobNumber": "0000123456",
"jobStatus": {
"code": "Bound",
"name": "Bound"
},
"jobType": {
"code": "Submission",
"name": "Submission"
},
...
}
}
}

Streamlined account and submission creation 405

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

406 Streamlined account and submission creation

chapter 46

Underwriting issues

When processing a job, an issue can occur that requires additional review by an underwriter. This review can determine
if and how to complete the job. To manage these circumstances, PolicyCenter provides underwriting issues.
An underwriting issue is an object attached to a job or policy that tracks an issue that may require underwriter review.
For detailed information on the business functionality of underwriting issues, see the Application Guide.
Cloud API provides endpoints for managing underwriting issues and related functionality. Most of these endpoints are
in the Job API, though there are a few in the Policy API.

Underwriting issues in PolicyCenter

An underwriting issue is a flag attached to a job or policy that indicates an issue that may require underwriter review.

Underwriting conditions
Some underwriting issues simply identify a situation. For example, an insurer may have an expectation that all insured
motorcycles have an anti-theft device. If a motorcycle is added to a personal auto submission without an anti-theft
device, the submission must be reviewed and approved. In this case, the underwriting issue identifies that there is a
motorcycle without an anti-theft device.
Other underwriting issues identify that a given value is above or below an expected threshold. For example, an insurer
may have a requirement for all drivers to be at or above the age of 25. If a driver under the age of 25 is added to a
submission, the submission must be reviewed and approved. In this case, the underwriting issue identifies a given value
(driver's age) with a comparator (under) and an expected threshold (25).

Blocking points
Typically, underwriting issues block the progress of the job at some point. For example, if a given type of underwriting
issue blocks job progress at quoting, then you cannot quote the job until the underwriting issue is resolved. The most
commonly used blocking points are Quoting, Binding, and Issuance.
Underwriting issues can also exist as informational only. These types of underwriting issues do not block job progress.

Managing jobs with underwriting issues

You can lock a job to indicate that there are associated underwriting issues to review and that the job ought to remain
unchanged while the issues are resolved.
In some situations, a job has underwriting issues that cannot be addressed by the user assigned to the job. In these
situations, the assigned user can request approval from another user (typically a user with a greater level of authority).
Underwriting issues 407
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

While a policy is in force, an insurer may become aware of information that has implications for the policy's renewal.
This information may require underwriter approval, but it is discovered before the start of the renewal job. Because
there is no active job, the information cannot be captured as an underwriting issue. To address these situations,
PolicyCenter supports referral reasons. Like underwriting issues, a referral reason is a flag that indicates an issue may
require underwriter review. However, referral reasons are attached only to policies. The next time a job is created for
the policy, the referral reason may trigger the creation of an underwriting issue.

Querying for underwriting issues

To request information about underwriting issues associated with jobs, use the following endpoints from the Job API:

Endpoint Response
GET /job/v1/jobs/{jobId}/uw-issues A collection of underwriting issues associated with the given job
GET /job/v1/jobs/{jobId}/uw-issues/ The specified underwriting issue
{uwIssueId}
GET /job/v1/jobs/{jobId}/uw-issues/ A collection of UWIssueHistory resources that trace the state history
{uwIssueId}/history of the specified underwriting issue.

When a job is bound, approved and informational underwriting issues are copied over to the policy.
To request information about underwriting issues associated with policies, use the following endpoints from the Policy
API:

Endpoint Response
GET /policy/v1/policies/{policyId}/uw-issues A collection of underwriting issues associated with the given policy

GET /policy/v1/policies/{policyId}/uw-issues/ The specified underwriting issue

{uwIssueId}

GET /policy/v1/policies/{policyId}/uw-issues/ A collection of UWIssueHistory resources that trace the state history
{uwIssueId}/history of the specified underwriting issue.

Creating underwriting issues

To create an underwriting issue, use the following endpoint:
• POST /job/v1/jobs/{jobId}/uw-issues

Minimum creation criteria

Issue types
At a minimum, an underwriting issue must specify:
• The issue type (specified by the issue type's code)
Through Cloud API, you can create only underwriting issues whose issue type has a checking set value of Manual. If
you attempt to create an underwriting issue using other issue types (such as the QuestionBlockingQuote issue type),
you will get an error message similar to the one below:

"userMessage": "data.attributes.issueType - The underwriting issue type with code

'QuestionBlockingQuote' has checking set 'Question'; expected 'Manual'"

There are two ways you can retrieve a list of existing issue types and their codes: through Cloud API and through
PolicyCenter.

Retrieving issue type codes from Cloud API

From Cloud API, you can use the following endpoint from the Product Definition API:

408 Underwriting issues

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• GET /productdefinition/v1/reference-data/uw-issue-types
The following is a snippet of the output when executing this endpoint from the base configuration. It includes the
response for two issue types: UWManagerReviewBlocksQuoteRelease and TSTManualMonetaryAmount.

{
"data": [
{
"attributes": {
"checkingSet": {
"code": "Manual",
"name": "Manual"
},
"code": "UWManagerReviewBlocksQuoteRelease",
"comparator": {
"code": "None",
"name": "None"
},
"description": "To be reviewed by underwriting manager, blocking quote release",
"name": "To be reviewed by underwriting manager, blocking quote release",
"valueFormatterType": {
"code": "Unformatted",
"name": "Unformatted"
}
},
},
{

"attributes": {
"checkingSet": {
"code": "Manual",
"name": "Manual"
},
"code": "TSTManualMonetaryAmount",
"comparator": {
"code": "Monetary_LE",
"name": "At most (monetary)"
},
"description": "Test manually triggered issue with monetary amount format",
"name": "Test manually triggered issue with monetary amount format",
"valueFormatterType": {
"code": "MonetaryAmount",
"name": "MonetaryAmount"
}
}
...

Retrieving issue type codes from PolicyCenter

You can also retrieve issue type codes directly from PolicyCenter by exporting metadata about the existing
underwriting issues. To do this:
1. In PolicyCenter, navigate to the Utilities screen on the Administration tab. (You must be logged in as a user who
has permission to export admin data.)
2. In the Export Administrative Data column, select Underwriting Issue Types.
3. Click Export.
PolicyCenter generates an XML file with metadata about the underwriting issue types. The code for each issue type is
defined in the <code> tag. The following is a snippet of the output when exporting this data from the base
configuration. It includes the XML for two issue types: UWManagerReviewBlocksQuoteRelease and
TSTManualMonetaryAmount:

<UWIssueType public-id="pc:ScEwfrYMvGZSphmhfSCtk">
<CheckingSet>Manual</CheckingSet>
<Code>UWManagerReviewBlocksQuoteRelease</Code>
<Comparator>None</Comparator>
<Description>To be reviewed by underwriting manager, blocking quote release</Description>
<Name>To be reviewed by underwriting manager, blocking quote release</Name>
<ValueFormatterType>Unformatted</ValueFormatterType>
</UWIssueType>
<UWIssueType public-id="pc:S6FIzWqP5JFpEaPvDURH5">
<CheckingSet>Manual</CheckingSet>
<Code>TSTManualMonetaryAmount</Code>
<Comparator>Monetary_LE</Comparator>
<Description>Test manually triggered issue with monetary amount format</Description>
<Name>Test manually triggered issue with monetary amount format</Name>
<ValueFormatterType>MonetaryAmount</ValueFormatterType>
</UWIssueType>

Underwriting issues 409

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Underwriting issues with conditions

Some underwriter issue types specify a condition, which consists of a comparator and a value. For example, an
underwriting issue could specify that the value of the coverable must be less than or equal to $1000. For these
underwriting issues, the value to be used for the comparison must be specified. The property used to specify this value
depends on the value's datatype.
• Decimal and integer values are specified using the decimalValue and integerValue scalars
• Monetary values are specified using the moneyValue object, with a currency and amount value
• Geographic state values are specified using the stateSetValue object, with:
◦ An inclusionType value set to inclusive
◦ A states array with exactly one typecode from the State typelist

Minimum creation criteria syntax

The following summarizes the syntax for required values. Properties that are required depending on the issue type are
in italics.

{
"data": {
"attributes": {
"issueType": {
"code": "<issue_type_code>"
},
"decimalValue": "<decimal>",
"integerValue": "<integer>
"moneyValue": {
"currency": "<currency>",
"amount": "<decimal>"
},
"stateSetValue": {
"inclusionType": "inclusive",
"states": [
"<code_from_State_typelist>",
"<code_from_State_typelist>"
]
}
}
}
}

Examples of creating an underwriting issue

The following code creates an underwriting issue for job pc:707. The underwriting issue blocks quoting until the job
has been reviewed by an underwriting manager (underwriting issue type UWManagerReviewBlocksQuoteRelease).

POST /job/v1/jobs/pc:707/uw-issues

{
"data": {
"attributes": {
"issueType": {
"code": "UWManagerReviewBlocksQuoteRelease"
}
}
}
}

The following code creates a test underwriting issue for job pc:707 that specifies a monetary condition (underwriting
issue type TSManualMonetaryAmount). The monetary amount used in the condition is $1000 USD.

POST /job/v1/jobs/pc:707/uw-issues

{
"data": {
"attributes": {
"issueType": {
"code": "TSTManualMonetaryAmount"
},
"moneyValue": {
"currency": "usd",
"amount": "1000.00"

410 Underwriting issues

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}
}
}

Managing underwriting issue approval

You can approve, reject, and reopen underwriting issues through Cloud API.

Approval underwriting issues

Types of approval
There are two actions that can be taken to approve an underwriting issue.
In most cases, an underwriting issue is approved. This action is equivalent to clicking the Approve button on the Risk
Analysis screen's UW Issues tab. In this circumstance:

• There is a user who has sufficient authority to approve the issue.

For example, suppose there is a personal auto policy with a driver who is 18 years old. The driver's age triggers the
creation of a "PA: Primary driver under 25" underwriting issue. Alice Applegate is an underwriter who has authority to
approve "PA: Primary driver under 25" underwriting issues for drivers who are 17 or older. Thus, Alice can approve
the underwriting issue on this policy.
In rare cases, an underwriting issue is special approved. This action is equivalent to clicking the Special Approve button
on the Risk Analysis screen's UW Issues tab, which is visible only to users with the uwapproveall system permission.
In this circumstance:
• The underwriting issue is blocking a job that, for the sake of the business, must be moved forward.
• There is no user with sufficient authority to approve the issue.
• There is a user with the uwapproveall system permission.
For example, suppose there is a personal auto policy with a driver who is 16 years old. The driver's age triggers the
creation of a "PA: Primary driver under 25" underwriting issue. There are no underwriters with authority to approve
"PA: Primary driver under 25" underwriting issues for drivers who are 16. But, the decision has been made to move
forward with the policy. Like all other underwriters, the supervisor Shelly Duggan does not have sufficient authority.
But she does have the uwapproveall system permission. Therefore, Shelly can "special approve" the underwriting
issue on this policy.

Approval endpoints
To approve an underwriting issue, use one of the following endpoints:
• POST /job/v1/jobs/{jobId}/uw-issues/{uwIssueId}/approve
• POST /job/v1/jobs/{jobId}/uw-issues/{uwIssueId}/special-approve
These endpoints do not require a request body.
When you either approve or "special approve" an underwriting issue:
• currentBlockingPoint is set to NonBlocking if the issue is fully approved
• hasApprovalOrRejection is set to true

Overriding approval defaults

When approving an underwriting issue, PolicyCenter provides default values for the following:
• The maximum, minimum, or acceptable value on the job that will permit the underwriting issue to be approved.
• Whether the approval can be edited before binding.

Underwriting issues 411

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• The duration of the approval, both as a stage of job processing and as a timeframe.
When approving an underwriting issue through Cloud API, you do not need to specify this information. However, you
can override the defaults by including the following properties in the approval request.

Approval Request body property Datatype Corresponding

default type field on the Risk
Approval Details
screen
Numeric One of the following, based on the String Value
default underwriting issue type:
• decimalApprovalValue
• integerApprovalValue

Money default moneyApprovalValue, which must include currency must be the value from the Value
a currency and amount value Currency typelist that matches the issue's
currency. amount must be a string.
State default stateSetValue object, which must include inclusionType is typically set to Value
an inclusionType and a states array inclusive. Members of the state array must
come from the State typelist and there must
be at least one value.
Approval canEditApprovalBeforeBind Boolean Allow Edit?
editability
Duration by job approvalBlockingPoint From the UWIssueBlockingPoint typelist Through
stage
Duration by approvalDurationType From the UWApprovalDurationType Valid until
time frame typelist which

The following example approves underwriting issue pc:2177 for job pc:707 with overrides for the default values.

POST /job/v1/jobs/pc:707/uw-issues/pc:2177/approve

{
"data": {
"attributes": {
"moneyApprovalValue": {
"currency": "usd",
"amount": "500.00"
},
"canEditApprovalBeforeBind": false,
"approvalBlockingPoint": {
"code": "BlocksIssuance"
},
"approvalDurationType": {
"code": "ThreeYears"
}
}
}
}

Rejecting underwriting issues

To reject an underwriting issue, use the following endpoint:
• POST /job/v1/jobs/{jobId}/uw-issues/{uwIssueId}/reject
The /reject endpoint does not require a request body.
When you reject an underwriting issue:
• currentBlockingPoint is set to Rejected
• Both rejected and hasApprovalOrRejection are set to true

412 Underwriting issues

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Reopening underwriting issues

Reopening an underwriting issue returns a previously approved or rejected underwriting issue to its open state. To
reopen an underwriting issue, use the following endpoint:
• POST /job/v1/jobs/{jobId}/uw-issues/{uwIssueId}/reopen
The /reopen endpoint does not require a request body.
When you reopen an underwriting issue:
• currentBlockingPoint is set to the default blocking point for the issue
• hasApprovalOrRejection is set to false
• If the issue was previous rejected, rejected is set to null

Job locks
A job can be locked to indicate that there are associated underwriting issues to review and the job ought to remain
unchanged while the issues are resolved. By default:
• A job in a draft state is unlocked.
• A job in a quoted state is locked.

Permissions related to job locks

• To edit an unlocked job, you need to have only the corresponding "edit jobType" permission. (For example, to edit a
submission, you must have the editsubmission permission.)
• To edit a locked job, you need to have both the corresponding "edit jobType" permission and the editlockoveride
permission.

Locking jobs
You can lock only jobs that are unlocked. To lock a job, use the following endpoint:
• /job/v1/jobs/{job-id}/edit-lock
The request object does not require a payload.
The /edit-lock endpoint sets the job's editLocked property to true.

Releasing locks
You can release the lock only for jobs that are locked. Note that if a quoted job is returned to a draft state (such as by
executing the POST /make-draft endpoint), it is still locked. You must use the POST /release-edit-lock endpoint
to unlock it.
To release a lock, use the following endpoint:
• /job/v1/jobs/{job-id}/release-edit-lock
The request object does not require a payload.
The /release-edit-lock endpoint sets the job's editLocked property to false.
When you release a lock, PolicyCenter automatically creates an activity using the uw_review_approved activity
pattern ("Underwriter has reviewed this job"). You can also optionally add a note.
When releasing a lock through Cloud API, you can optionally provide a request body with any of the following:
• Overrides of the activity values from the uw_review_approved activity pattern
• Activity assignment information

Underwriting issues 413

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• A note
The following is an example of releasing a lock with this optional information:
• The priority of the activity is set to low (which overrides any priority value coming from the activity pattern).
• The activity is assigned to the group with id demo_sample:31 and the user with id demo_sample:1.
• There is an attached note.

POST /job/v1/jobs/pc:2277/release-edit-lock

{
"data": {
"attributes": {
"activity": {
"priority": {
"code": "low"
},
"initialAssignment": {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:1"
}
},
"note": {
"body": "Lock release submitted through Cloud API",
"subject": "Lock release submitted through Cloud API"
}
}
}
}

For more information on specifying activity attributes, including activity assignment, see “Activities” on page 421.
For more information on specifying note attributes, see “Notes” on page 437.

Requesting approval
In some situations, a job has underwriting issues that cannot be addressed by the user assigned to the job. In these
situations, the assigned user can request approval from another user (typically a user with a greater level of authority).
For example, suppose there is a personal auto submission with three underwriting issues assigned to Alice Applegate.
Alice is able to approve the first two underwriting issues. But the third underwriting issue relates to a high deductible
and Alice lacks authority to approve this issue. Thus, Alice wishes to request approval from her supervisor.
When a user requests approval for an underwriting issue, PolicyCenter creates an activity using the approve_general
activity pattern ("Review and approve"). The requesting user can optionally:
• Override the default values coming from this activity pattern.
• Specify activity assignment logic
• Add a note
You can execute all of this functionality from Cloud API.

Requesting approval through Cloud API

To request approval for a job, use the following endpoint:
• POST /job/v1/jobs/{jobId}/request-approval
The request object does not require a payload. If you do not provide one, the resulting activity will have default values
from the approve_general activity, use default activity assignment, and have no associated note.
You can optionally provide a request body to do any of the following:
• Overrides of the values from the approve_general activity pattern
• Specify activity assignment
• Add a note

414 Underwriting issues

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following is an example of requesting approval with this optional information:

• The priority of the activity is set to low (which overrides any priority value coming from the activity pattern).
• The activity is assigned to the group with id demo_sample:31 and the user with id demo_sample:1.
• There is an attached note.

POST /job/v1/jobs/pc:2277/request-approval

{
"data": {
"attributes": {
"activity": {
"priority": {
"code": "low"
},
"initialAssignment": {
"groupId" : "demo_sample:31",
"userId" : "demo_sample:1"
}
},
"note": {
"body": "Requesting approval for high deductible",
"subject": "Requesting approval for high deductible"
}
}
}
}

For more information on specifying activity attributes, including activity assignment, see “Activities” on page 421.
For more information on specifying note attributes, see “Notes” on page 437.

Referral reasons
While a policy is in force, an insurer may become aware of information that has implications for the policy's renewal.
This information may require underwriter approval, but at the time the renewal has not yet been started. Because there
is no active job, the information cannot be captured as an underwriting issue.
To address these situations, PolicyCenter provides referral reasons. Like underwriting issues, a referral reason is an
object that tracks an issue that may require underwriter review. However, referral reasons are attached only to policies.
The next time a job is created for the policy, the referral reason may trigger the creation of an underwriting issue.

Querying for referral reasons

To request information about referral reasons associated with a policy, use the following endpoint:
• GET /policy/v1/policies/{policyId}/uw-referral-reasons
• GET /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}

Creating referral reasons

To create a referral reason, use the following endpoint:
• POST /policy/v1/policies/{policyId}/uw-referral-reasons

Minimum creation criteria

At a minimum, a referral reason must specify:
• The issue type (specified by the issue type's code)
Referral reasons use the same set of issue types as underwriting issues. Referral reasons created through Cloud API
must have a checking set of Referral. For information on how to retrieve a list of issue types, see “Minimum creation
criteria” on page 408.
As is the case with underwriting issues, some referral reasons require other values, depending on the issueType. For
example:

Underwriting issues 415

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• For money referral reasons, a moneyValue object with amount and currency is required
• For stateSet referral reasons, a stateSetValue object with inclusionType and states is required, and states
must have one or more members.
• The LegacyReferralReason issue type is explicitly disallowed by Cloud API.
The following fields are not required to create a referral reason. However, they are displayed in the user interface.
Referral reasons that do not have these fields specified may be difficult to work with in the user interface.
• A shortDescription (displayed when listing referral reasons)
• A longDescription (displayed when providing details about referral reasons)

Example of creating a referral reason

The following code creates a referral reason for policy pc:707. The referral reason (ReferralBlockingQuote) will be
used to create an underwriting issue that blocks quoting until an underwriter has reviewed the policy for potential
fraud.

POST /policy/v1/policies/pc:707/uw-referral-reasons

{
"data": {
"attributes": {
"issueType": {
"code": "ReferralBlockingQuote"
},
"shortDescription": "Potential fraud",
"longDescription": "Potential fraud - verify appraisal values for covered luxury items are accurate"
}
}
}

Closing and reopening referral reasons

For underwriting issues, you can resolve the issue and allow the job to move forward by either approving the issue or
"special approving" the issue. For more information on underwriting issue approval, see “Managing underwriting issue
approval” on page 411.
Referral reasons have a similar behavior. You can resolve a referral reason by either closing the reason or "special
closing" the reason. In either case, PolicyCenter will not create an open underwriting issue from the referral reason
when the next job is initiated.

Closing a referral reason

In most cases, a referral reason that is resolved is resolved by closing it. This action is equivalent to clicking the Close
button on the Risk Analysis screen's UW Referral Reasons tab.
To close a referral reason through Cloud API, use the following endpoint:
• POST /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}/close
The /close endpoint does not require a request body. When you close a referral reason, the status is set to "Closed".

"Special closing" a referral reason

In rare cases, an underwriting issue is closed by special closing it. This action is equivalent to clicking the Special Close
button on the Risk Analysis screen, which is visible only to users with the uwapproveall system permission.
To "special close" a referral reason through Cloud API, use the following endpoint:
• POST /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}/special-close
The /special-close endpoint does not require a request body. When you "special close" a referral reason, the status is
set to "Closed".

416 Underwriting issues

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Reopening a referral reason

To reopen a closed referral reason, use the following endpoint:
• POST /policy/v1/policies/{policyId}/uw-referral-reasons/{uwReferralReasonId}/reopen
The /reopen endpoint does not require a request body. When you reopen a closed referral reason, the status is set to
"Open".

Underwriting issues 417

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

418 Underwriting issues

part 7

Business flows: Framework APIs

The InsuranceSuite Cloud API is a set of RESTful system APIs that expose functionality in PolicyCenter so that caller
applications can request data from or initiate action within PolicyCenter.
The following topics discuss how caller applications can initiate business flows related to the Common API and the
Admin API. This includes:
• The Common API
◦ Activities
◦ Documents
◦ Notes
• The Admin API
◦ Users and groups
◦ Security zones
◦ Batch processes
◦ Database consistency checks
◦ Business entity schemas
◦ Testing
◦ Working with organizations
◦ Working with producer codes

Business flows: Framework APIs 419

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

420 Business flows: Framework APIs

chapter 47

Activities

An activity is an action related to the processing of an account, job, or policy 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 PolicyCenter 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 PolicyCenter, 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 accounts, jobs, and policies. These objects do
not exist in all InsuranceSuite applications. This means that other activity endpoints, such as the endpoint for
creating an activity for a job, are declared in the Account API, Job API, or Policy 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 PolicyCenter, activities can be
attached to accounts, jobs, or policies.
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
/account/v1/accounts/{accountId}/activities All activities associated with the given account
/job/v1/jobs/{jobId}/activities All activities associated with the given job
/policy/v1/policies/{policyId}/activities All activities associated with the given policy

Activities 421
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Note that the endpoints to retrieve activities exist in different APIs. To get all activities for an account, job, or policy,
you use endpoints in the Account API, Job API, or Policy API. But to get information about all activities (regardless of
parent), or to get information about a specific activity, you use endpoints in the Common API.
For example, the following query retrieves the IDs and subjects of all activities for account pc:101. This endpoint is in
the Account API.
Request

GET account/v1/accounts/pc:101/activities?fields=id,subject

Response

{
"count": 2,
"data": [
{
"attributes": {
"id": "pc:23221",
"subject": "All ordered MVRs received - Clear"
}
},
{
"attributes": {
"id": "pc:40404",
"subject": "Review Risk Information"
}
}
],
...

The following query retrieves activity pc:40404 in detail. This endpoint is in the Common API.
Request

GET /common/v1/activities/pc:40404

Response

{
"data": {
"attributes": {
"activityType": {
"code": "general",
"name": "General"
},
"assignedGroup": {
"displayName": "Los Angeles Branch UW",
"id": "pc:SPMK8WfF0qE3G7erNndfW"
},
"assignedUser": {
"displayName": "Alice Applegate",
"id": "pc:SSmfb1spW-C2IyI8rFOja",
"type": "User",
"uri": "/admin/v1/users/pc:SSmfb1spW-C2IyI8rFOja"
},
"assignmentStatus": {
"code": "assigned",
"name": "Assigned"
},
"createTime": "2023-11-26T08:02:56.607Z",
"description": "Review the risk information for the policy's scheduled items.",
"dueDate": "2023-11-26T08:02:56.604Z",
"escalated": false,
"externallyOwned": false,
"id": "pc:40404",
"mandatory": false,
"priority": {
"code": "normal",
"name": "Normal"
},
"recurring": false,
"status": {
"code": "open",
"name": "Open"
},
"subject": "Review Risk Information"
},
...

422 Activities
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Creating activities
Activities must be created from an existing account, job, or policy using one of the following endpoints:
• POST account/v1/accounts/{accountId}/activities
• POST job/v1/jobs/{jobId}/activities
• POST policy/v1/policies/{policyId}/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 /account/v1/accounts/{accountId}/activity-patterns
• GET /job/v1/jobs/{jobId}/activity-patterns
• GET /policy/v1/policies/{policyId}/activity-patterns
You can optionally specify values for the following fields, each of which overrides the value coming from the activity
pattern:

Field Datatype Description Default

description string The activity's description Typically comes from the activity
pattern
dueDate datetime The date by which the activity is expected to Typically calculated based on
be completed values in the activity pattern
escalationDate datetime The date on which the activity will be Typically calculated based on
escalated if it has not yet been completed values in the activity pattern
externallyOwned Boolean Whether the activity is to be assigned to an Typically comes from the activity
external group or external user pattern
importance Typekey (a value from the The activity's importance, as reflected on Typically comes from the activity
ImportanceLevel typelist) the user's calendar pattern
mandatory Boolean Whether the activity must be completed Typically comes from the activity
(true) or can be skipped (false) pattern
priority Typekey (a value from the The activity's priority Typically comes from the activity
Priority typelist) pattern
recurring Boolean Whether the activity repeats. If true, Typically comes from the activity
completing the activity creates a new one. pattern
subject String The activity's subject Typically comes from the activity
pattern

Examples of creating activities

The following is an example of creating a contact_insured activity for account pc:10. The activity defaults to all
values in the contact_insured activity pattern.
Command

POST /account/v1/accounts/pc:10/activities

Activities 423
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Request

{
"data": {
"attributes": {
"activityPattern": "contact_insured"
}
}
}

The following is an example of creating a legal_review activity for account pc:10. In this case, two activity pattern
values are overridden: the activity is mandatory (it cannot be skipped) and the priority is urgent.
Command

POST /account/v1/accounts/pc:10/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, PolicyCenter automatically executes the activity assignment rules to
initially assign the activity to a group and user. You can use the /{activityId}/assign endpoint to reassign the
activity as needed.

Assignment options
An activity can be assigned through Cloud API in the following ways:
• To a specific group and user in that group
• To a specific group only (and then PolicyCenter uses assignment rules to select a user in that group)
• To a specific group and queue
• To the user who holds a given role on the parent account, job, or policy
• By re-running the activity assignment rules
◦ This can be appropriate if you have modified the activity since the last time assignment rules were run and the
modification might affect who the activity would be assigned to.
The root resource for the /{activityId}/assign endpoint is Assignee. This resource specifies assignment criteria.
The Assignee schema has the following fields:

Field Type Description

autoAssign Boolean Whether to assign the activity using assignment rules
groupId string The ID of the group to assign the activity to

424 Activities
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Field Type Description

queueId string The ID of the queue to assign the activity to
role TypeKey (a value from the UserRole The role on the parent object that identifies the user to assign the activity to
typelist)
userId string The ID of the user to assign the activity to

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

Assignment examples
When assigning activities to users, the user must be active and must have the "own activity" system permission.

Assigning to a specific group (and user)

The following payload assigns activity xc:1 to group demo_sample:31 and user demo_sample:1.

POST /common/v1/activities/xc:1/assign

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

The following payload assigns activity xc:1 to group demo-sample:31. Because no user has been specified,
PolicyCenter will execute assignment rules to assign the activity to a user in group demo-sample:31.

POST /common/v1/activities/xc:1/assign

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

Assigning to a specific queue

The following payload assigns activity xc:1 to queue cc:32. Every queue is associated with a single group, so the
activity will also be assigned to that group. Users in that group who have access to this queue can then manually take
ownership of the activity.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes" : {
"queueId": "cc:32"
}
}
}

Assigning to a user with a given role

When an activity is assigned by role, PolicyCenter looks at the activity's parent (the account, job, or policy) and
identifies the user with the given role. The activity is then assigned to that user. The role must be a code from the
UserRole typelist.

For example, if an account activity is to be assigned to Underwriter and the underwriter for the account is Bruce
Baker, the activity is assigned to Bruce Baker.
If you attempt to assign an activity by role and there is no user on the parent object with the given role, PolicyCenter:
• Identifies the user that created the object (This is the user with the Creator role.)

Activities 425
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Adds the given role to this user

• Assigns the activity to this user
For example, suppose there is an account created by Christine Craft. The account has no underwriter. If a Cloud API
call attempts to assign an activity for this account to Underwriter, PolicyCenter will add the underwriter role to
Christine Craft and then assign the activity to her.
The following payload assigns activity xc:1 to the user on the activity parent that has the underwriter role.

POST /common/v1/activities/xc:1/assign

{
"data": {
"attributes" : {
"role" : {
"code" : "Underwriter"
}
}
}
}

Using automated assignment

The following payload assigns activity xc:1 using automated assignment rules.

POST /common/v1/activities/xc:1/assign

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

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

Retrieving recommended assignees

When PolicyCenter users are assigning activities manually, the user interface includes a drop-down list of
"recommended assignees". Typically, this list includes:
• The roles held by users on the parent object
• 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
/account/v1/accounts/{accountId}/activity-assignees The list of suggested assignees for activities on this account

/job/v1/jobs/{jobId}/activity-assignees The list of suggested assignees for activities on this job

/policy/v1/policies/{policyId}/activity-assignees The list of suggested assignees for activities on this policy

The following is a portion of an example response from the Common API's /assignees endpoint.

GET /common/v1/activities/pc:301/assignees

RESPONSE:
{
"count": 5,
"data": [
{
"attributes": {
"name": "Creator",

426 Activities
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"role": {
"code": "Creator",
"name": "Creator"
}
}
},
{
"attributes": {
"groupId": "systemTables:1",
"name": "Edward Lee (Enigma Fire & Casualty)",
"userId": "pc:23"
}
},
{
"attributes": {
"groupId": "systemTables:1",
"name": "Alice Applegate (Enigma Fire & Casualty)",
"userId": "pc:8"
}
},
...
],
...

Closing activities
An 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.
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.

Activities 427
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following payload skips activity xc:1.

POST /common/v1/activities/xc:1/skip

<no request payload>

The following payload skips activity xc:1 and creates a note.

POST /common/v1/activities/xc:1/skip

{
"included": {
"Note": [
{
"attributes": {
"body": "This activity was skipped by a system API call."
},
"method": "post",
"uri": "/common/v1/activities/xc:1/notes"
}
]
}
}

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

428 Activities
chapter 48

Documents

In PolicyCenter, a document is an electronic file (such as a PDF, Word document, or digital photograph) which
contains information relevant to an account, job, or policy. Examples of documents could include photographs of
covered jewelry, assessments from property inspectors, or correspondences with the insured. (Note that documents do
not contain contractual parts of the policy. The policy contract is specified in PolicyCenter forms, not PolicyCenter
documents.)
For a complete description of the functionality of documents in PolicyCenter, 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 accounts, jobs, and
policies. These objects do not exist in all InsuranceSuite applications. This means that other document
endpoints, such as the endpoint for creating a document for a job, are declared in the Account API, Job API, or
Policy 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,
PolicyCenter documents are always attached to an account, a job, or a policy.
In ContactManager, documents can be attached only to vendor contacts (contacts with the "vendor" tag).

Document metadata and content

The PolicyCenter 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. PolicyCenter 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 429
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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
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
/account/v1/accounts/{accountId}/documents Metadata for documents on the given account
/job/v1/jobs/{jobId}/documents Metadata for documents on the given job
/policy/v1/policies/{policyId}/documents Metadata for documents on the given policy

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

430 Documents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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 /account/v1/accounts/{accountId}/documents
• POST /job/v1/jobs/{jobId}/documents
• POST /policy/v1/policies/{policyId}/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)

Minimum creation criteria

When POSTing a document, the metadata JSON must include the following fields:
• name
• status (a typecode from the DocumentStatusType typelist)
• type (a typecode from the DocumentType typelist)
The content value is not required. In some use cases, it can be omitted.

Use cases for POSTing document information

There are several ways that a caller application can POST document information:

Documents 431
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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.
• PolicyCenter 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 account pc:10 that does not yet
exist in the Document Management System.

POST /account/v1/accounts/pc:10/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 account pc:10 that does exist in
the Document Management System with id "doc:11-31".

POST /account/v1/accounts/pc:10/documents

METADATA:
{
"data": {
"attributes": {
"docUID": "doc:11-31",
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}

CONTENTS:
<no content specified>

432 Documents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

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 PolicyCenter). 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 PolicyCenter must track.

POST /account/v1/accounts/pc:10/documents

METADATA:
{
"data": {
"attributes": {
"name": "Printout of email from auto dealership",
"status": {
"code": "final"
},
"type": {
"code": "letter_received"
}
}
}
}

CONTENTS:
<no content specified>

If a POST /documents call needs to specify document metadata only, it can be executed using a request body that is
formatted as JSON (as opposed to FormData). For more information, see “Sending document metadata only using
JSON” on page 435.

POSTing documents using Postman

About this task
From Postman, you can POST documents using FormData objects. When doing so, both the metadata and content must
be stored in separate files referenced by the Postman call.
Note: Every POST /documents endpoint supports the ability to receive the metadata as either a string or a file.
However, there is a known issue with Postman which prevents the sending of metadata as a string. When using
Postman, the metadata can be sent only as file. This is described in the following procedure. (Client
applications other than Postman may support both string and file.)

Procedure
1. Identify the files needed for the FormData object. This includes:
• A JSON file that contains the metadata. (The file extension must be .json.)
• The document file that has the content.
2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
3. Under the Untitled Request label, select POST.
4. In the Enter request URL field, enter the URL for the server and the endpoint.
• For example, to POST a document to an account on an instance of PolicyCenter on your machine, enter:
http://localhost:8180/pc/rest/account/v1/accounts/{accountId}/documents
5. On the Authorization tab, specify authorization information as appropriate.

Documents 433
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

6. Specify the request payload.

a) In the first row of tabs (the one that starts with Params), click Body.
b) In the row of radio buttons, select form-data.
c) On the first line, for KEY, enter: metadata
d) Click outside of the metadata cell. Then, mouse over the right side of the cell. A drop-down list appears.
Change the value from Text to File.
e) For VALUE, click the Select Files button and navigate to the JSON file containing the metadata.
f) On the second line, for KEY, enter: content
g) Click outside of the content cell. Then, mouse over the right side of the cell. A drop-down list appears.
Change the value from Text to File.
h) For VALUE, click the Select Files button and navigate to the file containing the document content.
7. Click Send. The response payload appears below the request payload.

PATCHing documents
Use the following to PATCH documents:
• PATCH /common/v1/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 435.

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

PATCH /common/v1/documents/xc:127

METADATA:

434 Documents
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

<contents of "Property Assessment Report.pdf" file>

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.

PATCH /common/v1/documents/xc:127

METADATA:
{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}

<contents of "Property Assessment Report.pdf" file>

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 PolicyCenter and ContactManager.
For example, the following call updates only the metadata document for document pc:555 for account pc:102. In this
case, the call can be sent with a request body formatted as JSON.

PATCH /account/v1/accounts/pc:102/documents/pc:555

{
"data": {
"attributes": {
"status": {
"code": "final"
}
}
}
}

DELETEing documents
Use the following to DELETE documents:
• /common/v1/documents/{documentId}
For example, the following request DELETEs document xc:101:

PATCH /common/v1/documents/xc:101

<no request body>

Documents 435
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

436 Documents
chapter 49

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 PolicyCenter. They can
also be created by caller applications using Cloud API.
Through Cloud API, a note can be attached to an account, a job, or a policy. Notes can also be attached to activities.
For a complete description of the functionality of notes in PolicyCenter, 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 endpoints for querying for a note with a given ID, are
declared in the Common API. Notes can also belong to accounts, jobs, and policies. These objects 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 job, are declared in the Account API, Job API, or Policy 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)
/account/v1/accounts/{accountId}/notes All notes associated with the given account
/job/v1/jobs/{jobId}/notes All notes associated with the given job
/policy/v1/policies/{policyId}/notes All notes associated with the given policy
/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.
Notes 437
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The /common/v1/notes/{noteId} endpoint can be used to retrieve any note in PolicyCenter. This includes notes that
are attached to a parent object other than an account, job, or policy.

Creating account, job, and policy notes

Notes must be created from an existing account, job, policy, or activity using one of the following endpoints:
• POST account/v1/accounts/{accountId}/notes
• POST job/v1/jobs/{jobId}/notes
• POST policy/v1/policies/{policyId}/notes
• POST common/v1/activities/{activityId}/notes
Be aware that PolicyCenter supports notes attached to other objects as well, such as PolicyPeriods. However, as of the
current release, Cloud API does not yet support the ability to create notes for parent objects beyond accounts, jobs,
policies, and activities.
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
securityType Typekey (a value from the NoteSecurityType typelist) The note's security type NULL
subject string The note's subject NULL
topic Typekey (a value from the NoteTopicType typelist) The note's topic type general

Minimal notes
The following is an example of creating a note for account pc:10.

POST /account/v1/accounts/pc:10/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 account pc:10.

POST /account/v1/accounts/pc:10/notes

{
"data": {
"attributes": {
"body": "The insured's last name, Cahill, is pronounced 'KAH-hill', not 'KAY-hill'." ,
"confidential": false,
"securityType": {
"code": "unrestricted"
},
"subject": "Pronunciation note",
"topic": {
"code": "general"
}
}
}
}

Notes for an activity

The following is an example of creating a note for activity xc:22.

POST /common/v1/activities/xc:22/notes

438 Notes
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"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 439
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

440 Notes
chapter 50

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 PolicyCenter and who is listed in the PolicyCenter 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 PolicyCenter but who are not
listed in the PolicyCenter database (such as account holders, policy holders, and service vendors).
For information on working with services and external users, see the Cloud API Developer Guide.
Note: Be aware that Cloud API enforces application constraints specified in internal code, but it does not
enforce constraint specified in the user interface. This is because internal code constraints cannot be modified or
removed, but user interface constraints can. As a result of this, there may be actions you can execute through
Cloud API that you cannot execute through the base configuration user interface.
For example, there is no internal code that requires a user to have a phone number. Therefore, you can create
and modify a user through Cloud API without ever specifying a primary phone number. However, the base
configuration user interface does require you to specify a phone number. Therefore, any user that you modify
through the base configuration user interface must have a phone number, even when that user was created
through Cloud API without a phone number.
If there is a desire to have the constraints of the two environments match, insurers can add constraints to Cloud
API and/or remove them from the user interface.

Querying for user information

To retrieve information about a user, you can use the following endpoints:
• GET /admin/v1/users
• GET /admin/v1/users/{userId}
For example, the following is the snippet of the response payload when retrieving the information for user pc:S-
sAtIMQDbK0z3b2E7Mvw (Alice Applegate).
Users and groups 441
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Note:

By default, only users in the requesting user’s organization will be returned. To retrieve users in all
organizations, include the following filter query parameter:
GET /admin/v1/users?filter=*none

Command

GET /admin/v1/users/pc:S-sAtIMQDbK0z3b2E7Mvw

Response

{
"data": {
"attributes": {
"active": true,
"displayName": "Alice Applegate",
"externalUser": false,
"firstName": "Alice",
"groups": [
{
"displayName": "Los Angeles Branch UW",
"id": "pc:SSXQ8EaLxQq4LZ33Ia76r"
},
{
"displayName": "Eastern Region Underwriting",
"id": "pc:SVZTqTgdrHJKYQV9aGCbN"
}
],
"id": "pc:S-sAtIMQDbK0z3b2E7Mvw",
"lastName": "Applegate",
"organization": {
"displayName": "Enigma Fire & Casualty",
"id": "systemTables:1",
"type": "Organization",
"uri": "/admin/v1/organizations/systemTables:1"
},
"roles": [
{
"displayName": "Reinsurance Manager",
"id": "reinsurance_manager",
"type": "Role"
},
{
"displayName": "Underwriter",
"id": "underwriter",
"type": "Role"
}
],
"useOrgAddress": true,
"useProducerCodeSecurity": false,
"userType": {
"code": "underwriter",
"name": "Underwriter"
},
"username": "aapplegate",
"uwAuthorityProfiles": [
{
"displayName": "Underwriter 1",
"id": "pc:underwriter1",
"type": "UWAuthorityProfile",
"uri": "/admin/v1/uw-authority-profiles/pc:underwriter1"
}
],
"vacationStatus": {
"code": "atwork",
"name": "At work"
},
"workPhone": {
"displayName": "213-555-8164",
"number": "2135558164"
}
}
}
}

Creating users
To create a user, use the following endpoint:

442 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• POST /admin/v1/users
Note: When a user is created through Cloud API, the user's password is set to a value that cannot be used for
authentication. (The password is set to a value that is not a valid Base64 string, but the authentication
framework can authenticate passwords only when they are valid Base64 strings.) In order for the new user to
authenticate, the password must first be changed to a valid Base64 string through some other method, such as
through the user interface.

Create a minimal user

The minimum creation criteria for a user is the username. For example, the following request creates a user with the
user name "amartin".

{
"data": {
"attributes": {
"username": "amartin"
}
}
}

The following is the response payload.

POST /admin/v1/users

{
"data": {
"attributes": {
"active": true,
"displayName": "",
"externalUser": false,
"id": "pc:SatEdbNuwVSfc2BvbG4g4",
"organization": {
"displayName": "Enigma Fire & Casualty",
"id": "systemTables:1",
"type": "Organization",
"uri": "/admin/v1/organizations/systemTables:1"
},
"useOrgAddress": true,
"useProducerCodeSecurity": false,
"userType": {
"code": "other",
"name": "Other"
},
"username": "amartin",
"vacationStatus": {
"code": "atwork",
"name": "At work"
}
},
"checksum": "8b01f84c8076ba3f8c235cb2483cdbfb",
"links": {
"self": {
"href": "/admin/v1/users/pc:SatEdbNuwVSfc2BvbG4g4",
"methods": [
"get",
"patch"
]
}
}
}
}

Create a typical user

You can specify additional information about a user as specified in the User schema. For example, the following
payload creates a user with the following attributes:
• First name: Adriana
• Last name: Diaz
• User name: adiaz
• Employee number: ACME-02027

Users and groups 443

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Roles: audit examiner (audit_examiner) and audit supervisor (audit_supervisor)

POST /admin/v1/users

{
"data": {
"attributes": {
"firstName": "Adriana",
"lastName": "Diaz",
"username": "adiaz",
"employeeNumber": "ACME-02027",
"roles" : [
{
"id": "audit_examiner"
},
{
"id": "audit_supervisor"
}

]
}
}
}

When you create a user, you can also specify the user's roles, authority profile, and producer codes (if the user is bound
by producer code security).
• For more information on working with user roles, see “User roles” on page 450.
• For more information on working with authority profiles, see “Authority profiles” on page 453.
• For more information on working with a user's producer codes, see “Producer codes” on page 465.

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

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.

444 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Querying for groups

To retrieve information about a group, use the following endpoints:
• GET /admin/v1/groups
• GET /admin/v1/groups/{groupId}
For example, the following is the snippet of the response payload when retrieving the information for group
demo_sample:31.

GET /admin/v1/users/demo_sample:31

{
"data": {
"attributes": {
"displayName": "Alexandria Branch",
"groupType": {
"code": "branch",
"name": "Branch office"
},
"id": "demo_sample:31",
"name": "Alexandria Branch",
"parent": {
"displayName": "Eastern Region",
"id": "demo_sample:29",
"type": "Group",
"uri": "/admin/v1/groups/demo_sample:29"
},
"securityZone": {
"displayName": "Auto and Property",
"id": "default_data:1"
},
"supervisor": {
"displayName": "Sue Smith",
"id": "demo_sample:2",
"type": "User",
"uri": "/admin/v1/users/demo_sample:2"
}
},
...
}
}

Creating groups
To create a group, use the following endpoint:
• POST /admin/v1/groups
When creating a group, you must specify the following values:
• groupType - a value from the GroupType typelist, such as general
• name - a string value
• parent - A JSON object with an id field that references the id of the parent group
• securityZone - A JSON object with an id field that references the id of the group's security zone
• supervisor - A JSON object with an id field that references the id of the user who is the supervisor
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"
},

Users and groups 445

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"name": "Cloud API Group 1",

"parent": {
"id": "systemTables:1"
},
"securityZone": {
"id": "default_data:1"
},
"supervisor": {
"id": "demo_sample:7"
}
}
}
}

Assigning users to a group

You cannot assign a user to a group using the /admin/v1/users endpoint. You must use the /admin/v1/groups/
{groupId}/users endpoint. For more information, see “Assigning users to groups” on page 446

Assigning producer codes to a group

A group can be associated with one or more producer codes. For more information, see “Producer codes” on page 465.
.

Assigning users to groups

The GroupUser entity
In PolicyCenter, 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

446 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"count": 12,
"data": [
{
"attributes": {
"id": "cc:SfZwdri9ldAAUgR46xZT7",
"manager": false,
"member": true,
"user": {
"displayName": "Andy Applegate",
"id": "demo_sample:1",
"type": "User",
"uri": "/admin/v1/users/demo_sample:1"
}
},
...
},
{
"attributes": {
"id": "cc:SZPhG_CUIA3E1sO2AiZ_s",
"manager": false,
"member": true,
"user": {
"displayName": "Betty Baker",
"id": "demo_sample:8",
"type": "User",
"uri": "/admin/v1/users/demo_sample:8"
}
},
...
},
...

Adding a user to a group

To add a user to a group, use the following endpoint:
• POST /admin/v1/groups/{groupId}/users
In the request, you must specify the user to be added to the group. You can optionally specify other attributes. If you do
not, the following default values are used:
• member: true
• manager: false
• loadFactor: null
For example, the following request adds user demo_sample:18 to group demo_sample:31.

POST /admin/v1/groups/demo_sample:31/users

{
"data": {
"attributes": {
"user": {
"id": "demo_sample:18"
}
}
}
}

This assigns user demo_sample:18 to group demo_sample:31 as a member. The user is not a manager of the group and
has a null load factor. (If a field’s value is null, the field is not included in Cloud API responses.)

Modifying information about a user’s GroupUser assignment

To modify a user’s GroupUser assignment information, use the following endpoint:
• PATCH /admin/v1/groups/{groupId}/users/{groupID}
For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser
object whose id is xc:55. This user is a member of the group and not a manager of the group. The following PATCHes
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

Users and groups 447

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"data": {
"attributes": {
"manager": true,
"member": false
}
}
}

Removing a user from a group

To remove a user from a group, you must delete the corresponding GroupUser assignment. To do this, use the
following endpoint:
• DELETE /admin/v1/groups/{groupId}/users/{groupUserId}
For example, suppose that user demo_sample:18 has been added to group demo_sample:31 through a GroupUser
object whose id is xc:55. The following request removes user demo_sample:18 to group demo_sample:31.

DELETE /admin/v1/groups/demo_sample:31/users/xc:55

<no request body>

Updating groups
Use the following endpoint to modify an existing group:
• PATCH /admin/v1/groups/{groupId}
For example, the following request updates the supervisor of group xc:202:
PATCH /admin/v1/groups/xc:202

{
"data": {
"attributes": {
"supervisor": {
"id": "demo_sample:6"
}
}
}
}

Deleting groups
Use the following endpoint to delete an existing group:
• DELETE /admin/v1/groups/{groupId}
For example, the following request deletes group xc:202:
DELETE /admin/v1/groups/xc:202

<no request body>

Queues
A queue is a named repository that belongs to a specific group and that contains activities assigned to the group but not
yet to any user in the group. Users who belong to the group can assign activities in a queue to themselves. Queues are
often used to allow users in a group to take ownership of activities as their workload or expertise permits.
In the data model, queues are managed using the AssignableQueue data model entity.
In order to work with queues in the base configuration, the following must exist:
• 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

448 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Users and groups 449

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

User roles
A system permission is a granular permission that identifies something a user can view, edit, create, or otherwise work
with.
A user role is a named group of system permissions. User roles simplify the work of granting access by allowing a set
of related system permissions to be assigned to a user. (Note that in most Guidewire documentation, user roles are
referred to simply as "roles". The Cloud API documentation uses the term "user role" to help distinguish them from
"API roles", which is a feature with a similar purpose but different underlying functionality.)

Querying for user roles

To retrieve information about user roles, use the following endpoints:
• GET /admin/v1/roles
• GET /admin/v1/roles/{roleId}
For example, the following is the snippet of the response payload when retrieving the first four roles in the base
configuration.

GET /admin/v1/roles?pageSize=4

{
"count": 5,
"data": [
{
"attributes": {
"carrierInternal": true,
"description": "Permissions for account admin",
"displayName": "Account Manager",
"id": "account_manager",
"name": "Account Manager"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "All permissions related to activity rules",
"displayName": "Activity Rules Admin",
"id": "activity_rules_admin",
"name": "Activity Rules Admin"
}
},
{

450 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"attributes": {
"carrierInternal": true,
"description": "Permissions to edit activity rules",
"displayName": "Activity Rules Editor",
"id": "activity_rules_editor",
"name": "Activity Rules Editor"
}
},
{
"attributes": {
"carrierInternal": true,
"description": "Permissions to view activity rules",
"displayName": "Activity Rules Viewer",
"id": "activity_rules_viewer",
"name": "Activity Rules Viewer"
}
}
]
}

Querying for permissions in a user role

To retrieve information about the permissions in a given user roles, use the following endpoints:
• GET /admin/v1/roles/{roleId}/permissions
• GET /admin/v1/roles/{roleId}/permissions/{permissionId}
For example, the following is the snippet of the response payload when retrieving the first three permissions associated
with a "claims_adjuster" role:

GET /admin/v1/roles/claims_adjuster/permissions

{
"count": 25,
"data": [
{
"attributes": {
"id": "sample_data:213",
"permission": {
"code": "lvprint",
"name": "Print listviews"
}
},
...
},
{
"attributes": {
"id": "sample_data:222",
"permission": {
"code": "searchpols",
"name": "Search related policies"
}
},
...
},
{
"attributes": {
"id": "sample_data:210",
"permission": {
"code": "actview",
"name": "View activities"
}
},
...
},
...

Creating user roles

To create a role through Cloud API, you must use multiple endpoints. The role itself is created using the /roles
endpoint. Permissions are added to the role using the /permissions endpoint.

Create the role

To create a role, use the following endpoint:
• POST /admin/v1/roles
For new roles, you must specify the following:

Users and groups 451

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• 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 and
response inclusion” on page 111.
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": [

452 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

{
"attributes": {
"permission": {
"code": "noteview"
}
},
"method": "post",
"uri": "/admin/v1/roles/this/permissions"
}
]
}
}

Updating user roles

Use the following endpoints to modify an existing role.

Endpoint Description
PATCH /admin/v1/roles/{roleId} Modify attributes about the role, such as its name or description
DELETE /admin/v1/roles/{roleId}/permissions/ Remove a permission from a role
{permissionId}
DELETE /admin/v1/roles/{roleId} Delete a role

Example of PATCHing a role

The following request modifies the name and description of role xc:222.

PATCH /admin/v1/roles/xc:222

{
"data": {
"attributes": {
"name": "Finance Administrator",
"description": "User role for finance administrators"
}
}
}

Example of removing a permission

The following request removes the permission with id xc:515 (notecreate) from role xc:222.

DELETE /admin/v1/roles/xc:222/permissions/xc:515

<no request body>

Example of DELETEing a role

The following request deletes role xc:222.

DELETE /admin/v1/roles/xc:222

<no request body>

You cannot a delete a role if it is associated with one or more users.

Authority profiles
An underwriting issue is an object attached to a policy transaction that indicates some aspect of the transaction requires
review and approval by an underwriter. Underwriting issues are created automatically by underwriting rules.
An authority profile is a collection of authority grants that can be associated with one or more users. Each authority
grant lists a type of underwriting issue, with an optional condition, that the associated users can approve. For example,
a given authority profile could grant the ability to approve the following types of underwriting issues:
• Producer code changed (issue type with no condition)

Users and groups 453

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• Claim total incurred is greater than $10,000 (issue type with a "> 10000" condition)
Through Cloud API, you can retrieve information about authority profiles and assign them to users. You can also
create, update, and delete them.

Retrieving information about underwriting authority profiles

To retrieve information about underwriting authority profiles, use the following endpoints:
• GET /admin/v1/uw-authority-profiles
• GET /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}
For example, the following payload retrieves information about the base configuration underwriting authority profiles.
(Checksum and link information has been omitted.)

GET /admin/v1/uw-authority-profiles/

{
"count": 9,
"data": [
{
"attributes": {
"description": "Agent 1",
"displayName": "Agent 1",
"id": "pc:agent1",
"name": "Agent 1"
}
},
{
"attributes": {
"description": "Agent 2",
"displayName": "Agent 2",
"id": "pc:SFWdb3rRQxDA9AyksL1p_",
"name": "Agent 2"
}
},
{
"attributes": {
"description": "External User Profile",
"displayName": "External User Profile",
"id": "authorityprofile:extuser",
"name": "External User Profile"
},
},
{
"attributes": {
"description": "Service User Profile",
"displayName": "Service User Profile",
"id": "authorityprofile:serviceuser",
"name": "Service User Profile"
}
},
{
"attributes": {
"description": "Unauthenticated User Profile",
"displayName": "Unauthenticated User Profile",
"id": "authorityprofile:uauser",
"name": "Unauthenticated User Profile"
}
},
{
"attributes": {
"description": "Underwriter 1",
"displayName": "Underwriter 1",
"id": "pc:underwriter1",
"name": "Underwriter 1"
}
},
{
"attributes": {
"description": "Underwriter 2",
"displayName": "Underwriter 2",
"id": "pc:underwriter2",
"name": "Underwriter 2"
}
},
{
"attributes": {
"description": "Underwriter Manager",
"displayName": "Underwriter Manager",
"id": "pc:SeOY1PmQwKcwQnuWvmCOy",
"name": "Underwriter Manager"
}

454 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
{
"attributes": {
"description": "internet portal",
"displayName": "internet portal",
"id": "pc:SZ6snOkKD_qhPHsqGgGwy",
"name": "internet portal"
}
}
]
}

Assigning authority profiles to users

When you create or edit a user, you can specify the user's authority profiles. For example, the following payload
creates a user with the following attributes:
• First name: Devon
• Last name: Byrne
• User name: dbyrne
• Roles: underwriter (underwriter)
• Authority profiles: Underwriter 1 (pc:underwriter1)

POST /admin/v1/users

{
"data": {
"attributes": {
"firstName": "Devon",
"lastName": "Byrne",
"username": "dbyrne",
"roles": [
{
"id": "underwriter"
}
],
"uwAuthorityProfiles": [
{
"id": "pc:underwriter1"
}
]
}
}
}

Modifying authority profile assignment

Similar to modifying a user's roles, you can use the PATCH /admin/v1/users/{userId} endpoint to assign or
unassign authority profiles to an existing user by modifying the uwAuthorityProfiles array.
Note that, within 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. 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.
For example, suppose you have an existing user named Devon Byrne with an ID of pc:235 and the Underwriter 1
authority profile (pc:underwriter1). You want to add the Underwriter 2 authority profile (pc:underwriter2) to this
user. To do so, you must use the following payload. (Note that the payload specifies the existing profile and the new
profile.)

PATCH /admin/v1/users/pc:235

{
"data": {
"attributes": {
"uwAuthorityProfiles": [
{
"id": "pc:underwriter1"
},
{
"id": "pc:underwriter2"
}

Users and groups 455

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

]
}
}
}

Creating authority profiles

Use the following endpoint to create an authority profiles:
• POST /admin/v1/uw-authority-profiles
The only required field is the profile's name.
For example, the following request creates a new profile for underwriters.

POST /admin/v1/uw-authority-profiles

{
"data": {
"attributes": {
"name": "Underwriter 3"
}
}
}

Modifying authority profiles

You can use the following endpoints to manage authority profiles:
• PATCH /admin/uw-authority-profiles/{uwAuthorityProfileId}
• DELETE /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}
The only field on an authority profile that you can PATCH is the description.
For example, suppose the profile created in the previous example has an id of pc:112. The following request modifies
its description.

PATCH /admin/v1/uw-authority-profiles/pc:112

{
"data": {
"attributes": {
"description": "Profile 3 for underwriters"
}
}
}

The following request deletes profile pc:112:

DELETE /admin/v1/uw-authority-profiles/pc:112

<no request body>

Authority profile grants

Cloud API provides endpoints to query for, create, and modify and delete grants.

Querying for grants

To retrieve information about grants, use the following endpoints:
• GET /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}/grants
• GET /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}/grants/{grantId}
For example, the following request retrieves one of the grants for underwriting authority profile pc:agent1.
GET /admin/v1/uw-authority-profiles/pc:agent1/grants/pc:SdRrdafrc_csBc6qMX2Wp

456 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"data": {
"attributes": {
"approveAnyValue": false,
"comparator": {
"code": "Monetary_LE",
"name": "At most (monetary)"
},
"id": "pc:SdRrdafrc_csBc6qMX2Wp",
"issueType": {
"code": "HOPCondoCovALimit",
"displayName": "HOP: Condo Coverage A limit value"
},
"moneyValue": {
"amount": "200000",
"currency": "usd"
},
"valueType": "money"
},
...

Creating grants
Use the following endpoint to create a new grant for an existing underwriting authority profile:
• POST /admin/v1/uw-authority-profiles/{uwAuthorityProfileId}/grants

The issueType field

For every new grant, you must specify the grant's issueType.
There are two ways you can retrieve a list of existing issue types and their codes: through Cloud API and through
PolicyCenter.
Retrieving issue type codes from Cloud API
From Cloud API, you can use the following endpoint from the Product Definition API:
• GET /productdefinition/v1/reference-data/uw-issue-types
The following is a snippet of the output when executing this endpoint from the base configuration. It includes the
response for two issue types: UWManagerReviewBlocksQuoteRelease and TSTManualMonetaryAmount.

{
"data": [
{
"attributes": {
"checkingSet": {
"code": "Manual",
"name": "Manual"
},
"code": "UWManagerReviewBlocksQuoteRelease",
"comparator": {
"code": "None",
"name": "None"
},
"description": "To be reviewed by underwriting manager, blocking quote release",
"name": "To be reviewed by underwriting manager, blocking quote release",
"valueFormatterType": {
"code": "Unformatted",
"name": "Unformatted"
}
},
},
{

"attributes": {
"checkingSet": {
"code": "Manual",
"name": "Manual"
},
"code": "TSTManualMonetaryAmount",
"comparator": {
"code": "Monetary_LE",
"name": "At most (monetary)"
},
"description": "Test manually triggered issue with monetary amount format",
"name": "Test manually triggered issue with monetary amount format",
"valueFormatterType": {
"code": "MonetaryAmount",
"name": "MonetaryAmount"
}

Users and groups 457

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
...

Retrieving issue type codes from PolicyCenter

You can also retrieve issue type codes directly from PolicyCenter by exporting metadata about the existing
underwriting issues. To do this:
1. In PolicyCenter, navigate to the Utilities screen on the Administration tab. (You must be logged in as a user who
has permission to export admin data.)
2. In the Export Administrative Data column, select Underwriting Issue Types.
3. Click Export.
PolicyCenter generates an XML file with metadata about the underwriting issue types. The code for each issue type is
defined in the <code> tag. The following is a snippet of the output when exporting this data from the base
configuration. It includes the XML for two issue types: UWManagerReviewBlocksQuoteRelease and
TSTManualMonetaryAmount:

<UWIssueType public-id="pc:ScEwfrYMvGZSphmhfSCtk">
<CheckingSet>Manual</CheckingSet>
<Code>UWManagerReviewBlocksQuoteRelease</Code>
<Comparator>None</Comparator>
<Description>To be reviewed by underwriting manager, blocking quote release</Description>
<Name>To be reviewed by underwriting manager, blocking quote release</Name>
<ValueFormatterType>Unformatted</ValueFormatterType>
</UWIssueType>
<UWIssueType public-id="pc:S6FIzWqP5JFpEaPvDURH5">
<CheckingSet>Manual</CheckingSet>
<Code>TSTManualMonetaryAmount</Code>
<Comparator>Monetary_LE</Comparator>
<Description>Test manually triggered issue with monetary amount format</Description>
<Name>Test manually triggered issue with monetary amount format</Name>
<ValueFormatterType>MonetaryAmount</ValueFormatterType>
</UWIssueType>

Note that you cannot have two or more grants in the same authority profile with the same UWIssueType. If you attempt
to add a grant whose UWIssueType is used by an existing grant, you will get a validation error. For example, attempting
to create a second grant of type ChangedProducerOrg results in this error:
"UWIssueTypes on grants must have unique code values. This underwriting authority profile has
more than one grant where the UWIssueType code is 'ChangedProducerOrg'."

Additional required fields

There may be an additional required field based on the valueFormatterType of the underwriting issue type. The
following table identifies the possible valueFormatterType values and the additional require field, if any.

valueFormatterType Additional required field Example

Age integerValue
"integerValue": "22"

Integer integerValue
"integerValue": "22"

MonetaryAmount moneyValue
"moneyValue": {
"amount": "200000",
"currency": "usd"
}

Number decimalValue
"decimalValue": "4"

StateSet stateSetValue
"stateSetValue": {
"inclusionType": "exclusive",
"states": ["CA","OR"]
}

Unformatted none

458 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following sections contain examples of commonly used valueFormatterType values.

Example of an unformatted grant

If an issueType has a valueFormatterType of Unformatted, then there is no required information beyond the
issueType.

For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType
is ChangedProducerOrg. This issue type is unformatted.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
"data": {
"attributes": {
"issueType": {
"code": "ChangedProducerOrg"
}
}
}
}

Example of a MonetaryAmount grant

If an issueType has a valueFormatterType of MonetaryAmount, you must include a moneyValue attribute with an
amount and currency.

For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType
is ClaimTotalIncurred. This issue type is monetary amount, so there is an additional moneyValue attribute that
specifies $200,000 USD.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
"data": {
"attributes": {
"issueType": {
"code": "ClaimTotalIncurred"
},
"moneyValue": {
"amount": "200000",
"currency": "usd"
}
}
}
}

Example of a Number grant

If an issueType has a valueFormatterType of Number, you must include a decimalValue attribute.
For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType
is IncidenceOfClaims. This issue type is decimal, so there is an additional decimalValue attribute that specifies 4.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
"data": {
"attributes": {
"issueType": {
"code": "IncidenceOfClaims"
},
"decimalValue": "4"
}
}
}

Example of a StateSet grant

If an issueType has a valueFormatterType of StateSet, you must include a stateSetValue attribute. This field has
two child fields:
• inclusionType, which must be set to one of these values:

Users and groups 459

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

◦ inclusive (if the value must be within one of the states listed)
◦ exclusive (if the value cannot be within one of the state listed)
• states, which must be a JSON string array of codes from the States typelist
For example, the following request creates a new grant for underwriting authority profile pc:agent1 whose issueType
is PAGargeState. This issue type is StateSet, so there is an additional stateSetValue attribute that specifies the
garage state cannot be California or Oregon.

POST /admin/v1/uw-authority-profiles/pc:agent1/grants

{
"data": {
"attributes": {
"issueType": {
"code": "PAGarageState"
},
"stateSetValue": {
"inclusionType": "exclusive",
"states": ["CA","OR"]
}
}
}
}

Creating authority profiles and grants in a single call

You can create an authority profile and one or more grants for the profile in a single call using request inclusion. For
more information on request inclusion, see “Request and response inclusion” on page 111.
For example, the following call creates an authority profile and two grants.

POST /admin/v1/uw-authority-profiles

{
"data": {
"attributes": {
"name": "Agent 3",
"description": "Profile 3 for agents"
}
},
"included": {
"UWAuthorityGrant": [
{
"attributes": {
"issueType": {
"code": "ChangedProducerOrg"
}
},
"method": "post",
"uri": "/admin/v1/uw-authority-profiles/this/grants"
},
{
"attributes": {
"issueType": {
"code": "ClaimTotalIncurred"
},
"moneyValue": {
"amount": "200000",
"currency": "usd"
}
},
"method": "post",
"uri": "/admin/v1/uw-authority-profiles/this/grants"
}
]
}
}

Modifying grants
You can use the following endpoints to PATCH or DELETE grants:
• PATCH /uw-authority-profiles/{uwAuthorityProfileId}/grants/{grantId}
• DELETE /uw-authority-profiles/{uwAuthorityProfileId}/grants/{grantId}

460 Users and groups

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following request modifies the moneyValue of grant pc:227:

PATCH /admin/v1/uw-authority-profiles/pc:agent1/grants/pc:227

{
"data": {
"attributes": {
"moneyValue": {
"amount": "100000",
"currency": "usd"
}
}
}
}

The following request deletes grant pc:227:

DELETE /admin/v1/uw-authority-profiles/pc:agent1/grants/pc:227

<no request body>

Users and groups 461

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

462 Users and groups

chapter 51

Producers

Producer is a generic term for a third party who connects people and businesses seeking insurance with insurance
companies. Producers often work with multiple insurers and know which one is best for applicant's needs.
There are two data model entities that track the fundamental information for producers: Organization and
ProducerCode.

• An organization represents a business entity. Most organizations in an instance of PolicyCenter are producers.
• A producer code is a unique alphanumeric id assigned to a producer. Producer codes are also assigned to policies to
identify the producer associated with the policy.
For a complete description of the functionality of organizations and producer codes in PolicyCenter, see the
Application Guide.
Cloud API provides support for both organization and producer codes. This topic identifies how to query for, create,
and modify them.

Organizations
In PolicyCenter, an organization represents a business entity. Typically:
• There is one organization that represents the insurer itself. (In the bootstrap data, this is the "Enigma Fire &
Casualty" organization.)
• All other organizations represent third-party entity that supports the insurer's business. Most of them are producers,
such as agencies or brokers.

Querying for organizations

Use the following endpoints to query for organizations:
• GET /admin/v1/organizations
• GET /admin/v1/organizations/{organizationId}
For example, the following call retrieves information about organization pc:1.

GET /admin/v1/organizations/pc:1

{
"data": {
"attributes": {
"contact": {
"companyName": "Armstrong and Sons",

Producers 463
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"displayName": "Armstrong and Sons",

"emailAddress1": "[email protected]",
"externalId": "pcext:Si4bMhki5VRx7aw6caZld",
"id": "pc:SJVasoc-ajz4VebEgoTD3",
"primaryAddress": {
"addressLine1": "610 Fifth Avenue",
"addressType": {
"code": "business",
"name": "Business"
},
"city": "Indianapolis",
"country": "US",
"description": "Work address",
"displayName": "610 Fifth Avenue, Indianapolis, IN 46201",
"id": "pc:S6eYG2634my1MQ3gLog9r",
"postalCode": "46201",
"state": {
"code": "IN",
"name": "Indiana"
}
},
"primaryPhone": "317-333-5900",
"primaryPhoneType": {
"code": "work",
"name": "Work"
},
"subtype": {
"code": "Company",
"name": "Company"
},
"workPhone": {
"displayName": "317-333-5900",
"number": "3173335900"
}
},
"displayName": "Armstrong and Company",
"groupLoadFactor": 100,
"groupSecurityZone": {
"displayName": "Western Region",
"id": "pc:SvYBVwzYpDJDEdrvsB_i2"
},
"groupSupervisor": {
"displayName": "External Admin",
"id": "pc:SbH5QuzhuuytAzZEITXp7",
"type": "User",
"uri": "/admin/v1/users/pc:SbH5QuzhuuytAzZEITXp7"
},
"id": "pc:1",
"name": "Armstrong and Company",
"producerStatus": {
"code": "Active",
"name": "Active"
},
"rootGroup": {
"displayName": "Armstrong and Company",
"id": "pc:SZYG2v5zDZCJMWCoiSlFi"
},
"type": {
"code": "agency",
"name": "Agency"
}
},
...

Creating organizations
Use the following endpoint to create an organization:
• POST /admin/v1/organizations

Minimum creation criteria

You must specify the following fields:
• name: The organization's name
• type: The organization type, which must be a typecode from the BusinessType typelist, such as agency or other.
◦ If the organizations type is agency, broker, or mga, then producerStatus is also required. It must be a
typecode from the ProducerStatus typelist, such as Active or Terminated.
◦ Each instance of PolicyCenter can have only one organization whose type is insurer. If an insurer organization
already exists (as it does in the bootstrap data), you cannot create a second one.

464 Producers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following request creates a new producer agency organization:

POST /admin/v1/organizations

{
"data": {
"attributes": {
"name": "Floodzone Specialists",
"type": {
"code": "agency"
},
"producerStatus": {
"code": "Active"
}
}
}
}

Updating organizations
Use the following endpoint to modify an organization:
• PATCH /admin/v1/organizations
For example, the following request sets the security zone for producer organization pc:202 to security zone pc:SR3:

PATCH /admin/v1/organizations/pc:202

{
"data": {
"attributes": {
"groupSecurityZone": {
"id": "pc:SR3"
}
}
}
}

Cloud API does not support DELETEing organizations.

Producer codes
A producer code is a unique alphanumeric id assigned to a producer. Producer codes are also assigned to policies to
identify the producer associated with the policy.
For example, the producer Allrisk Insurance may have a producer code of AI-50701. Whenever a policy is issued that
must be associated with Allrisk Insurance, the policy is given the producer code AI-50701.
A producer may have multiple producer codes so that a given policy can be associated with a specific section of the
producer's business or a specific tier. For example, Armstrong and Company could have the following producer codes:
• 100-002541 - For Armstrong premier clients
• 501-002542 - For Armstrong's Los Angeles branch
• 501-002543 - For Armstrong's San Diego branch
• 501-002544 - For Armstrong Professional Liability Services
• 501-002545 - For Armstrong Employer Services
• 501-002546 - For Armstrong Caymen Captive Services
A policy associated with Armstrong and Company for premier clients would have a producer code of 100-002541. A
policy associated with Armstrong and Company's Professional Liability Services would have a producer code of
501-002544.

Querying for producer codes

There are several endpoints that retrieve producer code information. Most of them are in the Admin API, but there is
one in the Account API. The following table summarizes them.

Producers 465
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

API Endpoint Description

Account GET /account/v1/producer-codes Returns only the producer
codes available to the caller.
Omits producer codes that
the caller cannot use (such as
producer codes that are
inactive or that are not
available to the specific
caller).
Admin GET /admin/v1/producer-codes Returns all producer codes,
regardless of their status.
Admin GET /admin/v1/organizations/{organizationId}/producer-codes Returns all producer codes for
a given organization.
Admin GET /admin/v1/producer-codes/{producerCodeId} Returns information about a
specific producer code.

For example, the following call retrieves information about all producer codes using the Admin API endpoint:

GET /admin/v1/producer-codes

{
"count": 25,
"data": [
{
"attributes": {
"branch": {
"branchCode": "301",
"displayName": "Minneapolis Branch UW",
"id": "pc:S17f59YeYbDQEVkdUiua9"
},
"code": "301-008578",
"description": "ACV Property Insurance",
"displayName": "301-008578",
"id": "pc:16",
"organization": {
"displayName": "ACV Property Insurance",
"id": "pc:4",
"type": "Organization",
"uri": "/admin/v1/organizations/pc:4"
},
"producerStatus": {
"code": "Active",
"name": "Active"
}
},
...

The following call retrieves information about the producer codes for organization pc:1.
GET /admin/v1/organizations/pc:1/producer-codes

{
"count": 6,
"data": [
{
"attributes": {
"branch": {
"branchCode": "501",
"displayName": "Los Angeles Branch UW",
"id": "pc:SKLwZJB_J2trSnepw0UsV"
},
"code": "100-002541",
"description": "Armstrong (Premier)",
"displayName": "100-002541",
"id": "pc:6",
"organization": {
"displayName": "Armstrong and Company",
"id": "pc:1",
"type": "Organization",
"uri": "/admin/v1/organizations/pc:1"
},
"producerStatus": {
"code": "Active",
"name": "Active"
}

466 Producers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
...

Creating producer codes

Use the following endpoint to create a producer code:
• POST /admin/v1/producer-codes endpoint.

Producer roles
In PolicyCenter, a producer can have one or more users who are able to log on to PolicyCenter and execute work on
behalf of the insurer, such as creating accounts or quoting submissions for policies that the producer will help to
service.
Typically, users that work for producers do not have the same range of capabilities as a user who works for the insurer.
PolicyCenter uses roles to define what a user can and cannot do. A role is a set of system permissions that define user
capabilities, such as "create account" or "quote job".
Roles are not associated with organizations (producers). Rather, they are associated with producer codes. When you
create a producer code, you must specify the id of one or more roles. Users who work for the producer are then
associated with one or more producer codes. This defines what each producer user is capable of doing.

Minimum creation criteria

When you create a producer code, you must specify:
• code: The alphanumeric id of the code
• id: The id of the producer organization
• roles: An array of one or more roles. Each member of the ray specifies one role by its id.
For example, the following request creates a new producer code 301-008578 for producer pc:4 with the role of
"producer".

POST /admin/v1/producer-codes

{
"data": {
"attributes": {
"code": "301-008579",
"organization": {
"id": "pc:4"
},
"roles": [
{
"id": "producer"
}
]
}
}
}

Updating producer codes

Use the following endpoint to modify an existing producer code:
• PATCH /admin/v1/producer-codes/{producerCodeId}
For example, the following request sets the appointment date (the date the code came into effect) for producer code pc:
664.
PATCH /admin/v1/producer-codes/pc:664

{
"data": {
"attributes": {
"appointmentDate": "2022-07-09"
}

Producers 467
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

Managing producer codes for users and groups

By default, PolicyCenter users who have sufficient permission to work on policies can work on any policy in the
database. PolicyCenter can also restrict a user's access to only the policies with a certain set of producer codes. This
feature is known as producer code security.
Producer code security lets you associate specific producer codes with a group or with a user. When a user is subject to
producer code security, they can only interact with policies whose producer code is associate with them directly or with
a group they belong to.
For more information on producer code security, see the Application Guide.
You can manage a user's producer codes and a group's producer codes through Cloud API.

The UserProducerCode and GroupProducerCode endpoints

Users and producer codes are tracked as separate User and ProducerCode entities. There is a third entity,
UserProducerCode, whose purpose is to track information about one association between a user and a producer code.

Similarly, groups and producer codes are tracked as separate entities. The GroupProducerCode is a third entity that
tracks information about one association between a group and a producer code.
When you call an endpoint that ends with "/{userId}/producer-codes " or "/{groupId}/producer-codes ", you
are retrieving, creating, or modifying instances of UserProducerCode or GroupProducerCode. Note the following:
• The id field in a UserProducerCode/GroupProducerCode instance is the id of the association.
• When you create or delete a UserProducerCode/GroupProducerCode instance, you are not creating or deleting
producer codes. You are only creating or deleting associations between users or groups and producer codes.
The UserProducerCode and endpoints can be used only on users that are subject to producer code security.

Querying for user and group producer codes

To retrieve information about a user's producer codes, use the following endpoints:
• GET /admin/v1/users/{userId}/producer-codes
• GET /admin/v1/users/{userId}/producer-codes/{producerCodeId}
To retrieve information about a group's producer codes, use the following endpoints:
• GET /admin/v1/group/{groupId}/producer-codes
• GET /admin/v1/group/{groupId}/producer-codes/{producerCodeId}
For example, the following is the snippet of the response payload when retrieving producer codes for user pc:305.
GET /admin/v1/users/pc:305/producer-codes

{
"count": 1,
"data": [
{
"attributes": {
"id": "pc:707",
"producerCode": {
"displayName": "301-008578",
"id": "pc:535"
},
"roles": [
{
"displayName": "Producer Code - Submissions",
"id": "producercode_submission",
"type": "Role",
"uri": "/admin/v1/roles/producercode_submission"
}
]

468 Producers
 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
...

Similarly, the following is the snippet of the response payload when retrieving producer codes for group pc:669:

GET /admin/v1/users/pc:669/producer-codes

{
"count": 1,
"data": [
{
"attributes": {
"branch": {
"branchCode": "301",
"displayName": "Minneapolis Branch UW",
"id": "pc:SsUrnb0oJPcQaFYvQOGH4"
},
"code": "301-008578",
"description": "ACV Property Insurance",
"id": "pc:16",
"producerCode": {
"displayName": "301-008578",
"id": "pc:16"
},
"producerStatus": {
"code": "Active",
"name": "Active"
}
},
...

Associating producer codes with users and groups

Creating an association
To associate a producer code with a user or group, use the following endpoint:
• POST /admin/v1/users/{userId}/producer-codes
• POST /admin/v1/groups/{groupId}/producer-codes
The only required field is the id of the producer code to be associated with the user or group.
For example, the following request associates producer code pc:535 with user pc:310.

POST /admin/v1/users/pc:310/producer-codes

{
"data": {
"attributes": {
"producerCode": {
"id": "pc:535"
}
}
}
}

Similarly, the following request associates producer code pc:17 with group pc:669.

POST /admin/v1/groups/pc:669/producer-codes

{
"data": {
"attributes": {
"producerCode": {
"id": "pc:17"
}
}
}
}

Deleting an association
To remove the association between a producer code and a user or group, use the following endpoint:
• DELETE /admin/v1/users/{userId}/producer-codes/{producerCodeId}

Producers 469
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• DELETE /admin/v1/groups/{groupId}/producer-codes/{producerCodeId}
For example, the following request disassociates producer code pc:535 with user pc:310.

DELETE /admin/v1/users/pc:310/producer-codes/pc:535

<no request body>

Similarly, the following request disassociates producer code pc:17 with group pc:669:

DELETE /admin/v1/groups/pc:669/producer-codes/pc:17

<no request body>

Exposing producer codes to external users

By default, producer codes are not exposed to external users. An external user is a user that is not in the PolicyCenter
database, such as an account holder.
In the PolicyCenter config.xml configuration file, the ExternallyVisibleProducerCodes parameter can be used to
expose one or more producer codes to external users. The parameter accepts a comma-separated list of producer codes,
in string format:

<param name="ExternallyVisibleProducerCodes" value="ProdCode1,ProdCode2"/>

For details on PolicyCenter configuration, see the Configuration Guide.

470 Producers
chapter 52

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 PolicyCenter, see the Application
Guide.
The endpoints for working with security zones are available in Cloud API for ClaimCenter, Cloud API for
PolicyCenter, and Cloud API for BillingCenter. They are not available in Cloud API for ContactManager.

Querying for security zones

Use the following endpoints to query for security zones:
• GET /admin/v1/security-zones
• GET /admin/v1/security-zones/{securityZoneId}
For example, the following request retrieves information about security zone "default_data:1".
GET /admin/v1/security-zones/default_data:1

{
"data": {
"attributes": {
"description": "Default Security Zone",
"displayName": "Default Security Zone",
"id": "default_data:1",
"name": "Default Security Zone"
},
...

Security zones 471

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Creating security zones

Use the following endpoint to create a security zone:
• POST /admin/v1/security-zones
The only required field is the zone name.
For example, the following request creates a new security zone named "Cloud API security zone".
POST /admin/v1/security-zones/

{
"data": {
"attributes": {
"name": "Cloud API security zone"
}
}
}

Note that there are differences between security zone functionality in the base configuration of the different
applications.
• In ClaimCenter and BillingCenter, users can create security zones. This is done from the Admin tab's Security Zones
screen in the Users & Security group.
• In PolicyCenter, users cannot create security zones. (There is no Security Zones screen.) However, users can import
security zones through the Import Administrative Data screen in the Utilities group.

Modifying and deleting security zones

Modifying security zones
Use the following endpoints to modify a security zone:
• PATCH /admin/v1/security-zones/{securityZoneId}
For example, the following request modifies security zone xc:111.

PATCH /admin/v1/security-zones/xc:111

{
"data": {
"attributes": {
"description": "Security zone created using Cloud API"
}
}
}

Note that there are differences between security zone functionality in the base configuration of the different
applications.
• In ClaimCenter and BillingCenter, users can edit security zones. This is done from the Admin tab's Security Zones
screen in the Users & Security group.
• In PolicyCenter, users cannot edit security zones.

Deleting security zones

In ClaimCenter, use the following endpoints to delete a security zone:
• DELETE /admin/v1/security-zones/{securityZoneId}
For example, in ClaimCenter, the following request deletes security zone xc:111.

DELETE /admin/v1/security-zones/xc:111

<no request body>

472 Security zones

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

In PolicyCenter and BillingCenter, users cannot delete security zones, either through the user interface or through
Cloud API. The DELETE /security-zones/{securityZoneId} endpoint is exposed in Cloud API for PolicyCenter
and Cloud API for BillingCenter. But if you attempt to use it, Cloud API returns the following error. This is true even
for the super user "su", who is not bound by permissions.

{
"status": 403,
"errorCode": "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 473

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

474 Security zones

chapter 53

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 475

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"zoneType": {
"code": "state",
"name": "State"
}
},
...
}

Here’s another example, this time with a broader search. This example will return a list of all provinces in Canada:

GET /admin/v1/geographic-zones?filter=country:eq:CA&filter=zoneType:eq:province

{
"data": [
{
"attributes": {
"code": "BC",
"country": {
"code": "CA",
"name": "Canada"
},
"displayName": "BC",
"id": "CA:SNAwbKcTW2uiIdv0FGcd0",
"name": "BC",
"zoneType": {
"code": "province",
"name": "Province"
}
},
},
{
"attributes": {
"code": "NL",
"country": {
"code": "CA",
"name": "Canada"
},
"displayName": "NL",
"id": "CA:SGVv0UjgB0_EJCt80VU1K",
"name": "NL",
"zoneType": {
"code": "province",
"name": "Province"
}
},
...

476 Geographic zones

chapter 54

Typelist metadata

There may be situations where a caller application needs to retrieve information about PolicyCenter 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 PolicyCenter.
• 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 477
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The typekeyFilter query parameter

When using the /typelists/{typelistName} endpoint, if the typelist is associated with a typekey filter, you can limit
the results to only those typecodes that have a given relationship with the typekey filter. You can specify three types of
criteria:
• /typelists/{typelistName}?typekeyFilter=category:in:typecodeList
◦ Returns all typekeys whose categories array contains at least one of the listed typecodes
• /typelists/{typelistName}?typekeyFilter=category:cn:typecodeList
◦ Returns all typekeys whose categories array contains all of the listed typecodes
• /typelists/{typelistName}?typekeyFilter=category:ni:typecodeList
◦ Returns all typekeys whose categories array does not contain any of the listed typecodes
The typecode list must be specified as:
relatedTypelist1.Typecode1,relatedTypelist2.Typecode2,...

where:
• relatedTypelistX is the name of the Nth related typelist.
• TypecodeX is the Nth typecode to use as a filter

Examples
No filter parameter
This call does not use the typekeyFilter query parameter. Therefore, it retrieves all typecodes in the
ActivityCategory typelist:

GET /common/v1/typelists/ActivityCategory
Associated with one category
This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of
General:
GET /common/v1/typelists/ActivityCategory?typekeyFilter=category:in:ActivityType.general
Associated with any of the listed categories
This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of
either General or Approval:
GET /common/v1/typelists/ActivityCategory?
typekeyFilter=category:in:ActivityType.general,ActivityType.approval

Associated with all of the listed categories

This call retrieves only the typecodes in the ActivityCategory typelist that are associated with the ActivityType of
both General and Approval: (Note that, in the base configuration, there are no typecodes that meet this criteria.)
GET /common/v1/typelists/ActivityCategory?
typekeyFilter=category:in: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:

GET /common/v1/typelists/ActivityCategory?
typekeyFilter=category:ni:ActivityType.general,ActivityType.approval

478 Typelist metadata

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Tutorial: Query for typelist metadata

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more
information, see “Tutorial: Set up your Postman environment” on page 32.
In this tutorial, you will query for all typecodes in the VehicleType typelist. You will then use a typekey filter to query
for all vehicle types that are related to the personal auto policy line.

Tutorial steps
1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
2. Specify Basic Auth authorization using user su and password gw.
3. Enter the following call and click Send:
• GET http://localhost:8180/pc/rest/common/v1/typelists/VehicleType
4. The response payload contains all non-retired vehicle types. Verify that the first three codes in the payload are:
Commercial, PP, PublicTransport.)
5. Modify the call by adding the following query parameter to the end, and then click Send:
• ?typekeyFilter=category:cn:PolicyLine.PersonalAutoLine
6. The response payload now contains only vehicle types relevant to personal auto policies. Verify that there are
only two codes in the payload now: auto, other. (Commercial, PP, and PublicTransport no longer appear
because they are not valid vehicle types for a personal auto policy.)

Typelist metadata 479

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

480 Typelist metadata

chapter 55

Batch processes

The PolicyCenter 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 481

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Querying for batch process information

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

The BatchProcess resource

Cloud API manages batch process information using the BatchProcess resource. This resource contains the following
fields:

Field Description Returned By Default?

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

The information in the response varies based on whether the batch process has completed, is running, or has never been
run.

Response for a completed batch process

The following is an example of querying for the Activity Escalation batch process after the batch process has been run.
Note that the status object includes the dateCompleted field, and there is no opsExpected field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
"data": {
"attributes": {
"distributed": false,
"status": {
"dateCompleted": "2022-09-19T17:30:00.021Z",
"dateCreated": "2022-09-19T17:30:00.003Z",
"failedOps": 0,
"opsCompleted": 0,
"serverId": "55d109613ac9",
"startDate": "2022-09-19T17:30:00.011Z",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
}
},
...

482 Batch processes

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Response for a running batch process

The following is an example of querying for the Activity Escalation batch process while the batch process is running.
Note that the status object includes the opsExpected field, and there is no dateCompleted field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
"data": {
"attributes": {
"distributed": false,
"status": {
"dateCreated": "2022-09-19T17:30:00.003Z",
"failedOps": 0,
"opsCompleted": 0,
"opsExpected": 0,
"progress": "1 out of 3",
"serverId": "55d109613ac9",
"startDate": "2022-09-19T17:30:00.011Z",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
}
},
...

Response for a batch process that has never been run

The following is an example of querying for the Activity Escalation batch process before the first iteration of the batch
process. Note that the status object includes only the failureReason field and the type field.

GET /systemtools/v1/batch-processes/ActivityEsc

{
"data": {
"attributes": {
"distributed": false,
"status": {
"failureReason": "This batch process type has never run",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
}
},
...

Managing batch processes

You can use Cloud API endpoints to start and stop batch processes.

Starting a batch process

Use the following endpoint to start a batch process:
• POST /systemtools/v1/batch-processes/{batchProcessType}/start
The POST does not require a request body. However, if the batch process has arguments and Cloud API supports those
arguments, you can add an optional request body to specify arguments. For more information, see “Starting a batch
process with arguments” on page 484.
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 483

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

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

Example of starting a batch process

The following is an example of the response to starting the Activity Escalation batch process.

POST /systemtools/v1/batch-processes/ActivityEsc/start

RESPONSE:
{
"data": {
"attributes": {
"distributed": true,
"processId": 4055,
"status": {
"dateCreated": "2022-09-19T17:54:19.929Z",
"failedOps": 0,
"opsCompleted": 0,
"serverId": "55d109613ac9",
"type": "ActivityEsc"
},
"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
},
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},
...

Starting a batch process with arguments

In PolicyCenter, 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>,
...
}

484 Batch processes

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}
}

For example, the PurgeAsyncApiRequests object has one integer field, purgeDaysOld. The following request starts
the Purge Async API Requests batch process and passes in a purgeDaysOld value of 3.

POST /systemtools/v1/batch-processes/PurgeAsyncApiRequests/start

{
"data": {
"attributes": {
"purgeAsyncApiRequests": {
"purgeDaysOld": 3
}
}
}
}

Note that the structure of the JSON object varies based on the datatype of the arguments. For example, the following is
an example of starting the Database Consistency Check batch process with arguments. Note that one of the arguments,
tableNames, is an array, whereas the other, description, is a string.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
],
"description": "Start of Q1 maintenance"
}
}
}
}

If the attributes section contains any property with an unexpected name, Cloud API returns a 400 error.

Custom batch processes with arguments

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

Stopping a batch process

Use the following endpoint to stop a batch process:
• POST /systemtools/v1/batch-processes/{batchProcessType}/stop
The POST does not require a request body.
The response to the /stop endpoint includes the wasStopped field. This field is set to true if the batch process was
stopped while the batch process was executing. It is set to false if the batch process was not running when the /stop
request was made.
For example, the following request stops the Activity Escalation batch process:
POST /systemtools/v1/-batch-processes/ActivityEsc/stop

RESPONSE:
{
"data": {
"attributes": {
"distributed": true,
"status": {
"dateCompleted": "2022-09-19T18:00:51.304Z",
"dateCreated": "2022-09-19T18:00:51.291Z",
"failedOps": 0,
"opsCompleted": 0,
"serverId": "55d109613ac9",
"startDate": "2022-09-19T18:00:51.298Z",
"type": "ActivityEsc"
},

Batch processes 485

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"type": {
"code": "ActivityEsc",
"name": "Activity Escalation"
},
"wasStopped": true,
"workQueueStatus": {
"numActiveExecutors": 1,
"numActiveWorkItems": 0
}
},

486 Batch processes

chapter 56

Database consistency checks

A database consistency check (DBCC) is a check that PolicyCenter 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 PolicyCenter 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 PolicyCenter 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 PolicyCenter. 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 487

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

If you run the DBCCs only for the cc_activity table (but for all check types), then the description is:

Tables: cc_activity; Checks: All.

If you run only the assignment check DBCCs (on all tables), then the description is:

Tables: All.; Checks: assignmentcheck.

If you run only the assignment check DBCCs for only the cc_activity table, then the description is:

Tables: cc_activity.; Checks: assignmentcheck.

Running DBCCs
Use the following endpoint to run database consistency checks:
• POST /systemtools/v1/batch-processes/{batchProcessType}/start
The value of {batchProcessType} must be: DBConsistencyCheck.

Running all DBCCs

To run all DBCCs, execute the request with no request body. PolicyCenter runs all DBCCs on all tables for all check
types.
The following request runs all DBCCs.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

<no request body>

Running DBCCs for a specific set of tables

To limit a DBCC run to a single set of tables, you must include a request body. The body must contain a
dbconsistencycheck property with a tableNames array that names the tables.

For example, the following request runs all DBCCs for the cc_activity and cc_address tables.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
]
}
}
}
}

Note that PolicyCenter 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, PolicyCenter ignores the name.

Running DBCCs for a specific set of check types

To limit a DBCC run to a single set of check types, you must include a request body. The body must contain a
dbconsistencycheck property with a checkTypes array that names the check types.

For example, the following request runs all DBCCs whose check type is either 0lengthstringcheck or
assignmentcheck.

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {

488 Database consistency checks

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"attributes": {
"dbconsistencycheck": {
"checkTypes": [
"0lengthstringcheck",
"assignmentcheck"
]
}
}
}
}

Note that PolicyCenter 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, PolicyCenter 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. PolicyCenter prepends the user-provided description to its own generated
description.
For example, the following request runs all DBCCs with a description of "Start of Q1 maintenance".

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"description": "Start of Q1 maintenance"
}
}
}
}

The description stored in the database is:

"description": "Start of Q1 maintenance; Tables: All.; Checks: All.",

Combining Run DBCC criteria

You can combine multiple DBCC criteria in a single call.
For example, the following request runs all DBCCs for the cc_activity and cc_address tables whose check type is
either 0lengthstringcheck or assignmentcheck, and it adds a custom description of "Start of Q1 maintenance".

POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"tableNames": [
"cc_activity",
"cc_address"
],
" checkTypes ": [
"0lengthstringcheck",
"assignmentcheck"
],
"description": "Start of Q1 maintenance"
}
}
}
}

Running a previously run DBCC

A DBCC can fail due to database consistency errors. After you have fixed the errors, you may want to rerun the DBCC
to ensure all errors have been fixed. You can do this through Cloud API by including a request body with a rerunKey
attribute. This attribute must be set to the Key value provided by the GET /systemtools/v1/database-consistency-

Database consistency checks 489

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

checks endpoint. Note that the Key value is expressed as an integer. For more information on this endpoint, see
“Querying for DBCC run information” on page 490.
For example, suppose you ran a DBCC that had errors. The GET /systemtools/v1/database-consistency-checks
endpoint identifies the Key for this run is 21. You have fixed the errors and now want to rerun the same DBCC. The
following request does this.
POST /systemtools/v1/batch-processes/DBConsistencyCheck/start

{
"data": {
"attributes": {
"dbconsistencycheck": {
"rerunKey": 21
}
}
}
}

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

490 Database consistency checks

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

DBCC is complete? Number of errors Response

Yes 1 or more A report of the errors and only the errors.
Yes 0 The following error message: "The count of consistency checks with errors
in this run is zero. To download the full report, retry the
request without the 'errorsOnly' query parameter."
No n/a The following error message: "Cannot generate the report because the
consistency check run '{0}' is still running. Retry after the
batch process is finished."

Note that when you run a DBCC using the POST /systemtools/v1/batch-processes/DBConsistencyCheck/start
endpoint, the response does not include the dbccId value. This is because, for most batch processes, the results are not
stored in the database. Therefore, there is no "ID value" that can be provided for all batch process types. If you want to
run a DBCC and then download the report through Cloud API, you must execute three calls:
1. Execute the batch process with POST /systemtools/v1/batch-processes/DBConsistencyCheck/start
2. Retrieve the dbccID value with GET /systemtools/v1/database-consistency-checks
3. Get the DBCC report with GET /systemtools/v1/database-consistency-checks/{dbccId}/report

Database consistency checks 491

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

492 Database consistency checks

chapter 57

Personal data destruction

Note: The data destruction features described in this topic provide a set of features that help enable insurers to
comply with some of their data destruction requirements. These requirements may be driven by insurers’
policies and practices, as well as by their interpretation of various regulatory requirements. Such regulatory
requirements may come from, for example, the European Union General Data Protection Regulation (GDPR) or
the New York State Cybersecurity Requirements for Financial Services Companies law.
PolicyCenter supports destruction of some kinds of data. Destruction can mean either purging the data completely from
the database or it can mean obfuscating data, making the original contents permanently unreadable.
Obfuscation might be required if destroying the data affects contacts that cannot be destroyed. For example, purging
user data for a former employee could affect hundreds or even thousands of contacts. Therefore it makes more sense to
obfuscate the data for the user and leave the other data alone.
Guidewire provides several Cloud API endpoints that obfuscate or purge personally identifiable information (PII). Note
that while the terms destruction and destroy encompass both obfuscating and purging, in Cloud API the destroy
endpoints perform a purge.
PolicyCenter provides the following endpoints for data destruction:
• POST /admin/v1/users/{userId}/obfuscate
• POST /common/v1/contacts/{contactId}/destroy
• POST /account/v1/accounts/{accountId}/destroy
• POST /policy/v1/policies/{policyId}/destroy
The following supporting endpoints are also discussed in this topic:
• POST /common/v1/contacts/{contactId}/do-not-destroy
• POST /common/v1/search/contacts
Note: For detailed information on data destruction, refer to the following resources:

• Application Guide
• Configuration Guide

API entity destruction overview

The type of data destruction available varies based on the entity. The following table describes the entities that can be
destroyed through Cloud API.
Personal data destruction 493
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Entity Destruction Type Immediacy

User Obfuscate Immediate

Contact Purge Work queue process

Account Purge Immediate

Policy Purge Immediate

System configuration
In the PolicyCenter base configuration, data destruction is not enabled by default. If you attempt to run the obfuscate or
destroy endpoints you’ll receive one or both of the following errors:
Cannot purge 'Node = [C000000001 NotPurgeable]' because the DoNotDestroy flag is set

Cannot purge 'Node = [C000000001 NotPurgeable]' because PersonalDataDestruction plugin

disposition for node is MUST_NOT_DESTROY"

To enable data destruction, you must update certain configuration parameters. For complete details on these settings,
refer to the Configuration Guide

Obfuscating user data

Obfuscation is a form of data destruction that permanently overwrites data in certain fields with randomized data (such
as GUIDs). These actions cannot be undone.
Note: This process differs from “Obfuscating response data”. Obfuscating response data leaves the data intact
in the database and obfuscates only the data displayed in the response. The endpoints described here obfuscate
at the database level, permanently overwriting the data in the database.
PolicyCenter provides an endpoint to obfuscate user data. The user must be inactive (the active attribute must be set
to false) for the user to be obfuscated.
The following endpoint obfuscates a user’s data:
• POST /admin/v1/users/{userId}/obfuscate
This example demonstrates obfuscating PII for user pc:120.
Before obfuscating, if you retrieve information for user pc:120 you’ll see something like this:

{
"data": {
"attributes": {
"active": false,
"displayName": "Ronald Rutherford",
"externalUser": false,
"firstName": "Ronald",
"id": "pc:120",
"lastName": "Rutherford",
"username": "rrutherford",
…
},

You can then use the following endpoint to obfuscate the record for user pc:120:

POST/admin/v1/users/pc:120/obfuscate

No request body is required for this POST action.

The response shows that fields with PII, such as displayName and userName, have all been overwritten:

{
"data": {

494 Personal data destruction

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"attributes": {
"active": false,
"displayName": "71633b5ed0dba332f1f4b645682c6d 71633b5ed0dba332f1f4b645682c6d",
"externalUser": false,
"firstName": "71633b5ed0dba332f1f4b645682c6d",
"id": "pc:120",
"lastName": "71633b5ed0dba332f1f4b645682c6d",
"username": "80aef0777aa07c8cf79b454bab2df5",
…
},

After obfuscation, you can still retrieve the user record based on ID, but there is no way to personally identify that user.

Destroying a contact
Destroying, or purging, is a form of data destruction that completely removes contact data and policy or account data
from PolicyCenter. There can be multiple objects associated with the contact, account, or policy that are also removed
as they are detected by traversing the entity domain graph.

Search for contacts

Before destroying any data, you first need to find the record for the contact whose data you want to destroy. You can do
this using the following endpoint:
In the request body, you must include at least one of these fields:
• For a person:
◦ firstName and lastName
◦ taxId
• For a company:
◦ companyName
◦ phoneNumber
This example retrieves the user named John Smith:
Command

POST /common/v1/search/contacts

Request

{
"data": {
"attributes": {
"lastName": "Smith",
"firstName": "John"
}
}
}

This example retrieves the company named Wright Construction:

Request

{
"data": {
"attributes": {
"companyName": "Wright Construction"
}
}
}

Destroy the contact

When you call the endpoint to destroy a contact, the contact is not destroyed immediately. Instead, the contact is placed
in the DestroyContactForPersonalData work queue, and continues to exist until a scheduled batch process is run to

Personal data destruction 495

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

destroy all data in the queue. See the Administration Guide for information on the DestroyContactForPersonalData
work queue.
Use the following endpoint to destroy a contact:
• POST /common/v1/contacts/{userId}/destroy
The following example destroys the contact with user ID pc:234.
Command

POST /common/v1/contacts/pc:234/destroy

The request contains only the ID of the requester. This requester ID does not have to match the ID of a user in
PolicyCenter.
Request

{
"data": {
"attributes": {
"requesterId": "5678"
}
}
}

Retrieve contacts scheduled for destruction

You can retrieve a list of contacts that are scheduled to be destroyed but have not yet been run through the batch
process. Use the following endpoints to retrieve contacts that are scheduled for destruction:
• GET /systemtools/v1/personal-data-destruction-requests
• GET /systemtools/v1/personal-data-destruction-requests/pc:999
For example:
Command

GET /systemtools/v1/personal-data-destruction-requests

Response

{
"data": [
{
"attributes": {
"allRequestsFulfilled": false,
"destructionRequestStatus": {
"code": "Unprocessed",
"name": "Unprocessed"
},
"displayName": "PersonalDataDestructionRequest pc:234",
"id": "pc:234",
"requesterIds": [
"5678"
]
},
...

You can also filter based on the ID of the destruction requester:

GET /systemtools/v1/personal-data-destruction-requests?filter=requeterIds:in:5678

Destroying an account
When you run the destroy endpoint on an account, destruction happens immediately. This differs from running the
destroy endpoint on a contact, where the actual destruction of data doesn’t happen until a scheduled batch process has
run.

496 Personal data destruction

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Use the following endpoint to destroy an account:

• POST /account/v1/accounts/{accountId}/destroy
This example immediately removes account pc:987 from the database:
Command

POST /account/v1/accounts/pc:987/destroy

The request contains only the ID of the requester. The requester ID does not have to match the ID of a user in
PolicyCenter.
Request

{
"data": {
"attributes": {
"requesterId": "5678"
}
}
}

Destroying a policy
When you run the destroy endpoint on a policy, destruction happens immediately. This differs from running the destroy
endpoint on a contact, where the actual destruction of data doesn’t happen until a scheduled batch process has run.
Use the following endpoint to destroy a policy:
• POST /policy/v1/policies/{policyId}/destroy
This example immediately removes policy pc:5454 from the database:
Command

POST /policy/v1/policies/pc:5454/destroy

The request contains only the ID of the requester. The requester ID does not have to match the ID of a user in
PolicyCenter.
Request

{
"data": {
"attributes": {
"requesterId": "5678"
}
}
}

Preventing data destruction

You can prevent a specific contact, account, or policy from being destroyed by setting its doNotDestroy attribute to
true. (This attribute is false by default.) For example, if account pc:500 is set to doNotDestroy: true, and account pc:
600 is set to doNotDestroy: false (the default), you can destroy account pc:600 but you cannot destroy account pc:
500.
Use the following endpoints to set the doNotDestroy attribute:
• POST /common/v1/contacts/{contactId}/do-not-destroy
• POST /account/v1/accounts/{accountId}/do-not-destroy
• POST /policy/v1/policies/{policyId}/do-not-destroy

Personal data destruction 497

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Set the doNotDestroy attribute to either true or false in the request body. For example, use the following command and
request to specify that contact pc:234 cannot be destroyed:
Command

POST /common/v1/contacts/pc:234/do-not-destroy

Request

{
"data": {
"attributes": {
"doNotDestroy": true
}
}
}

498 Personal data destruction

chapter 58

Business entity schemas

For some use cases, it’s necessary to have a schema with detailed graph and entity information. For this purpose,
PolicyCenter provides endpoints that retrieve schema information that can be used to navigate the graph structure for
various purposes and to build out custom user interfaces.
The schema endpoints return metadata about the business entities that are exposed by the API (such as Users and
Contacts) as normal JSON schema documents. In addition to standard JSON Schema properties, the schema endpoints
can also return additional application-specific metadata. This additional metadata is returned in the form of x-gw-*
properties.
The topics in this section describe the endpoints and query parameters for retrieving schemas. They also describe
properties that are specific to entity and graph schemas and not found in the standard business schemas (such as
OpenAPI).

Retrieve an entity schema

The entity-schemas endpoints return a complete product schema, or can be filtered to target specific sets of entities.
The information returned is similar to what you would find in the swagger and openapi endpoints, but with additional
metadata. (See “Viewing API definitions” on page 21 for information on the swagger and openapi endpoints.)
Use the following command to retrieve a JSON-formatted entity schema:
GET /common/v1/entity-schemas
To retrieve the schema for a single entity, use the following command:
GET /common/v1/entity-schemas/{entityId}
For example, you can return the schema for the User entity with the following command:

GET /common/v1/entity-schemas/User

The schema returned by the entity-schemas/{entityId} endpoint returns the schema for the specified entity and
other schemas transitively referenced from that entity. In the preceding example, in the base configuration the returned
entity schema would include User, plus related schemas such as UserGroupReference and UserRoleReference.
However, it won’t return the schemas for any child entities. Instead it will return a list of children (if any) in the x-gw-
children property for each entity. (See “Child entities” in “Schema properties usage” on page 506 for more
information.)
To retrieve a specific entity along with the complete schema information for all its children, filter the entity-schemas
endpoint on rootEntity:
Business entity schemas 499
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

GET /common/v1/entity-schemas?filter=rootEntity:eq:{entityId}
Filtering on rootEntity retrieves a more detailed schema than using the entity-schemas/{entityId} endpoint by
traversing the entity graph tree and including all the child entities of the specified entity.

Business entity schema query parameters

The following table includes query parameters that are specific to business entity schemas. For each parameter, a short
description is provided along with possible values. Also listed for each parameter are any other parameters that must be
included in order for the given parameter to be used. See below for detailed descriptions of each.

Parameter Description Values Other parameters

required

editionCode Enriches the schema based on the rules in {editionId} product

the specified product edition.

includeLocalizations Include localization strings in the schema for • {language code} none
all localizable strings for the specified
• {language-region
installed languages.
code}
• *all (all installed
languages)

inlineProductDefinition Include information about coverages, Boolean product

answers, and scheduled items inline in the
schema.

inlineTypelists Include typelist values in the schema. Boolean none

onlyReturnChangedSchemas Return only schema definitions that have Boolean • editionCode

changed between the specified edition and
• product
the base product.

product Return the schema for the specified product • {productId} none
and any non-product specific entities. Use
• null (all non-LOB
null to retrieve only non-product schema
entities)
entities.

editionCode
Use the editionCode query parameter to enrich the schema with additional information based on the rules for that
edition. When fetching the schema with an edition specified, the schema properties are adjusted based on changes that
have been made in that edition, such as to whether coverage options are available or what a field's maximum value can
be. For changes made in the edition that do not have any rule conditions, the associated schema element will be
changed directly. For example, if an integer field has a maximum set to 10000 for a given edition, the schema property
for that field will have "maximum": 10000 added to it. If the change is conditional, it will result in a rule added to the
x-gw-rules schema property. See “Rules” on page 520 for more details.
The product parameter must also be included in the query string, because editions are tied to products. (For more
information on editions, see "Editons for product lines" in "Advanced Product Designer in PolicyCenter".)
• GET /common/v1/entity-schemas?editionCode={editionId}&product={productId}
For example, to retrieve the entity schema for the BaseEditon edition of the PersonalAuto product, use the following
command:

GET /common/v1/entity-schemas?editionCode=BaseEdition&product=PersonalAuto

If the specified edition doesn’t match a valid edition for the requested product, the request will fail.

500 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

To allow for testing of existing products that have been defined with rules but no editions, the edition code BaseEdition
is a valid code for visualized products. In that case, the main template serves as the base edition. The BaseEdition code
is also accepted for cloud-synced installed lines managed via Advanced Product Designer (APD), since APD always
creates a base edition.
To retrieve a list of editions available for a product, use the productdefinition API:
• GET /productdefinition/v1/products/{productId}/editions
See “Product definitions for products” on page 317 for more details on the productdefinition API.

includeLocalizations
The includeLocalizations query parameter includes localized versions of all strings in the schema response. Any
element that can be localized will include an x-gw-localizations property containing localized versions of the
associated schema property. (If no localized version for a given language exists, the value will be provided in the
default language.)
The localized languages that are displayed depend on the value assigned to the parameter. You can retrieve localized
strings for all installed languages (languages in the LangaugeType typelist) by assigning the *all value to the
parameter.
To retrieve localized strings for only specific languages, include the language code as the value. The language code can
be in any of the following formats:
• Language code, such as fr (French).
• Language and region, such as fr-CA (French, Canada) or fr-FA (French, France).
• Language and region with either a hyphen or an underscore. Both fr-CA and fr_CA will return French (Canada)
localized strings.
Note that the value is case-sensitive; you’ll receive an error if the installed language is en_US and you specify en_us.
Only installed languages can be specified. If you set a value to a language that is not installed you’ll receive an error.
The following examples show different options for calling includeLocalizations:
Retrieve localized values for all installed languages:

GET /common/v1/entity-schemas?includeLocalizations=*all

Retrieve localized values for US English:

GET /common/v1/entity-schemas?includeLocalizations=en_US

Retrieve localized values for all versions of French:

GET /common/v1/entity-schemas?includeLocalizations=fr

Retrieve localized values for English and French (Canada):

GET /common/v1/entity-schemas?includeLocalizations=en,fr_CA

For details on the schema structure, see “Localizations” on page 516.

inlineProductDefinition
Setting the inlineProductDefinition query parameter to true will cause information about coverages, answers, and
scheduled items to be inlined into the returned schema. The product parameter must also be included in the query
string.
• GET /common/v1/entity-schemas?inlineProductDefinition=true&product={productId}

Business entity schemas 501

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The top-level properties x-gw-coverages, x-gw-answers, and x-gw-scheduledItems are returned in the schema.
These function as if they were schema property definitions, with a $ref property that references the appropriate
schema definition.
See “Product definition properties” on page 519 for more information.

inlineTypelists
The inlineTypelists query parameter is used to include typelist metadata for each typekey field or term so that
typelist metadata doesn’t need to be fetched separately. Set inlineTypelists to true to enable this feature.
• GET /common/v1/entity-schemas?inlineTypelists=true
See “Choice values” on page 508 for more information and schema examples.

onlyReturnChangedSchemas
This query parameter cannot be used without also specifying the editionCode and product query parameters. If
onlyReturnChangedSchemas is set to true, only schema definitions that have changed between the edition specified
by the editionCode and the base product are returned.
• GET /common/v1/entity-schemas?
editionCode={editionId}&product={productId}&onlyReturnChangedSchemas=true

product
The product query parameter filters the returned schema entities based on the product specified.
GET /common/v1/entity-schemas?product={productId}
If product is set to a non-null value, entities that match the specified product and all non-product specific entities will
be returned. If product is set to null, only non-product-specific entities will be returned. Here are some examples.
Return only non-product specific entities:

GET /common/v1/entity-schemas?product=null

Return entities for the PersonalAuto product:

GET /common/v1/entity-schemas?product=PersonalAuto

If product is used along with the inlineProductDefintion parameter, the product value will be used to determine
which product to use for Job, PolicyLocation, and PolicyLine questions (and anything else that attaches to the product).

ETag support
The business entity schema endpoints support the use of ETags. An ETag response header is returned with every
request. The ETag acts as a checksum of schema content, so it changes depending on which query parameters you use.
Use the ETag with the If-None-Match request header. If this matches the current checksum, you’ll receive a “304 not
modified” response. If it doesn’t match, the request will be processed normally.
ETag is a standard HTTP header. More information can be found by doing an internet search.

CreateSubmissionAttributes schema
When a new submission is generated (such as through a call to POST /job/v1/submissions), the special schema
definition CreateSubmissionAttributes is used. When retrieving the entity schema, the
CreateSubmissionAttributes schema definition is included anytime the Job schema is retrieved. This means that
any results that include the Job schema will also include the schema definition needed to know how to create a
submission.

502 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

For example, the following commands will return the CreateSubmissionAttributes schema:

GET /common/v1/entity-schemas/Job
GET /common/v1/entity-schemas
GET /common/v1/entity-schemas?rootEntity:eq:Job

Response

…
"CreateSubmissionAttributes": {
"description": "Details of the `Submission` job to create",
"properties": {
account": {
"$ref": "#/definitions/SimpleReference",
"description": "A reference to the `Account` that the policy is being created for",
"title": "Account"
},
"baseState": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The state or jurisdiction that the policy is based on",
"title": "Base state",
"x-gw-typelist": "Jurisdiction"
},
"dateQuoteNeeded": {
"description": "The date that a quote for this submission is needed by",
"format": "date",
"nullable": true,
"title": "Date quote needed",
"type": "string"
},
…

Schema properties
The InsuranceSuite business entity schemas are returned as JSON documents using the JSON Schema Draft-7
specification. In addition to standard JSON schema properties, the business entity schemas include a number of
additional schema properties that include metadata about the entities and their representation in APIs and AppEvents.
• “Schema properties overview” on page 503
• “Schema properties usage” on page 506

Schema properties overview

This table provides a list of schema properties specific to business entities. See “Business entity schemas” on page 499
for more information on retrieving these schemas.

Property Description More information

x-gw-actions A list of logical actions that you can take on an entity. This “Cloud API endpoint
encompasses standard HTTP operations on the element or elements” on page 511
collection, as well as custom actions.

x-gw-after Applies to properties of format date or date-time. Indicates a “Date and date-time fields”
date or date-time that the value must be later than. on page 514

x-gw-answers A product definition property that references the answer “Product definition
schema definition. Only available when the properties” on page 519
inlineProductDefinition query parameter is set to
true.

x-gw-before Applies to properties of format date or date-time. Indicates a “Date and date-time fields”
date or date-time that the value must be earlier than. on page 514

Business entity schemas 503

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Property Description More information

x-gw- For entities that can be accessed through a Cloud API “Cloud API endpoint
canonicalCollectionUri endpoint, this object contains the URI to the collection elements” on page 511
endpoint.

x-gw-canonicalElementUri For entities that can be accessed through a Cloud API “Cloud API endpoint
endpoint, this object contains the URI to the individual elements” on page 511
element endpoint.

x-gw-canonicalParent For entities that can be accessed through a Cloud API “Cloud API endpoint
endpoint, this object contains the ID of the parent entity. elements” on page 511

x-gw-calculatedValues An object whose keys represent schema properties that have “Calculated values” on page
dynamic values. Dynamic values are calculated based on 506
evaluation of static values retrieved through JsonLogic.

x-gw-children An object containing information about child objects of an “Child entities” on page 507
entity.

x-gw-choices This property contains typelist values associated with the “Choice values” on page 508
entity objects. It is included in the schema response when the
inlineTypelists query parameter is set to true.

x-gw-coverageCategory A property attached to the coverage in the schema. It “Coverage category” on page
provides a coverage code, description, name, and sort order. 513

x-gw-coverages A product definition property that references the coverage “Product definition
schema definition. Only available when the properties” on page 519
inlineProductDefinition query parameter is set to
true.

x-gw-coveredLocationField This property differentiates address information for a covered “Covered location field” on
location from LOB-specific additions. page 514

x-gw-createOnly Indicates that a property can be set when creating the entity “Update restrictions” on page
(during an initial POST), but not modified. 524

x-gw-defaultValues An array of strings that indicate what default views a property “Cloud API responses” on
will appear in. Possible values include detail, summary, and page 511
none.

x-gw-dynamicProperties An object where each key in the map represents a named “Rules” on page 520
rule. The values of such keys have a jsonLogic object
defining the rules.

x-gw-entityId A marker on every schema that corresponds to an entity that “Entity ID” on page 515
contains the id of that entity.

x-gw-filterBy Applies to typekey properties that have typelists that are “Typekey references” on page
filtered by categories from other typelists represented on the 524
same object. This property is an array of schema property
names for the filtering typekey properties.

x-gw-forbidden This property contains an array of one or more values that • “Forbidden fields” on
indicate properties that are forbidden for use in a particular page 515
context. Often used within an x-gw-rules object to identify
fields that cannot be used in certain situations. • “Country-specific fields”
on page 512

504 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Property Description More information

• “Coverage parent/child
dependencies” on page
514

x-gw-localizations When the “Localizations” on page 516

includeLocalizations query parameter is set to true,

this property is included in the schema to show localized
versions of strings for every installed language.
x-gw-maximum Used to represent a maximum value for a property that is not “Numeric values” on page
a standard JSON integer or decimal, such as a gw- 518
bigdecimal or MonetaryAmount object.

x-gw-minimum Used to represent a minimum value for a property that is not “Numeric values” on page
a standard JSON integer or decimal, such as a gw- 518
bigdecimal or MonetaryAmount object.

x-gw-owningPolicyLine If an entity is associated with a policy line, this property “Owning policy line” on page
contains the ID and name of the policy line. 518

x-gw-owningProducts If an entity is LOB-specific, this property will display an ID and “Owning products” on page
name of all products associated with the entity. 518

x-gw-patchOnly Indicates that the value can be set only during updates “Update restrictions” on page
(PATCH requests), not during the initial creation (POST 524
request).

x-gw-precision The precision of a fixed-point decimal value (the total number “Numeric values” on page
of digits allowed in a number). 518

x-gw-reference-schema The name of the schema definition associated with a given “References” on page 519
type when a property is a reference (such as
SimpleReference).

x-gw-referenceType The name of the referenced entity type when a property is a “References” on page 519
reference (such as SimpleReference).

x-gw-requiredForBind An array of property names for properties whose values must “Required properties” on
be specified in order to bind a job. page 519

x-gw-requiredForCreate An array of property names for properties whose values must “Required properties” on
be specified as part of POST requests to create a new entity. page 519

x-gw-requiredForQuote An array of property names for properties whose values must “Required properties” on
be specified in order to quote a job. page 519

x-gw- This property identifies fields that are required for a particular • “Required properties” on
requiredForValidation entity to be valid. A typical use case is to define required page 519
fields in an address.
• “Country-specific fields”
on page 512

x-gw-resourceReference A marker attached to schema definitions such as “References” on page 519

SimpleReference that indicates that the schema represents a
reference to another entity.

x-gw-rules This property contains a jsonLogic attribute where you can • “Rules” on page 520
apply conditional rules to various schema elements.

Business entity schemas 505

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Property Description More information

• “Country-specific fields”
on page 512
• “Coverage parent/child
dependencies” on page
514
• “Tags” on page 523

x-gw-scale The scale of a fixed-point decimal value (the number of digits “Numeric values” on page
allowed to the right of the decimal point). 518

x-gw-scheduledItems A product definition property that references the scheduled “Product definition
items schema definition. Only available when the properties” on page 519
inlineProductDefinition query parameter is set to
true.

x-gw-segmentField Contains a Boolean value specifying whether the entity is “Segments” on page 522
based off of a segment field in APD.

x-gw-sortOrder The sequence number of coverable fields defined in APD. • “Sort order” on page 522
• “Choice values” on page
508

x-gw-tags This object represents tags that have been attached to “Tags” on page 523
clauses, clause terms, and so on in APD.

x-gw-typelist The name of the typelist when the property is a reference to “Typekey references” on page
a TypeKeyReference. 524

x-gw-valueProperty This property provides the name of the property that stores a “Value properties” on page
term, scheduled item property, or answer value. 525

Schema properties usage

The following topics provide detailed descriptions and examples that will help in understanding the properties returned
in the business entity schemas. See “Schema properties overview” on page 503 for a list of properties that are specific
to these schemas.

Calculated values
APD supports calculated values for coverage terms on a parent coverage where the minimum or maximum are
calculated based on terms on the child coverages. For example, the parent coverage can have a limit whose minimum
value is the sum of the limits of a set of child coverages. Calculated values can use a sum, min, or max across the child
terms, or be a direct reference to a child term.
The entity schema provides the x-gw-calculatedValues property to support this type of scenario. This property is an
object whose keys represent schema properties that have dynamic values rather than static values. Each schema
property will have a value with a jsonLogic property that can be evaluated, resulting in the concrete value to attach to
that schema property.
The x-gw-calculatedValues property is primarily intended for use by client code that uses schema-based validation.
In order to interpret the calculated values at runtime, a client needs to iterate through each property on the x-gw-
calculatedValues object, evaluate the JsonLogic expression for that property, and then attach the resulting value to
the containing schema definition.
See https://jsonlogic.com/ for more information on using JsonLogic.

506 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following is an example of a calculated value. This is a simple example where the value must be retrieved from
another entity:

"x-gw-calculatedValues": {
"x-gw-maximum": {
"jsonLogic": {
"+": {
"uri": "/jobs/{jobId}/lines/TSTLine/test-coverables/{testCoverableId}/coverages/TSTChildCov/
terms.TSTChildCovPackageTerm.choiceValue.values[0].value"
}
}
}
}

Child entities
An entity can (but doesn’t have to) have child objects. These child objects are returned in the x-gw-children schema
object. The following properties can be included with the x-gw-children object:
• childType: The type related to certain product model metadata. See “Special child types” below.
• description: A description of the children.
• graphProperty: The property used to attach these children in the schema.
• id: The id of the child entity.
• title: The title for the children.
• urlPart: The URL fragment used for the collection of child entities in the API.
The following example shows some of the children for the Account entity in the base configuration:

"x-gw-children": [
{
"id": "Activity",
"urlPart": "activities"
},
{
"id": "Assignee",
"urlPart": "activity-assignees"
},
{
"id": "ActivityPattern",
"urlPart": "activity-patterns"
},

Special child types

Some of the entity children in PolicyCenter need special product model metadata. The primary use case for this is for
creating user interface elements, which in some cases have special components associated with them. Those children
can be one of the following types:
• coverage
• scheduledItem
• questions
To distinguish these types of children, each one has the type indicator property childType. For example, the Job entity
might include the following children:

"Job": {
...
{
"id": "Note",
"urlPart": "notes"
},
...
, {
"childType": "questions",
"id": "PolicyQuestions",
"urlPart": "questions"
},
...

Business entity schemas 507

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Notice that the child PolicyQuestions has a childType property. There is no childType property on Notes because
Notes are not among the types of children requiring special components.

Policy line children

The entity schema treats policy lines as direct child properties of the Job entity. This relationship is shown in the
schema by including the policy line child on the Job with a urlPart property that includes “lines”. The following
example shows the PersonalAutoLine child of the Job:

"Job": {
...
"x-gw-children": [
...
{
"description": "Personal Auto",
"graphProperty": "PersonalAutoLine",
"id": "PersonalAutoLine",
"title": "Personal Auto Line",
"urlPart": "lines/PersonalAutoLine"
},

Notice the urlPart property is set to lines/PersonalAutoLine.

Choice values
For entities that contain choice values, the entity schema returns the x-gw-choices object. You must include the query
parameter inlineTypelists set to true to retrieve this object. The object contains the following properties:

Property Description Used with

code The unique identifier for the choice. • Typelists

• Option/package choices
• Coverage term choices

name The name of the choice. • Typelists

• Option/package choices
• Coverage term choices

description The description of the choice. • Typelists

• Option/package choices
• Coverage term choices

sortOrder The canonical sort order for the choice, relative to other choices in the same list. • Typelists
• Option/package choices
• Coverage term choices

categories A list of strings that indicate the categories the typekey belongs to. Categories are • Option/package choices
presented in the form Typelist.Code, such as Country.US.
• Coverage term choices

values An array of additional values relating to coverage terms. • Coverage term choices

Typelist choice values

The x-gw-choices property can contain typelist values associated with the entity objects. For example, in the
PolicyCenter base configuration the Account Status on the Account entity is a typelist of type AccountStatus. The
typekeys in the AccountStatus typelist are Active, Merged, Pending, and Withdrawn. Without inlineTypelists set to
true, the schema endpoint returns the following:

"accountStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The current status of this account",

508 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"readOnly": true,
"title": "Account status",
"x-gw-typelist": "AccountStatus"
},

This example shows that accountStatus is a typelist of type AccountStatus, but the values of that typelist are not
displayed. When you add inlineTypelists=true to the endpoint query string, the individual values are included in
the schema in the x-gw-choices object:

"accountStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The current status of this account",
"readOnly": true,
"title": "Account status",
"x-gw-choices": [
{
"code": "Active",
"description": "The account is fully ready and open, and submissions have been created for it.",
"name": "Active",
"sortOrder": 0
},
{
"code": "Merged",
"description": "The account has been merged into another account and is available for read only access.",
"name": "Merged",
"sortOrder": 1
},
{
"code": "Pending",
"description": "The account is ready for data entry, but data entry is still ongoing and the account is not
considered fully open.",
"name": "Pending",
"sortOrder": 2
},
{
"code": "Withdrawn",
"description": "The account has been withdrawn from consideration for business with the carrier.",
"name": "Withdrawn",
"sortOrder": 3
}
],
"x-gw-typelist": "AccountStatus"

Notice the sortOrder value under each choice. This ordering can be used to ensure the desired order of user interface
elements. See “Sort order” on page 522 for more information.
Coverage term choices
When the inlineProductDefinition query parameter is set to true, additional values are returned in the schema for
coverage term choices. Coverage terms include option and package terms that offer choices in the form of numerical
values. For an option term, there's one numerical value per choice, whereas for a package term there can be more than
one. In addition, a package term such as "100/250" might represent the numbers 100 and 250, or they might actually be
100,000 and 250,000.
To distinguish between option terms and package terms, the x-gw-choiceType field is included on the choiceValue
property. Possible values are option and package.

"choiceValue": {
"$ref": "#/definitions/ProductModelChoice",
"description": "The value of this term as an enumerated choice. Only applicable if the `covTermType` is `choice`.",
"nullable": true,
"title": "Choice value",
"x-gw-choiceType": "option",

Because the coverage terms typically involve monetary amounts, the currency field is included on each x-gw-
choices array element.

"x-gw-choices": [
{
"code": "00",
"currency": "usd",
"name": "No Deductible",

Each x-gw-choices array element also includes a values array. For option terms there will only ever be one value in
the array. Package terms can have multiple values. Each value in the array can have the following fields:

Business entity schemas 509

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Field Description Examples Applies to

aggregationModel A typecode value that indicates how a limit or • pp (per person) Option and package
deductible needs to be aggregated during claims terms
• ea (each)
handling.

name The name of the value. The name explains what Bodily injury per-person Package terms
that part of a package value means. limit

restrictionModel A typecode value that indicates what sort of • bi (bodily injury) Option and package
exposure the term applies to. terms
• pd (property damage)

value A string containing the actual value. • 5000.0000 Option and package
terms
• 0

valueType What the value number represents • money Option and package
terms
• count
• other

The following are examples of option and package term choice values.
Option term values:

"x-gw-choiceType": "option",
"x-gw-choices": [
{
"code": "00",
"currency": "usd",
"name": "No Deductible",
"sortOrder": 0,
"values": [
{
"aggregationModel": "po",
"restrictionModel": "prp",
"value": "0",
"valueType": "money"
}
]
},

Package term values:

"x-gw-choiceType": "package",
"x-gw-choices": [
{
"code": "0/0/5",
"currency": "usd",
"name": "0/0/5",
"sortOrder": 5,
"values": [
{
"aggregationModel": "pp",
"name": "PA_person_agglimit",
"restrictionModel": "bi",
"value": "0",
"valueType": "money"
},
{
"aggregationModel": "ea",
"name": "PA_accident_agglimit",
"restrictionModel": "bi",
"value": "0.0000",
"valueType": "money"
},
{
"aggregationModel": "ea",
"name": "PA_property_agglimit",
"restrictionModel": "pd",
"value": "5000.0000",
"valueType": "money"
}
]
},

510 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Cloud API endpoint elements

For schema entities that can be accessed through Cloud API endpoints, the schema includes information on options for
accessing those endpoints:
• x-gw-canonicalParent: The parent entity.
• x-gw-canonicalCollectionUri: The endpoint that accesses a collection of entities.
• x-gw-canonicalElementUri: The endpoint that accesses individual instances of the entity.
• x-gw-actions: An array of actions that can be taken on the endpoints. Each object in the array includes:
◦ httpMethod: A command that can be used with the endpoint.
◦ actionTarget: Whether the command applies to the individual element endpoint or the collection endpoint.
◦ description: Optional. Describes the action.
◦ urlSuffix: Optional. An additional action that can be taken on the endpoint by using the httpMethod with the
endpoint, followed by the urlSuffix at the end of the endpoint. (See example below.)
For example, here are the endpoint elements available for the RolePermission entity:

"title": "Role permission",

"type": "object",
"x-gw-actions": [
{
"actionTarget": "collection",
"httpMethod": "GET"
},
{
"actionTarget": "collection",
"httpMethod": "POST"
},
{
"actionTarget": "element",
"httpMethod": "DELETE"
},
{
"actionTarget": "element",
"httpMethod": "GET"
}
],
"x-gw-canonicalCollectionUri": "/admin/v1/roles/{roleId}/permissions",
"x-gw-canonicalElementUri": "/admin/v1/roles/{roleId}/permissions/{permissionId}",
"x-gw-canonicalParent": {
"id": "Role"
},

This example shows that you can take the following actions on the RolePermission entity through Cloud API:
• GET a collection of role permissions. (GET /admin/v1/roles/{roleId}/permissions)
• Create a new role permission with the POST command on the permissions collection. (POST /admin/v1/roles/
{roleId}/permissions)
• DELETE a single role permission. (DELETE /admin/v1/roles/{roleId}/permissions/{permissionId})
• GET a single role permission. (GET /admin/v1/roles/{roleId}/permissions/{permissionId})
Note that the x-gw-canonicalParent identifies the Role entity as the canonical parent of RolePermissions.

Cloud API responses

When an element is retrieved with a Cloud API command, it’s possible that not all properties of that element will be
displayed in the response by default. This might be desirable, for example, in cases where retrieving the contents of a
certain property could impact performance if it were to be retrieved for every instance of that element.
You can identify the circumstances under which a property will be displayed based on the x-gw-defaultViews
property. This property is an array with the following possible values:
• detail: This property is in the response when a single instance of the element is retrieved, not when a collection is
retrieved.

Business entity schemas 511

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• summary: This property is in the response when a collection is retrieved.

• none: This property is in the response only when it is explicitly identified in the fields query parameter.
In this example, the accountContactRoles property is displayed in the response only when a single instance of an
AccountContact is retrieved:

"AccountContact": {
...
"properties": {
"accountContactRoles": {
...
"x-gw-defaultViews": [
"detail"
],
...
},

The following command retrieves a single account contact, and therefore displays the accountContactRoles property:
Command

GET /account/v1/accounts/pc:Su4p27AlTSug_SWq-8koA/contacts/pc:S9rwT9nWtFBArb3GFDwkc

Response

{
"data": {
"attributes": {
"accountContactRoles": [
{
"code": "AccountHolder",
"name": "AccountHolder"
}
],
"active": true,
"authorizationID": "S5qmqyeE_7azM0VwejF2r",
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},

However, when the collection of account contacts is retrieved, account contact roles is not included:
Command

GET /account/v1/accounts/pc:Su4p27AlTSug_SWq-8koA/contacts

Response

{
"count": 5,
"data": [
{
"attributes": {
"authorizationID": "S5qmqyeE_7azM0VwejF2r",
"cellPhone": {
"countryCode": {
"code": "US",
"name": "United States (1)"
},

Country-specific fields
Entity schemas use JSON logic conditional rules to define whether certain fields are forbidden or required based on the
country. In some cases a field might be forbidden for use in a particular county. In other cases, such as addresses,
required fields differ by country. These rules are specified in the x-gw-rules property.
Note: See “Rules” on page 520 and “Forbidden fields” on page 515 for more information.

512 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

In this example, there is a rule on PolicyLocation that makes certain location fields forbidden and others required for
the US:

"x-gw-entityId": "PolicyLocation",
"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
"===": [
{
"var": "country"
},
"US"
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"CEDEX",
"addressLine1Kanji",
"addressLine2Kanji",
"area",
"cityKanji",
"department",
"emirate",
"island",
"oblast",
"parish",
"prefecture",
"province"
],
"x-gw-requiredForValidation": [
"addressLine1",
"city",
"postalCode",
"state"
]
},

In some cases the same set of rules apply to multiple countries. In those cases, all countries are listed in an array using
in logic on the rules, as shown here:

"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
…
},
{
"in": [
{
"var": "country"
},
[
"AS",
"AU",
"FM",
"GU",
"IN",
"MH",
...

Coverage category
The x-gw-coverageCategory property is attached to the coverage in the schema. It provides the following information
about the coverage category:
• code: The coverage category code.
• description: A description of the coverage category.
• name: The name of the coverage category.
• sortOrder. The sort order. See “Sort order” on page 522 for more information.

Business entity schemas 513

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

The following is an example of a coverage category as it appears in the schema. In this case, it describes the coverage
category in the base configuration Personal Auto line for collision (PACollisionCov) coverage.

"x-gw-coverageCategory": {
"code": "PAPPhysDamGrp",
"description": "Personal Auto Physical Damage Group",
"name": "Personal Auto Physical Damage Group",
"sortOrder": 50
}

This property is included with the schema only when the inlineProductDefinition query string is set to true.

Coverage parent/child dependencies

Coverages in PolicyCenter have clauses, which can have subclauses. In some cases a subclause can be applied to a
coverage only if its parent clause has been selected. For example, Liability coverage could have a subclause of Bodily
Injury. You can’t apply Liability for Bodily Injury if you haven’t selected Liability coverage.
You must set the inlineProductDefinition query parameter to true to see these dependencies. If you don’t set this
parameter to true, the *Coverages schemas (such as PersonalAutoLine_Coverages) that contain these dependencies
aren’t included in the response.
The entity schema tracks subclause requirements through rules. If a child entity (the subclause) cannot be added
without the parent entity (parent clause), a rule such as the following is attached to the *_Coverages schema that
contains the properties for each individual coverage:

"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
"!==": [
{
"var": "TSTParentCov.selected"
},
true
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"TSTChildCov"
]
}
]
}
},

In this example, the rule is checking to see if the selected property on the parent entity (TSTParentCov) is not true
(meaning the parent clause has not been selected). If that’s the case, the child coverage (TSTChildCov) is listed as
forbidden.
See “Rules” on page 520 for more information on working with rules. See “Forbidden fields” on page 515 for more
information on the x-gw-forbidden property.

Covered location field

The x-gw-coveredLocationField property applies to location properties that are automatically added to a covered
location, such as "addressLine1" or "city". The purpose of this property is to differentiate address information for a
covered location from LOB-specific additions. Every schema property that is inherited from the CoveredLocationBase
schema definition is marked as true.

"x-gw-coveredLocationField": true

Date and date-time fields

Some properties that contain dates have restrictions on the date range allowed. There are instances where a date must
be before or after a certain timeframe. To allow for this, the following attributes can be found on a date or date-time
property when applicable:

514 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

• x-gw-before: The date or date-time must be earlier than this value.

• x-gw-after: The date or date-time must be later than this value.
In the following example, dateOfBirth is a date that must have a value before the date the value is entered (now):

"dateOfBirth": {
"description": "The person's date of birth. Only applicable for an `AccountContact` that represents a person.",
"format": "date",
"nullable": true,
"title": "Date of birth",
"type": "string",
"x-gw-before": "now"
},

Entity ID
Every schema that contains an entity has a corresponding entity ID. For example, the User schema has an entity ID of
User:

"x-gw-entityId": "User"

In contrast, the SimpleReference schema is not an entity, and therefore does not have an x-gw-entityId property.
Note that the x-gw-entityId property is available only when a schema is retrieved through the entity-schemas
endpoints.

Forbidden fields
The schema can include the x-gw-forbidden property. This property is an array used to indicate that one or more
properties are not allowed or available under certain conditions. It is often defined inside JsonLogic decisions that
provide the conditions under which something is forbidden. (See https://jsonlogic.com/ for more information on using
JsonLogic.)
This example shows a section of the schema that indicates certain properties are forbidden based on a contact subtype:

"x-gw-rules": [
{
"jsonLogic": {
"if": [
…
{
"in": [
{
"var": "contactSubtype"
},
[
"Adjudicator",
"Person",
"PersonVendor",
"UserContact"
]
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"companyName"
]
},
{
"in": [
{
"var": "contactSubtype"
},
[
"LegalVenue",
"Place"
]
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"applicableGoodDriverDiscount",
"cellPhone",
"companyName",
…

Business entity schemas 515

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

]
},

The x-gw-forbidden property is used in several contexts. It is used to designate forbidden fields for things such as:
• Subtype-specific fields.
• Product edition rules that indicate that a given element is unavailable for that edition.
• Choices on options, packages, or typekeys. In these cases, x-gw-forbidden is an array of objects, where each
object has a code and name for the forbidden choice.
See “Country-specific fields” on page 512 for more examples of x-gw-forbidden.

Localizations
When you call the schema retrieval endpoint with the includeLocalizations parameter set to true, the returned
schema will contain localized versions of all localizable strings in the schema. (See “includeLocalizations” on page 501
for information on using this parameter.) If you also specify the inlineTypelists parameter, localized strings will be
included for typelist values. Similarly, if you specify the inlineProductDefinition parameter, localized strings will
be included for localizable product model elements such as coverage names and descriptions.
Localization strings are returned on the x-gw-localizations property on the associated element. The value of x-gw-
localizations is an object with a key for each localized property, such as title or description. The values of those
keys are another object with key/value pairs for each requested language and the localized value for those languages.
For example, suppose you have two languages configured, English (US) and French (France). You also have a schema
object on an entity named username. The object looks like this:

"username": {
"description": "The username for the user",
"maxLength": 30,
"minLength": 1,
"pattern": "\\S",
"title": "Username",
"type": "string",

Retrieve localized values for all installed languages:

Command

GET /common/v1/entity-schemas?includeLocalizations=*all

Schema example

"x-gw-localizations": {
"description": {
"en_US": "The username for the user",
"fr_FR": "Le nom d’utilisateur de l’utilisateur"
},
"title": {
"en_US": "Username",
"fr_FR": "Nom d’utilisateur"
}
}

Retrieve localized values for US English:

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US

Schema example

"x-gw-localizations": {
"description": {
"en_US": "The username for the user"
},
"title": {
"en_US": "Username"

516 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

Retrieve localized values in US English including typelists:

Command

GET /common/v1/entity-schemas?includeLocalizations=en_US&inlineTypelists=true

Schema example

"vacationStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "Indicates whether the user is considered to be on vacation",
"title": "Vacation status",
"x-gw-choices": [
{
"code": "atwork",
"description": "The user is at work",
"name": "At work",
"sortOrder": 0,
"x-gw-localizations": {
"description": {
"en-US": "The user is at work"
},
"name": {
"en-US": "At work"
}
}
},
{
"code": "onvacation",
"description": "The user is on vacation",
"name": "On vacation",
"sortOrder": 1,
"x-gw-localizations": {
"description": {
"en-US": "The user is on vacation"
},
"name": {
"en-US": "On vacation"
}
}
},
…
],
"x-gw-localizations": {
"description": {
"en-US": "Indicates whether the user is considered to be on vacation"
},
"title": {
"en-US": "Vacation status"
}
},
"x-gw-typelist": "VacationStatusType"
},

A value will always be included in x-gw-localizations for each installed language. If the value has not been
localized for a language, normal localization fallback rules will apply. If a language code and region are specified, the
first fallback will be to language code, then to the default language. For example, suppose fr_CA (Frech, Canada) is an
installed language. If there is no localization for a particular property for fr_CA, it will fall back to a value specified for
fr (French). If there is no localized value for fr, the value will be the default language (if the default language is not
fr_CA or fr).
Command

GET /common/v1/entity-schemas?includeLocalizations=en_US,fr_FR

Schema example

"x-gw-localizations": {
"description": {
"en_US": "The username for the user",
"fr_FR": "The username for the user"
},
"title": {
"en_US": "Username",
"fr_FR": "Username"

Business entity schemas 517

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

}
}

Numeric values
Properties that are numeric types can have additional defining properties depending on the type of value.
Fixed-point decimal values
Certain decimal values need to be restricted as to the maximum number of digits allowed in the value. This is depicted
in the schema through the x-gw-precision and x-gw-scale properties:
• x-gw-precision: The maximum number of digits allowed for a value.
• x-gw-scale: The scale of the value, such as the maximum number of digits to the right of a decimal point.
These properties apply only to elements of type gw-bigdecimal and to MonetaryAmount references.
In this example, the cost of a new car can be up to 18 digits, with up to two digits following the decimal point:

"PersonalVehicle": {
"description": "Personal Vehicle",
"properties": {
...
"costNew": {
"$ref": "#/definitions/MonetaryAmount",
"description": "Original retail cost of car.",
"nullable": true,
"title": "Cost New",
"x-gw-precision": 18,
"x-gw-scale": 2,
"x-gw-sortOrder": 6
},

Minimum and maximum values

Numeric properties that are non-standard JSON decimal or integer types (such as MonetaryAmount and gw-
bigdecimal) can have maximum and minimum values defined in the x-gw-maximum and x-gw-minimum properties. In
this example, the maximum amount allowed is 5000, and the minimum is 250:

"amount": {
"$ref": "#/definitions/MonetaryAmount",
"description": "The transaction amount for the effective time",
"readOnly": true,
"title": "Amount",
"x-gw-maximum": 5000,
"x-gw-minimum": 250
},

Owning policy line

If an entity is associated with a particular policy line pattern, the x-gw-owningPolicyLine property will contain the ID
and name of that policy line. In this example, the entity is associated with the Personal Auto policy line:

"x-gw-owningPolicyLine": {
"id": "PersonalAutoLine",
"name": "Personal Auto Line"
},

No query parameters are required in the API command to retrieve this property.

Owning products
If an entity is LOB-specific, the x-gw-owningProducts property will contain an array of products that include that
entity. In this example, the entity is part of the PersonalAuto product:

"x-gw-owningProducts": [
{
"id": "PersonalAuto",
"name": "Personal Auto"
}
]

518 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

No query parameters are required on the command to retrieve this property. However, if you include the product query
parameter, all entities returned will either not have any owning products or will contain the specified product in the x-
gw-owningProducts array.

Product definition properties

When the inlineProductDefinition query parameter is set to true, the following additional properties are returned
inline with the schema:
• x-gw-coverages
• x-gw-answers
• x-gw-scheduledItems
Only defined properties are returned. For example, if there are no scheduled items, the x-gw-scheduledItems property
is not in the response schema.
The product definition properties contain a $ref property, which references the appropriate schema definition. Here’s
an example for a coverage:

"x-gw-coverages": {
"$ref": "#/definitions/PersonalAutoLine_Coverages"
},

References
There are some schema definitions that are references to other entities. Examples are entities such as SimpleReference
and GroupReference. When this is the case, the entity has an x-gw-resourceReference property set to true.

"x-gw-resourceReference": true

For properties that are reference types, such as SimpleReference, the name of the referenced entity type is defined in
the x-gw-referenceType property. The name of the schema definition associated with a given type is specified in the
x-gw-reference-schema property. In this example, accountHolder is a SimpleReference associated with the
AccountContact schema, of type AccountContact:

"accountHolder": {
"$ref": "#/definitions/SimpleReference",
"description": "A reference to the `AccountContact` that represents the owner of the policies for this account",
"title": "Account holder",
"x-gw-reference-schema": "AccountContact",
"x-gw-referenceType": "AccountContact"
},

Required properties
Some entities have a required property. This property is an array containing a list of properties that must have values
on instances of the entity. In addition, there are properties that are required only when certain actions, such as creation
or validation, take place on those entities.
• requiredForBind: The property must have a value for a job to bind.
• requiredForCreate: The property must have a value for an entity to be created.
• requiredForQuote: The property must have a value for a job to be quoted.
• requiredForValidation: The property must have a value for the object to validate.
For example, the following specifies that an address cannot be validated if there are not values for addressLine1,
city, postalCode, and state:

"x-gw-requiredForValidation": [
"addressLine1",
"city",
"postalCode",
"State"
]

Business entity schemas 519

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Rules
The entity schema applies rules to some entities, both conditional and non-conditional. Rules are required for several
different areas of the schema. For details on some of the specific areas of the entity schema where rules are used, see
the following sections:
• “Country-specific fields” on page 512
• “Coverage parent/child dependencies” on page 514
• “Tags” on page 523
Rules Overview
In some cases there is schema metadata about a business entity, or associated product model entity, that is conditional
rather than static. To support those use cases, where possible the Guidewire schema APIs translate those rules into
conditions using the JsonLogic format. The JsonLogic expressions, when evaluated, will return a JSON object that
might contain additional JSON Schema properties to apply to the attached schema.
For example, if a direct coverage term has a conditional maximum value, the directValue schema property for the
term's schema will have an x-gw-rules array with an object representing this rule. Evaluating the JsonLogic
expression for the associated rule might return a result such as:

{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-maximum": "500.00"
}

This means that the x-gw-maximum schema property needs to be applied to the term's schema dynamically, replacing
any value that might already be there. If the result returns null or the empty object, it means no changes to the schema
are needed. (The x-gw-dynamicPropertiesMarker property is a marker property that can be ignored at runtime).
JsonLogic expressions need to be evaluated using the associated root API object's attributes as the context for
evaluation.
See https://jsonlogic.com/ for more information on using JsonLogic.
The following are examples of places where rules can be attached:
• Field existence rules are attached to the containing schema definition.
• Field min/max/default rules are attached to the associated property definition.
• Field typekey existence rules are attached to the associated property definition.
• Clause existence rules are attached to the _Coverages schema definition that defines a container for all coverages
on the coverable.
• Term existence rules are attached to the terms property on the _Coverage schema definition.
• Term min/max/default rules are attached to the Value property for the term, such as directValue.
• Term option/package/typekey existence rules are attached to the choiceValue or typekeyValue property for the
term.
Rules Examples
Conditional rules are provided with JsonLogic. Often (but not always) this logic is nested within the x-gw-rules array.
Here’s an example. (Note that while this example pertains specifically to PolicyCenter, the functionality of x-gw-rules
is the same across all InsuranceSuite products.)

"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
"===": [
{
"uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
},
1002

520 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-maximum": "500.00"
}
},
{
"===": [
{
"uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
},
1003
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-maximum": "400.00"
},

In this case, if the property at the specified uri is equal to 1002, the maximum value for this property is 500. But if the
value is 1003, the maximum is 400.
Rules can also exist without conditions. For example, if a direct coverage term always has a maximum of 500.00 for a
particular product edition, fetching the schema in the context of that edition includes the property directly.

"directValue": {
"x-gw-maximum": "500.00",
…
}

The x-gw-rules property is an array of JsonLogic rules. Another property, x-gw-dynamicProperties, is similar to x-
gw-rules, but instead of being an array, it’s an object containing named rules. In this example, there are two named
rules, one for accountHolderCreation and one for primaryLocationCreation:

"x-gw-dynamicProperties": {
"accountHolderCreation": {
"forbiddenError": "Exactly one of either 'accountHolder' or 'initialAccountHolder' is required on creation",
"jsonLogic": {
"if": [
{
"===": [
{
"var": "accountHolder"
},
null
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-requiredForCreate": [
"initialAccountHolder"
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [
"initialAccountHolder"
]
}
]
},
"requiredError": "Exactly one of either 'accountHolder' or 'initialAccountHolder' is required on creation"
},
"primaryLocationCreation": {
"forbiddenError": "Exactly one of either 'primaryLocation' or 'initialPrimaryLocation' is required on creation",
"jsonLogic": {
"if": [
{
"===": [
{
"var": "primaryLocation"
},
null
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-requiredForCreate": [
"initialPrimaryLocation"
]
},
{
"x-gw-dynamicPropertiesMarker": true,
"x-gw-forbidden": [

Business entity schemas 521

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"initialPrimaryLocation"
]
}
]
},
"requiredError": "Exactly one of either 'primaryLocation' or 'initialPrimaryLocation' is required on creation"
}
},

Segments
Fields of type "segment" in Advanced Product Designer (APD) are special in that they can cause the product edition to
change. Because of this, a user interface (or any other consumer) might need to treat those fields specially if they're
edited, in case the edition (and thus the appropriate edition-related rules) changes as a result.
Segment fields are shown in the schema with the x-gw-segmentField property set to true.

"x-gw-segmentField": true

Sort order
Sort order is preserved in various situations and can be used to ensure the desired order of user interface elements.
x-gw-sortOrder
APD attaches a sequence number to every coverable field. The entity schema preserves that ordering through the x-
gw-sortOrder property.

In this example, the PersonalVehicle entity has been configured so Annual Mileage is ordered before Basis Amount,
followed by Body Type, and so on.

"PersonalVehicle": {
"description": "Personal Vehicle",
"properties": {
"annualMileage": {
"description": "Annual miles for this vehicle",
"nullable": true,
"title": "Annual Mileage",
"type": "integer",
"x-gw-sortOrder": 1
},
"basisAmount": {
"description": "Basis Amount",
"nullable": true,
"title": "Basis Amount",
"type": "integer",
"x-gw-sortOrder": 2
},
"bodyType": {
"$ref": "#/definitions/TypeKeyReference",
"description": "Body type of the vehicle.",
"nullable": true,
"title": "Body Type",
"x-gw-filterBy": [
"vehicleType"
],
"x-gw-sortOrder": 3,
"x-gw-typelist": "BodyType"
},

sortOrder
In this example, the order of Account Status choices has been preserved through the sortOrder on the choice options,
with Active first, Merged second, and so on. Note that counting starts at 0, so the first choice is sortOrder 0.

"accountStatus": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The current status of this account",
"readOnly": true,
"title": "Account status",
"x-gw-choices": [
{
"code": "Active",
"description": "The account is fully ready and open, and submissions have been created for it.",
"name": "Active",
"sortOrder": 0
},
{

522 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"code": "Merged",
"description": "The account has been merged into another account and is available for read only access.",
"name": "Merged",
"sortOrder": 1
},
{
"code": "Pending",
"description": "The account is ready for data entry, but data entry is still ongoing and the account is not
considered fully open.",
"name": "Pending",
"sortOrder": 2
},

See “Choice values” on page 508 above for more information.

Tags
In APD, you can attach tags to most things that can be modeled, such as:
• Clauses
• Clause terms
• Clause term choices (options, packages, or typekeys)
• Risk object fields
• Risk object field choices (typekeys)
See Product Designer Guide for more information on applying tags in APD.
Tags consist of a particular code that either applies or does not apply. Tags can also have rules, such that they apply
conditionally.
Tags are represented in the entity schema via the x-gw-tags object, where each property is the code for a tag, and the
value of each code is an object with a single applies Boolean property. If a tag has no conditions, x-gw-tags is
attached directly to the resulting schema. If the tags do have conditions, the associated rules are in the x-gw-rules
array, and the tag-related rules produce JSON schema fragments that contain the x-gw-tags object. See “Rules” on
page 520 for more information on working with rules.
Tags are returned with the entity schema only when the editionCode query parameter is included with the command.
(See “Business entity schema query parameters” on page 500 for more information.)
This example shows tags as part of a rule on a coverage. In this case, if this property is less than 100, it’s rateable (rate
is applicable), otherwise it’s not rateable (rate is not applicable).

"x-gw-rules": [
{
"jsonLogic": {
"if": [
{
"<": [
{
"uri": "/jobs/{jobId}/lines/PersonalAutoLine/integerProperty"
},
100
},
{
"x-gw-tags": {
"rate": {
"applies": true
}
}
},
{
"x-gw-tags": {
"rate": {
"applies": false
}
}

This example shows a tag that is not conditional:

"name": {
"description": "Name field",
"maxLength": 255,
"minLength": 1,

Business entity schemas 523

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"nullable": true,
"x-gw-tags": {
"rate": {
"applies": true
}
}
},

Update restrictions
Some properties can be assigned values only when the entity is first created. In those cases, the property will have a
value of x-gw-createOnly set to true.
For example, an initial account holder can be specified only at the time the account is created (POST), and cannot be
modified later.

"Account": {
...
"initialAccountHolder": {
...
"title": "Initial account holder",
"x-gw-createOnly": true
},

In other cases, a property can be assigned a value only when the entity is updated (PATCH). In those cases, the property
will have x-gw-patchOnly set to true:

"x-gw-patchOnly": true

Typekey references
Some properties in the schema are used to identify typekey properties and behaviors.
Typelist
If an element in the schema is a TypeKeyReference, the applicable typelist is specific in the x-gw-typelist property.
In this example, the organizationType property is a TypeKeyReference to the AccountOrgType typelist:

"organizationType": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The type of organization of the company or person represented by this account, such as `individual`
or `corporation`",
"nullable": true,
"title": "Organization type",
"x-gw-typelist": "AccountOrgType"
},

Filter
Some typelists are filtered by categories from other typelists represented on the same object. The x-gw-filterBy
property contains an array of categories on which to filter. For example, a country typelist might include states,
provinces, islands, and so on. Not all of these options apply to all countries. In these cases, the typelist needs to be
filtered by country, as in the following examples:

"province": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The province of the location's address. Only applicable in certain countries.",
"nullable": true,
"title": "Province",
"x-gw-createOnly": true,
"x-gw-filterBy": [
"country"
],
"x-gw-typelist": "State"
},
"state": {
"$ref": "#/definitions/TypeKeyReference",
"description": "The state of the location's address. Only applicable in certain countries.",
"nullable": true,
"title": "State",
"x-gw-createOnly": true,
"x-gw-filterBy": [
"country"
],

524 Business entity schemas

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

"x-gw-typelist": "State"
}

Value properties
The x-gw-valueProperty property is in the schema attached to terms, scheduled item properties, and answers. This
property provides the name of the property that actually stores the term, scheduled item property, or answer value. This
makes it easier to determine the term, scheduled item property, or answer type without having to parse through the
other properties.
For example, this schema excerpt shows a term named PAMedLimit. The x-gw-valueProperty is set to
“choiceValue”, so you know that for this particular term you need to look for the choiceValue property to get or set the
value of the term.

"terms": {
"description": "The terms of a coverage",
"properties": {
"PAMedLimit": {
"properties": {
…
"choiceValue": {
"$ref": "#/definitions/ProductModelChoice",
…
"x-gw-choices": [
…
],
},
},
},
…
"x-gw-valueProperty": "choiceValue"
},

This property is only relevant to schemas created for product model entities, and therefore it will only appear when the
inlineProductDefinition query parameter is set to true.

Business entity schemas 525

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

526 Business entity schemas

chapter 59

The Test Util API

To facilitate development, Cloud API includes a Test Util API. The Test Util API is an API that provides functionality
to facilitate testing during development. The API is also sometime referred to by its internal name (testutil).
By default, the Test Util API is not enabled.

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

Learn more about the Test Util API and some of the available endpoints:
• “Enabling the Test Util API” on page 527
• “View the Test Util API in Swagger UI” on page 528
• “Test Util API endpoints” on page 528

Enabling the Test Util API

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

The Test Util API is enabled 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
The syntax for a substitution variable varies slightly based on where the value is 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

Then, you must start (or restart) the server.

The Test Util API 527
Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Setting the values in Guidewire Cloud Console environment variables

To set the values in Guidewire Cloud Console, specify the following:

PUBLISHEDAPIS_testutil_publish = true

Then, you must start (or restart) the server.

Setting the values in the application's config.properties file

To set the values in the application's config.properties file, specify the following:

published-apis.PUBLISHEDAPIS_testutil_publish = true

Then, you must start (or restart) the server.

View the Test Util API in Swagger UI

About this task

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

After you enable Test Util, you can use Swagger UI to view the Test Util API definition. (See “Enabling the Test Util
API” on page 527 for instructions on enabling Test Util.)

Procedure
1. Start PolicyCenter.
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 PolicyCenter, use: http://localhost:8180/pc/resources/swagger-
ui/
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.

Test Util API endpoints

The Test Util API provides endpoints that help with development and testing.

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

Document deletion endpoint

In the base configuration, you can use the LocalDocumentContentSource plugin during testing to store files from a
document management system. (See Plugins, Prebuilt Integrations, and SOAP APIs for more information on this
plugin.) The following endpoint deletes all files stored by this plugin.

POST /test-util/v1/delete-documents

This command does not take a request body.

528 The Test Util API

 Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Schema reloading endpoints

To help maintain a consistent environment during testing, you can enable and disable automatic schema reloading
when APD products change with the following endpoints:
• POST /test-util/v1/enable-schema-reload
• POST /test-util/v1/disable-schema-reload
Neither of these commands takes a request body.

Job testing endpoints

Use the following endpoints to test job activity:
• GET /test-util/v1/jobs/{jobId}
• POST /test-util/v1/jobs/{jobId}/complete-active-workflow
• POST /test-util/v1/jobs/{jobId}/set-non-renewal-notif-date

Retrieve a job for testing

To retrieve a job to use for test actions, use the following command:
GET /test-util/v1/jobs/{jobId}
Command

GET /test-util/v1/jobs/pc:101

Response

{
"data": {
"attributes": {
"id": "pc:101",
"jobStatus": {
"code": "Draft",
"name": "Draft"
}
},

This command retrieves the ID and status of the job. The results are identical to using the Job API with the following
query parameters:

GET /job/v1/jobs/{jobId}?fields=id,jobStatus

Complete an active job workflow

You can force completion of an active workflow with the following endpoint:
POST /test-util/v1/jobs/{jobId}/complete-active-workflow
This command does not take a request body.
For detailed information on workflows, see Configuration

Set non-renewal notification date

If you’re testing a non-renewal workflow, you can use the following endpoint to set the non-renewal notification date
(nonRenewalNotificationDate) to the current date:
• POST /test-util/v1/jobs/{jobId}/set-non-renewal-notif-date
This endpoint can be called only on jobs that are unlocked with a jobType of Renewal.
This command does not take a request body.

The Test Util API 529

Guidewire PolicyCenter for Guidewire Cloud 2024.02 Cloud API Consumer Guide

Test group endpoint

IMPORTANT:

Guidewire recommends using the groups endpoint in the admin API rather than the test-util groups endpoint.
The test-util endpoint is available only for backward compatibility. See “Groups” on page 444 for more
information on groups.

You can create a new group for testing purposes using the following endpoint:
POST /test-util/v1/groups

The request must include both the following properties:

• groupType: A value from the GroupType typelist, such as general.
• name: A string value containing the name you want to give the new group.
It also must include one of the following:
• organization: A JSON object with an id field that references the group id of the associated organization.
• parent: A JSON object with an id field that references the id of the parent group.
Request

{
"data": {
"attributes": {
"groupType": {
"code": "general"
},
"name": "Cloud API Group 1",
"parent": {
"id": "systemTables:1"
} }
}
}

Using this endpoint is similar to using the groups endpoint in the Admin API, but with test-util there are fewer
fields required to create the group. Guidewire recommends using the Admin API endpoint for both testing and
production purposes.

530 The Test Util API